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/19 18:43:54 UTC
svn commit: r728079 - in
/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http:
impl/io/ io/ util/
Author: olegk
Date: Fri Dec 19 09:43:54 2008
New Revision: 728079
URL: http://svn.apache.org/viewvc?rev=728079&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageParser.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageWriter.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionInputBuffer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionOutputBuffer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestParser.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestWriter.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseParser.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseWriter.java
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
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/ByteArrayBuffer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/CharArrayBuffer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/EntityUtils.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/VersionInfo.java
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageParser.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageParser.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageParser.java Fri Dec 19 09:43:54 2008
@@ -48,7 +48,8 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Message parser base class.
+ * Abstract base class for HTTP message parsers that obtain input from
+ * an instance of {@link SessionInputBuffer}.
*
* @author Michael Becke
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
@@ -61,6 +62,27 @@
protected final LineParser lineParser;
+ /**
+ * Creates an instance of this class.
+ * <p>
+ * The following HTTP parameters affect the initialization:
+ * <p>
+ * {@link CoreConnectionPNames#MAX_HEADER_COUNT} parameter determines
+ * the maximum HTTP header count allowed. If set to a positive value,
+ * the number of HTTP headers received from the data stream exceeding
+ * this limit will cause an IOException. A negative or zero value will
+ * effectively disable the check. Per default the check is disabled.
+ * <p>
+ * {@link CoreConnectionPNames#MAX_LINE_LENGTH} parameter determines
+ * the maximum line length limit. If set to a positive value, any HTTP line
+ * exceeding this limit will cause an IOException. A negative or zero value
+ * will effectively disable the check the check. Per default the check is
+ * disabled.
+ *
+ * @param buffer the session input buffer.
+ * @param parser the line parser.
+ * @param params HTTP parameters.
+ */
public AbstractMessageParser(
final SessionInputBuffer buffer,
final LineParser parser,
@@ -88,13 +110,14 @@
* @param maxHeaderCount maximum number of headers allowed. If the number
* of headers received from the data stream exceeds maxCount value, an
* IOException will be thrown. Setting this parameter to a negative value
- * or zero will disable the check.
+ * or zero will disable the check.
* @param maxLineLen maximum number of characters for a header line,
- * including the continuation lines
+ * including the continuation lines. Setting this parameter to a negative
+ * value or zero will disable the check.
* @return array of HTTP headers
*
- * @throws HttpException
- * @throws IOException
+ * @throws IOException in case of an I/O error
+ * @throws HttpException in case of HTTP protocol violation
*/
public static Header[] parseHeaders(
final SessionInputBuffer inbuffer,
@@ -165,6 +188,20 @@
return headers;
}
+ /**
+ * Subclasses must override this method to generate an instance of
+ * {@link HttpMessage} based on the initial input from the session buffer.
+ * <p>
+ * Usually this method is expected to read just the very first line or
+ * the very first valid from the data stream and based on the input generate
+ * an appropriate instance of {@link HttpMessage}.
+ *
+ * @param sessionBuffer the session input buffer.
+ * @return HTTP message based on the input from the session buffer.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation.
+ * @throws ParseException in case of a parse error.
+ */
protected abstract HttpMessage parseHead(SessionInputBuffer sessionBuffer)
throws IOException, HttpException, ParseException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageWriter.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageWriter.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractMessageWriter.java Fri Dec 19 09:43:54 2008
@@ -44,12 +44,25 @@
import org.apache.http.params.HttpParams;
import org.apache.http.util.CharArrayBuffer;
+/**
+ * Abstract base class for HTTP message writers that serialize output to
+ * an instance of {@link SessionOutputBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ */
public abstract class AbstractMessageWriter implements HttpMessageWriter {
protected final SessionOutputBuffer sessionBuffer;
protected final CharArrayBuffer lineBuf;
protected final LineFormatter lineFormatter;
+ /**
+ * Creates an instance of AbstractMessageWriter.
+ *
+ * @param buffer the session output buffer.
+ * @param formatter the line formatter.
+ * @param params HTTP parameters.
+ */
public AbstractMessageWriter(final SessionOutputBuffer buffer,
final LineFormatter formatter,
final HttpParams params) {
@@ -63,9 +76,14 @@
formatter : BasicLineFormatter.DEFAULT;
}
- protected abstract void writeHeadLine(HttpMessage message)
- throws IOException
- ;
+ /**
+ * Subclasses must override this method to write out the first header line
+ * based on the {@link HttpMessage} passed as a parameter.
+ *
+ * @param message the message whose first line is to be written out.
+ * @throws IOException in case of an I/O error.
+ */
+ protected abstract void writeHeadLine(HttpMessage message) throws IOException;
public void write(
final HttpMessage message) throws IOException, HttpException {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionInputBuffer.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionInputBuffer.java Fri Dec 19 09:43:54 2008
@@ -37,6 +37,7 @@
import org.apache.http.io.SessionInputBuffer;
import org.apache.http.io.HttpTransportMetrics;
import org.apache.http.params.CoreConnectionPNames;
+import org.apache.http.params.CoreProtocolPNames;
import org.apache.http.params.HttpParams;
import org.apache.http.params.HttpProtocolParams;
import org.apache.http.protocol.HTTP;
@@ -44,11 +45,15 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Abstract base class for session input buffers that stream data
- * from a {@link InputStream}.
+ * Abstract base class for session input buffers that stream data from
+ * an arbitrary {@link InputStream}. This class buffers input data in
+ * an internal byte array for optimal input performance.
+ * <p>
+ * {@link #readLine(CharArrayBuffer)} and {@link #readLine()} methods of this
+ * class treat a lone LF as valid line delimiters in addition to CR-LF required
+ * by the HTTP specification.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
- *
*/
public abstract class AbstractSessionInputBuffer implements SessionInputBuffer {
@@ -65,6 +70,28 @@
private HttpTransportMetricsImpl metrics;
+ /**
+ * Initializes this session input buffer.
+ * <p>
+ * The following HTTP parameters affect the initialization:
+ * <p>
+ * The {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET}
+ * parameter determines the charset to be used for decoding HTTP lines. If
+ * not specified, <code>US-ASCII</code> will be used per default.
+ * <p>
+ * The {@link CoreConnectionPNames#MAX_LINE_LENGTH} parameter determines
+ * the maximum line length limit. If set to a positive value, any HTTP
+ * line exceeding this limit will cause an IOException. A negative or zero
+ * value will effectively disable the check. Per default the line length
+ * check is disabled.
+ *
+ * @param instream the source input stream.
+ * @param buffersize the size of the internal buffer.
+ * @param params HTTP parameters.
+ *
+ * @see CoreProtocolPNames#HTTP_ELEMENT_CHARSET
+ * @see CoreConnectionPNames#MAX_LINE_LENGTH
+ */
protected void init(final InputStream instream, int buffersize, final HttpParams params) {
if (instream == null) {
throw new IllegalArgumentException("Input stream may not be null");
@@ -161,6 +188,21 @@
return -1;
}
+ /**
+ * 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>
+ * This method treats a lone LF as a valid line delimiters in addition
+ * to CR-LF required by the HTTP specification.
+ *
+ * @param charbuffer the line buffer.
+ * @return one line of characters
+ * @exception IOException if an I/O error occurs.
+ */
public int readLine(final CharArrayBuffer charbuffer) throws IOException {
if (charbuffer == null) {
throw new IllegalArgumentException("Char array buffer may not be null");
@@ -204,6 +246,19 @@
return lineFromLineBuffer(charbuffer);
}
+ /**
+ * 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>
+ * This method treats a lone LF as a valid line delimiters in addition
+ * to CR-LF required by the HTTP specification.
+ *
+ * @return HTTP line as a string
+ * @exception IOException if an I/O error occurs.
+ */
private int lineFromLineBuffer(final CharArrayBuffer charbuffer)
throws IOException {
// discard LF if found
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionOutputBuffer.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/AbstractSessionOutputBuffer.java Fri Dec 19 09:43:54 2008
@@ -36,6 +36,7 @@
import org.apache.http.io.SessionOutputBuffer;
import org.apache.http.io.HttpTransportMetrics;
+import org.apache.http.params.CoreProtocolPNames;
import org.apache.http.params.HttpParams;
import org.apache.http.params.HttpProtocolParams;
import org.apache.http.protocol.HTTP;
@@ -43,11 +44,14 @@
import org.apache.http.util.CharArrayBuffer;
/**
- * Abstract base class for session output buffers that stream data
- * to an {@link OutputStream}.
+ * Abstract base class for session output buffers that stream data to
+ * an arbitrary {@link OutputStream}. This class buffers small chunks of
+ * output data in an internal byte array for optimal output performance.
+ * <p>
+ * {@link #writeLine(CharArrayBuffer)} and {@link #writeLine(String)} methods
+ * of this class use CR-LF as a line delimiter.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
- *
*/
public abstract class AbstractSessionOutputBuffer implements SessionOutputBuffer {
@@ -63,6 +67,21 @@
private HttpTransportMetricsImpl metrics;
+ /**
+ * Initializes this session output buffer.
+ * <p>
+ * The following HTTP parameters affect the initialization:
+ * <p>
+ * The {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET}
+ * parameter determines the charset to be used for encoding HTTP lines. If
+ * not specified, <code>US-ASCII</code> will be used per default.
+ *
+ * @param outstream the destination output stream.
+ * @param buffersize the size of the internal buffer.
+ * @param params HTTP parameters.
+ *
+ * @see CoreProtocolPNames#HTTP_ELEMENT_CHARSET
+ */
protected void init(final OutputStream outstream, int buffersize, final HttpParams params) {
if (outstream == null) {
throw new IllegalArgumentException("Input stream may not be null");
@@ -134,6 +153,15 @@
this.buffer.append(b);
}
+ /**
+ * Writes characters from the specified string followed by a line delimiter
+ * to this session buffer.
+ * <p>
+ * This method uses CR-LF as a line delimiter.
+ *
+ * @param s the line.
+ * @exception IOException if an I/O error occurs.
+ */
public void writeLine(final String s) throws IOException {
if (s == null) {
return;
@@ -144,6 +172,15 @@
write(CRLF);
}
+ /**
+ * Writes characters from the specified char array followed by a line
+ * delimiter to this session buffer.
+ * <p>
+ * This method uses CR-LF as a line delimiter.
+ *
+ * @param s the buffer containing chars of the line.
+ * @exception IOException if an I/O error occurs.
+ */
public void writeLine(final CharArrayBuffer s) throws IOException {
if (s == null) {
return;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestParser.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestParser.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestParser.java Fri Dec 19 09:43:54 2008
@@ -36,6 +36,7 @@
import org.apache.http.ConnectionClosedException;
import org.apache.http.HttpException;
import org.apache.http.HttpMessage;
+import org.apache.http.HttpRequest;
import org.apache.http.HttpRequestFactory;
import org.apache.http.RequestLine;
import org.apache.http.ParseException;
@@ -45,11 +46,24 @@
import org.apache.http.params.HttpParams;
import org.apache.http.util.CharArrayBuffer;
+/**
+ * HTTP request parser that obtain its input from an instance
+ * of {@link SessionInputBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ */
public class HttpRequestParser extends AbstractMessageParser {
private final HttpRequestFactory requestFactory;
private final CharArrayBuffer lineBuf;
+ /**
+ * @param buffer the session input buffer.
+ * @param parser the line parser.
+ * @param requestFactory the factory to use to create
+ * {@link HttpRequest}s.
+ * @param params HTTP parameters.
+ */
public HttpRequestParser(
final SessionInputBuffer buffer,
final LineParser parser,
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestWriter.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestWriter.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpRequestWriter.java Fri Dec 19 09:43:54 2008
@@ -38,8 +38,13 @@
import org.apache.http.io.SessionOutputBuffer;
import org.apache.http.message.LineFormatter;
import org.apache.http.params.HttpParams;
-import org.apache.http.util.CharArrayBuffer;
+/**
+ * HTTP request writer that serializes its output to an instance
+ * of {@link SessionOutputBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ */
public class HttpRequestWriter extends AbstractMessageWriter {
public HttpRequestWriter(final SessionOutputBuffer buffer,
@@ -51,9 +56,9 @@
protected void writeHeadLine(final HttpMessage message)
throws IOException {
- final CharArrayBuffer buffer = lineFormatter.formatRequestLine
- (this.lineBuf, ((HttpRequest) message).getRequestLine());
- this.sessionBuffer.writeLine(buffer);
+ lineFormatter.formatRequestLine(this.lineBuf,
+ ((HttpRequest) message).getRequestLine());
+ this.sessionBuffer.writeLine(this.lineBuf);
}
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseParser.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseParser.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseParser.java Fri Dec 19 09:43:54 2008
@@ -35,6 +35,7 @@
import org.apache.http.HttpException;
import org.apache.http.HttpMessage;
+import org.apache.http.HttpResponse;
import org.apache.http.HttpResponseFactory;
import org.apache.http.NoHttpResponseException;
import org.apache.http.StatusLine;
@@ -45,11 +46,24 @@
import org.apache.http.params.HttpParams;
import org.apache.http.util.CharArrayBuffer;
+/**
+ * HTTP response parser that obtain its input from an instance
+ * of {@link SessionInputBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ */
public class HttpResponseParser extends AbstractMessageParser {
private final HttpResponseFactory responseFactory;
private final CharArrayBuffer lineBuf;
+ /**
+ * @param buffer the session input buffer.
+ * @param parser the line parser.
+ * @param responseFactory the factory to use to create
+ * {@link HttpResponse}s.
+ * @param params HTTP parameters.
+ */
public HttpResponseParser(
final SessionInputBuffer buffer,
final LineParser parser,
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseWriter.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseWriter.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/io/HttpResponseWriter.java Fri Dec 19 09:43:54 2008
@@ -38,8 +38,13 @@
import org.apache.http.io.SessionOutputBuffer;
import org.apache.http.message.LineFormatter;
import org.apache.http.params.HttpParams;
-import org.apache.http.util.CharArrayBuffer;
+/**
+ * HTTP response writer that serializes its output to an instance
+ * of {@link SessionOutputBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ */
public class HttpResponseWriter extends AbstractMessageWriter {
public HttpResponseWriter(final SessionOutputBuffer buffer,
@@ -51,9 +56,9 @@
protected void writeHeadLine(final HttpMessage message)
throws IOException {
- final CharArrayBuffer buffer = lineFormatter.formatStatusLine
- (this.lineBuf, ((HttpResponse) message).getStatusLine());
- this.sessionBuffer.writeLine(buffer);
+ lineFormatter.formatStatusLine(this.lineBuf,
+ ((HttpResponse) message).getStatusLine());
+ this.sessionBuffer.writeLine(this.lineBuf);
}
}
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=728079&r1=728078&r2=728079&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 Fri Dec 19 09:43:54 2008
@@ -130,7 +130,8 @@
* <p>
* Implementing classes can choose a char encoding and a line delimiter
* as appropriate.
- *
+ *
+ * @return HTTP line as a string
* @exception IOException if an I/O error occurs.
*/
String readLine() throws IOException;
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=728079&r1=728078&r2=728079&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 Fri Dec 19 09:43:54 2008
@@ -102,7 +102,7 @@
* Implementing classes can choose a char encoding and a line delimiter
* as appropriate.
*
- * @param buffer the line.
+ * @param buffer the buffer containing chars of the line.
* @exception IOException if an I/O error occurs.
*/
void writeLine(CharArrayBuffer buffer) throws IOException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/ByteArrayBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/ByteArrayBuffer.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/ByteArrayBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/ByteArrayBuffer.java Fri Dec 19 09:43:54 2008
@@ -47,7 +47,8 @@
/**
* Creates an instance of {@link ByteArrayBuffer} with the given initial
- * capacity
+ * capacity.
+ *
* @param capacity the capacity
*/
public ByteArrayBuffer(int capacity) {
@@ -66,15 +67,15 @@
/**
* Appends <code>len</code> bytes to this buffer from the given source
- * array starting at index <code>offset</code>. The capacity of the buffer
- * is increased if necessary to accommodate all <code>len</code> bytes.
+ * array starting at index <code>off</code>. The capacity of the buffer
+ * is increased, if necessary, to accommodate all <code>len</code> bytes.
*
* @param b the bytes to be appended.
- * @param offset the index of the first byte to append.
+ * @param off the index of the first byte to append.
* @param len the number of bytes to append.
- * @throws IndexOutOfBoundsException if <code>offset</code> if out of
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
* range, <code>len</code> is negative, or
- * <code>offset</code> + <code>len</code> is out of range.
+ * <code>off</code> + <code>len</code> is out of range.
*/
public void append(final byte[] b, int off, int len) {
if (b == null) {
@@ -96,8 +97,8 @@
}
/**
- * Appends <code>b</code> bytes into this buffer. The capacity of the buffer
- * is increased if necessary to accommodate the additional byte.
+ * Appends <code>b</code> byte to this buffer. The capacity of the buffer
+ * is increased, if necessary, to accommodate the additional byte.
*
* @param b the byte to be appended.
*/
@@ -112,17 +113,17 @@
/**
* Appends <code>len</code> chars to this buffer from the given source
- * array starting at index <code>offset</code>. The capacity of the buffer
+ * array starting at index <code>off</code>. The capacity of the buffer
* is increased if necessary to accommodate all <code>len</code> chars.
* <p>
* The chars are converted to bytes using simple cast.
*
* @param b the chars to be appended.
- * @param offset the index of the first char to append.
+ * @param off the index of the first char to append.
* @param len the number of bytes to append.
- * @throws IndexOutOfBoundsException if <code>offset</code> if out of
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
* range, <code>len</code> is negative, or
- * <code>offset</code> + <code>len</code> is out of range.
+ * <code>off</code> + <code>len</code> is out of range.
*/
public void append(final char[] b, int off, int len) {
if (b == null) {
@@ -148,18 +149,18 @@
/**
* Appends <code>len</code> chars to this buffer from the given source
- * char array buffer starting at index <code>offset</code>. The capacity
+ * char array buffer starting at index <code>off</code>. The capacity
* of the buffer is increased if necessary to accommodate all
* <code>len</code> chars.
* <p>
* The chars are converted to bytes using simple cast.
*
* @param b the chars to be appended.
- * @param offset the index of the first char to append.
+ * @param off the index of the first char to append.
* @param len the number of bytes to append.
- * @throws IndexOutOfBoundsException if <code>offset</code> if out of
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
* range, <code>len</code> is negative, or
- * <code>offset</code> + <code>len</code> is out of range.
+ * <code>off</code> + <code>len</code> is out of range.
*/
public void append(final CharArrayBuffer b, int off, int len) {
if (b == null) {
@@ -193,7 +194,7 @@
* index. The index argument must be greater than or equal to
* <code>0</code>, and less than the length of this buffer.
*
- * @param index the index of the desired byte value.
+ * @param i the index of the desired byte value.
* @return the byte value at the specified index.
* @throws IndexOutOfBoundsException if <code>index</code> is
* negative or greater than or equal to {@link #length()}.
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/CharArrayBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/CharArrayBuffer.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/CharArrayBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/CharArrayBuffer.java Fri Dec 19 09:43:54 2008
@@ -47,6 +47,12 @@
private char[] buffer;
private int len;
+ /**
+ * Creates an instance of {@link CharArrayBuffer} with the given initial
+ * capacity.
+ *
+ * @param capacity the capacity
+ */
public CharArrayBuffer(int capacity) {
super();
if (capacity < 0) {
@@ -61,6 +67,18 @@
this.buffer = newbuffer;
}
+ /**
+ * Appends <code>len</code> chars to this buffer from the given source
+ * array starting at index <code>off</code>. The capacity of the buffer
+ * is increased, if necessary, to accommodate all <code>len</code> chars.
+ *
+ * @param b the chars to be appended.
+ * @param off the index of the first char to append.
+ * @param len the number of chars to append.
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>off</code> + <code>len</code> is out of range.
+ */
public void append(final char[] b, int off, int len) {
if (b == null) {
return;
@@ -80,6 +98,12 @@
this.len = newlen;
}
+ /**
+ * Appends chars of the given string to this buffer. The capacity of the
+ * buffer is increased, if necessary, to accommodate all chars.
+ *
+ * @param str the string.
+ */
public void append(String str) {
if (str == null) {
str = "null";
@@ -93,6 +117,19 @@
this.len = newlen;
}
+ /**
+ * Appends <code>len</code> chars to this buffer from the given source
+ * buffer starting at index <code>off</code>. The capacity of the
+ * destination buffer is increased, if necessary, to accommodate all
+ * <code>len</code> chars.
+ *
+ * @param b the source buffer to be appended.
+ * @param off the index of the first char to append.
+ * @param len the number of chars to append.
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>off</code> + <code>len</code> is out of range.
+ */
public void append(final CharArrayBuffer b, int off, int len) {
if (b == null) {
return;
@@ -100,6 +137,13 @@
append(b.buffer, off, len);
}
+ /**
+ * Appends all chars to this buffer from the given source buffer starting
+ * at index <code>0</code>. The capacity of the destination buffer is
+ * increased, if necessary, to accommodate all {@link #length()} chars.
+ *
+ * @param b the source buffer to be appended.
+ */
public void append(final CharArrayBuffer b) {
if (b == null) {
return;
@@ -107,6 +151,12 @@
append(b.buffer,0, b.len);
}
+ /**
+ * Appends <code>ch</code> char to this buffer. The capacity of the buffer
+ * is increased, if necessary, to accommodate the additional char.
+ *
+ * @param ch the char to be appended.
+ */
public void append(char ch) {
int newlen = this.len + 1;
if (newlen > this.buffer.length) {
@@ -116,6 +166,20 @@
this.len = newlen;
}
+ /**
+ * Appends <code>len</code> bytes to this buffer from the given source
+ * array starting at index <code>off</code>. The capacity of the buffer
+ * is increased, if necessary, to accommodate all <code>len</code> bytes.
+ * <p>
+ * The bytes are converted to chars using simple cast.
+ *
+ * @param b the bytes to be appended.
+ * @param off the index of the first byte to append.
+ * @param len the number of bytes to append.
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>off</code> + <code>len</code> is out of range.
+ */
public void append(final byte[] b, int off, int len) {
if (b == null) {
return;
@@ -133,15 +197,25 @@
expand(newlen);
}
for (int i1 = off, i2 = oldlen; i2 < newlen; i1++, i2++) {
- int ch = b[i1];
- if (ch < 0) {
- ch = 256 + ch;
- }
- this.buffer[i2] = (char) ch;
+ this.buffer[i2] = (char) (b[i1] & 0xff);
}
this.len = newlen;
}
+ /**
+ * Appends <code>len</code> bytes to this buffer from the given source
+ * array starting at index <code>off</code>. The capacity of the buffer
+ * is increased, if necessary, to accommodate all <code>len</code> bytes.
+ * <p>
+ * The bytes are converted to chars using simple cast.
+ *
+ * @param b the bytes to be appended.
+ * @param off the index of the first byte to append.
+ * @param len the number of bytes to append.
+ * @throws IndexOutOfBoundsException if <code>off</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>off</code> + <code>len</code> is out of range.
+ */
public void append(final ByteArrayBuffer b, int off, int len) {
if (b == null) {
return;
@@ -149,14 +223,29 @@
append(b.buffer(), off, len);
}
+ /**
+ * Appends chars of the textual representation of the given object to this
+ * buffer. The capacity of the buffer is increased, if necessary, to
+ * accommodate all chars.
+ *
+ * @param obj the object.
+ */
public void append(final Object obj) {
append(String.valueOf(obj));
}
+ /**
+ * Clears content of the buffer. The underlying char array is not resized.
+ */
public void clear() {
this.len = 0;
}
+ /**
+ * Converts the content of this buffer to an array of chars.
+ *
+ * @return char array
+ */
public char[] toCharArray() {
char[] b = new char[this.len];
if (this.len > 0) {
@@ -165,29 +254,77 @@
return b;
}
+ /**
+ * Returns the <code>char</code> value in this buffer at the specified
+ * index. The index argument must be greater than or equal to
+ * <code>0</code>, and less than the length of this buffer.
+ *
+ * @param i the index of the desired char value.
+ * @return the char value at the specified index.
+ * @throws IndexOutOfBoundsException if <code>index</code> is
+ * negative or greater than or equal to {@link #length()}.
+ */
public char charAt(int i) {
return this.buffer[i];
}
+ /**
+ * Returns reference to the underlying char array.
+ *
+ * @return the char array.
+ */
public char[] buffer() {
return this.buffer;
}
+ /**
+ * Returns the current capacity. The capacity is the amount of storage
+ * available for newly appended chars, beyond which an allocation will
+ * occur.
+ *
+ * @return the current capacity
+ */
public int capacity() {
return this.buffer.length;
}
+ /**
+ * Returns the length of the buffer (char count).
+ *
+ * @return the length of the buffer
+ */
public int length() {
return this.len;
}
+ /**
+ * Ensures that the capacity is at least equal to the specified minimum.
+ * If the current capacity is less than the argument, then a new internal
+ * array is allocated with greater capacity. If the <code>required</code>
+ * argument is non-positive, this method takes no action.
+ *
+ * @param required the minimum required capacity.
+ */
public void ensureCapacity(int required) {
+ if (required <= 0) {
+ return;
+ }
int available = this.buffer.length - this.len;
if (required > available) {
expand(this.len + required);
}
}
+ /**
+ * Sets the length of the buffer. The new length value is expected to be
+ * less than the current capacity and greater than or equal to
+ * <code>0</code>.
+ *
+ * @param len the new length
+ * @throws IndexOutOfBoundsException if the
+ * <code>len</code> argument is greater than the current
+ * capacity of the buffer or less than <code>0</code>.
+ */
public void setLength(int len) {
if (len < 0 || len > this.buffer.length) {
throw new IndexOutOfBoundsException();
@@ -195,14 +332,47 @@
this.len = len;
}
+ /**
+ * Returns <code>true</code> if this buffer is empty, that is, its
+ * {@link #length()} is equal to <code>0</code>.
+ * @return <code>true</code> if this buffer is empty, <code>false</code>
+ * otherwise.
+ */
public boolean isEmpty() {
return this.len == 0;
}
+ /**
+ * Returns <code>true</code> if this buffer is full, that is, its
+ * {@link #length()} is equal to its {@link #capacity()}.
+ * @return <code>true</code> if this buffer is full, <code>false</code>
+ * otherwise.
+ */
public boolean isFull() {
return this.len == this.buffer.length;
}
+ /**
+ * Returns the index within this buffer of the first occurrence of the
+ * specified character, starting the search at the specified
+ * <code>beginIndex</code> and finishing at <code>endIndex</code>.
+ * If no such character occurs in this buffer within the specified bounds,
+ * <code>-1</code> is returned.
+ * <p>
+ * There is no restriction on the value of <code>beginIndex</code> and
+ * <code>endIndex</code>. If <code>beginIndex</code> is negative,
+ * it has the same effect as if it were zero. If <code>endIndex</code> is
+ * greater than {@link #length()}, it has the same effect as if it were
+ * {@link #length()}. If the <code>beginIndex</code> is greater than
+ * the <code>endIndex</code>, <code>-1</code> is returned.
+ *
+ * @param ch the char to search for.
+ * @param beginIndex the index to start the search from.
+ * @param endIndex the index to finish the search at.
+ * @return the index of the first occurrence of the character in the buffer
+ * within the given bounds, or <code>-1</code> if the character does
+ * not occur.
+ */
public int indexOf(int ch, int beginIndex, int endIndex) {
if (beginIndex < 0) {
beginIndex = 0;
@@ -221,10 +391,34 @@
return -1;
}
+ /**
+ * Returns the index within this buffer of the first occurrence of the
+ * specified character, starting the search at <code>0</code> and finishing
+ * at {@link #length()}. If no such character occurs in this buffer within
+ * those bounds, <code>-1</code> is returned.
+ *
+ * @param ch the char to search for.
+ * @return the index of the first occurrence of the character in the
+ * buffer, or <code>-1</code> if the character does not occur.
+ */
public int indexOf(int ch) {
return indexOf(ch, 0, this.len);
}
+ /**
+ * Returns a substring of this buffer. The substring begins at the specified
+ * <code>beginIndex</code> and extends to the character at index
+ * <code>endIndex - 1</code>.
+ *
+ * @param beginIndex the beginning index, inclusive.
+ * @param endIndex the ending index, exclusive.
+ * @return the specified substring.
+ * @exception IndexOutOfBoundsException if the
+ * <code>beginIndex</code> is negative, or
+ * <code>endIndex</code> is larger than the length of this
+ * buffer, or <code>beginIndex</code> is larger than
+ * <code>endIndex</code>.
+ */
public String substring(int beginIndex, int endIndex) {
if (beginIndex < 0) {
throw new IndexOutOfBoundsException();
@@ -238,6 +432,22 @@
return new String(this.buffer, beginIndex, endIndex - beginIndex);
}
+ /**
+ * Returns a substring of this buffer with leading and trailing whitespace
+ * omitted. The substring begins with the first non-whitespace character
+ * from <code>beginIndex</code> and extends to the last
+ * non-whitespace character with the index lesser than
+ * <code>endIndex</code>.
+ *
+ * @param beginIndex the beginning index, inclusive.
+ * @param endIndex the ending index, exclusive.
+ * @return the specified substring.
+ * @exception IndexOutOfBoundsException if the
+ * <code>beginIndex</code> is negative, or
+ * <code>endIndex</code> is larger than the length of this
+ * buffer, or <code>beginIndex</code> is larger than
+ * <code>endIndex</code>.
+ */
public String substringTrimmed(int beginIndex, int endIndex) {
if (beginIndex < 0) {
throw new IndexOutOfBoundsException();
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/EntityUtils.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/EntityUtils.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/EntityUtils.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/EntityUtils.java Fri Dec 19 09:43:54 2008
@@ -126,7 +126,7 @@
*
* @param entity must not be null
* @param defaultCharset character set to be applied if none found in the entity
- * @return the entity content as a Stting
+ * @return the entity content as a String
* @throws ParseException if header elements cannot be parsed
* @throws IllegalArgumentException if entity is null or if content length > Integer.MAX_VALUE
* @throws IOException if an error occurs reading the input stream
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/VersionInfo.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/VersionInfo.java?rev=728079&r1=728078&r2=728079&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/VersionInfo.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/VersionInfo.java Fri Dec 19 09:43:54 2008
@@ -40,9 +40,6 @@
/**
* Provides access to version information for HTTP components.
- * Instances of this class provide version information for a single module
- * or informal unit, as explained
- * <a href="http://wiki.apache.org/jakarta-httpclient/HttpComponents">here</a>.
* Static methods are used to extract version information from property
* files that are automatically packaged with HTTP component release JARs.
* <br/>