hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r1202826 - /httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/
Date Wed, 16 Nov 2011 18:35:52 GMT
Author: olegk
Date: Wed Nov 16 18:35:52 2011
New Revision: 1202826

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

Modified:
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncRequestConsumer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncResponseConsumer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestConsumer.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/HttpAsyncResponseConsumer.java
    httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseProducer.java

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncRequestConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncRequestConsumer.java?rev=1202826&r1=1202825&r2=1202826&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncRequestConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncRequestConsumer.java
Wed Nov 16 18:35:52 2011
@@ -28,6 +28,7 @@ package org.apache.http.nio.protocol;
 
 import java.io.IOException;
 
+import org.apache.http.HttpEntityEnclosingRequest;
 import org.apache.http.HttpException;
 import org.apache.http.HttpRequest;
 import org.apache.http.annotation.ThreadSafe;
@@ -36,6 +37,10 @@ import org.apache.http.nio.IOControl;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Abstract {@link HttpAsyncRequestConsumer} implementation that relieves its
+ * subclasses form having to synchronize access to internal instance variables
+ * and provides a number of protected methods that they need to implement.
+ *
  * @since 4.2
  */
 @ThreadSafe
@@ -49,25 +54,69 @@ public abstract class AbstractAsyncReque
         super();
     }
 
+    /**
+     * Invoked when a HTTP request message is received. Please note
+     * that the {@link #onContentReceived(ContentDecoder, IOControl)} method
+     * will be invoked only for if the request message implements
+     * {@link HttpEntityEnclosingRequest} interface and has a content
+     * entity enclosed.
+     *
+     * @return HTTP request message.
+     * @throws HttpException in case of HTTP protocol violation
+     * @throws IOException in case of an I/O error
+     */
     protected abstract void onRequestReceived(HttpRequest request) throws HttpException,
IOException;
 
+    /**
+     * Invoked to process a chunk of content from the {@link ContentDecoder}.
+     * The {@link IOControl} interface can be used to suspend input events
+     * if the consumer is temporarily unable to consume more content.
+     * <p/>
+     * The consumer can use the {@link ContentDecoder#isCompleted()} method
+     * to find out whether or not the message content has been fully consumed.
+     *
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
+     * @throws IOException in case of an I/O error
+     */
     protected abstract void onContentReceived(
             ContentDecoder decoder, IOControl ioctrl) throws IOException;
 
+    /**
+     * Invoked to generate a result object from the received HTTP request
+     * message.
+     *
+     * @param context HTTP context.
+     * @return result of the request processing.
+     * @throws Exception in case of an abnormal termination.
+     */
     protected abstract T buildResult(HttpContext context) throws Exception;
 
+    /**
+     * Invoked to release all system resources currently allocated.
+     */
     protected abstract void releaseResources();
 
-    public synchronized void requestReceived(HttpRequest request) throws HttpException, IOException
{
+    /**
+     * Use {@link #onRequestReceived(HttpRequest)} instead.
+     */
+    public final synchronized void requestReceived(
+            final HttpRequest request) throws HttpException, IOException {
         onRequestReceived(request);
     }
 
-    public synchronized void consumeContent(
+    /**
+     * Use {@link #onContentReceived(ContentDecoder, IOControl) instead.
+     */
+    public final synchronized void consumeContent(
             final ContentDecoder decoder, final IOControl ioctrl) throws IOException {
         onContentReceived(decoder, ioctrl);
     }
 
-    public synchronized void requestCompleted(final HttpContext context) {
+    /**
+     * Use {@link #buildResult(HttpContext)} instead.
+     */
+    public final synchronized void requestCompleted(final HttpContext context) {
         if (this.completed) {
             return;
         }
@@ -81,7 +130,7 @@ public abstract class AbstractAsyncReque
         }
     }
 
-    public synchronized void close() throws IOException {
+    public final synchronized void close() throws IOException {
         if (this.completed) {
             return;
         }

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncResponseConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncResponseConsumer.java?rev=1202826&r1=1202825&r2=1202826&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncResponseConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/AbstractAsyncResponseConsumer.java
Wed Nov 16 18:35:52 2011
@@ -36,6 +36,10 @@ import org.apache.http.nio.IOControl;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Abstract {@link HttpAsyncResponseConsumer} implementation that relieves its
+ * subclasses form having to synchronize access to internal instance variables
+ * and provides a number of protected methods that they need to implement.
+ *
  * @since 4.2
  */
 @ThreadSafe
@@ -49,25 +53,68 @@ public abstract class AbstractAsyncRespo
         super();
     }
 
+    /**
+     * Invoked when a HTTP response message is received. Please note
+     * that the {@link #onContentReceived(ContentDecoder, IOControl)} method
+     * will be invoked only if the response messages has a content entity
+     * enclosed.
+     *
+     * @return HTTP response message.
+     * @throws HttpException in case of HTTP protocol violation
+     * @throws IOException in case of an I/O error
+     */
     protected abstract void onResponseReceived(final HttpResponse response) throws HttpException,
IOException;
 
+    /**
+     * Invoked to process a chunk of content from the {@link ContentDecoder}.
+     * The {@link IOControl} interface can be used to suspend input events
+     * if the consumer is temporarily unable to consume more content.
+     * <p/>
+     * The consumer can use the {@link ContentDecoder#isCompleted()} method
+     * to find out whether or not the message content has been fully consumed.
+     *
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
+     * @throws IOException in case of an I/O error
+     */
     protected abstract void onContentReceived(
             final ContentDecoder decoder, final IOControl ioctrl) throws IOException;
 
+    /**
+     * Invoked to generate a result object from the received HTTP response
+     * message.
+     *
+     * @param context HTTP context.
+     * @return result of the response processing.
+     * @throws Exception in case of an abnormal termination.
+     */
     protected abstract T buildResult(HttpContext context) throws Exception;
 
+    /**
+     * Invoked to release all system resources currently allocated.
+     */
     protected abstract void releaseResources();
 
-    public synchronized void responseReceived(final HttpResponse response) throws IOException,
HttpException {
+    /**
+     * Use {@link #onResponseReceived(HttpResponse) instead.
+     */
+    public final synchronized void responseReceived(
+            final HttpResponse response) throws IOException, HttpException {
         onResponseReceived(response);
     }
 
-    public synchronized void consumeContent(
+    /**
+     * Use {@link #onContentReceived(ContentDecoder, IOControl) instead.
+     */
+    public final synchronized void consumeContent(
             final ContentDecoder decoder, final IOControl ioctrl) throws IOException {
         onContentReceived(decoder, ioctrl);
     }
 
-    public synchronized void responseCompleted(final HttpContext context) {
+    /**
+     * Use {@link #buildResult(HttpContext)} instead.
+     */
+    public final synchronized void responseCompleted(final HttpContext context) {
         if (this.completed) {
             return;
         }
@@ -81,7 +128,7 @@ public abstract class AbstractAsyncRespo
         }
     }
 
-    public synchronized boolean cancel() {
+    public final synchronized boolean cancel() {
         if (this.completed) {
             return false;
         }
@@ -90,7 +137,7 @@ public abstract class AbstractAsyncRespo
         return true;
     }
 
-    public synchronized void failed(final Exception ex) {
+    public final synchronized void failed(final Exception ex) {
         if (this.completed) {
             return;
         }
@@ -99,7 +146,7 @@ public abstract class AbstractAsyncRespo
         releaseResources();
     }
 
-    public synchronized void close() {
+    public final synchronized void close() {
         if (this.completed) {
             return;
         }

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestConsumer.java?rev=1202826&r1=1202825&r2=1202826&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncRequestConsumer.java
Wed Nov 16 18:35:52 2011
@@ -29,6 +29,7 @@ package org.apache.http.nio.protocol;
 import java.io.Closeable;
 import java.io.IOException;
 
+import org.apache.http.HttpEntityEnclosingRequest;
 import org.apache.http.HttpException;
 import org.apache.http.HttpRequest;
 import org.apache.http.nio.ContentDecoder;
@@ -36,20 +37,71 @@ import org.apache.http.nio.IOControl;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncRequestConsumer</tt> is a callback interface whose methods
+ * get invoked to process an HTTP request message and to stream message
+ * content from a non-blocking HTTP connection through a {@link ContentDecoder}.
+ *
  * @since 4.2
  */
 public interface HttpAsyncRequestConsumer<T> extends Closeable {
 
+    /**
+     * Invoked when a HTTP request message is received. Please note
+     * that the {@link #consumeContent(ContentDecoder, IOControl)} method
+     * will be invoked only for if the request message implements
+     * {@link HttpEntityEnclosingRequest} interface and has a content
+     * entity enclosed.
+     *
+     * @return HTTP request message.
+     * @throws HttpException in case of HTTP protocol violation
+     * @throws IOException in case of an I/O error
+     */
     void requestReceived(HttpRequest request) throws HttpException, IOException;
 
+    /**
+     * Invoked to process a chunk of content from the {@link ContentDecoder}.
+     * The {@link IOControl} interface can be used to suspend input events
+     * if the consumer is temporarily unable to consume more content.
+     * <p/>
+     * The consumer can use the {@link ContentDecoder#isCompleted()} method
+     * to find out whether or not the message content has been fully consumed.
+     *
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
+     * @throws IOException in case of an I/O error
+     */
     void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
 
+    /**
+     * Invoked to signal that the request has been fully processed.
+     *
+     * @param context HTTP context
+     */
     void requestCompleted(HttpContext context);
 
+    /**
+     * Returns an exception in case of an abnormal termination. This method
+     * returns <code>null</code> if the request execution is still ongoing
+     * or if it completed successfully.
+     *
+     * @see #isDone()
+     */
     Exception getException();
 
+    /**
+     * Returns a result of the request execution, when available. This method
+     * returns <code>null</code> if the request execution is still ongoing.
+     *
+     * @see #isDone()
+     */
     T getResult();
 
+    /**
+     * Determines whether or not the request execution completed. If the
+     * request processing terminated normally {@link #getResult()}
+     * can be used to obtain the result. If the request processing terminated
+     * abnormally {@link #getException()} can be used to obtain the cause.
+     */
     boolean isDone();
 
 }

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=1202826&r1=1202825&r2=1202826&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 Nov 16 18:35:52 2011
@@ -39,9 +39,9 @@ import org.apache.http.protocol.HttpCont
 
 /**
  * <tt>HttpAsyncRequestProducer</tt> is a callback interface whose methods
- * get invoked to generate an HTTP request message and to stream out message
+ * get invoked to generate an HTTP request message and to stream message
  * content to a non-blocking HTTP connection through a {@link ContentEncoder}.
- * <p>
+ * <p/>
  * Repeatable request producers capable of generating the same request
  * message more than once can be reset to their initial state by calling
  * the {@link #resetRequest()} method, at which point request producers are
@@ -73,8 +73,8 @@ public interface HttpAsyncRequestProduce
     /**
      * Invoked to write out a chunk of content to the {@link ContentEncoder}.
      * The {@link IOControl} interface can be used to suspend output events
-     * if the entity is temporarily unable to produce more content.
-     * <p>
+     * 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.
      *

Modified: httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.java?rev=1202826&r1=1202825&r2=1202826&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.java
(original)
+++ httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.java
Wed Nov 16 18:35:52 2011
@@ -37,22 +37,77 @@ import org.apache.http.nio.IOControl;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncResponseConsumer</tt> is a callback interface whose methods
+ * get invoked to process an HTTP response message and to stream message
+ * content from a non-blocking HTTP connection through a {@link ContentDecoder}.
+ *
  * @since 4.2
  */
 public interface HttpAsyncResponseConsumer<T> extends Closeable, Cancellable {
 
+    /**
+     * Invoked when a HTTP response message is received. Please note
+     * that the {@link #consumeContent(ContentDecoder, IOControl)} method
+     * will be invoked only if the response messages has a content entity
+     * enclosed.
+     *
+     * @return HTTP response message.
+     * @throws HttpException in case of HTTP protocol violation
+     * @throws IOException in case of an I/O error
+     */
     void responseReceived(HttpResponse response) throws IOException, HttpException;
 
+    /**
+     * Invoked to process a chunk of content from the {@link ContentDecoder}.
+     * The {@link IOControl} interface can be used to suspend input events
+     * if the consumer is temporarily unable to consume more content.
+     * <p/>
+     * The consumer can use the {@link ContentDecoder#isCompleted()} method
+     * to find out whether or not the message content has been fully consumed.
+     *
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
+     * @throws IOException in case of an I/O error
+     */
     void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
 
+    /**
+     * Invoked to signal that the response has been fully processed.
+     *
+     * @param context HTTP context
+     */
     void responseCompleted(HttpContext context);
 
+    /**
+     * Invoked to signal that the response processing terminated abnormally.
+     *
+     * @param ex exception
+     */
     void failed(Exception ex);
 
-    T getResult();
-
+    /**
+     * Returns an exception in case of an abnormal termination. This method
+     * returns <code>null</code> if the response processing is still ongoing
+     * or if it completed successfully.
+     *
+     * @see #isDone()
+     */
     Exception getException();
 
+    /**
+     * Returns a result of the response processing, when available. This method
+     * returns <code>null</code> if response processing is still ongoing.
+     *
+     * @see #isDone()
+     */
+    T getResult();
+
+    /**
+     * Determines whether or not the response processing completed. If the
+     * response processing terminated normally {@link #getResult()}
+     * can be used to obtain the result. If the response processing terminated
+     * abnormally {@link #getException()} can be used to obtain the cause.
+     */
     boolean isDone();
 
 }

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=1202826&r1=1202825&r2=1202826&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 Nov 16 18:35:52 2011
@@ -30,20 +30,49 @@ package org.apache.http.nio.protocol;
 import java.io.Closeable;
 import java.io.IOException;
 
+import org.apache.http.HttpException;
 import org.apache.http.HttpResponse;
 import org.apache.http.nio.ContentEncoder;
 import org.apache.http.nio.IOControl;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * <tt>HttpAsyncResponseProducer</tt> is a callback interface whose methods
+ * get invoked to generate an HTTP response message and to stream message
+ * content to a non-blocking HTTP connection through a {@link ContentEncoder}.
+ *
  * @since 4.2
  */
 public interface HttpAsyncResponseProducer extends Closeable {
 
+    /**
+     * Invoked to generate a HTTP response message.
+     *
+     * @return HTTP response message.
+     * @throws HttpException in case of HTTP protocol violation
+     * @throws IOException in case of an I/O error
+     */
     HttpResponse generateResponse();
 
+    /**
+     * Invoked to write out a chunk of content to the {@link ContentEncoder}.
+     * 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.
+     *
+     * @param encoder content encoder.
+     * @param ioctrl I/O control of the underlying connection.
+     * @throws IOException in case of an I/O error
+     */
     void produceContent(ContentEncoder encoder, IOControl ioctrl) throws IOException;
 
+    /**
+     * Invoked to signal that the response has been fully written out.
+     *
+     * @param context HTTP context
+     */
     void responseCompleted(HttpContext context);
 
 }



Mime
View raw message