hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r1221788 - in /httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio: entity/ protocol/
Date Wed, 21 Dec 2011 16:26:38 GMT
Author: olegk
Date: Wed Dec 21 16:26:37 2011
New Revision: 1221788

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

Modified:
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/entity/HttpAsyncContentProducer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestConsumer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestProducer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseConsumer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseProducer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BufferingAsyncRequestHandler.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncClientProtocolHandler.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncExpectationVerifier.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutionHandler.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutor.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandler.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerRegistry.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerResolver.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestProducer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServerProtocolHandler.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServiceExchange.java

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/entity/HttpAsyncContentProducer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/entity/HttpAsyncContentProducer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/entity/HttpAsyncContentProducer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/entity/HttpAsyncContentProducer.java
Wed Dec 21 16:26:37 2011
@@ -47,8 +47,9 @@ public interface HttpAsyncContentProduce
      * The {@link IOControl} interface can be used to suspend output events
      * if the entity is temporarily unable to produce more content.
      * <p>
-     * When all content is finished, this <b>MUST</b> call {@link ContentEncoder#complete()}.
-     * Failure to do so could result in the entity never being written.
+     * When all content is finished, the producer <b>MUST</b> call 
+     * {@link ContentEncoder#complete()}. Failure to do so may cause the entity
+     * to be incorrectly delimited.
      *
      * @param encoder content encoder.
      * @param ioctrl I/O control of the underlying connection.

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestConsumer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestConsumer.java
Wed Dec 21 16:26:37 2011
@@ -41,6 +41,10 @@ import org.apache.http.nio.util.SimpleIn
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Basic implementation of {@link HttpAsyncRequestConsumer}. Please note that
+ * this consumer buffers request content in memory and should be used for
+ * relatively small request messages.
+ *
  * @since 4.2
  */
 @ThreadSafe

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestProducer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestProducer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestProducer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncRequestProducer.java
Wed Dec 21 16:26:37 2011
@@ -40,6 +40,13 @@ import org.apache.http.nio.entity.HttpAs
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Basic implementation of {@link HttpAsyncRequestProducer}. The producer
+ * can make use of the {@link HttpAsyncContentProducer} interface to
+ * efficiently stream out message content to the underlying non-blocking HTTP
+ * connection, if it is implemented by the enclosed {@link HttpEntity}.
+ *
+ * @see HttpAsyncContentProducer
+ *
  * @since 4.2
  */
 @ThreadSafe
@@ -49,6 +56,17 @@ public class BasicAsyncRequestProducer i
     private final HttpRequest request;
     private final HttpAsyncContentProducer producer;
 
+    /**
+     * Creates a producer that can be used to transmit the given request
+     * message. The given content producer will be used to stream out message
+     * content. Please note that the request message is expected to enclose
+     * an {@link HttpEntity} whose properties are consistent with the behavior
+     * of the content producer.
+     *
+     * @param target target host.
+     * @param request request message.
+     * @param producer request content producer.
+     */
     protected BasicAsyncRequestProducer(
             final HttpHost target,
             final HttpEntityEnclosingRequest request,
@@ -68,6 +86,14 @@ public class BasicAsyncRequestProducer i
         this.producer = producer;
     }
 
+    /**
+     * Creates a producer that can be used to transmit the given request
+     * message. If the request message encloses an {@link HttpEntity}
+     * it is also expected to implement {@link HttpAsyncContentProducer}.
+     *
+     * @param target target host.
+     * @param request request message.
+     */
     public BasicAsyncRequestProducer(final HttpHost target, final HttpRequest request) {
         if (target == null) {
             throw new IllegalArgumentException("HTTP host may not be null");

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseConsumer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseConsumer.java
Wed Dec 21 16:26:37 2011
@@ -40,6 +40,10 @@ import org.apache.http.nio.util.SimpleIn
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Basic implementation of {@link HttpAsyncResponseConsumer}. Please note that
+ * this consumer buffers response content in memory and should be used for
+ * relatively small response messages.
+ *
  * @since 4.2
  */
 @ThreadSafe

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseProducer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseProducer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseProducer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BasicAsyncResponseProducer.java
Wed Dec 21 16:26:37 2011
@@ -39,6 +39,13 @@ import org.apache.http.nio.entity.HttpAs
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Basic implementation of {@link HttpAsyncResponseProducer}. The producer
+ * can make use of the {@link HttpAsyncContentProducer} interface to
+ * efficiently stream out message content to the underlying non-blocking HTTP
+ * connection, if it is implemented by the enclosed {@link HttpEntity}.
+ *
+ * @see HttpAsyncContentProducer
+ *
  * @since 4.2
  */
 @ThreadSafe
@@ -47,6 +54,16 @@ public class BasicAsyncResponseProducer 
     private final HttpResponse response;
     private final HttpAsyncContentProducer producer;
 
+    /**
+     * Creates a producer that can be used to transmit the given response
+     * message. The given content producer will be used to stream out message
+     * content. Please note that the response message is expected to enclose
+     * an {@link HttpEntity} whose properties are consistent with the behavior
+     * of the content producer.
+     *
+     * @param response response message.
+     * @param producer response content producer.
+     */
     protected BasicAsyncResponseProducer(
             final HttpResponse response,
             final HttpAsyncContentProducer producer) {
@@ -61,6 +78,13 @@ public class BasicAsyncResponseProducer 
         this.producer = producer;
     }
 
+    /**
+     * Creates a producer that can be used to transmit the given response
+     * message. If the response message encloses an {@link HttpEntity}
+     * it is also expected to implement {@link HttpAsyncContentProducer}.
+     *
+     * @param response response message.
+     */
     public BasicAsyncResponseProducer(final HttpResponse response) {
         super();
         if (response == null) {

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BufferingAsyncRequestHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BufferingAsyncRequestHandler.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BufferingAsyncRequestHandler.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/BufferingAsyncRequestHandler.java
Wed Dec 21 16:26:37 2011
@@ -36,6 +36,11 @@ import org.apache.http.protocol.HttpCont
 import org.apache.http.protocol.HttpRequestHandler;
 
 /**
+ * Basic implementation of {@link HttpAsyncRequestHandler} that delegates
+ * the process of request handling to a {@link HttpRequestHandler}. Please note
+ * that this handler buffers request content in memory and should be used for
+ * relatively small request messages.
+ *
  * @since 4.2
  */
 @Immutable

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncClientProtocolHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncClientProtocolHandler.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncClientProtocolHandler.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncClientProtocolHandler.java
Wed Dec 21 16:26:37 2011
@@ -43,10 +43,39 @@ import org.apache.http.nio.ContentEncode
 import org.apache.http.nio.NHttpClientConnection;
 import org.apache.http.nio.NHttpClientEventHandler;
 import org.apache.http.nio.NHttpConnection;
+import org.apache.http.nio.NHttpServerEventHandler;
 import org.apache.http.params.CoreProtocolPNames;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Fully asynchronous HTTP client side protocol handler that translates
+ * individual events fired through the {@link NHttpServerEventHandler}
+ * interface into logically related HTTP message exchanges.
+ * <p/>
+ * This handler is capable of processing HTTP requests with nearly constant
+ * memory footprint. Only HTTP message heads are stored in memory, while
+ * content of message bodies is streamed directly from the entity to
+ * the underlying channel (and vice versa) using
+ * {@link HttpAsyncRequestProducer} and {@link HttpAsyncResponseConsumer}
+ * interfaces.
+ * <p/>
+ * The protocol handler relies on the {@link HttpAsyncRequestExecutionHandler}
+ * interface to generate outgoing HTTP requests and to process incoming HTTP
+ * responses. The caller is expected to pass an instance of
+ * {@link HttpAsyncRequestExecutionHandler} to be used for the next series
+ * of HTTP message exchanges through the connection context using
+ * {@link #HTTP_HANDLER} attribute. HTTP exchange sequence is considered
+ * complete when the {@link HttpAsyncRequestExecutionHandler#isDone()}
+ * method returns <code>true</tt>.
+ * <p/>
+ * The following parameters can be used to customize the behavior of this
+ * class:
+ * <ul>
+ *  <li>{@link org.apache.http.params.CoreProtocolPNames#WAIT_FOR_CONTINUE}</li>
+ * </ul>
+ *
+ * @see HttpAsyncRequestExecutionHandler
+ *
  * @since 4.2
  */
 @Immutable

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncExpectationVerifier.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncExpectationVerifier.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncExpectationVerifier.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncExpectationVerifier.java
Wed Dec 21 16:26:37 2011
@@ -33,6 +33,16 @@ import org.apache.http.HttpException;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncExpectationVerifier</tt> defines a strategy to verify whether
+ * or not an incoming HTTP request meets the target server's expectations.
+ *<p/>
+ * A server that does not understand or is unable to comply with any of
+ * the expectation values in the Expect field of a request MUST respond
+ * with appropriate error status. The server MUST respond with a 417
+ * (Expectation Failed) status if any of the expectations cannot be met
+ * or, if there are other problems with the request, some other 4xx
+ * status.
+ *
  * @since 4.2
  */
 public interface HttpAsyncExpectationVerifier {

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutionHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutionHandler.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutionHandler.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutionHandler.java
Wed Dec 21 16:26:37 2011
@@ -31,12 +31,30 @@ import org.apache.http.ConnectionReuseSt
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncRequestExecutionHandler</tt> represents a callback interface
+ * that combines functionality of {@link HttpAsyncRequestProducer} and
+ * {@link HttpAsyncResponseConsumer} and is capable of handling logically
+ * related series of HTTP request / response exchanges.
+ *
  * @since 4.2
  */
-public interface HttpAsyncRequestExecutionHandler<T> extends HttpAsyncRequestProducer,
HttpAsyncResponseConsumer<T> {
+public interface HttpAsyncRequestExecutionHandler<T>
+    extends HttpAsyncRequestProducer, HttpAsyncResponseConsumer<T> {
 
+    /**
+     * Returns shared {@link HttpContext} instance.
+     *
+     * @return HTTP context
+     */
     HttpContext getContext();
 
+    /**
+     * Returns {@link ConnectionReuseStrategy} implementation that can be used
+     * to determine whether or not the underlying connection can be kept alive
+     * after a particular HTTP request / response exchange.
+     *
+     * @return connection re-use strategy.
+     */
     ConnectionReuseStrategy getConnectionReuseStrategy();
 
 }

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutor.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutor.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestExecutor.java
Wed Dec 21 16:26:37 2011
@@ -209,12 +209,12 @@ public class HttpAsyncRequestExecutor {
             try {
                 this.requestProducer.close();
             } catch (IOException ioex) {
-                onException(ioex);
+                log(ioex);
             }
             try {
                 this.responseConsumer.close();
             } catch (IOException ioex) {
-                onException(ioex);
+                log(ioex);
             }
         }
 
@@ -262,7 +262,7 @@ public class HttpAsyncRequestExecutor {
 
     }
 
-    protected void onException(Exception ex) {
+    protected void log(Exception ex) {
     }
 
 }

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandler.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandler.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandler.java
Wed Dec 21 16:26:37 2011
@@ -34,14 +34,54 @@ import org.apache.http.HttpRequest;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncRequestHandler</tt> represents a routine for asynchronous
+ * processing of a specific group of non-blocking HTTP requests. Protocol
+ * handlers are designed to take care of protocol specific aspects, whereas
+ * individual request handlers are expected to take care of application
+ * specific HTTP processing. The main purpose of a request handler is to
+ * generate a response object with a content entity to be sent back to
+ * the client in response to the given request
+ *
  * @since 4.2
  */
 public interface HttpAsyncRequestHandler<T> {
 
+    /**
+     * Triggered when an incoming request is received. This method should
+     * return a {@link HttpAsyncRequestConsumer} that will be used to process
+     * the request and consume message content if enclosed. The consumer
+     * can optionally parse or transform the message content into a structured
+     * object which is then passed onto
+     * the {@link #handle(Object, HttpAsyncServiceExchange, HttpContext))}
+     * method for further processing.
+     *
+     * @param request the entity enclosing request.
+     * @param context the execution context.
+     * @return request consumer.
+     * @throws IOException in case of an I/O error.
+     * @throws HttpException in case of HTTP protocol violation or a processing
+     *   problem.
+     */
     HttpAsyncRequestConsumer<T> processRequest(
             HttpRequest request,
             HttpContext context) throws HttpException, IOException;
 
+    /**
+     * Triggered to complete request processing and to initiate the process of
+     * generating a response. This method does not have to submit a response
+     * immediately. It can defer transmission of an HTTP response back to
+     * the client without blocking the I/O thread by delegating the process
+     * of request handling to another service or a worker thread. HTTP response
+     * can be submitted as a later a later point of time using
+     * {@link HttpAsyncServiceExchange} once response content becomes available.
+     *
+     * @param data request data returned by the request consumer.
+     * @param httpExchange HTTP exchange.
+     * @param context HTTP execution context.
+     * @throws IOException in case of an I/O error.
+     * @throws HttpException in case of HTTP protocol violation or a processing
+     *   problem.
+     */
     void handle(
             T data,
             HttpAsyncServiceExchange httpExchange,

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerRegistry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerRegistry.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerRegistry.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerRegistry.java
Wed Dec 21 16:26:37 2011
@@ -42,9 +42,9 @@ import org.apache.http.protocol.UriPatte
  *   <li><code>&lt;uri&gt;*</code></li>
  * </ul>
  * <br>
- * This class can be used to resolve an instance of {@link HttpAsyncRequestHandler} matching
- * a particular request URI. Usually the resolved request handler will be used to process
- * the request with the specified request URI.
+ * This class can be used to resolve an instance of {@link HttpAsyncRequestHandler}
+ * matching a particular request URI. Usually the resolved request handler
+ * will be used to process the request with the specified request URI.
  *
  * @since 4.2
  */

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerResolver.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerResolver.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerResolver.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestHandlerResolver.java
Wed Dec 21 16:26:37 2011
@@ -28,9 +28,10 @@
 package org.apache.http.nio.protocol;
 
 /**
- * HttpAsyncRequestHandlerResolver can be used to resolve an instance of
- * {@link HttpAsyncRequestHandler} matching a particular request URI. Usually the resolved
- * request handler will be used to process the request with the specified request URI.
+ * <tt>HttpAsyncRequestHandlerResolver</tt> can be used to resolve an instance
+ * of {@link HttpAsyncRequestHandler} matching a particular request URI.
+ * Usually the resolved request handler will be used to process the request
+ * with the specified request URI.
  *
  * @since 4.2
  */

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestProducer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestProducer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestProducer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestProducer.java
Wed Dec 21 16:26:37 2011
@@ -75,8 +75,9 @@ public interface HttpAsyncRequestProduce
      * The {@link IOControl} interface can be used to suspend output events
      * if the producer is temporarily unable to produce more content.
      * <p/>
-     * When all content is finished, this <b>MUST</b> call {@link ContentEncoder#complete()}.
-     * Failure to do so could result in the entity never being written.
+     * When all content is finished, the producer <b>MUST</b> call
+     * {@link ContentEncoder#complete()}. Failure to do so may cause the entity
+     * to be incorrectly delimited.
      *
      * @param encoder content encoder.
      * @param ioctrl I/O control of the underlying connection.

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java
Wed Dec 21 16:26:37 2011
@@ -59,8 +59,9 @@ public interface HttpAsyncResponseProduc
      * The {@link IOControl} interface can be used to suspend output events
      * if the producer is temporarily unable to produce more content.
      * <p/>
-     * When all content is finished, this <b>MUST</b> call {@link ContentEncoder#complete()}.
-     * Failure to do so could result in the entity never being written.
+     * When all content is finished, the producer <b>MUST</b> call
+     * {@link ContentEncoder#complete()}. Failure to do so may cause the entity
+     * to be incorrectly delimited.
      *
      * @param encoder content encoder.
      * @param ioctrl I/O control of the underlying connection.

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServerProtocolHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServerProtocolHandler.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServerProtocolHandler.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServerProtocolHandler.java
Wed Dec 21 16:26:37 2011
@@ -47,6 +47,7 @@ import org.apache.http.concurrent.Cancel
 import org.apache.http.impl.DefaultHttpResponseFactory;
 import org.apache.http.nio.ContentDecoder;
 import org.apache.http.nio.ContentEncoder;
+import org.apache.http.nio.NHttpClientEventHandler;
 import org.apache.http.nio.NHttpConnection;
 import org.apache.http.nio.NHttpServerConnection;
 import org.apache.http.nio.NHttpServerEventHandler;
@@ -59,6 +60,33 @@ import org.apache.http.protocol.HttpCont
 import org.apache.http.protocol.HttpProcessor;
 
 /**
+ * Fully asynchronous HTTP server side protocol handler that translates
+ * individual events fired through the {@link NHttpClientEventHandler}
+ * interface into logically related HTTP message exchanges.
+ * <p/>
+ * This handler is capable of executing HTTP requests with nearly constant
+ * memory footprint. Only HTTP message heads are stored in memory, while
+ * content of message bodies is streamed directly from the entity to
+ * the underlying channel (and vice versa) using
+ * {@link HttpAsyncRequestConsumer} and {@link HttpAsyncResponseProducer}
+ * interfaces.
+ * <p/>
+ * Once an incoming request is received the message is optionally verified
+ * for compliance with the server expectations using
+ * {@link HttpAsyncExpectationVerifier} if provided and then
+ * {@link HttpAsyncRequestHandlerResolver} interface is used to resolve
+ * the request URI to a particular {@link HttpAsyncRequestHandler} intended
+ * to handle the request. The protocol handler on the selected
+ * {@link HttpAsyncRequestHandler} instance to process the incoming request
+ * and to generate an outgoing response.
+ * <p/>
+ * Individual {@link HttpAsyncRequestHandler}s do not have to submit a response
+ * immediately. They can defer transmission of an HTTP response back to
+ * the client without blocking the I/O thread by delegating the process of
+ * request handling to another service or a worker thread. HTTP response can
+ * be submitted as a later a later point of time once response content becomes
+ * available.
+ *
  * @since 4.2
  */
 @Immutable // provided injected dependencies are immutable
@@ -73,6 +101,16 @@ public class HttpAsyncServerProtocolHand
     private final HttpAsyncExpectationVerifier expectationVerifier;
     private final HttpParams params;
 
+    /**
+     * Creates an instance of <tt>HttpAsyncServerProtocolHandler</tt>.
+     *
+     * @param httpProcessor HTTP protocol processor (required).
+     * @param connStrategy Connection re-use strategy (required).
+     * @param responseFactory HTTP response factory (required).
+     * @param handlerResolver Request handler resolver.
+     * @param expectationVerifier Request expectation verifier (optional).
+     * @param params HTTP parameters (required).
+     */
     public HttpAsyncServerProtocolHandler(
             final HttpProcessor httpProcessor,
             final ConnectionReuseStrategy connStrategy,
@@ -101,6 +139,14 @@ public class HttpAsyncServerProtocolHand
         this.params = params;
     }
 
+    /**
+     * Creates an instance of <tt>HttpAsyncServerProtocolHandler</tt>.
+     *
+     * @param httpProcessor HTTP protocol processor (required).
+     * @param connStrategy Connection re-use strategy (required).
+     * @param handlerResolver Request handler resolver.
+     * @param params HTTP parameters (required).
+     */
     public HttpAsyncServerProtocolHandler(
             final HttpProcessor httpProcessor,
             final ConnectionReuseStrategy connStrategy,
@@ -525,7 +571,7 @@ public class HttpAsyncServerProtocolHand
         private volatile HttpRequest request;
         private volatile HttpResponse response;
         private volatile Cancellable cancellable;
-        
+
         State() {
             super();
             this.context = new BasicHttpContext();
@@ -650,7 +696,7 @@ public class HttpAsyncServerProtocolHand
         private final NHttpServerConnection conn;
 
         private volatile boolean completed;
-        
+
         public Exchange(
                 final HttpRequest request,
                 final HttpResponse response,

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServiceExchange.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServiceExchange.java?rev=1221788&r1=1221787&r2=1221788&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServiceExchange.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncServiceExchange.java
Wed Dec 21 16:26:37 2011
@@ -41,7 +41,7 @@ public interface HttpAsyncServiceExchang
     HttpResponse getResponse();
 
     void setCallback(Cancellable cancellable);
-    
+
     void submitResponse(HttpAsyncResponseProducer responseProducer);
 
     void submitResponse();



Mime
View raw message