You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/01/05 00:00:04 UTC
svn commit: r731382 - in
/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor:
EventMask.java IOEventDispatch.java IOReactor.java IOReactorStatus.java
IOSession.java
Author: olegk
Date: Sun Jan 4 15:00:04 2009
New Revision: 731382
URL: http://svn.apache.org/viewvc?rev=731382&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOEventDispatch.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactor.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorStatus.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java?rev=731382&r1=731381&r2=731382&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java Sun Jan 4 15:00:04 2009
@@ -33,6 +33,9 @@
import java.nio.channels.SelectionKey;
+/**
+ * Type of I/O event notifications I/O sessions can declare interest in.
+ */
public interface EventMask {
public static final int READ = SelectionKey.OP_READ;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOEventDispatch.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOEventDispatch.java?rev=731382&r1=731381&r2=731382&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOEventDispatch.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOEventDispatch.java Sun Jan 4 15:00:04 2009
@@ -31,16 +31,54 @@
package org.apache.http.nio.reactor;
+/**
+ * IOEventDispatch interface is used by I/O reactors to notify clients of I/O
+ * events pending for a particular session. All methods of this interface are
+ * executed on a dispatch thread of the I/O reactor. Therefore, it is important
+ * that processing that takes place in the event methods will not block the
+ * dispatch thread for too long, as the I/O reactor will be unable to react to
+ * other events.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ *
+ */
public interface IOEventDispatch {
+ /**
+ * Triggered after the given session has been just created.
+ *
+ * @param session the I/O session.
+ */
void connected(IOSession session);
+ /**
+ * Triggered when the given session has input pending.
+ *
+ * @param session the I/O session.
+ */
void inputReady(IOSession session);
+ /**
+ * Triggered when the given session is ready for output.
+ *
+ * @param session the I/O session.
+ */
void outputReady(IOSession session);
+ /**
+ * Triggered when the given session as timed out.
+ *
+ * @param session the I/O session.
+ */
void timeout(IOSession session);
+ /**
+ * Triggered when the given session has been terminated.
+ *
+ * @param session the I/O session.
+ */
void disconnected(IOSession session);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactor.java?rev=731382&r1=731381&r2=731382&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactor.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactor.java Sun Jan 4 15:00:04 2009
@@ -33,16 +33,66 @@
import java.io.IOException;
+/**
+ * HttpCore NIO is based on the Reactor pattern as described by Doug Lea.
+ * The purpose of I/O reactors is to react to I/O events and to dispatch event
+ * notifications to individual I/O sessions. The main idea of I/O reactor
+ * pattern is to break away from the one thread per connection model imposed
+ * by the classic blocking I/O model.
+ * <p>
+ * The IOReactor interface represents an abstract object implementing
+ * the Reactor pattern.
+ * <p>
+ * I/O reactors usually employ a small number of dispatch threads (often as
+ * few as one) to dispatch I/O event notifications to a much greater number
+ * (often as many as several thousands) of I/O sessions or connections. It is
+ * generally recommended to have one dispatch thread per CPU core.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ *
+ */
public interface IOReactor {
+ /**
+ * Returns the current status of the reactor.
+ *
+ * @return reactor status.
+ */
IOReactorStatus getStatus();
+ /**
+ * Starts the reactor and initiates the dispatch of I/O event notifications
+ * to the given {@link IOEventDispatch}.
+ *
+ * @param eventDispatch the I/O event dispatch.
+ * @throws IOException in case of an I/O error.
+ */
void execute(IOEventDispatch eventDispatch)
throws IOException;
+ /**
+ * Initiates shutdown of the reactor and blocks approximately for the given
+ * period of time in milliseconds waiting for the reactor to terminate all
+ * active connections, to shut down itself and to release system resources
+ * it currently holds.
+ *
+ * @param waitMs wait time in milliseconds.
+ * @throws IOException in case of an I/O error.
+ */
void shutdown(long waitMs)
throws IOException;
+ /**
+ * Initiates shutdown of the reactor and blocks for a default period of
+ * time waiting for the reactor to terminate all active connections, to shut
+ * down itself and to release system resources it currently holds. It is
+ * up to individual implementations to decide for how long this method can
+ * remain blocked.
+ *
+ * @throws IOException in case of an I/O error.
+ */
void shutdown()
throws IOException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorStatus.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorStatus.java?rev=731382&r1=731381&r2=731382&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorStatus.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOReactorStatus.java Sun Jan 4 15:00:04 2009
@@ -31,12 +31,34 @@
package org.apache.http.nio.reactor;
+/**
+ * IOReactorStatus represents an internal status of an I/O reactor.
+ */
public enum IOReactorStatus {
+ /**
+ * The reactor is inactive / has not been started
+ */
INACTIVE,
+
+ /**
+ * The reactor is active / processing I/O events.
+ */
ACTIVE,
+
+ /**
+ * Shutdown of the reactor has been requested.
+ */
SHUTDOWN_REQUEST,
+
+ /**
+ * The reactor is shutting down.
+ */
SHUTTING_DOWN,
+
+ /**
+ * The reactor has shut down.
+ */
SHUT_DOWN;
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java?rev=731382&r1=731381&r2=731382&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java Sun Jan 4 15:00:04 2009
@@ -34,28 +34,90 @@
import java.net.SocketAddress;
import java.nio.channels.ByteChannel;
+/**
+ * IOSession interface represents a sequence of logically related data exchanges
+ * between two end points.
+ * <p>
+ * The channel associated with implementations of this interface can be used to
+ * read data from and write data to the session.
+ * <p>
+ * I/O sessions are not bound to an execution thread, therefore one cannot use
+ * the context of the thread to store a session's state. All details about
+ * a particular session must be stored within the session itself, usually
+ * using execution context associated with it.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ *
+ */
public interface IOSession {
+ /**
+ * Name of the context attribute key, which can be used to obtain the
+ * session attachment object.
+ */
public static final String ATTACHMENT_KEY = "http.session.attachment";
public static final int ACTIVE = 0;
public static final int CLOSING = 1;
public static final int CLOSED = Integer.MAX_VALUE;
+ /**
+ * Returns the underlying I/O channel associated with this session.
+ *
+ * @return the I/O channel.
+ */
ByteChannel channel();
+ /**
+ * Returns address of the remote peer.
+ *
+ * @return socket address.
+ */
SocketAddress getRemoteAddress();
+ /**
+ * Returns local address.
+ *
+ * @return socket address.
+ */
SocketAddress getLocalAddress();
+ /**
+ * Returns mask of I/O evens this session declared interest in.
+ *
+ * @return I/O event mask.
+ */
int getEventMask();
+ /**
+ * Declares interest in I/O event notifications by setting the event mask
+ * associated with the session
+ *
+ * @param ops new I/O event mask.
+ */
void setEventMask(int ops);
+ /**
+ * Declares interest in a particular I/O event type by updating the event
+ * mask associated with the session.
+ *
+ * @param op I/O event type.
+ */
void setEvent(int op);
+ /**
+ * Clears interest in a particular I/O event type by updating the event
+ * mask associated with the session.
+ *
+ * @param op I/O event type.
+ */
void clearEvent(int op);
+ /**
+ * Closes the session and the underlying I/O channel.
+ */
void close();
void shutdown();