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/05 20:28:02 UTC
svn commit: r731653 - in /httpcomponents/httpcore/trunk:
module-main/src/main/java/org/apache/http/params/
module-main/src/main/java/org/apache/http/protocol/
module-nio/src/main/java/org/apache/http/nio/reactor/
Author: olegk
Date: Mon Jan 5 11:28:01 2009
New Revision: 731653
URL: http://svn.apache.org/viewvc?rev=731653&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParams.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParams.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParams.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParams.java Mon Jan 5 11:28:01 2009
@@ -50,7 +50,7 @@
* Obtains value of the {@link CoreConnectionPNames#SO_TIMEOUT} parameter.
* If not set, defaults to <code>0</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return SO_TIMEOUT.
*/
public static int getSoTimeout(final HttpParams params) {
@@ -63,8 +63,8 @@
/**
* Sets value of the {@link CoreConnectionPNames#SO_TIMEOUT} parameter.
*
- * @param HTTP parameters.
- * @param SO_TIMEOUT.
+ * @param params HTTP parameters.
+ * @param timeout SO_TIMEOUT.
*/
public static void setSoTimeout(final HttpParams params, int timeout) {
if (params == null) {
@@ -78,7 +78,7 @@
* Obtains value of the {@link CoreConnectionPNames#TCP_NODELAY} parameter.
* If not set, defaults to <code>true</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return Nagle's algorithm flag
*/
public static boolean getTcpNoDelay(final HttpParams params) {
@@ -92,8 +92,8 @@
/**
* Sets value of the {@link CoreConnectionPNames#TCP_NODELAY} parameter.
*
- * @param HTTP parameters.
- * @param Nagle's algorithm flag
+ * @param params HTTP parameters.
+ * @param value Nagle's algorithm flag
*/
public static void setTcpNoDelay(final HttpParams params, boolean value) {
if (params == null) {
@@ -106,7 +106,7 @@
* Obtains value of the {@link CoreConnectionPNames#SOCKET_BUFFER_SIZE}
* parameter. If not set, defaults to <code>-1</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return socket buffer size
*/
public static int getSocketBufferSize(final HttpParams params) {
@@ -121,8 +121,8 @@
* Sets value of the {@link CoreConnectionPNames#SOCKET_BUFFER_SIZE}
* parameter.
*
- * @param HTTP parameters.
- * @param socket buffer size
+ * @param params HTTP parameters.
+ * @param size socket buffer size
*/
public static void setSocketBufferSize(final HttpParams params, int size) {
if (params == null) {
@@ -135,7 +135,7 @@
* Obtains value of the {@link CoreConnectionPNames#SO_LINGER} parameter.
* If not set, defaults to <code>-1</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return SO_LINGER.
*/
public static int getLinger(final HttpParams params) {
@@ -148,8 +148,8 @@
/**
* Sets value of the {@link CoreConnectionPNames#SO_LINGER} parameter.
*
- * @param HTTP parameters.
- * @param SO_LINGER.
+ * @param params HTTP parameters.
+ * @param value SO_LINGER.
*/
public static void setLinger(final HttpParams params, int value) {
if (params == null) {
@@ -162,7 +162,7 @@
* Obtains value of the {@link CoreConnectionPNames#CONNECTION_TIMEOUT}
* parameter. If not set, defaults to <code>0</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return connect timeout.
*/
public static int getConnectionTimeout(final HttpParams params) {
@@ -177,8 +177,8 @@
* Sets value of the {@link CoreConnectionPNames#CONNECTION_TIMEOUT}
* parameter.
*
- * @param HTTP parameters.
- * @param connect timeout.
+ * @param params HTTP parameters.
+ * @param timeout connect timeout.
*/
public static void setConnectionTimeout(final HttpParams params, int timeout) {
if (params == null) {
@@ -192,7 +192,7 @@
* Obtains value of the {@link CoreConnectionPNames#STALE_CONNECTION_CHECK}
* parameter. If not set, defaults to <code>true</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return stale connection check flag.
*/
public static boolean isStaleCheckingEnabled(final HttpParams params) {
@@ -207,8 +207,8 @@
* Sets value of the {@link CoreConnectionPNames#STALE_CONNECTION_CHECK}
* parameter.
*
- * @param HTTP parameters.
- * @param stale connection check flag.
+ * @param params HTTP parameters.
+ * @param value stale connection check flag.
*/
public static void setStaleCheckingEnabled(final HttpParams params, boolean value) {
if (params == null) {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java Mon Jan 5 11:28:01 2009
@@ -56,7 +56,7 @@
* Obtains value of the {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET} parameter.
* If not set, defaults to <code>US-ASCII</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return HTTP element charset.
*/
public static String getHttpElementCharset(final HttpParams params) {
@@ -74,8 +74,8 @@
/**
* Sets value of the {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET} parameter.
*
- * @param HTTP parameters.
- * @param HTTP element charset.
+ * @param params HTTP parameters.
+ * @param charset HTTP element charset.
*/
public static void setHttpElementCharset(final HttpParams params, final String charset) {
if (params == null) {
@@ -88,7 +88,7 @@
* Obtains value of the {@link CoreProtocolPNames#HTTP_CONTENT_CHARSET} parameter.
* If not set, defaults to <code>ISO-8859-1</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return HTTP content charset.
*/
public static String getContentCharset(final HttpParams params) {
@@ -106,8 +106,8 @@
/**
* Sets value of the {@link CoreProtocolPNames#HTTP_CONTENT_CHARSET} parameter.
*
- * @param HTTP parameters.
- * @param HTTP content charset.
+ * @param params HTTP parameters.
+ * @param charset HTTP content charset.
*/
public static void setContentCharset(final HttpParams params, final String charset) {
if (params == null) {
@@ -120,7 +120,7 @@
* Obtains value of the {@link CoreProtocolPNames#PROTOCOL_VERSION} parameter.
* If not set, defaults to {@link HttpVersion#HTTP_1_1}.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return HTTP protocol version.
*/
public static ProtocolVersion getVersion(final HttpParams params) {
@@ -138,8 +138,8 @@
/**
* Sets value of the {@link CoreProtocolPNames#PROTOCOL_VERSION} parameter.
*
- * @param HTTP parameters.
- * @param HTTP protocol version.
+ * @param params HTTP parameters.
+ * @param version HTTP protocol version.
*/
public static void setVersion(final HttpParams params, final ProtocolVersion version) {
if (params == null) {
@@ -152,7 +152,7 @@
* Obtains value of the {@link CoreProtocolPNames#USER_AGENT} parameter.
* If not set, returns <code>null</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return User agent string.
*/
public static String getUserAgent(final HttpParams params) {
@@ -165,8 +165,8 @@
/**
* Sets value of the {@link CoreProtocolPNames#USER_AGENT} parameter.
*
- * @param HTTP parameters.
- * @param User agent string.
+ * @param params HTTP parameters.
+ * @param useragent User agent string.
*/
public static void setUserAgent(final HttpParams params, final String useragent) {
if (params == null) {
@@ -179,7 +179,7 @@
* Obtains value of the {@link CoreProtocolPNames#USE_EXPECT_CONTINUE} parameter.
* If not set, returns <code>false</code>.
*
- * @param HTTP parameters.
+ * @param params HTTP parameters.
* @return User agent string.
*/
public static boolean useExpectContinue(final HttpParams params) {
@@ -193,8 +193,8 @@
/**
* Sets value of the {@link CoreProtocolPNames#USE_EXPECT_CONTINUE} parameter.
*
- * @param HTTP parameters.
- * @param User agent string.
+ * @param params HTTP parameters.
+ * @param b expect-continue flag.
*/
public static void setUseExpectContinue(final HttpParams params, boolean b) {
if (params == null) {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java Mon Jan 5 11:28:01 2009
@@ -31,8 +31,6 @@
package org.apache.http.protocol;
-import org.apache.http.HttpConnection;
-
/**
* {@link HttpContext} attribute names for protocol execution.
*
@@ -45,32 +43,32 @@
public interface ExecutionContext {
/**
- * Attribute name of a {@link HttpConnection} object that represents
- * the actual HTTP connection.
+ * Attribute name of a {@link org.apache.http.HttpConnection} object that
+ * represents the actual HTTP connection.
*/
public static final String HTTP_CONNECTION = "http.connection";
/**
- * Attribute name of a {@link HttpRequest} object that represents
- * the actual HTTP request.
+ * Attribute name of a {@link org.apache.http.HttpRequest} object that
+ * represents the actual HTTP request.
*/
public static final String HTTP_REQUEST = "http.request";
/**
- * Attribute name of a {@link HttpResponse} object that represents the
- * actual HTTP response.
+ * Attribute name of a {@link org.apache.http.HttpResponse} object that
+ * represents the actual HTTP response.
*/
public static final String HTTP_RESPONSE = "http.response";
/**
- * Attribute name of a {@link HttpHost} object that represents the
- * connection target.
+ * Attribute name of a {@link org.apache.http.HttpHost} object that
+ * represents the connection target.
*/
public static final String HTTP_TARGET_HOST = "http.target_host";
/**
- * Attribute name of a {@link HttpHost} object that represents the
- * connection proxy.
+ * Attribute name of a {@link org.apache.http.HttpHost} object that
+ * represents the connection proxy.
*/
public static final String HTTP_PROXY_HOST = "http.proxy_host";
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/EventMask.java Mon Jan 5 11:28:01 2009
@@ -38,8 +38,19 @@
*/
public interface EventMask {
+ /**
+ * Interest in data input.
+ */
public static final int READ = SelectionKey.OP_READ;
+
+ /**
+ * Interest in data output.
+ */
public static final int WRITE = SelectionKey.OP_WRITE;
+
+ /**
+ * Interest in data input/output.
+ */
public static final int READ_WRITE = READ | WRITE;
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/IOSession.java Mon Jan 5 11:28:01 2009
@@ -45,6 +45,8 @@
* the context of the thread to store a session's state. All details about
* a particular session must be stored within the session itself, usually
* using execution context associated with it.
+ * <p>
+ * Implementations of this interface are expected to be threading safe.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -116,30 +118,126 @@
void clearEvent(int op);
/**
- * Closes the session and the underlying I/O channel.
+ * Terminates the session gracefully and closes the underlying I/O channel.
+ * This method ensures that session termination handshake, such as the one
+ * used by the SSL/TLS protocol, is correctly carried out.
*/
void close();
+ /**
+ * Terminates the session by shutting down the underlying I/O channel.
+ */
void shutdown();
+ /**
+ * Returns status of the session:
+ * <p>
+ * {@link #ACTIVE}: session is active.
+ * <p>
+ * {@link #CLOSING}: session is being closed.
+ * <p>
+ * {@link #CLOSED}: session has been terminated.
+ *
+ * @return session status.
+ */
int getStatus();
+ /**
+ * Determines if the session has been terminated.
+ *
+ * @return <code>true</code> if the session has been terminated,
+ * <code>false</code> otherwise.
+ */
boolean isClosed();
+ /**
+ * Returns value of the socket timeout in milliseconds. The value of
+ * <code>0</code> signifies the session cannot time out.
+ *
+ * @return socket timeout.
+ */
int getSocketTimeout();
+ /**
+ * Sets value of the socket timeout in milliseconds. The value of
+ * <code>0</code> signifies the session cannot time out.
+ *
+ * @param timeout socket timeout.
+ */
void setSocketTimeout(int timeout);
+ /**
+ * Quite often I/O sessions need to maintain internal I/O buffers in order
+ * to transform input / output data prior to returning it to the consumer or
+ * writing it to the underlying channel. Memory management in HttpCore NIO
+ * is based on the fundamental principle that the data consumer can read
+ * only as much input data as it can process without having to allocate more
+ * memory. That means, quite often some input data may remain unread in one
+ * of the internal or external session buffers. The I/O reactor can query
+ * the status of these session buffers, and make sure the consumer gets
+ * notified correctly as more data gets stored in one of the session
+ * buffers, thus allowing the consumer to read the remaining data once it
+ * is able to process it
+ * <p>
+ * I/O sessions can be made aware of the status of external session buffers
+ * using the {@link SessionBufferStatus} interface.
+ *
+ * @param status
+ */
void setBufferStatus(SessionBufferStatus status);
+ /**
+ * Determines if the input buffer associated with the session contains data.
+ *
+ * @return <code>true</code> if the session input buffer contains data,
+ * <code>false</code> otherwise.
+ */
boolean hasBufferedInput();
+ /**
+ * Determines if the output buffer associated with the session contains
+ * data.
+ *
+ * @return <code>true</code> if the session output buffer contains data,
+ * <code>false</code> otherwise.
+ */
boolean hasBufferedOutput();
+ /**
+ * This method can be used to associate a particular object with the
+ * session by the given attribute name.
+ * <p>
+ * I/O sessions are not bound to an execution thread, therefore one cannot
+ * use the context of the thread to store a session's state. All details
+ * about a particular session must be stored within the session itself.
+ *
+ * @param name name of the attribute.
+ * @param obj value of the attribute.
+ */
void setAttribute(String name, Object obj);
+ /**
+ * Returns the value of the attribute with the given name. The value can be
+ * <code>null</code> if not set.
+ * <p>
+ * The value of the session attachment object can be obtained using
+ * {@link #ATTACHMENT_KEY} name.
+ *
+ * @see #setAttribute(String, Object)
+ *
+ * @param name name of the attribute.
+ * @return value of the attribute.
+ */
Object getAttribute(String name);
+ /**
+ * Removes attribute with the given name.
+ *
+ * @see #setAttribute(String, Object)
+ *
+ * @param name name of the attribute to be removed.
+ * @return value of the removed attribute.
+ */
Object removeAttribute(String name);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionBufferStatus.java Mon Jan 5 11:28:01 2009
@@ -32,14 +32,27 @@
package org.apache.http.nio.reactor;
/**
- * Interface to query the status of session I/O buffers.
+ * SessionBufferStatus interface is intended to query the status of session
+ * I/O buffers.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*/
public interface SessionBufferStatus {
+ /**
+ * Determines if the session input buffer contains data.
+ *
+ * @return <code>true</code> if the session input buffer contains data,
+ * <code>false</code> otherwise.
+ */
boolean hasBufferedInput();
+ /**
+ * Determines if the session output buffer contains data.
+ *
+ * @return <code>true</code> if the session output buffer contains data,
+ * <code>false</code> otherwise.
+ */
boolean hasBufferedOutput();
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionInputBuffer.java Mon Jan 5 11:28:01 2009
@@ -40,7 +40,11 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Session input buffer for non-blocking connections.
+ * Session input buffer for non-blocking connections. This interface facilitates
+ * intermediate buffering of input data streamed from a source channel and
+ * reading buffered data to a destination, usually {@link ByteBuffer} or
+ * {@link WritableByteChannel}. This interface also provides methods for reading
+ * CR-LF delimited lines.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -48,26 +52,135 @@
*/
public interface SessionInputBuffer {
+ /**
+ * Determines if the buffer contains data.
+ *
+ * @return <code>true</code> if there is data in the buffer,
+ * <code>false</code> otherwise.
+ */
boolean hasData();
+ /**
+ * Returns the length of this buffer.
+ *
+ * @return buffer length.
+ */
int length();
- int fill(ReadableByteChannel channel)
- throws IOException;
-
+ /**
+ * Makes an attempt to fill the buffer with data from the given
+ * {@link ReadableByteChannel}.
+ *
+ * @param src the source channel
+ * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
+ * channel has reached end-of-stream.
+ * @throws IOException in case of an I/O error.
+ */
+ int fill(ReadableByteChannel src) throws IOException;
+
+ /**
+ * Reads one byte from the buffer. If the buffer is empty this method can
+ * throw a runtime exception. The exact type of runtime exception thrown
+ * by this method depends on implementation.
+ *
+ * @return one byte
+ */
int read();
+ /**
+ * Reads a sequence of bytes from this buffer into the destination buffer,
+ * up to the given maximum limit. The exact number of bytes transferred
+ * depends on availability of data in this buffer and capacity of the
+ * destination buffer, but cannot be more than <code>maxLen</code> value.
+ *
+ * @param dst the destination buffer.
+ * @param maxLen the maximum number of bytes to be read.
+ * @return The number of bytes read, possibly zero.
+ */
int read(ByteBuffer dst, int maxLen);
+ /**
+ * Reads a sequence of bytes from this buffer into the destination buffer.
+ * The exact number of bytes transferred depends on availability of data
+ * in this buffer and capacity of the destination buffer.
+ *
+ * @param dst the destination buffer.
+ * @return The number of bytes read, possibly zero.
+ */
int read(ByteBuffer dst);
+ /**
+ * Reads a sequence of bytes from this buffer into the destination channel,
+ * up to the given maximum limit. The exact number of bytes transferred
+ * depends on availability of data in this buffer, but cannot be more than
+ * <code>maxLen</code> value.
+ *
+ * @param dst the destination channel.
+ * @param maxLen the maximum number of bytes to be read.
+ * @return The number of bytes read, possibly zero.
+ * @throws IOException in case of an I/O error.
+ */
int read(WritableByteChannel dst, int maxLen) throws IOException;
+ /**
+ * Reads a sequence of bytes from this buffer into the destination channel.
+ * The exact number of bytes transferred depends on availability of data in
+ * this buffer.
+ *
+ * @param dst the destination channel.
+ * @return The number of bytes read, possibly zero.
+ * @throws IOException in case of an I/O error.
+ */
int read(WritableByteChannel dst) throws IOException;
- boolean readLine(CharArrayBuffer linebuffer, boolean endOfStream)
+ /**
+ * Attempts to transfer a complete line of characters up to a line delimiter
+ * from this buffer to the destination buffer. If a complete line is
+ * available in the buffer, the sequence of chars is transferred to the
+ * destination buffer the method returns <code>true</code>. The line
+ * delimiter itself is discarded. If a complete line is not available in
+ * the buffer, this method returns <code>false</code> without transferring
+ * anything to the destination buffer. If <code>endOfStream</code> parameter
+ * is set to <code>true</code> this method assumes the end of stream has
+ * been reached and the content currently stored in the buffer should be
+ * treated as a complete line.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param dst the destination buffer.
+ * @param endOfStream
+ * @return <code>true</code> if a sequence of chars representing a complete
+ * line has been transferred to the destination buffer, <code>false</code>
+ * otherwise.
+ *
+ * @throws CharacterCodingException in case a character encoding or decoding
+ * error occurs.
+ */
+ boolean readLine(CharArrayBuffer dst, boolean endOfStream)
throws CharacterCodingException;
+ /**
+ * Attempts to transfer a complete line of characters up to a line delimiter
+ * from this buffer to a newly created string. If a complete line is
+ * available in the buffer, the sequence of chars is transferred to a newly
+ * created string. The line delimiter itself is discarded. If a complete
+ * line is not available in the buffer, this method returns
+ * <code>null</code>. If <code>endOfStream</code> parameter
+ * is set to <code>true</code> this method assumes the end of stream has
+ * been reached and the content currently stored in the buffer should be
+ * treated as a complete line.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param endOfStream
+ * @return a string representing a complete line, if available.
+ * <code>null</code> otherwise.
+ *
+ * @throws CharacterCodingException in case a character encoding or decoding
+ * error occurs.
+ */
String readLine(boolean endOfStream)
throws CharacterCodingException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java?rev=731653&r1=731652&r2=731653&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/reactor/SessionOutputBuffer.java Mon Jan 5 11:28:01 2009
@@ -40,7 +40,11 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Session output buffer for non-blocking connections.
+ * Session output buffer for non-blocking connections. This interface
+ * facilitates intermediate buffering of output data streamed out to
+ * a destination channel and writing data to the buffer from a source, usually
+ * {@link ByteBuffer} or {@link ReadableByteChannel}. This interface also
+ * provides methods for writing CR-LF delimited lines.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*