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 2009/01/10 20:52:29 UTC
svn commit: r733324 -
/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/
Author: olegk
Date: Sat Jan 10 11:52:28 2009
New Revision: 733324
URL: http://svn.apache.org/viewvc?rev=733324&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientConnection.java Sat Jan 10 11:52:28 2009
@@ -37,15 +37,19 @@
import org.apache.http.HttpRequest;
/**
- * Abstract non-blocking client-side HTTP connection. It can be used to
- * submit HTTP requests and asynchronously receive HTTP responses.
+ * Abstract non-blocking client-side HTTP connection interface. It can be used
+ * to submit HTTP requests and asynchronously receive HTTP responses.
+ *
+ * @see NHttpConnection
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
*/
public interface NHttpClientConnection extends NHttpConnection {
/**
- * Submits the HTTP request to the target server.
+ * Submits {@link HttpRequest} to be sent to the target server.
*
* @param request HTTP request
* @throws IOException if I/O error occurs while submitting the request
@@ -54,11 +58,11 @@
void submitRequest(HttpRequest request) throws IOException, HttpException;
/**
- * Returns <tt>true</tt> if an HTTP request has been submitted to the
+ * Returns <code>true</code> if an HTTP request has been submitted to the
* target server.
*
- * @return <tt>true</tt> if an HTTP request has been submitted,
- * <tt>false</tt> otherwise.
+ * @return <code>true</code> if an HTTP request has been submitted,
+ * <code>false</code> otherwise.
*/
boolean isRequestSubmitted();
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientHandler.java Sat Jan 10 11:52:28 2009
@@ -36,9 +36,11 @@
import org.apache.http.HttpException;
/**
- * Abstract client-side HTTP event handler.
+ * Abstract client-side HTTP protocol handler.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
*/
public interface NHttpClientHandler {
@@ -46,17 +48,18 @@
* Triggered when a new outgoing connection is created.
*
* @param conn new outgoing HTTP connection.
- * @param attachment an arbitrary object that was attached to the
- * session request
+ * @param attachment an object that was attached to the session request
*/
void connected(NHttpClientConnection conn, Object attachment);
/**
- * Triggered when the connection is ready to send an HTTP request.
+ * Triggered when the connection is ready to accept a new HTTP request.
+ * The protocol handler does not have to submit a request if it is not
+ * ready.
*
* @see NHttpClientConnection
*
- * @param conn HTTP connection that is ready to send an HTTP request
+ * @param conn HTTP connection that is ready to accept a new HTTP request.
*/
void requestReady(NHttpClientConnection conn);
@@ -66,7 +69,7 @@
* a valid HTTP response object.
* <p/>
* If the response received encloses a response entity this method will
- * be followed a series of
+ * be followed by a series of
* {@link #inputReady(NHttpClientConnection, ContentDecoder)} calls
* to transfer the response content.
*
@@ -82,11 +85,12 @@
* content decoder.
* <p/>
* If the content consumer is unable to process the incoming content,
- * input event notifications can be temorarily suspended using
- * {@link NHttpConnection#suspendInput()}.
+ * input event notifications can be temporarily suspended using
+ * {@link IOControl} interface.
*
- * @see NHttpConnection
+ * @see NHttpClientConnection
* @see ContentDecoder
+ * @see IOControl
*
* @param conn HTTP connection that can produce a new portion of the
* incoming response content.
@@ -95,16 +99,16 @@
void inputReady(NHttpClientConnection conn, ContentDecoder decoder);
/**
- * Triggered when the underlying channel is ready for writing a
- * next portion of the request entity through the corresponding
- * content encoder.
- * <p/>
- * If the content producer is unable to generate the outgoing content,
- * output event notifications can be temorarily suspended using
- * {@link NHttpConnection#suspendOutput()}.
+ * Triggered when the underlying channel is ready for writing a next portion
+ * of the request entity through the corresponding content encoder.
+ * <p>
+ * If the content producer is unable to generate the outgoing content,
+ * output event notifications can be temporarily suspended using
+ * {@link IOControl} interface.
*
- * @see NHttpConnection
+ * @see NHttpClientConnection
* @see ContentEncoder
+ * @see IOControl
*
* @param conn HTTP connection that can accommodate a new portion
* of the outgoing request content.
@@ -113,7 +117,7 @@
void outputReady(NHttpClientConnection conn, ContentEncoder encoder);
/**
- * Triggered when an I/O error occurrs while reading from or writing
+ * Triggered when an I/O error occurs while reading from or writing
* to the underlying channel.
*
* @param conn HTTP connection that caused an I/O error
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpClientIOTarget.java Sat Jan 10 11:52:28 2009
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -34,8 +34,9 @@
import org.apache.http.nio.reactor.IOEventDispatch;
/**
- * Extended version of the {@link NHttpClientConnection} used by {@link IOEventDispatch}
- * implementations to inform client-side connection objects of I/O events.
+ * Extended version of the {@link NHttpClientConnection} used by
+ * {@link IOEventDispatch} implementations to inform client-side connection
+ * objects of I/O events.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*/
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpConnection.java Sat Jan 10 11:52:28 2009
@@ -37,11 +37,22 @@
import org.apache.http.protocol.HttpContext;
/**
- * Abstract non-blocking HTTP connection interface. It contains the current
- * HTTP context, as well as the actual HTTP request and HTTP response objects
- * that are being received / transferred over this connection.
+ * Abstract non-blocking HTTP connection interface. Each connection contains an
+ * HTTP execution context, which can be used to maintain a processing state,
+ * as well as the actual {@link HttpRequest} and {@link HttpResponse} that are
+ * being transmitted over this connection. Both the request and
+ * the response objects can be <code>null</code> if there is no incoming or
+ * outgoing message currently being transferred.
+ * <p>
+ * Please note non-blocking HTTP connections are stateful and not thread safe.
+ * Input / output operations on non-blocking HTTP connections should be
+ * restricted to the dispatch events triggered by the I/O event dispatch thread.
+ * However, the {@link IOControl} interface is fully threading safe and can be
+ * manipulated from any thread.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
*/
public interface NHttpConnection extends HttpConnection, IOControl {
@@ -49,13 +60,24 @@
public static final int CLOSING = 1;
public static final int CLOSED = 2;
+ /**
+ * Returns status of the connection:
+ * <p>
+ * {@link #ACTIVE}: connection is active.
+ * <p>
+ * {@link #CLOSING}: connection is being closed.
+ * <p>
+ * {@link #CLOSED}: connection has been closed.
+ *
+ * @return connection status.
+ */
int getStatus();
/**
* Returns the current HTTP request if one is being received / transmitted.
- * Otherwise returns <tt>null</tt>.
+ * Otherwise returns <code>null</code>.
*
- * @return an HTTP request if available. Otherwise returns <tt>null</tt>.
+ * @return HTTP request, if available, <code>null</code> otherwise.
*/
HttpRequest getHttpRequest();
@@ -63,7 +85,7 @@
* Returns the current HTTP response if one is being received / transmitted.
* Otherwise returns <tt>null</tt>.
*
- * @return an HTTP response if available. Otherwise returns <tt>null</tt>.
+ * @return HTTP response, if available, <code>null</code> otherwise.
*/
HttpResponse getHttpResponse();
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageParser.java Sat Jan 10 11:52:28 2009
@@ -48,11 +48,33 @@
*/
public interface NHttpMessageParser {
+ /**
+ * Resets the parser. The parser will be ready to start parsing another
+ * HTTP message.
+ */
void reset();
+ /**
+ * Fills the internal buffer of the parser with input data from the
+ * given {@link ReadableByteChannel}.
+ *
+ * @param channel the input channel
+ * @return number of bytes read.
+ * @throws IOException in case of an I/O error.
+ */
int fillBuffer(ReadableByteChannel channel)
throws IOException;
+ /**
+ * Attempts to parse a complete message head from the content of the
+ * internal buffer. If the message in the input buffer is incomplete
+ * this method will return <code>null</code>.
+ *
+ * @return HTTP message head, if available, <code>null</code> otherwise.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case the HTTP message is malformed or
+ * violates the HTTP protocol.
+ */
HttpMessage parse()
throws IOException, HttpException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpMessageWriter.java Sat Jan 10 11:52:28 2009
@@ -47,8 +47,20 @@
*/
public interface NHttpMessageWriter {
+ /**
+ * Resets the writer. The writer will be ready to start serializing another
+ * HTTP message.
+ */
void reset();
+ /**
+ * Serializes out the HTTP message head.
+ *
+ * @param message HTTP message.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case the HTTP message is malformed or
+ * violates the HTTP protocol.
+ */
void write(HttpMessage message)
throws IOException, HttpException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerConnection.java Sat Jan 10 11:52:28 2009
@@ -37,15 +37,19 @@
import org.apache.http.HttpResponse;
/**
- * Abstract non-blocking server-side HTTP connection. It can be used to
- * receive HTTP requests and asynchronously submit HTTP responses.
+ * Abstract non-blocking server-side HTTP connection interface. It can be used
+ * to receive HTTP requests and asynchronously submit HTTP responses.
+ *
+ * @see NHttpConnection
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
*/
public interface NHttpServerConnection extends NHttpConnection {
/**
- * Submits the HTTP response to the client.
+ * Submits {link @HttpResponse} to be sent to the client.
*
* @param response HTTP response
*
@@ -55,11 +59,11 @@
void submitResponse(HttpResponse response) throws IOException, HttpException;
/**
- * Returns <tt>true</tt> if an HTTP response has been submitted to the
+ * Returns <code>true</code> if an HTTP response has been submitted to the
* client.
*
- * @return <tt>true</tt> if an HTTP response has been submitted,
- * <tt>false</tt> otherwise.
+ * @return <code>true</code> if an HTTP response has been submitted,
+ * <code>false</code> otherwise.
*/
boolean isResponseSubmitted();
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServerIOTarget.java Sat Jan 10 11:52:28 2009
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -34,8 +34,9 @@
import org.apache.http.nio.reactor.IOEventDispatch;
/**
- * Extended version of the {@link NHttpServerConnection} used by {@link IOEventDispatch}
- * implementations to inform server-side connection objects of I/O events.
+ * Extended version of the {@link NHttpServerConnection} used by
+ * {@link IOEventDispatch} implementations to inform server-side connection
+ * objects of I/O events.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*/
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java?rev=733324&r1=733323&r2=733324&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/NHttpServiceHandler.java Sat Jan 10 11:52:28 2009
@@ -36,9 +36,11 @@
import org.apache.http.HttpException;
/**
- * Abstract server-side HTTP event handler.
+ * Abstract server-side HTTP protocol handler.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
*/
public interface NHttpServiceHandler {
@@ -71,11 +73,12 @@
* content decoder.
* <p/>
* If the content consumer is unable to process the incoming content,
- * input event notifications can be temorarily suspended using
- * {@link NHttpConnection#suspendInput()}.
+ * input event notifications can be temporarily suspended using
+ * {@link IOControl} interface.
*
- * @see NHttpConnection
+ * @see NHttpServerConnection
* @see ContentDecoder
+ * @see IOControl
*
* @param conn HTTP connection that can produce a new portion of the
* incoming request content.
@@ -84,7 +87,9 @@
void inputReady(NHttpServerConnection conn, ContentDecoder decoder);
/**
- * Triggered when the connection is ready to send an HTTP response.
+ * Triggered when the connection is ready to accept a new HTTP response.
+ * The protocol handler does not have to submit a response if it is not
+ * ready.
*
* @see NHttpServerConnection
*
@@ -98,11 +103,12 @@
* content encoder.
* <p/>
* If the content producer is unable to generate the outgoing content,
- * output event notifications can be temorarily suspended using
- * {@link NHttpConnection#suspendOutput()}.
+ * output event notifications can be temporarily suspended using
+ * {@link IOControl} interface.
*
- * @see NHttpConnection
+ * @see NHttpServerConnection
* @see ContentEncoder
+ * @see IOControl
*
* @param conn HTTP connection that can accommodate a new portion
* of the outgoing response content.
@@ -111,7 +117,7 @@
void outputReady(NHttpServerConnection conn, ContentEncoder encoder);
/**
- * Triggered when an I/O error occurrs while reading from or writing
+ * Triggered when an I/O error occurs while reading from or writing
* to the underlying channel.
*
* @param conn HTTP connection that caused an I/O error