hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r733324 - /httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/
Date Sat, 10 Jan 2009 19:52:29 GMT
Author: olegk
Date: Sat Jan 10 11:52:28 2009
New Revision: 733324

URL: http://svn.apache.org/viewvc?rev=733324&view=rev
Log:
Javadoc updates

Modified:
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
Sat Jan 10 11:52:28 2009
@@ -37,15 +37,19 @@
 import org.apache.http.HttpRequest;
 
 /**
- * Abstract non-blocking client-side HTTP connection. It can be used to
- * submit HTTP requests and asynchronously receive HTTP responses. 
+ * Abstract non-blocking client-side HTTP connection interface. It can be used 
+ * to submit HTTP requests and asynchronously receive HTTP responses. 
+ * 
+ * @see NHttpConnection
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface NHttpClientConnection extends NHttpConnection {
 
     /**
-     * Submits the HTTP request to the target server.
+     * Submits {@link HttpRequest} to be sent to the target server.
      *  
      * @param request HTTP request
      * @throws IOException if I/O error occurs while submitting the request
@@ -54,11 +58,11 @@
     void submitRequest(HttpRequest request) throws IOException, HttpException;
 
     /**
-     * Returns <tt>true</tt> if an HTTP request has been submitted to the 
+     * Returns <code>true</code> if an HTTP request has been submitted to the

      * target server.
      * 
-     * @return <tt>true</tt> if an HTTP request has been submitted, 
-     * <tt>false</tt> otherwise. 
+     * @return <code>true</code> if an HTTP request has been submitted, 
+     * <code>false</code> otherwise. 
      */
     boolean isRequestSubmitted();
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
Sat Jan 10 11:52:28 2009
@@ -36,9 +36,11 @@
 import org.apache.http.HttpException;
 
 /**
- * Abstract client-side HTTP event handler.   
+ * Abstract client-side HTTP protocol handler.   
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface NHttpClientHandler {
 
@@ -46,17 +48,18 @@
      * Triggered when a new outgoing connection is created.
      * 
      * @param conn new outgoing HTTP connection.
-     * @param attachment an arbitrary object that was attached to the
-     *  session request
+     * @param attachment an object that was attached to the session request
      */
     void connected(NHttpClientConnection conn, Object attachment);
     
     /**
-     * Triggered when the connection is ready to send an HTTP request.
+     * Triggered when the connection is ready to accept a new HTTP request. 
+     * The protocol handler does not have to submit a request if it is not 
+     * ready.
      * 
      * @see NHttpClientConnection
      * 
-     * @param conn HTTP connection that is ready to send an HTTP request
+     * @param conn HTTP connection that is ready to accept a new HTTP request.
      */
     void requestReady(NHttpClientConnection conn);
 
@@ -66,7 +69,7 @@
      * a valid HTTP response object.
      * <p/>
      * If the response received encloses a response entity this method will 
-     * be followed a series of 
+     * be followed by a series of 
      * {@link #inputReady(NHttpClientConnection, ContentDecoder)} calls
      * to transfer the response content.
      * 
@@ -82,11 +85,12 @@
      * content decoder. 
      * <p/>
      * If the content consumer is unable to process the incoming content,
-     * input event notifications can be temorarily suspended using 
-     * {@link NHttpConnection#suspendInput()}.
+     * input event notifications can be temporarily suspended using 
+     * {@link IOControl} interface.
      * 
-     * @see NHttpConnection
+     * @see NHttpClientConnection
      * @see ContentDecoder
+     * @see IOControl
      *  
      * @param conn HTTP connection that can produce a new portion of the
      * incoming response content.
@@ -95,16 +99,16 @@
     void inputReady(NHttpClientConnection conn, ContentDecoder decoder);
     
     /**
-     * Triggered when the underlying channel is ready for writing a
-     * next portion of the request entity through the corresponding 
-     * content encoder. 
-     * <p/>
-     * If the content producer is unable to generate the outgoing content,
-     * output event notifications can be temorarily suspended using 
-     * {@link NHttpConnection#suspendOutput()}.
+     * Triggered when the underlying channel is ready for writing a next portion 
+     * of the request entity through the corresponding content encoder. 
+     * <p>
+     * If the content producer is unable to generate the outgoing content, 
+     * output event notifications can be temporarily suspended using 
+     * {@link IOControl} interface. 
      * 
-     * @see NHttpConnection
+     * @see NHttpClientConnection
      * @see ContentEncoder
+     * @see IOControl
      *  
      * @param conn HTTP connection that can accommodate a new portion 
      * of the outgoing request content.
@@ -113,7 +117,7 @@
     void outputReady(NHttpClientConnection conn, ContentEncoder encoder);
     
     /**
-     * Triggered when an I/O error occurrs while reading from or writing
+     * Triggered when an I/O error occurs while reading from or writing
      * to the underlying channel.
      * 
      * @param conn HTTP connection that caused an I/O error

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
Sat Jan 10 11:52:28 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -34,8 +34,9 @@
 import org.apache.http.nio.reactor.IOEventDispatch;
 
 /**
- * Extended version of the {@link NHttpClientConnection} used by {@link IOEventDispatch}
- * implementations to inform client-side connection objects of I/O events.
+ * Extended version of the {@link NHttpClientConnection} used by 
+ * {@link IOEventDispatch} implementations to inform client-side connection 
+ * objects of I/O events.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  */

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
Sat Jan 10 11:52:28 2009
@@ -37,11 +37,22 @@
 import org.apache.http.protocol.HttpContext;
 
 /**
- * Abstract non-blocking HTTP connection interface. It contains the current
- * HTTP context, as well as the actual HTTP request and HTTP response objects
- * that are being received / transferred over this connection.
+ * Abstract non-blocking HTTP connection interface. Each connection contains an 
+ * HTTP execution context, which can be used to maintain a processing state, 
+ * as well as the actual {@link HttpRequest} and {@link HttpResponse} that are 
+ * being transmitted over this connection. Both the request and 
+ * the response objects can be <code>null</code> if there is no incoming or 
+ * outgoing message currently being transferred.
+ * <p>
+ * Please note non-blocking HTTP connections are stateful and not thread safe. 
+ * Input / output operations on non-blocking HTTP connections should be 
+ * restricted to the dispatch events triggered by the I/O event dispatch thread.
+ * However, the {@link IOControl} interface is fully threading safe and can be 
+ * manipulated from any thread.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ * 
+ * @version $Revision$
  */
 public interface NHttpConnection extends HttpConnection, IOControl {
 
@@ -49,13 +60,24 @@
     public static final int CLOSING     = 1;
     public static final int CLOSED      = 2;
     
+    /**
+     * Returns status of the connection:
+     * <p>
+     * {@link #ACTIVE}: connection is active.
+     * <p> 
+     * {@link #CLOSING}: connection is being closed.
+     * <p> 
+     * {@link #CLOSED}: connection has been closed.
+     * 
+     * @return connection status.
+     */
     int getStatus();
     
     /** 
      * Returns the current HTTP request if one is being received / transmitted.
-     * Otherwise returns <tt>null</tt>.
+     * Otherwise returns <code>null</code>.
      * 
-     * @return an HTTP request if available. Otherwise returns <tt>null</tt>.
+     * @return HTTP request, if available, <code>null</code> otherwise.
      */
     HttpRequest getHttpRequest();
 
@@ -63,7 +85,7 @@
      * Returns the current HTTP response if one is being received / transmitted. 
      * Otherwise returns <tt>null</tt>.
      * 
-     * @return an HTTP response if available. Otherwise returns <tt>null</tt>.
+     * @return HTTP response, if available, <code>null</code> otherwise.
      */
     HttpResponse getHttpResponse();
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
Sat Jan 10 11:52:28 2009
@@ -48,11 +48,33 @@
  */
 public interface NHttpMessageParser {
     
+    /**
+     * Resets the parser. The parser will be ready to start parsing another 
+     * HTTP message.
+     */
     void reset();
     
+    /**
+     * Fills the internal buffer of the parser with input data from the 
+     * given {@link ReadableByteChannel}.
+     * 
+     * @param channel the input channel
+     * @return number of bytes read.
+     * @throws IOException in case of an I/O error.
+     */
     int fillBuffer(ReadableByteChannel channel) 
         throws IOException;    
 
+    /**
+     * Attempts to parse a complete message head from the content of the 
+     * internal buffer. If the message in the input buffer is incomplete
+     * this method will return <code>null</code>.  
+     * 
+     * @return HTTP message head, if available, <code>null</code> otherwise.
+     * @throws IOException in case of an I/O error.
+     * @throws HttpException in case the HTTP message is malformed or
+     *  violates the HTTP protocol.
+     */
     HttpMessage parse()
         throws IOException, HttpException;
 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
Sat Jan 10 11:52:28 2009
@@ -47,8 +47,20 @@
  */
 public interface NHttpMessageWriter {
     
+    /**
+     * Resets the writer. The writer will be ready to start serializing another 
+     * HTTP message.
+     */
     void reset();
     
+    /**
+     * Serializes out the HTTP message head.
+     * 
+     * @param message HTTP message.
+     * @throws IOException in case of an I/O error.
+     * @throws HttpException in case the HTTP message is malformed or
+     *  violates the HTTP protocol.
+     */
     void write(HttpMessage message)
         throws IOException, HttpException;
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
Sat Jan 10 11:52:28 2009
@@ -37,15 +37,19 @@
 import org.apache.http.HttpResponse;
 
 /**
- * Abstract non-blocking server-side HTTP connection. It can be used to
- * receive HTTP requests and asynchronously submit HTTP responses. 
+ * Abstract non-blocking server-side HTTP connection interface. It can be used 
+ * to receive HTTP requests and asynchronously submit HTTP responses. 
+ * 
+ * @see NHttpConnection
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ * 
+ * @version $Revision$
  */
 public interface NHttpServerConnection extends NHttpConnection {
 
     /**
-     * Submits the HTTP response to the client.
+     * Submits {link @HttpResponse} to be sent to the client.
      *  
      * @param response HTTP response
      * 
@@ -55,11 +59,11 @@
     void submitResponse(HttpResponse response) throws IOException, HttpException;
 
     /**
-     * Returns <tt>true</tt> if an HTTP response has been submitted to the 
+     * Returns <code>true</code> if an HTTP response has been submitted to the

      * client.
      * 
-     * @return <tt>true</tt> if an HTTP response has been submitted, 
-     * <tt>false</tt> otherwise. 
+     * @return <code>true</code> if an HTTP response has been submitted, 
+     * <code>false</code> otherwise. 
      */
     boolean isResponseSubmitted();
     

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
Sat Jan 10 11:52:28 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -34,8 +34,9 @@
 import org.apache.http.nio.reactor.IOEventDispatch;
 
 /**
- * Extended version of the {@link NHttpServerConnection} used by {@link IOEventDispatch}
- * implementations to inform server-side connection objects of I/O events.
+ * Extended version of the {@link NHttpServerConnection} used by 
+ * {@link IOEventDispatch} implementations to inform server-side connection 
+ * objects of I/O events.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  */

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java
(original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java
Sat Jan 10 11:52:28 2009
@@ -36,9 +36,11 @@
 import org.apache.http.HttpException;
 
 /**
- * Abstract server-side HTTP event handler.   
+ * Abstract server-side HTTP protocol handler.   
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
  */
 public interface NHttpServiceHandler {
 
@@ -71,11 +73,12 @@
      * content decoder. 
      * <p/>
      * If the content consumer is unable to process the incoming content,
-     * input event notifications can be temorarily suspended using 
-     * {@link NHttpConnection#suspendInput()}.
+     * input event notifications can be temporarily suspended using 
+     * {@link IOControl} interface.
      * 
-     * @see NHttpConnection
+     * @see NHttpServerConnection
      * @see ContentDecoder
+     * @see IOControl
      *  
      * @param conn HTTP connection that can produce a new portion of the
      * incoming request content.
@@ -84,7 +87,9 @@
     void inputReady(NHttpServerConnection conn, ContentDecoder decoder);
     
     /**
-     * Triggered when the connection is ready to send an HTTP response.
+     * Triggered when the connection is ready to accept a new HTTP response. 
+     * The protocol handler does not have to submit a response if it is not 
+     * ready.
      * 
      * @see NHttpServerConnection
      * 
@@ -98,11 +103,12 @@
      * content encoder. 
      * <p/>
      * If the content producer is unable to generate the outgoing content,
-     * output event notifications can be temorarily suspended using 
-     * {@link NHttpConnection#suspendOutput()}.
+     * output event notifications can be temporarily suspended using 
+     * {@link IOControl} interface.
      * 
-     * @see NHttpConnection
+     * @see NHttpServerConnection
      * @see ContentEncoder
+     * @see IOControl
      *  
      * @param conn HTTP connection that can accommodate a new portion 
      * of the outgoing response content.
@@ -111,7 +117,7 @@
     void outputReady(NHttpServerConnection conn, ContentEncoder encoder);
 
     /**
-     * Triggered when an I/O error occurrs while reading from or writing
+     * Triggered when an I/O error occurs while reading from or writing
      * to the underlying channel.
      * 
      * @param conn HTTP connection that caused an I/O error



Mime
View raw message