hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject 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
Date Sun, 04 Jan 2009 23:00:04 GMT
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();



Mime
View raw message