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/11/16 19:35:52 UTC
svn commit: r1202826 -
/httpcomponents/httpcore/trunk/httpcore-nio/src/main/java/org/apache/http/nio/protocol/
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);
}