hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject 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/
Date Thu, 18 Dec 2008 22:19:09 GMT
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>



Mime
View raw message