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 2011/12/21 17:26:38 UTC
svn commit: r1221788 - in
/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio:
entity/ protocol/
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><uri>*</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();