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/18 23:19:09 UTC
svn commit: r727839 - in /httpcomponents/httpcore/trunk: ./
module-main/src/main/java/org/apache/http/io/
module-main/src/main/java/org/apache/http/util/
Author: olegk
Date: Thu Dec 18 14:19:09 2008
New Revision: 727839
URL: http://svn.apache.org/viewvc?rev=727839&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageParser.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageWriter.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpTransportMetrics.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/package.html
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/EntityUtils.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/package.html
httpcomponents/httpcore/trunk/pom.xml
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageParser.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageParser.java?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageParser.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageParser.java Thu Dec 18 14:19:09 2008
@@ -37,7 +37,8 @@
import org.apache.http.HttpMessage;
/**
- * Generic message parser interface.
+ * Abstract message parser intended to build HTTP messages from an arbitrary
+ * data source.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -47,6 +48,14 @@
*/
public interface HttpMessageParser {
+ /**
+ * Generates an instance of {@link HttpMessage} from the underlying data
+ * source.
+ *
+ * @return HTTP message
+ * @throws IOException in case of an I/O error
+ * @throws HttpException in case of HTTP protocol violation
+ */
HttpMessage parse()
throws IOException, HttpException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageWriter.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageWriter.java?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageWriter.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpMessageWriter.java Thu Dec 18 14:19:09 2008
@@ -37,7 +37,8 @@
import org.apache.http.HttpMessage;
/**
- * Generic message writer interface.
+ * Abstract message writer intended to serialize HTTP messages to an arbitrary
+ * data sink.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -47,6 +48,14 @@
*/
public interface HttpMessageWriter {
+ /**
+ * Serializes an instance of {@link HttpMessage} to the underlying data
+ * sink.
+ *
+ * @param message
+ * @throws IOException in case of an I/O error
+ * @throws HttpException in case of HTTP protocol violation
+ */
void write(HttpMessage message)
throws IOException, HttpException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpTransportMetrics.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpTransportMetrics.java?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpTransportMetrics.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/HttpTransportMetrics.java Thu Dec 18 14:19:09 2008
@@ -31,10 +31,14 @@
package org.apache.http.io;
+/**
+ * The point of access to the statistics of {@link SessionInputBuffer} or
+ * {@link SessionOutputBuffer}.
+ */
public interface HttpTransportMetrics {
/**
- * Returns the number of bytes trasferred.
+ * Returns the number of bytes transferred.
*/
long getBytesTransferred();
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=727839&r1=727838&r2=727839&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 Thu Dec 18 14:19:09 2008
@@ -131,7 +131,6 @@
* 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;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/package.html?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/io/package.html Thu Dec 18 14:19:09 2008
@@ -34,14 +34,9 @@
-->
</head>
<body>
-The transport layer abstraction of the HTTP components.
-
-This layer is used to transfer messages over connections.
-Connections are typically based on sockets: plain or secure,
-direct or via SOCKS hosts, with bandwidth throttling, or
-whatever else you might think of.
-However, opening connections is not within the responsibility
-of HttpCore.
-
+The blocking I/O abstraction of the HTTP components.
+<p/>
+This layer defines interfaces for transferring basic elements of
+HTTP messages over connections.
</body>
</html>
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=727839&r1=727838&r2=727839&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 Thu Dec 18 14:19:09 2008
@@ -45,6 +45,11 @@
private byte[] buffer;
private int len;
+ /**
+ * Creates an instance of {@link ByteArrayBuffer} with the given initial
+ * capacity
+ * @param capacity the capacity
+ */
public ByteArrayBuffer(int capacity) {
super();
if (capacity < 0) {
@@ -58,7 +63,19 @@
System.arraycopy(this.buffer, 0, newbuffer, 0, this.len);
this.buffer = newbuffer;
}
-
+
+ /**
+ * 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.
+ *
+ * @param b the bytes to be appended.
+ * @param offset 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
+ * range, <code>len</code> is negative, or
+ * <code>offset</code> + <code>len</code> is out of range.
+ */
public void append(final byte[] b, int off, int len) {
if (b == null) {
return;
@@ -78,6 +95,12 @@
this.len = newlen;
}
+ /**
+ * Appends <code>b</code> bytes into this buffer. The capacity of the buffer
+ * is increased if necessary to accommodate the additional byte.
+ *
+ * @param b the byte to be appended.
+ */
public void append(int b) {
int newlen = this.len + 1;
if (newlen > this.buffer.length) {
@@ -87,6 +110,20 @@
this.len = newlen;
}
+ /**
+ * Appends <code>len</code> chars 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> 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 len the number of bytes to append.
+ * @throws IndexOutOfBoundsException if <code>offset</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>offset</code> + <code>len</code> is out of range.
+ */
public void append(final char[] b, int off, int len) {
if (b == null) {
return;
@@ -109,6 +146,21 @@
this.len = newlen;
}
+ /**
+ * Appends <code>len</code> chars to this buffer from the given source
+ * char array buffer starting at index <code>offset</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 len the number of bytes to append.
+ * @throws IndexOutOfBoundsException if <code>offset</code> if out of
+ * range, <code>len</code> is negative, or
+ * <code>offset</code> + <code>len</code> is out of range.
+ */
public void append(final CharArrayBuffer b, int off, int len) {
if (b == null) {
return;
@@ -116,10 +168,18 @@
append(b.buffer(), off, len);
}
+ /**
+ * Clears content of the buffer. The underlying byte array is not resized.
+ */
public void clear() {
this.len = 0;
}
-
+
+ /**
+ * Converts the content of this buffer to an array of bytes.
+ *
+ * @return byte array
+ */
public byte[] toByteArray() {
byte[] b = new byte[this.len];
if (this.len > 0) {
@@ -128,22 +188,59 @@
return b;
}
+ /**
+ * Returns the <code>byte</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 index 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()}.
+ */
public int byteAt(int i) {
return this.buffer[i];
}
+ /**
+ * Returns the current capacity. The capacity is the amount of storage
+ * available for newly appended bytes, beyond which an allocation
+ * will occur.
+ *
+ * @return the current capacity
+ */
public int capacity() {
return this.buffer.length;
}
+ /**
+ * Returns the length of the buffer (byte count).
+ *
+ * @return the length of the buffer
+ */
public int length() {
return this.len;
}
+ /**
+ * Returns reference to the underlying byte array.
+ *
+ * @return the byte array.
+ */
public byte[] buffer() {
return this.buffer;
}
+ /**
+ * 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();
@@ -151,10 +248,22 @@
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;
}
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=727839&r1=727838&r2=727839&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 Thu Dec 18 14:19:09 2008
@@ -43,7 +43,7 @@
import org.apache.http.protocol.HTTP;
/**
- * Static helpers for dealing with {@link HttpEntity entities}.
+ * Static helpers for dealing with {@link HttpEntity}s.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -53,7 +53,6 @@
*/
public final class EntityUtils {
- /** Disabled default constructor. */
private EntityUtils() {
}
@@ -94,7 +93,7 @@
}
/**
- * Get the character set from the entity.
+ * Obtains character set of the entity, if known.
*
* @param entity must not be null
* @return the character set, or null if not found
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/package.html?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/util/package.html Thu Dec 18 14:19:09 2008
@@ -34,12 +34,9 @@
-->
</head>
<body>
-Mostly utility classes with static helper methods for various purposes.
-
-The helper classes for resizable
+Resizable
{@link org.apache.http.util.ByteArrayBuffer byte} and
{@link org.apache.http.util.CharArrayBuffer char} arrays
-do not fall into this category.
-
+and various utility classes with static helper methods.
</body>
</html>
Modified: httpcomponents/httpcore/trunk/pom.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/pom.xml?rev=727839&r1=727838&r2=727839&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/pom.xml (original)
+++ httpcomponents/httpcore/trunk/pom.xml Thu Dec 18 14:19:09 2008
@@ -91,7 +91,11 @@
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
+ <source>1.5</source>
<aggregate>true</aggregate>
+ <links>
+ <link>http://java.sun.com/j2se/1.5.0/docs/api/</link>
+ </links>
</configuration>
</plugin>
<plugin>