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 2008/12/17 23:13:59 UTC
svn commit: r727536 - in
/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io:
SessionInputBuffer.java SessionOutputBuffer.java
Author: olegk
Date: Wed Dec 17 14:13:59 2008
New Revision: 727536
URL: http://svn.apache.org/viewvc?rev=727536&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java?rev=727536&r1=727535&r2=727536&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionInputBuffer.java Wed Dec 17 14:13:59 2008
@@ -36,7 +36,12 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Session input buffer for blocking connections.
+ * Session input buffer for blocking connections. This interface is similar to
+ * InputStream class, but it also provides methods for reading CR-LF delimited
+ * lines.
+ * <p>
+ * Implementing classes are also expected to manage intermediate data buffering
+ * for optimal input performance.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -46,18 +51,107 @@
*/
public interface SessionInputBuffer {
+ /**
+ * Reads up to <code>len</code> bytes of data from the session buffer into
+ * an array of bytes. An attempt is made to read as many as
+ * <code>len</code> bytes, but a smaller number may be read, possibly
+ * zero. The number of bytes actually read is returned as an integer.
+ *
+ * <p> This method blocks until input data is available, end of file is
+ * detected, or an exception is thrown.
+ *
+ * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
+ * <code>off+len</code> is greater than the length of the array
+ * <code>b</code>, then an <code>IndexOutOfBoundsException</code> is
+ * thrown.
+ *
+ * @param b the buffer into which the data is read.
+ * @param off the start offset in array <code>b</code>
+ * at which the data is written.
+ * @param len the maximum number of bytes to read.
+ * @return the total number of bytes read into the buffer, or
+ * <code>-1</code> if there is no more data because the end of
+ * the stream has been reached.
+ * @exception IOException if an I/O error occurs.
+ */
int read(byte[] b, int off, int len) throws IOException;
+ /**
+ * Reads some number of bytes from the session buffer and stores them into
+ * the buffer array <code>b</code>. The number of bytes actually read is
+ * returned as an integer. This method blocks until input data is
+ * available, end of file is detected, or an exception is thrown.
+ *
+ * @param b the buffer into which the data is read.
+ * @return the total number of bytes read into the buffer, or
+ * <code>-1</code> is there is no more data because the end of
+ * the stream has been reached.
+ * @exception IOException if an I/O error occurs.
+ */
int read(byte[] b) throws IOException;
+ /**
+ * Reads the next byte of data from this session buffer. The value byte is
+ * returned as an <code>int</code> in the range <code>0</code> to
+ * <code>255</code>. If no byte is available because the end of the stream
+ * has been reached, the value <code>-1</code> is returned. This method
+ * blocks until input data is available, the end of the stream is detected,
+ * or an exception is thrown.
+ *
+ * @return the next byte of data, or <code>-1</code> if the end of the
+ * stream is reached.
+ * @exception IOException if an I/O error occurs.
+ */
int read() throws IOException;
+ /**
+ * Reads a complete line of characters up to a line delimiter from this
+ * session buffer into the given line buffer. The number of chars actually
+ * read is returned as an integer. The line delimiter itself is discarded.
+ * If no char is available because the end of the stream has been reached,
+ * the value <code>-1</code> is returned. This method blocks until input
+ * data is available, end of file is detected, or an exception is thrown.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param buffer the line buffer.
+ * @return one line of characters
+ * @exception IOException if an I/O error occurs.
+ */
int readLine(CharArrayBuffer buffer) throws IOException;
+ /**
+ * Reads a complete line of characters up to a line delimiter from this
+ * session buffer. The line delimiter itself is discarded. If no char is
+ * available because the end of the stream has been reached,
+ * <code>null</code> is returned. This method blocks until input data is
+ * available, end of file is detected, or an exception is thrown.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param buffer the line buffer.
+ * @exception IOException if an I/O error occurs.
+ */
String readLine() throws IOException;
+ /** Blocks until some data becomes available in the session buffer or the
+ * given timeout period in milliseconds elapses. If the timeout value is
+ * <code>0</code> this method blocks indefinitely.
+ *
+ * @param timeout in milliseconds.
+ * @return <code>true</code> if some data is available in the session
+ * buffer or <code>false</code> otherwise.
+ * @exception IOException if an I/O error occurs.
+ */
boolean isDataAvailable(int timeout) throws IOException;
+ /**
+ * Returns {@link HttpTransportMetrics} for this session buffer.
+ *
+ * @return transport metrics.
+ */
HttpTransportMetrics getMetrics();
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java?rev=727536&r1=727535&r2=727536&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/SessionOutputBuffer.java Wed Dec 17 14:13:59 2008
@@ -36,7 +36,12 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Session output buffer for blocking connections.
+ * Session output buffer for blocking connections. This interface is similar to
+ * OutputStream class, but it also provides methods for writing CR-LF delimited
+ * lines.
+ * <p>
+ * Implementing classes are also expected to manage intermediate data buffering
+ * for optimal output performance.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -46,18 +51,79 @@
*/
public interface SessionOutputBuffer {
+ /**
+ * Writes <code>len</code> bytes from the specified byte array
+ * starting at offset <code>off</code> to this session buffer.
+ * <p>
+ * If <code>off</code> is negative, or <code>len</code> is negative, or
+ * <code>off+len</code> is greater than the length of the array
+ * <code>b</code>, then an <tt>IndexOutOfBoundsException</tt> is thrown.
+ *
+ * @param b the data.
+ * @param off the start offset in the data.
+ * @param len the number of bytes to write.
+ * @exception IOException if an I/O error occurs.
+ */
void write(byte[] b, int off, int len) throws IOException;
+ /**
+ * Writes <code>b.length</code> bytes from the specified byte array
+ * to this session buffer.
+ *
+ * @param b the data.
+ * @exception IOException if an I/O error occurs.
+ */
void write(byte[] b) throws IOException;
+ /**
+ * Writes the specified byte to this session buffer.
+ *
+ * @param b the <code>byte</code>.
+ * @exception IOException if an I/O error occurs.
+ */
void write(int b) throws IOException;
+ /**
+ * Writes characters from the specified string followed by a line delimiter
+ * to this session buffer.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param s the line.
+ * @exception IOException if an I/O error occurs.
+ */
void writeLine(String s) throws IOException;
+ /**
+ * Writes characters from the specified char array followed by a line
+ * delimiter to this session buffer.
+ * <p>
+ * Implementing classes can choose a char encoding and a line delimiter
+ * as appropriate.
+ *
+ * @param buffer the line.
+ * @exception IOException if an I/O error occurs.
+ */
void writeLine(CharArrayBuffer buffer) throws IOException;
+ /**
+ * Flushes this session buffer and forces any buffered output bytes
+ * to be written out. The general contract of <code>flush</code> is
+ * that calling it is an indication that, if any bytes previously
+ * written have been buffered by the implementation of the output
+ * stream, such bytes should immediately be written to their
+ * intended destination.
+ *
+ * @exception IOException if an I/O error occurs.
+ */
void flush() throws IOException;
+ /**
+ * Returns {@link HttpTransportMetrics} for this session buffer.
+ *
+ * @return transport metrics.
+ */
HttpTransportMetrics getMetrics();
}