hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r729513 - in /httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http: impl/ impl/entity/ message/ params/
Date Fri, 26 Dec 2008 17:06:05 GMT
Author: olegk
Date: Fri Dec 26 09:06:04 2008
New Revision: 729513

URL: http://svn.apache.org/viewvc?rev=729513&view=rev
Log:
Javadoc updates

Modified:
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpClientConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpServerConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultConnectionReuseStrategy.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpClientConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpRequestFactory.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpResponseFactory.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpServerConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/EnglishReasonPhraseCatalog.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/HttpConnectionMetricsImpl.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpClientConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpServerConnection.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntityDeserializer.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntitySerializer.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/LaxContentLengthStrategy.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/StrictContentLengthStrategy.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/package.html
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/package.html
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/BasicHttpParams.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreConnectionPNames.java
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreProtocolPNames.java

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpClientConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpClientConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpClientConnection.java Fri Dec 26 09:06:04 2008
@@ -41,6 +41,7 @@
 import org.apache.http.HttpRequest;
 import org.apache.http.HttpResponse;
 import org.apache.http.HttpResponseFactory;
+import org.apache.http.entity.ContentLengthStrategy;
 import org.apache.http.impl.entity.EntityDeserializer;
 import org.apache.http.impl.entity.EntitySerializer;
 import org.apache.http.impl.entity.LaxContentLengthStrategy;
@@ -52,11 +53,14 @@
 import org.apache.http.io.HttpMessageWriter;
 import org.apache.http.io.SessionInputBuffer;
 import org.apache.http.io.SessionOutputBuffer;
+import org.apache.http.message.LineFormatter;
+import org.apache.http.message.LineParser;
 import org.apache.http.params.HttpParams;
 
 /**
- * Abstract client-side HTTP connection capable of transmitting and receiving data
- * using arbitrary {@link SessionInputBuffer} and {@link SessionOutputBuffer}
+ * Abstract client-side HTTP connection capable of transmitting and receiving 
+ * data using arbitrary {@link SessionInputBuffer} and 
+ * {@link SessionOutputBuffer} implementations.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -76,41 +80,126 @@
     private HttpMessageWriter requestWriter = null;
     private HttpConnectionMetricsImpl metrics = null;
 
+    /**
+     * Creates an instance of this class.
+     * <p>
+     * This constructor will invoke {@link #createEntityDeserializer()}
+     * and {@link #createEntitySerializer()} methods in order to initialize 
+     * HTTP entity serializer and deserializer implementations for this 
+     * connection. 
+     */
     public AbstractHttpClientConnection() {
         super();
         this.entityserializer = createEntitySerializer();
         this.entitydeserializer = createEntityDeserializer();
     }
     
+    /**
+     * Asserts if the connection is open.
+     * 
+     * @throws IllegalStateException if the connection is not open.
+     */
     protected abstract void assertOpen() throws IllegalStateException;
 
+    /**
+     * Creates an instance of {@link EntityDeserializer} with the 
+     * {@link LaxContentLengthStrategy} implementation to be used for 
+     * de-serializing entities received over this connection. 
+     * <p>
+     * This method can be overridden in super class in order to create instances 
+     * of {@link EntityDeserializer} using a custom 
+     * {@link ContentLengthStrategy}.
+     * 
+     * @return HTTP entity deserializer
+     */
     protected EntityDeserializer createEntityDeserializer() {
         return new EntityDeserializer(new LaxContentLengthStrategy());
     }
 
+    /**
+     * Creates an instance of {@link EntitySerializer} with the
+     * {@link StrictContentLengthStrategy} implementation to be used for
+     * serializing HTTP entities sent over this connection. 
+     * <p>
+     * This method can be overridden in super class in order to create instances 
+     * of {@link EntitySerializer} using a custom {@link ContentLengthStrategy}.
+     * 
+     * @return HTTP entity serialzier.
+     */
     protected EntitySerializer createEntitySerializer() {
         return new EntitySerializer(new StrictContentLengthStrategy());
     }
 
+    /**
+     * Creates an instance of {@link DefaultHttpResponseFactory} to be used 
+     * for creating {@link HttpResponse} objects received by over this 
+     * connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpResponseFactory} interface. 
+     * 
+     * @return HTTP response factory.
+     */
     protected HttpResponseFactory createHttpResponseFactory() {
         return new DefaultHttpResponseFactory();
     }
 
+    /**
+     * Creates an instance of {@link HttpMessageParser} to be used for parsing
+     * HTTP responses received over this connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpMessageParser} interface or
+     * to pass a different implementation of {@link LineParser} to the 
+     * the default implementation {@link HttpResponseParser}. 
+     * 
+     * @param buffer the session input buffer.
+     * @param responseFactory the HTTP response factory.
+     * @param params HTTP parameters.
+     * @return HTTP message parser.
+     */
     protected HttpMessageParser createResponseParser(
             final SessionInputBuffer buffer,
             final HttpResponseFactory responseFactory,
             final HttpParams params) {
-        // override in derived class to specify a line parser
         return new HttpResponseParser(buffer, null, responseFactory, params);
     }
 
+    /**
+     * Creates an instance of {@link HttpMessageWriter} to be used for 
+     * writing out HTTP requests sent over this connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpMessageWriter} interface or
+     * to pass a different implementation of {@link LineFormatter} to the 
+     * the default implementation {@link HttpRequestWriter}. 
+     * 
+     * @param buffer the session output buffer
+     * @param params HTTP parameters
+     * @return HTTP message writer
+     */
     protected HttpMessageWriter createRequestWriter(
             final SessionOutputBuffer buffer,
             final HttpParams params) {
-        // override in derived class to specify a line formatter
         return new HttpRequestWriter(buffer, null, params);
     }
 
+    /**
+     * Initializes this connection object with {@link SessionInputBuffer} and
+     * {@link SessionOutputBuffer} instances to be used for sending and 
+     * receiving data. These session buffers can be bound to any arbitrary 
+     * physical output medium. 
+     * <p>
+     * This method will invoke {@link #createHttpResponseFactory()},
+     * {@link #createRequestWriter(SessionOutputBuffer, HttpParams)}
+     * and {@link #createResponseParser(SessionInputBuffer, HttpResponseFactory, HttpParams)} 
+     * methods to initialize HTTP request writer and response parser for this
+     * connection. 
+     * 
+     * @param inbuffer the session input buffer.
+     * @param outbuffer the session output buffer.
+     * @param params HTTP parameters.
+     */
     protected void init(
             final SessionInputBuffer inbuffer,
             final SessionOutputBuffer outbuffer,

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpServerConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpServerConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpServerConnection.java Fri Dec 26 09:06:04 2008
@@ -41,6 +41,7 @@
 import org.apache.http.HttpRequestFactory;
 import org.apache.http.HttpResponse;
 import org.apache.http.HttpServerConnection;
+import org.apache.http.entity.ContentLengthStrategy;
 import org.apache.http.impl.entity.EntityDeserializer;
 import org.apache.http.impl.entity.EntitySerializer;
 import org.apache.http.impl.entity.LaxContentLengthStrategy;
@@ -52,11 +53,14 @@
 import org.apache.http.io.HttpMessageWriter;
 import org.apache.http.io.SessionInputBuffer;
 import org.apache.http.io.SessionOutputBuffer;
+import org.apache.http.message.LineFormatter;
+import org.apache.http.message.LineParser;
 import org.apache.http.params.HttpParams;
 
 /**
- * Abstract server-side HTTP connection capable of transmitting and receiving data
- * using arbitrary {@link SessionInputBuffer} and {@link SessionOutputBuffer}
+ * Abstract server-side HTTP connection capable of transmitting and receiving 
+ * data using arbitrary {@link SessionInputBuffer} and 
+ * {@link SessionOutputBuffer} implementations.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -76,42 +80,126 @@
     private HttpMessageWriter responseWriter = null;
     private HttpConnectionMetricsImpl metrics = null;
 
+    /**
+     * Creates an instance of this class.
+     * <p>
+     * This constructor will invoke {@link #createEntityDeserializer()}
+     * and {@link #createEntitySerializer()} methods in order to initialize 
+     * HTTP entity serializer and deserializer implementations for this 
+     * connection. 
+     */
     public AbstractHttpServerConnection() {
         super();
         this.entityserializer = createEntitySerializer();
         this.entitydeserializer = createEntityDeserializer();
     }
     
+    /**
+     * Asserts if the connection is open.
+     * 
+     * @throws IllegalStateException if the connection is not open.
+     */
     protected abstract void assertOpen() throws IllegalStateException;
 
+    /**
+     * Creates an instance of {@link EntityDeserializer} with the 
+     * {@link LaxContentLengthStrategy} implementation to be used for 
+     * de-serializing entities received over this connection. 
+     * <p>
+     * This method can be overridden in super class in order to create instances 
+     * of {@link EntityDeserializer} using a custom 
+     * {@link ContentLengthStrategy}.
+     * 
+     * @return HTTP entity deserializer
+     */
     protected EntityDeserializer createEntityDeserializer() {
         return new EntityDeserializer(new LaxContentLengthStrategy());
     }
 
+    /**
+     * Creates an instance of {@link EntitySerializer} with the
+     * {@link StrictContentLengthStrategy} implementation to be used for
+     * serializing HTTP entities sent over this connection. 
+     * <p>
+     * This method can be overridden in super class in order to create instances 
+     * of {@link EntitySerializer} using a custom {@link ContentLengthStrategy}.
+     * 
+     * @return HTTP entity serialzier.
+     */
     protected EntitySerializer createEntitySerializer() {
         return new EntitySerializer(new StrictContentLengthStrategy());
     }
 
+    /**
+     * Creates an instance of {@link DefaultHttpRequestFactory} to be used 
+     * for creating {@link HttpRequest} objects received by over this 
+     * connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpRequestFactory} interface. 
+     * 
+     * @return HTTP request factory.
+     */
     protected HttpRequestFactory createHttpRequestFactory() {
         return new DefaultHttpRequestFactory();
     }
 
+    /**
+     * Creates an instance of {@link HttpMessageParser} to be used for parsing
+     * HTTP requests received over this connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpMessageParser} interface or
+     * to pass a different implementation of {@link LineParser} to the 
+     * the default implementation {@link HttpRequestParser}. 
+     * 
+     * @param buffer the session input buffer.
+     * @param requestFactory the HTTP request factory.
+     * @param params HTTP parameters.
+     * @return HTTP message parser.
+     */
     protected HttpMessageParser createRequestParser(
             final SessionInputBuffer buffer,
             final HttpRequestFactory requestFactory,
             final HttpParams params) {
-        // override in derived class to specify a line parser
         return new HttpRequestParser(buffer, null, requestFactory, params);
     }
     
+    /**
+     * Creates an instance of {@link HttpMessageWriter} to be used for 
+     * writing out HTTP responses sent over this connection.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a different implementation of the {@link HttpMessageWriter} interface or
+     * to pass a different implementation of {@link LineFormatter} to the 
+     * the default implementation {@link HttpResponseWriter}. 
+     * 
+     * @param buffer the session output buffer
+     * @param params HTTP parameters
+     * @return HTTP message writer
+     */
     protected HttpMessageWriter createResponseWriter(
             final SessionOutputBuffer buffer,
             final HttpParams params) {
-        // override in derived class to specify a line formatter
         return new HttpResponseWriter(buffer, null, params);
     }
 
-
+    /**
+     * Initializes this connection object with {@link SessionInputBuffer} and
+     * {@link SessionOutputBuffer} instances to be used for sending and 
+     * receiving data. These session buffers can be bound to any arbitrary 
+     * physical output medium. 
+     * <p>
+     * This method will invoke {@link #createHttpRequestFactory},
+     * {@link #createRequestParser(SessionInputBuffer, HttpRequestFactory, HttpParams)}
+     * and {@link #createResponseWriter(SessionOutputBuffer, HttpParams)} 
+     * methods to initialize HTTP request parser and response writer for this
+     * connection. 
+     * 
+     * @param inbuffer the session input buffer.
+     * @param outbuffer the session output buffer.
+     * @param params HTTP parameters.
+     */
     protected void init(
             final SessionInputBuffer inbuffer,
             final SessionOutputBuffer outbuffer,

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultConnectionReuseStrategy.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultConnectionReuseStrategy.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultConnectionReuseStrategy.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultConnectionReuseStrategy.java Fri Dec 26 09:06:04 2008
@@ -50,15 +50,16 @@
  * The default implementation first checks some basics, for example
  * whether the connection is still open or whether the end of the
  * request entity can be determined without closing the connection.
- * If these checks pass, the tokens in the "Connection" header will
- * be examined. In the absence of a "Connection" header, the
- * non-standard but commonly used "Proxy-Connection" header takes
- * it's role. A token "close" indicates that the connection cannot
- * be reused. If there is no such token, a token "keep-alive" indicates
- * that the connection should be re-used. If neither token is found,
- * or if there are no "Connection" headers, the default policy for
- * the HTTP version is applied. Since HTTP/1.1, connections are re-used
- * by default. Up until HTTP/1.0, connections are not re-used by default.
+ * If these checks pass, the tokens in the <code>Connection</code> header will
+ * be examined. In the absence of a <code>Connection</code> header, the
+ * non-standard but commonly used <code>Proxy-Connection</code> header takes
+ * it's role. A token <code>close</code> indicates that the connection cannot
+ * be reused. If there is no such token, a token <code>keep-alive</code> 
+ * indicates that the connection should be re-used. If neither token is found,
+ * or if there are no <code>Connection</code> headers, the default policy for
+ * the HTTP version is applied. Since <code>HTTP/1.1</code>, connections are 
+ * re-used by default. Up until <code>HTTP/1.0</code>, connections are not 
+ * re-used by default.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
@@ -67,8 +68,7 @@
  * 
  * @since 4.0
  */
-public class DefaultConnectionReuseStrategy
-    implements ConnectionReuseStrategy {
+public class DefaultConnectionReuseStrategy implements ConnectionReuseStrategy {
 
     public DefaultConnectionReuseStrategy() {
         super();

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpClientConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpClientConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpClientConnection.java Fri Dec 26 09:06:04 2008
@@ -34,6 +34,7 @@
 import java.io.IOException;
 import java.net.Socket;
 
+import org.apache.http.params.CoreConnectionPNames;
 import org.apache.http.params.HttpConnectionParams;
 import org.apache.http.params.HttpParams;
 
@@ -52,6 +53,27 @@
         super();
     }
     
+    /**
+     * {@inheritDoc}
+     * <p>
+     * {@link CoreConnectionPNames#TCP_NODELAY} parameter determines whether 
+     * Nagle's algorithm is to be used. The Nagle's algorithm tries to conserve 
+     * bandwidth by minimizing the number of segments that are sent. When 
+     * applications wish to decrease network latency and increase performance, 
+     * they can disable Nagle's algorithm (that is enable TCP_NODELAY). Data 
+     * will be sent earlier, at the cost of an increase in bandwidth 
+     * consumption.
+     * <p>
+     * {@link CoreConnectionPNames#SO_TIMEOUT} parameter defines the socket 
+     * timeout in milliseconds, which is the timeout for waiting for data. 
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * <p>
+     * {@link CoreConnectionPNames#SO_LINGER} parameter defines linger time 
+     * in seconds. The maximum timeout value is platform specific. Value 
+     * <code>0</code> implies that the option is disabled. Value <code>-1</code>
+     * implies that the JRE default is to be used. The setting only affects 
+     * socket close.
+     */
     public void bind(
             final Socket socket, 
             final HttpParams params) throws IOException {

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpRequestFactory.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpRequestFactory.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpRequestFactory.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpRequestFactory.java Fri Dec 26 09:06:04 2008
@@ -39,7 +39,7 @@
 import org.apache.http.message.BasicHttpRequest;
 
 /**
- * Default implementation of a factory for creating request objects.
+ * Default factory for creating {@link HttpRequest} objects.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpResponseFactory.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpResponseFactory.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpResponseFactory.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpResponseFactory.java Fri Dec 26 09:06:04 2008
@@ -44,7 +44,7 @@
 import org.apache.http.impl.EnglishReasonPhraseCatalog;
 
 /**
- * Default implementation of a factory for creating response objects.
+ * Default factory for creating {@link HttpResponse} objects.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -73,8 +73,7 @@
 
     /**
      * Creates a new response factory with the default catalog.
-     * The default catalog is
-     * {@link EnglishReasonPhraseCatalog EnglishReasonPhraseCatalog}.
+     * The default catalog is {@link EnglishReasonPhraseCatalog}.
      */
     public DefaultHttpResponseFactory() {
         this(EnglishReasonPhraseCatalog.INSTANCE);

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpServerConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpServerConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/DefaultHttpServerConnection.java Fri Dec 26 09:06:04 2008
@@ -34,6 +34,7 @@
 import java.io.IOException;
 import java.net.Socket;
 
+import org.apache.http.params.CoreConnectionPNames;
 import org.apache.http.params.HttpConnectionParams;
 import org.apache.http.params.HttpParams;
 
@@ -52,6 +53,27 @@
         super();
     }
     
+    /**
+     * {@inheritDoc}
+     * <p>
+     * {@link CoreConnectionPNames#TCP_NODELAY} parameter determines whether 
+     * Nagle's algorithm is to be used. The Nagle's algorithm tries to conserve 
+     * bandwidth by minimizing the number of segments that are sent. When 
+     * applications wish to decrease network latency and increase performance, 
+     * they can disable Nagle's algorithm (that is enable TCP_NODELAY). Data 
+     * will be sent earlier, at the cost of an increase in bandwidth 
+     * consumption.
+     * <p>
+     * {@link CoreConnectionPNames#SO_TIMEOUT} parameter defines the socket 
+     * timeout in milliseconds, which is the timeout for waiting for data. 
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * <p>
+     * {@link CoreConnectionPNames#SO_LINGER} parameter defines linger time 
+     * in seconds. The maximum timeout value is platform specific. Value 
+     * <code>0</code> implies that the option is disabled. Value <code>-1</code>
+     * implies that the JRE default is to be used. The setting only affects 
+     * socket close.
+     */
     public void bind(final Socket socket, final HttpParams params) throws IOException {
         if (socket == null) {
             throw new IllegalArgumentException("Socket may not be null");

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/EnglishReasonPhraseCatalog.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/EnglishReasonPhraseCatalog.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/EnglishReasonPhraseCatalog.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/EnglishReasonPhraseCatalog.java Fri Dec 26 09:06:04 2008
@@ -48,8 +48,7 @@
  * 
  * @version $Revision$
  */
-public class EnglishReasonPhraseCatalog
-    implements ReasonPhraseCatalog {
+public class EnglishReasonPhraseCatalog implements ReasonPhraseCatalog {
 
     // static array with english reason phrases defined below
 

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/HttpConnectionMetricsImpl.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/HttpConnectionMetricsImpl.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/HttpConnectionMetricsImpl.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/HttpConnectionMetricsImpl.java Fri Dec 26 09:06:04 2008
@@ -36,7 +36,7 @@
 import org.apache.http.io.HttpTransportMetrics;
 
 /**
- * Implementation of the metrics interface.
+ * Default implementation of the {@link HttpConnectionMetrics} interface.
  */
 public class HttpConnectionMetricsImpl implements HttpConnectionMetrics {
     

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpClientConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpClientConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpClientConnection.java Fri Dec 26 09:06:04 2008
@@ -41,12 +41,14 @@
 import org.apache.http.impl.io.SocketOutputBuffer;
 import org.apache.http.io.SessionInputBuffer;
 import org.apache.http.io.SessionOutputBuffer;
+import org.apache.http.params.CoreConnectionPNames;
 import org.apache.http.params.HttpConnectionParams;
 import org.apache.http.params.HttpParams;
 
 /**
- * Implementation of a client-side HTTP connection that can be bound to a 
- * network Socket in order to receive and transmit data.
+ * Implementation of a client-side HTTP connection that can be bound to an 
+ * arbitrary {@link Socket} for receiving data from and transmitting data to
+ * a remote server.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -76,6 +78,21 @@
         }
     }
 
+    /**
+     * Creates an instance of {@link SocketInputBuffer} to be used for 
+     * receiving data from the given {@link Socket}.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a custom implementation of {@link SessionInputBuffer} interface.
+     * 
+     * @see SocketInputBuffer#SocketInputBuffer(Socket, int, HttpParams)
+     * 
+     * @param socket the socket.
+     * @param buffersize the buffer size.
+     * @param params HTTP parameters.
+     * @return session input buffer.
+     * @throws IOException in case of an I/O error.
+     */
     protected SessionInputBuffer createSessionInputBuffer(
             final Socket socket, 
             int buffersize,
@@ -83,6 +100,21 @@
         return new SocketInputBuffer(socket, buffersize, params);
     }
     
+    /**
+     * Creates an instance of {@link SessionOutputBuffer} to be used for 
+     * sending data to the given {@link Socket}.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a custom implementation of {@link SocketOutputBuffer} interface.
+     * 
+     * @see SocketOutputBuffer#SocketOutputBuffer(Socket, int, HttpParams)
+     * 
+     * @param socket the socket.
+     * @param buffersize the buffer size.
+     * @param params HTTP parameters.
+     * @return session output buffer.
+     * @throws IOException in case of an I/O error.
+     */
     protected SessionOutputBuffer createSessionOutputBuffer(
             final Socket socket, 
             int buffersize,
@@ -90,6 +122,31 @@
         return new SocketOutputBuffer(socket, buffersize, params);
     }
     
+    /**
+     * Binds this connection to the given {@link Socket}. This socket will be 
+     * used by the connection to send and receive data.
+     * <p>
+     * This method will invoke {@link #createSessionInputBuffer(Socket, int, HttpParams)}
+     * and {@link #createSessionOutputBuffer(Socket, int, HttpParams)} methods 
+     * to create session input / output buffers bound to this socket and then 
+     * will invoke {@link #init(SessionInputBuffer, SessionOutputBuffer, HttpParams)} 
+     * method to pass references to those buffers to the underlying HTTP message
+     * parser and formatter. 
+     * <p>
+     * After this method's execution the connection status will be reported
+     * as open and the {@link #isOpen()} will return <code>true</code>.
+     * <p>
+     * The following HTTP parameters affect configuration this connection:
+     * <p>
+     * The {@link CoreConnectionPNames#SOCKET_BUFFER_SIZE}
+     * parameter determines the size of the internal socket buffer. If not 
+     * defined or set to <code>-1</code> the default value will be chosen
+     * automatically.
+     * 
+     * @param socket the socket.
+     * @param params HTTP parameters.
+     * @throws IOException in case of an I/O error.
+     */
     protected void bind(
             final Socket socket, 
             final HttpParams params) throws IOException {

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpServerConnection.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpServerConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/SocketHttpServerConnection.java Fri Dec 26 09:06:04 2008
@@ -41,6 +41,7 @@
 import org.apache.http.impl.io.SocketOutputBuffer;
 import org.apache.http.io.SessionInputBuffer;
 import org.apache.http.io.SessionOutputBuffer;
+import org.apache.http.params.CoreConnectionPNames;
 import org.apache.http.params.HttpConnectionParams;
 import org.apache.http.params.HttpParams;
 
@@ -96,6 +97,21 @@
         return createSessionOutputBuffer(socket, buffersize, params);
     }
 
+    /**
+     * Creates an instance of {@link SocketInputBuffer} to be used for 
+     * receiving data from the given {@link Socket}.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a custom implementation of {@link SessionInputBuffer} interface.
+     * 
+     * @see SocketInputBuffer#SocketInputBuffer(Socket, int, HttpParams)
+     * 
+     * @param socket the socket.
+     * @param buffersize the buffer size.
+     * @param params HTTP parameters.
+     * @return session input buffer.
+     * @throws IOException in case of an I/O error.
+     */
     protected SessionInputBuffer createSessionInputBuffer(
             final Socket socket, 
             int buffersize,
@@ -103,6 +119,21 @@
         return new SocketInputBuffer(socket, buffersize, params);
     }
     
+    /**
+     * Creates an instance of {@link SessionOutputBuffer} to be used for 
+     * sending data to the given {@link Socket}.
+     * <p>
+     * This method can be overridden in super class in order to provide 
+     * a custom implementation of {@link SocketOutputBuffer} interface.
+     * 
+     * @see SocketOutputBuffer#SocketOutputBuffer(Socket, int, HttpParams)
+     * 
+     * @param socket the socket.
+     * @param buffersize the buffer size.
+     * @param params HTTP parameters.
+     * @return session output buffer.
+     * @throws IOException in case of an I/O error.
+     */
     protected SessionOutputBuffer createSessionOutputBuffer(
             final Socket socket, 
             int buffersize,
@@ -110,6 +141,31 @@
         return new SocketOutputBuffer(socket, buffersize, params);
     }
     
+    /**
+     * Binds this connection to the given {@link Socket}. This socket will be 
+     * used by the connection to send and receive data.
+     * <p>
+     * This method will invoke {@link #createSessionInputBuffer(Socket, int, HttpParams)}
+     * and {@link #createSessionOutputBuffer(Socket, int, HttpParams)} methods 
+     * to create session input / output buffers bound to this socket and then 
+     * will invoke {@link #init(SessionInputBuffer, SessionOutputBuffer, HttpParams)} 
+     * method to pass references to those buffers to the underlying HTTP message
+     * parser and formatter. 
+     * <p>
+     * After this method's execution the connection status will be reported
+     * as open and the {@link #isOpen()} will return <code>true</code>.
+     * <p>
+     * The following HTTP parameters affect configuration this connection:
+     * <p>
+     * The {@link CoreConnectionPNames#SOCKET_BUFFER_SIZE}
+     * parameter determines the size of the internal socket buffer. If not 
+     * defined or set to <code>-1</code> the default value will be chosen
+     * automatically.
+     * 
+     * @param socket the socket.
+     * @param params HTTP parameters.
+     * @throws IOException in case of an I/O error.
+     */
     protected void bind(final Socket socket, final HttpParams params) throws IOException {
         if (socket == null) {
             throw new IllegalArgumentException("Socket may not be null");

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntityDeserializer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntityDeserializer.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntityDeserializer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntityDeserializer.java Fri Dec 26 09:06:04 2008
@@ -46,10 +46,18 @@
 import org.apache.http.protocol.HTTP;
 
 /**
- * Default implementation of an entity deserializer.
+ * HTTP entity deserializer.
  * <p>
- * This entity deserializer currently supports only "chunked" and "identitiy" transfer-coding</a>
- * </p>
+ * This entity deserializer supports "chunked" and "identitiy" transfer-coding
+ * and content length delimited content.
+ * <p>
+ * This class relies on a specific implementation of 
+ * {@link ContentLengthStrategy} to determine the content length or transfer
+ * encoding of the entity.
+ * <p>
+ * This class generates an instance of {@link HttpEntity} based on 
+ * properties of the message. The content of the entity will be decoded 
+ * transparently for the consumer. 
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -69,6 +77,21 @@
         this.lenStrategy = lenStrategy;
     }
 
+    /**
+     * Creates a {@link BasicHttpEntity} based on properties of the given 
+     * message. The content of the entity is created by wrapping 
+     * {@link SessionInputBuffer} with a content decoder depending on the
+     * transfer mechanism used by the message.
+     * <p>
+     * This method is called by the public
+     * {@link #deserialize(SessionInputBuffer, HttpMessage)}.
+     * 
+     * @param inbuffer the session input buffer.
+     * @param message the message.
+     * @return HTTP entity.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
+     */
     protected BasicHttpEntity doDeserialize(
             final SessionInputBuffer inbuffer,
             final HttpMessage message) throws HttpException, IOException {
@@ -100,6 +123,20 @@
         return entity;
     }
         
+    /**
+     * Creates an {@link HttpEntity} based on properties of the given message.
+     * The content of the entity is created by wrapping 
+     * {@link SessionInputBuffer} with a content decoder depending on the
+     * transfer mechanism used by the message.
+     * <p>
+     * The content of the entity is NOT retrieved by this method.
+     *  
+     * @param inbuffer the session input buffer.
+     * @param message the message.
+     * @return HTTP entity.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
+     */
     public HttpEntity deserialize(
             final SessionInputBuffer inbuffer,
             final HttpMessage message) throws HttpException, IOException {

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntitySerializer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntitySerializer.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntitySerializer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/EntitySerializer.java Fri Dec 26 09:06:04 2008
@@ -44,10 +44,17 @@
 import org.apache.http.io.SessionOutputBuffer;
 
 /**
- * Default implementation of an entity serializer.
+ * HTTP entity serializer.
  * <p>
- * This entity serializer currently supports only "chunked" and "identitiy" transfer-coding</a>
- * </p>
+ * This entity serializer currently supports "chunked" and "identitiy" 
+ * transfer-coding and content length delimited content.
+ * <p>
+ * This class relies on a specific implementation of 
+ * {@link ContentLengthStrategy} to determine the content length or transfer
+ * encoding of the entity.
+ * <p>
+ * This class writes out the content of {@link HttpEntity} to the data stream
+ * using a transfer coding based on properties on the HTTP message. 
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
@@ -67,6 +74,20 @@
         this.lenStrategy = lenStrategy;
     }
 
+    /**
+     * Creates a transfer codec based on properties of the given HTTP message
+     * and returns {@link OutputStream} instance that transparently encodes 
+     * output data as it is being written out to the output stream.      
+     * <p>
+     * This method is called by the public
+     * {@link #serialize(SessionOutputBuffer, HttpMessage, HttpEntity)}.
+     * 
+     * @param outbuffer the session output buffer.
+     * @param message the HTTP message.
+     * @return output stream.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
+     */
     protected OutputStream doSerialize(
             final SessionOutputBuffer outbuffer,
             final HttpMessage message) throws HttpException, IOException {
@@ -80,6 +101,16 @@
         }
     }
 
+    /**
+     * Writes out the content of the given HTTP entity to the session output
+     * buffer based on properties of the given HTTP message.
+     * 
+     * @param outbuffer the output session buffer.
+     * @param message the HTTP message.
+     * @param entity the HTTP entity to be written out.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
+     */
     public void serialize(
             final SessionOutputBuffer outbuffer,
             final HttpMessage message,

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/LaxContentLengthStrategy.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/LaxContentLengthStrategy.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/LaxContentLengthStrategy.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/LaxContentLengthStrategy.java Fri Dec 26 09:06:04 2008
@@ -43,134 +43,12 @@
 import org.apache.http.protocol.HTTP;
 
 /**
- * The lax implementation of the content length strategy.
+ * The lax implementation of the content length strategy. This class will ignore 
+ * unrecognized transfer encodings and malformed <code>Content-Length</code> 
+ * header values if the {@link CoreProtocolPNames#STRICT_TRANSFER_ENCODING} 
+ * parameter of the given message is not set or set to <code>false</code>. 
  * <p>
- * This strategy conforms to the entity transfer rules outlined in  
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec4.4">Section 4.4</a>, 
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6">Section 3.6</a>, 
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.41">Section 14.41</a>
- * and <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec14.13">Section 14.13</a>
- * of <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616</a>, but is lenient 
- * about unsupported transfer codecs and malformed content-length headers.
- * </p>
- * <h>4.4 Message Length</h>
- * <p>
- * The transfer-length of a message is the length of the message-body as it appears in the 
- * message; that is, after any transfer-codings have been applied. When a message-body is 
- * included with a message, the transfer-length of that body is determined by one of the 
- * following (in order of precedence):
- * </p>
- * <p>
- * 1.Any response message which "MUST NOT" include a message-body (such as the 1xx, 204, 
- * and 304 responses and any response to a HEAD request) is always terminated by the first 
- * empty line after the header fields, regardless of the entity-header fields present in the 
- * message.
- * </p>
- * <p>
- * 2.If a Transfer-Encoding header field (section 14.41) is present and has any value other 
- * than "identity", then the transfer-length is defined by use of the "chunked" transfer-
- * coding (section 3.6), unless the message is terminated by closing the connection.
- * </p>
- * <p>
- * 3.If a Content-Length header field (section 14.13) is present, its decimal value in 
- * OCTETs represents both the entity-length and the transfer-length. The Content-Length 
- * header field MUST NOT be sent if these two lengths are different (i.e., if a 
- * Transfer-Encoding
- * </p>
- * <pre>
- *    header field is present). If a message is received with both a
- *    Transfer-Encoding header field and a Content-Length header field,
- *    the latter MUST be ignored.
- * </pre>
- * <p>
- * 4.If the message uses the media type "multipart/byteranges", and the ransfer-length is not 
- * otherwise specified, then this self- elimiting media type defines the transfer-length. 
- * This media type UST NOT be used unless the sender knows that the recipient can arse it; the 
- * presence in a request of a Range header with ultiple byte- range specifiers from a 1.1 
- * client implies that the lient can parse multipart/byteranges responses.
- * </p>
- * <pre>
- *     A range header might be forwarded by a 1.0 proxy that does not
- *     understand multipart/byteranges; in this case the server MUST
- *     delimit the message using methods defined in items 1,3 or 5 of
- *     this section.
- * </pre>
- * <p>
- * 5.By the server closing the connection. (Closing the connection cannot be used to indicate 
- * the end of a request body, since that would leave no possibility for the server to send back 
- * a response.)
- * </p>
- * <p>
- * For compatibility with HTTP/1.0 applications, HTTP/1.1 requests containing a message-body 
- * MUST include a valid Content-Length header field unless the server is known to be HTTP/1.1 
- * compliant. If a request contains a message-body and a Content-Length is not given, the 
- * server SHOULD respond with 400 (bad request) if it cannot determine the length of the 
- * message, or with 411 (length required) if it wishes to insist on receiving a valid 
- * Content-Length.
- * </p>
- * <p>All HTTP/1.1 applications that receive entities MUST accept the "chunked" transfer-coding 
- * (section 3.6), thus allowing this mechanism to be used for messages when the message 
- * length cannot be determined in advance. 
- * </p>
- * <h>3.6 Transfer Codings</h>
- * <p>
- * Transfer-coding values are used to indicate an encoding transformation that 
- * has been, can be, or may need to be applied to an entity-body in order to ensure 
- * "safe transport" through the network. This differs from a content coding in that 
- * the transfer-coding is a property of the message, not of the original entity.
- * </p>
- * <pre>
- * transfer-coding         = "chunked" | transfer-extension
- * transfer-extension      = token *( ";" parameter )
- * </pre>
- * <p>
- * Parameters are in the form of attribute/value pairs.
- * </p>
- * <pre>
- * parameter               = attribute "=" value
- * attribute               = token
- * value                   = token | quoted-string
- * </pre>
- * <p>
- * All transfer-coding values are case-insensitive. HTTP/1.1 uses transfer-coding values in 
- * the TE header field (section 14.39) and in the Transfer-Encoding header field (section 14.41).
- * </p>
- * <p>
- * Whenever a transfer-coding is applied to a message-body, the set of transfer-codings MUST 
- * include "chunked", unless the message is terminated by closing the connection. When the 
- * "chunked" transfer-coding is used, it MUST be the last transfer-coding applied to the 
- * message-body. The "chunked" transfer-coding MUST NOT be applied more than once to a 
- * message-body. These rules allow the recipient to determine the transfer-length of the 
- * message (section 4.4).
- * </p>
- * <h>14.41 Transfer-Encoding</h>
- * <p>
- * The Transfer-Encoding general-header field indicates what (if any) type of transformation has 
- * been applied to the message body in order to safely transfer it between the sender and the 
- * recipient. This differs from the content-coding in that the transfer-coding is a property of 
- * the message, not of the entity.
- * </p>
- * <pre>
- *   Transfer-Encoding       = "Transfer-Encoding" ":" 1#transfer-coding
- * </pre>
- * <p>
- * If multiple encodings have been applied to an entity, the transfer- codings MUST be listed in 
- * the order in which they were applied. Additional information about the encoding parameters 
- * MAY be provided by other entity-header fields not defined by this specification.
- * </p> 
- * <h>14.13 Content-Length</h>
- * <p>
- * The Content-Length entity-header field indicates the size of the entity-body, in decimal 
- * number of OCTETs, sent to the recipient or, in the case of the HEAD method, the size of 
- * the entity-body that would have been sent had the request been a GET.
- * </p>
- * <pre>
- *   Content-Length    = "Content-Length" ":" 1*DIGIT
- * </pre>
- * <p>
- * Applications SHOULD use this field to indicate the transfer-length of the message-body, 
- * unless this is prohibited by the rules in section 4.4. 
- * </p>
+ * This class recognizes "chunked" and "identitiy" transfer-coding only.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/StrictContentLengthStrategy.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/StrictContentLengthStrategy.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/StrictContentLengthStrategy.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/StrictContentLengthStrategy.java Fri Dec 26 09:06:04 2008
@@ -40,133 +40,12 @@
 import org.apache.http.protocol.HTTP;
 
 /**
- * The strict implementation of the content length strategy.
+ * The strict implementation of the content length strategy. This class
+ * will throw {@link ProtocolException} if it encounters an unsupported
+ * transfer encoding or a malformed <code>Content-Length</code> header 
+ * value.
  * <p>
- * This entity generator comforms to the entity transfer rules outlined in the 
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec4.4">Section 4.4</a>, 
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6">Section 3.6</a>, 
- * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.41">Section 14.41</a>
- * and <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec14.13">Section 14.13</a>
- * of <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616</a>
- * </p>
- * <h>4.4 Message Length</h>
- * <p>
- * The transfer-length of a message is the length of the message-body as it appears in the 
- * message; that is, after any transfer-codings have been applied. When a message-body is 
- * included with a message, the transfer-length of that body is determined by one of the 
- * following (in order of precedence):
- * </p>
- * <p>
- * 1.Any response message which "MUST NOT" include a message-body (such as the 1xx, 204, 
- * and 304 responses and any response to a HEAD request) is always terminated by the first 
- * empty line after the header fields, regardless of the entity-header fields present in the 
- * message.
- * </p>
- * <p>
- * 2.If a Transfer-Encoding header field (section 14.41) is present and has any value other 
- * than "identity", then the transfer-length is defined by use of the "chunked" transfer-
- * coding (section 3.6), unless the message is terminated by closing the connection.
- * </p>
- * <p>
- * 3.If a Content-Length header field (section 14.13) is present, its decimal value in 
- * OCTETs represents both the entity-length and the transfer-length. The Content-Length 
- * header field MUST NOT be sent if these two lengths are different (i.e., if a 
- * Transfer-Encoding
- * </p>
- * <pre>
- *    header field is present). If a message is received with both a
- *    Transfer-Encoding header field and a Content-Length header field,
- *    the latter MUST be ignored.
- * </pre>
- * <p>
- * 4.If the message uses the media type "multipart/byteranges", and the ransfer-length is not 
- * otherwise specified, then this self- elimiting media type defines the transfer-length. 
- * This media type UST NOT be used unless the sender knows that the recipient can arse it; the 
- * presence in a request of a Range header with ultiple byte- range specifiers from a 1.1 
- * client implies that the lient can parse multipart/byteranges responses.
- * </p>
- * <pre>
- *     A range header might be forwarded by a 1.0 proxy that does not
- *     understand multipart/byteranges; in this case the server MUST
- *     delimit the message using methods defined in items 1,3 or 5 of
- *     this section.
- * </pre>
- * <p>
- * 5.By the server closing the connection. (Closing the connection cannot be used to indicate 
- * the end of a request body, since that would leave no possibility for the server to send back 
- * a response.)
- * </p>
- * <p>
- * For compatibility with HTTP/1.0 applications, HTTP/1.1 requests containing a message-body 
- * MUST include a valid Content-Length header field unless the server is known to be HTTP/1.1 
- * compliant. If a request contains a message-body and a Content-Length is not given, the 
- * server SHOULD respond with 400 (bad request) if it cannot determine the length of the 
- * message, or with 411 (length required) if it wishes to insist on receiving a valid 
- * Content-Length.
- * </p>
- * <p>All HTTP/1.1 applications that receive entities MUST accept the "chunked" transfer-coding 
- * (section 3.6), thus allowing this mechanism to be used for messages when the message 
- * length cannot be determined in advance. 
- * </p>
- * <h>3.6 Transfer Codings</h>
- * <p>
- * Transfer-coding values are used to indicate an encoding transformation that 
- * has been, can be, or may need to be applied to an entity-body in order to ensure 
- * "safe transport" through the network. This differs from a content coding in that 
- * the transfer-coding is a property of the message, not of the original entity.
- * </p>
- * <pre>
- * transfer-coding         = "chunked" | transfer-extension
- * transfer-extension      = token *( ";" parameter )
- * </pre>
- * <p>
- * Parameters are in the form of attribute/value pairs.
- * </p>
- * <pre>
- * parameter               = attribute "=" value
- * attribute               = token
- * value                   = token | quoted-string
- * </pre>
- * <p>
- * All transfer-coding values are case-insensitive. HTTP/1.1 uses transfer-coding values in 
- * the TE header field (section 14.39) and in the Transfer-Encoding header field (section 14.41).
- * </p>
- * <p>
- * Whenever a transfer-coding is applied to a message-body, the set of transfer-codings MUST 
- * include "chunked", unless the message is terminated by closing the connection. When the 
- * "chunked" transfer-coding is used, it MUST be the last transfer-coding applied to the 
- * message-body. The "chunked" transfer-coding MUST NOT be applied more than once to a 
- * message-body. These rules allow the recipient to determine the transfer-length of the 
- * message (section 4.4).
- * </p>
- * <h>14.41 Transfer-Encoding</h>
- * <p>
- * The Transfer-Encoding general-header field indicates what (if any) type of transformation has 
- * been applied to the message body in order to safely transfer it between the sender and the 
- * recipient. This differs from the content-coding in that the transfer-coding is a property of 
- * the message, not of the entity.
- * </p>
- * <pre>
- *   Transfer-Encoding       = "Transfer-Encoding" ":" 1#transfer-coding
- * </pre>
- * <p>
- * If multiple encodings have been applied to an entity, the transfer- codings MUST be listed in 
- * the order in which they were applied. Additional information about the encoding parameters 
- * MAY be provided by other entity-header fields not defined by this specification.
- * </p> 
- * <h>14.13 Content-Length</h>
- * <p>
- * The Content-Length entity-header field indicates the size of the entity-body, in decimal 
- * number of OCTETs, sent to the recipient or, in the case of the HEAD method, the size of 
- * the entity-body that would have been sent had the request been a GET.
- * </p>
- * <pre>
- *   Content-Length    = "Content-Length" ":" 1*DIGIT
- * </pre>
- * <p>
- * Applications SHOULD use this field to indicate the transfer-length of the message-body, 
- * unless this is prohibited by the rules in section 4.4. 
- * </p>
+ * This class recognizes "chunked" and "identitiy" transfer-coding only.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/package.html?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/entity/package.html Fri Dec 26 09:06:04 2008
@@ -35,7 +35,8 @@
 </head>
 <body>
 Default implementations for interfaces in
-{@link org.apache.http.entity org.apache.http.entity}.
+{@link org.apache.http.entity org.apache.http.entity} and provides utility
+classes for serialization and deserialization of HTTP content entities.
 
 </body>
 </html>

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/package.html?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/package.html Fri Dec 26 09:06:04 2008
@@ -34,9 +34,7 @@
 -->
 </head>
 <body>
-A selection of HTTP
-{@link org.apache.http.message.AbstractHttpMessage message}
-implementations.
+A selection of HTTP message implementations.
 
 There are basic implementations for HTTP requests
 {@link org.apache.http.message.BasicHttpEntityEnclosingRequest with}

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/BasicHttpParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/BasicHttpParams.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/BasicHttpParams.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/BasicHttpParams.java Fri Dec 26 09:06:04 2008
@@ -39,11 +39,10 @@
 import org.apache.http.params.HttpParams;
 
 /**
- * This class represents a collection of HTTP protocol parameters.
- * Protocol parameters may be linked together to form a hierarchy.
- * If a particular parameter value has not been explicitly defined
- * in the collection itself, its value will be drawn from the parent 
- * collection of parameters.
+ * Default implementation of {@link HttpParams} interface.
+ * <p>
+ * Please note methods of this class are not synchronized and therefore may
+ * be threading unsafe.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  * 

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreConnectionPNames.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreConnectionPNames.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreConnectionPNames.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreConnectionPNames.java Fri Dec 26 09:06:04 2008
@@ -31,7 +31,6 @@
 
 package org.apache.http.params;
 
-
 /**
  * Defines parameter names for connections in HttpCore.
  * 
@@ -42,9 +41,9 @@
 public interface CoreConnectionPNames {
 
     /**
-     * Defines the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the 
-     * timeout for waiting for data. A timeout value of zero is interpreted as an infinite 
-     * timeout. 
+     * Defines the socket timeout (<code>SO_TIMEOUT</code>) in milliseconds,
+     * which is the timeout for waiting for data. A timeout value of zero is 
+     * interpreted as an infinite timeout. 
      * <p>
      * This parameter expects a value of type {@link Integer}.
      * </p>
@@ -56,8 +55,9 @@
      * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm 
      * tries to conserve bandwidth by minimizing the number of segments that are 
      * sent. When applications wish to decrease network latency and increase 
-     * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY). 
-     * Data will be sent earlier, at the cost of an increase in bandwidth consumption. 
+     * performance, they can disable Nagle's algorithm (that is enable 
+     * TCP_NODELAY). Data will be sent earlier, at the cost of an increase 
+     * in bandwidth consumption. 
      * <p>
      * This parameter expects a value of type {@link Boolean}.
      * </p>
@@ -75,10 +75,10 @@
     public static final String SOCKET_BUFFER_SIZE = "http.socket.buffer-size"; 
 
     /**
-     * Sets SO_LINGER with the specified linger time in seconds. The maximum timeout 
-     * value is platform specific. Value <tt>0</tt> implies that the option is disabled.
-     * Value <tt>-1</tt> implies that the JRE default is used. The setting only affects 
-     * socket close.  
+     * Sets SO_LINGER with the specified linger time in seconds. The maximum 
+     * timeout value is platform specific. Value <code>0</code> implies that 
+     * the option is disabled. Value <code>-1</code> implies that the JRE 
+     * default is used. The setting only affects  socket close.  
      * <p>
      * This parameter expects a value of type {@link Integer}.
      * </p>
@@ -87,8 +87,8 @@
     public static final String SO_LINGER = "http.socket.linger"; 
 
     /**
-     * Determines the timeout in milliseconds until a connection is established. A timeout 
-     * value of zero is interpreted as an infinite timeout.
+     * Determines the timeout in milliseconds until a connection is established. 
+     * A timeout value of zero is interpreted as an infinite timeout.
      * <p>
      * This parameter expects a value of type {@link Integer}.
      * </p>
@@ -107,9 +107,9 @@
     public static final String STALE_CONNECTION_CHECK = "http.connection.stalecheck"; 
 
     /**
-     * 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.
+     * 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.
      * <p>
      * This parameter expects a value of type {@link Integer}.
      * </p>
@@ -117,10 +117,10 @@
     public static final String MAX_LINE_LENGTH = "http.connection.max-line-length";
     
     /**
-     * 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. 
+     * 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. 
      * <p>
      * This parameter expects a value of type {@link Integer}.
      * </p>

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreProtocolPNames.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreProtocolPNames.java?rev=729513&r1=729512&r2=729513&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreProtocolPNames.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/CoreProtocolPNames.java Fri Dec 26 09:06:04 2008
@@ -31,6 +31,7 @@
 
 package org.apache.http.params;
 
+import org.apache.http.ProtocolVersion;
 
 /**
  * Defines parameter names for protocol execution in HttpCore.
@@ -42,11 +43,9 @@
 public interface CoreProtocolPNames {
 
     /**
-     * Defines the {@link org.apache.http.ProtocolVersion protocol version}
-     * used per default.
+     * Defines the {@link ProtocolVersion} used per default.
      * <p>
-     * This parameter expects a value of type
-     * {@link org.apache.http.ProtocolVersion}.
+     * This parameter expects a value of type {@link ProtocolVersion}.
      * </p>
      */
     public static final String PROTOCOL_VERSION = "http.protocol.version"; 
@@ -68,7 +67,7 @@
     public static final String HTTP_CONTENT_CHARSET = "http.protocol.content-charset"; 
     
     /**
-     * Defines the content of the <tt>User-Agent</tt> header.
+     * Defines the content of the <code>User-Agent</code> header.
      * <p>
      * This parameter expects a value of type {@link String}.
      * </p>
@@ -76,7 +75,7 @@
     public static final String USER_AGENT = "http.useragent"; 
 
     /**
-     * Defines the content of the <tt>Server</tt> header.
+     * Defines the content of the <code>Server</code> header.
      * <p>
      * This parameter expects a value of type {@link String}.
      * </p>
@@ -84,8 +83,8 @@
     public static final String ORIGIN_SERVER = "http.origin-server"; 
 
     /**
-     * Defines whether responses with an invalid <tt>Transfer-Encoding</tt> header should be 
-     * rejected.
+     * Defines whether responses with an invalid <code>Transfer-Encoding</code> 
+     * header should be rejected.
      * <p>
      * This parameter expects a value of type {@link Boolean}.
      * </p>



Mime
View raw message