svn commit: r718330 - in /httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol: AsyncNHttpServiceHandler.java NHttpResponseTrigger.java

[ol...@apache.org]

Author: olegk
Date: Mon Nov 17 11:24:24 2008
New Revision: 718330

URL: http://svn.apache.org/viewvc?rev=718330&view=rev
Log:
Updated javadocs

Modified:
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/AsyncNHttpServiceHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/AsyncNHttpServiceHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/AsyncNHttpServiceHandler.java?rev=718330&r1=718329&r2=718330&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/AsyncNHttpServiceHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/AsyncNHttpServiceHandler.java Mon Nov 17 11:24:24 2008
@@ -68,26 +68,32 @@
 import org.apache.http.util.EncodingUtils;
 
 /**
- * HTTP service handler implementation that works with
+ * Fully asynchronous HTTP service handler implementation that works with
  * {@link ConsumingNHttpEntity} and {@link ProducingNHttpEntity}. The contents
  * of HTTP headers are stored in memory, HTTP entities are streamed directly
  * from the entities to the underlying channel (and vice versa).
- * <p>
- * When using this, it is important to ensure that entities supplied for writing
- * implement ProducingNHttpEntity. Doing so will allow the entity to be written
- * out asynchronously. If entities supplied for writing do not implement
- * ProducingNHttpEntity, a delegate is added that buffers the entire contents in
- * memory. Additionally, the buffering might take place in the I/O thread, which
- * could cause I/O to block temporarily. For best results, ensure that all
- * entities set on {@link HttpResponse HttpResponses} from
- * {@link NHttpRequestHandler NHttpRequestHandlers} implement
- * ProducingNHttpEntity.
- * <p>
- * If incoming requests are entity requests, NHttpRequestHandlers are expected
- * to return a ConsumingNHttpEntity for reading the content. After the entity is
- * finished reading the data,
+ * <p/>
+ * When using class, it is important to ensure that entities supplied for writing
+ * implement {@link ProducingNHttpEntity}. Doing so will allow the entity to be 
+ * written out asynchronously. If entities supplied for writing do not implement
+ * {@link ProducingNHttpEntity}, a delegate is added that buffers the entire 
+ * contents in memory. Additionally, the buffering might take place in the I/O 
+ * thread, which could cause I/O to block temporarily. For best results, ensure 
+ * that all entities set on {@link HttpResponse}s from  
+ * {@link NHttpRequestHandler}s implement {@link ProducingNHttpEntity}.
+ * <p/>
+ * If incoming requests enclose a content entity, {@link NHttpRequestHandler}s 
+ * are expected to return a {@link ConsumingNHttpEntity} for reading the 
+ * content. After the entity is finished reading the data,
  * {@link NHttpRequestHandler#handle(HttpRequest, HttpResponse, NHttpResponseTrigger, HttpContext)}
  * is called to generate a response.
+ * <p/>
+ * Individual {@link NHttpRequestHandler} do not have to submit a response 
+ * immediately. They can defer transmission of the HTTP response back to the 
+ * client without blocking the I/O thread and to delegate the processing the 
+ * HTTP request to a worker thread. The worker thread in its turn can use an 
+ * instance of {@link NHttpResponseTrigger} passed as a parameter to submit 
+ * a response as at a later point of time once the response becomes available.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java?rev=718330&r1=718329&r2=718330&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java Mon Nov 17 11:24:24 2008
@@ -36,22 +36,32 @@
 import org.apache.http.HttpException;
 import org.apache.http.HttpResponse;
 
+/**
+ * Callback interface to submit HTTP responses asynchronously.
+ * <p/>
+ * The {@link NHttpRequestHandler#handle(org.apache.http.HttpRequest, HttpResponse, NHttpResponseTrigger, org.apache.http.protocol.HttpContext)} 
+ * method does not have to submit a response immediately. I can defer 
+ * transmittion of the HTTP response back to the client without blocking the 
+ * I/O thread by delegating the process of handling the HTTP request to a worker 
+ * thread. The worker thread in its turn can use the instance of 
+ * {@link NHttpResponseTrigger} passed as a parameter to submit a response as at
+ * a later point of time once the response becomes avaialble.
+ */
 public interface NHttpResponseTrigger {
 
     /**
-     * Submits a response for sending.
+     * Submits a response to be sent back to the client as a result of 
+     * processing of the request.
      */
     void submitResponse(HttpResponse response);
 
     /**
-     * Submits a protocol exception that was generated while
-     * processing a request.
+     * Reports a protocol exception thrown while processing the request.
      */
     void handleException(HttpException ex);
 
     /**
-     * Submits an IOException that was generated while
-     * processing a request.
+     * Report an IOException thrown while processing the request.
      */
     void handleException(IOException ex);