Javadoc updates

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1514638 13f79535-47bb-0310-9956-ffa450edef68

httpclient/src/main/java-deprecated/org/apache/http/client/RequestDirector.java

@@ -43,7 +43,10 @@ import org.apache.http.protocol.HttpContext;
  * send a sequence of requests in order to execute one initial request.
  *
  * @since 4.0
+ *
+ * @deprecated (4.3) No longer used
  */
+@Deprecated
 public interface RequestDirector {
 
 

httpclient/src/main/java/org/apache/http/client/HttpClient.java

@@ -42,62 +42,6 @@ import java.io.IOException;
  * execution. It imposes no restrictions or particular details on the request
  * execution process and leaves the specifics of state management,
  * authentication and redirect handling up to individual implementations.
- * This should make it easier to decorate the interface with additional
- * functionality such as response content caching.
- * <p/>
- * The usual execution flow can be demonstrated by the code snippet below:
- * <PRE>
- * MinimalHttpClient httpclient = HttpClientBuilder.buildDefault();
- *
- * // Prepare a request object
- * HttpGet httpget = new HttpGet("http://www.apache.org/");
- *
- * // Execute the request
- * HttpResponse response = httpclient.execute(httpget);
- *
- * // Examine the response status
- * System.out.println(response.getStatusLine());
- *
- * // Get hold of the response entity
- * HttpEntity entity = response.getEntity();
- *
- * // If the response does not enclose an entity, there is no need
- * // to worry about connection release
- * if (entity != null) {
- *     InputStream instream = entity.getContent();
- *     try {
- *
- *         BufferedReader reader = new BufferedReader(
- *                 new InputStreamReader(instream));
- *         // do something useful with the response
- *         System.out.println(reader.readLine());
- *
- *     } catch (IOException ex) {
- *
- *         // In case of an IOException the connection will be released
- *         // back to the connection manager automatically
- *         throw ex;
- *
- *     } catch (RuntimeException ex) {
- *
- *         // In case of an unexpected exception you may want to abort
- *         // the HTTP request in order to shut down the underlying
- *         // connection and release it back to the connection manager.
- *         httpget.abort();
- *         throw ex;
- *
- *     } finally {
- *
- *         // Closing the input stream will trigger connection release
- *         instream.close();
- *
- *     }
- *
- *     // When HttpClient instance is no longer needed, it can be closed
- *     // to ensure immediate deallocation of all system resources
- *     httpclient.close();
- * }
- * </PRE>
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/config/RequestConfig.java

@@ -86,62 +86,179 @@ public class RequestConfig implements Cloneable {
         this.socketTimeout = socketTimeout;
     }
 
+    /**
+     * Determines whether the 'Expect: 100-Continue' handshake is enabled
+     * for entity enclosing methods. The purpose of the 'Expect: 100-Continue'
+     * handshake is to allow a client that is sending a request message with
+     * a request body to determine if the origin server is willing to
+     * accept the request (based on the request headers) before the client
+     * sends the request body.
+     * <p/>
+     * The use of the 'Expect: 100-continue' handshake can result in
+     * a noticeable performance improvement for entity enclosing requests
+     * (such as POST and PUT) that require the target server's
+     * authentication.
+     * <p/>
+     * 'Expect: 100-continue' handshake should be used with caution, as it
+     * may cause problems with HTTP servers and proxies that do not support
+     * HTTP/1.1 protocol.
+     * <p/>
+     * Default: <code>false</code>
+     */
     public boolean isExpectContinueEnabled() {
         return expectContinueEnabled;
     }
 
+    /**
+     * Returns HTTP proxy to be used for request execution.
+     * <p/>
+     * Default: <code>null</code>
+     */
     public HttpHost getProxy() {
         return proxy;
     }
 
+    /**
+     * Returns local address to be used for request execution.
+     * <p/>
+     * On machines with multiple network interfaces, this parameter
+     * can be used to select the network interface from which the
+     * connection originates.
+     * <p/>
+     * Default: <code>null</code>
+     */
     public InetAddress getLocalAddress() {
         return localAddress;
     }
 
+    /**
+     * Determines whether stale connection check is to be used. The stale
+     * connection check can cause up to 30 millisecond overhead per request and
+     * should be used only when appropriate. For performance critical
+     * operations this check should be disabled.
+     * <p/>
+     * Default: <code>true</code>
+     */
     public boolean isStaleConnectionCheckEnabled() {
         return staleConnectionCheckEnabled;
     }
 
+    /**
+     * Determines the name of the cookie specification to be used for HTTP state
+     * management.
+     * <p/>
+     * Default: <code>null</code>
+     */
     public String getCookieSpec() {
         return cookieSpec;
     }
 
+    /**
+     * Determines whether redirects should be handled automatically.
+     * <p/>
+     * Default: <code>true</code>
+     */
     public boolean isRedirectsEnabled() {
         return redirectsEnabled;
     }
 
+    /**
+     * Determines whether relative redirects should be rejected. HTTP specification
+     * requires the location value be an absolute URI.
+     * <p/>
+     * Default: <code>true</code>
+     */
     public boolean isRelativeRedirectsAllowed() {
         return relativeRedirectsAllowed;
     }
 
+    /**
+     * Determines whether circular redirects (redirects to the same location) should
+     * be allowed. The HTTP spec is not sufficiently clear whether circular redirects
+     * are permitted, therefore optionally they can be enabled
+     * <p/>
+     * Default: <code>false</code>
+     */
     public boolean isCircularRedirectsAllowed() {
         return circularRedirectsAllowed;
     }
 
+    /**
+     * Returns the maximum number of redirects to be followed. The limit on number
+     * of redirects is intended to prevent infinite loops.
+     * <p/>
+     * Default: <code>50</code>
+     */
     public int getMaxRedirects() {
         return maxRedirects;
     }
 
+    /**
+     * Determines whether authentication should be handled automatically.
+     * <p/>
+     * Default: <code>true</code>
+     */
     public boolean isAuthenticationEnabled() {
         return authenticationEnabled;
     }
 
+    /**
+     * Determines the order of preference for supported authentication schemes
+     * when authenticating with the target host.
+     * <p/>
+     * Default: <code>null</code>
+     */
     public Collection<String> getTargetPreferredAuthSchemes() {
         return targetPreferredAuthSchemes;
     }
 
+    /**
+     * Determines the order of preference for supported authentication schemes
+     * when authenticating with the proxy host.
+     * <p/>
+     * Default: <code>null</code>
+     */
     public Collection<String> getProxyPreferredAuthSchemes() {
         return proxyPreferredAuthSchemes;
     }
 
+    /**
+     * Returns the timeout in milliseconds used when requesting a connection
+     * from the connection manager. A timeout value of zero is interpreted
+     * as an infinite timeout.
+     * <p/>
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * A negative value is interpreted as undefined (system default).
+     * <p/>
+     * Default: <code>-1</code>
+     */
     public int getConnectionRequestTimeout() {
         return connectionRequestTimeout;
     }
 
+    /**
+     * Determines the timeout in milliseconds until a connection is established.
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * <p/>
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * A negative value is interpreted as undefined (system default).
+     * <p/>
+     * Default: <code>-1</code>
+     */
     public int getConnectTimeout() {
         return connectTimeout;
     }
 
+    /**
+     * Defines the socket timeout (<code>SO_TIMEOUT</code>) in milliseconds,
+     * which is the timeout for waiting for data  or, put differently,
+     * a maximum period inactivity between two consecutive data packets).
+     * <p/>
+     * A timeout value of zero is interpreted as an infinite timeout.
+     * A negative value is interpreted as undefined (system default).
+     * <p/>
+     * Default: <code>-1</code>
+     */
     public int getSocketTimeout() {
         return socketTimeout;
     }

httpclient/src/main/java/org/apache/http/client/entity/EntityBuilder.java

@@ -46,6 +46,20 @@ import org.apache.http.entity.SerializableEntity;
 import org.apache.http.entity.StringEntity;
 
 /**
+ * Builder for {@link HttpEntity} instances.
+ * <p/>
+ * Several setter methods of this builder are mutually exclusive. In case of multiple invocations
+ * of the following methods only the last one will have effect:
+ * <ul>
+ *   <li>{@link #setText(String)}</li>
+ *   <li>{@link #setBinary(byte[])}</li>
+ *   <li>{@link #setStream(java.io.InputStream)}</li>
+ *   <li>{@link #setSerializable(java.io.Serializable)}</li>
+ *   <li>{@link #setParameters(java.util.List)}</li>
+ *   <li>{@link #setParameters(org.apache.http.NameValuePair...)}</li>
+ *   <li>{@link #setFile(java.io.File)}</li>
+ * </ul>
+ *
  * @since 4.3
  */
 @NotThreadSafe
@@ -79,101 +93,210 @@ public class EntityBuilder {
         this.file = null;
     }
 
+    /**
+     * Returns entity content as a string if set using {@link #setText(String)} method.
+     */
     public String getText() {
         return text;
     }
 
+    /**
+     * Sets entity content as a string. This method is mutually exclusive with
+     * {@link #setBinary(byte[])},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setSerializable(java.io.Serializable)} ,
+     * {@link #setParameters(java.util.List)},
+     * {@link #setParameters(org.apache.http.NameValuePair...)}
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setText(final String text) {
         clearContent();
         this.text = text;
         return this;
     }
 
+    /**
+     * Returns entity content as a byte array if set using
+     * {@link #setBinary(byte[])} method.
+     */
     public byte[] getBinary() {
         return binary;
     }
 
+    /**
+     * Sets entity content as a byte array. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setSerializable(java.io.Serializable)} ,
+     * {@link #setParameters(java.util.List)},
+     * {@link #setParameters(org.apache.http.NameValuePair...)}
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setBinary(final byte[] binary) {
         clearContent();
         this.binary = binary;
         return this;
     }
 
+    /**
+     * Returns entity content as a {@link InputStream} if set using
+     * {@link #setStream(java.io.InputStream)} method.
+     */
     public InputStream getStream() {
         return stream;
     }
 
+    /**
+     * Sets entity content as a {@link InputStream}. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setBinary(byte[])},
+     * {@link #setSerializable(java.io.Serializable)} ,
+     * {@link #setParameters(java.util.List)},
+     * {@link #setParameters(org.apache.http.NameValuePair...)}
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setStream(final InputStream stream) {
         clearContent();
         this.stream = stream;
         return this;
     }
 
+    /**
+     * Returns entity content as a parameter list if set using
+     * {@link #setParameters(java.util.List)} or
+     * {@link #setParameters(org.apache.http.NameValuePair...)} methods.
+     */
     public List<NameValuePair> getParameters() {
         return parameters;
     }
 
+    /**
+     * Sets entity content as a parameter list. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setBinary(byte[])},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setSerializable(java.io.Serializable)} ,
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setParameters(final List<NameValuePair> parameters) {
         clearContent();
         this.parameters = parameters;
         return this;
     }
 
+    /**
+     * Sets entity content as a parameter list. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setBinary(byte[])},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setSerializable(java.io.Serializable)} ,
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setParameters(final NameValuePair... parameters) {
         return setParameters(Arrays.asList(parameters));
     }
 
+    /**
+     * Returns entity content as a {@link Serializable} if set using
+     * {@link #setSerializable(java.io.Serializable)} method.
+     */
     public Serializable getSerializable() {
         return serializable;
     }
 
+    /**
+     * Sets entity content as a {@link Serializable}. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setBinary(byte[])},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setParameters(java.util.List)},
+     * {@link #setParameters(org.apache.http.NameValuePair...)}
+     * {@link #setFile(java.io.File)} methods.
+     */
     public EntityBuilder setSerializable(final Serializable serializable) {
         clearContent();
         this.serializable = serializable;
         return this;
     }
 
+    /**
+     * Returns entity content as a {@link File} if set using
+     * {@link #setFile(java.io.File)} method.
+     */
     public File getFile() {
         return file;
     }
 
+    /**
+     * Sets entity content as a {@link File}. This method is mutually exclusive with
+     * {@link #setText(String)},
+     * {@link #setBinary(byte[])},
+     * {@link #setStream(java.io.InputStream)} ,
+     * {@link #setParameters(java.util.List)},
+     * {@link #setParameters(org.apache.http.NameValuePair...)}
+     * {@link #setSerializable(java.io.Serializable)} methods.
+     */
     public EntityBuilder setFile(final File file) {
         clearContent();
         this.file = file;
         return this;
     }
 
+    /**
+     * Returns {@link ContentType} of the entity, if set.
+     */
     public ContentType getContentType() {
         return contentType;
     }
 
+    /**
+     * Sets {@link ContentType} of the entity.
+     */
     public EntityBuilder setContentType(final ContentType contentType) {
         this.contentType = contentType;
         return this;
     }
 
+    /**
+     * Returns content encoding of the entity, if set.
+     */
     public String getContentEncoding() {
         return contentEncoding;
     }
 
+    /**
+     * Sets content encoding of the entity.
+     */
     public EntityBuilder setContentEncoding(final String contentEncoding) {
         this.contentEncoding = contentEncoding;
         return this;
     }
 
+    /**
+     * Returns <code>true</code> if entity is to be chunk coded, <code>false</code> otherwise.
+     */
     public boolean isChunked() {
         return chunked;
     }
 
+    /**
+     * Makes entity chunk coded.
+     */
     public EntityBuilder chunked() {
         this.chunked = true;
         return this;
     }
 
+    /**
+     * Returns <code>true</code> if entity is to be GZIP compressed, <code>false</code> otherwise.
+     */
     public boolean isGzipCompress() {
         return gzipCompress;
     }
 
+    /**
+     * Makes entity GZIP compressed.
+     */
     public EntityBuilder gzipCompress() {
         this.gzipCompress = true;
         return this;
@@ -183,6 +306,9 @@ public class EntityBuilder {
         return this.contentType != null ? this.contentType : def;
     }
 
+    /**
+     * Creates new instance of {@link HttpEntity} based on the current state.
+     */
     public HttpEntity build() {
         final AbstractHttpEntity e;
         if (this.text != null) {

httpclient/src/main/java/org/apache/http/client/methods/Configurable.java

@@ -36,6 +36,9 @@ import org.apache.http.client.config.RequestConfig;
  */
 public interface Configurable {
 
+    /**
+     * Returns actual request configuration.
+     */
     RequestConfig getConfig();
 
 }

httpclient/src/main/java/org/apache/http/client/methods/RequestBuilder.java

@@ -51,6 +51,14 @@ import org.apache.http.protocol.HTTP;
 import org.apache.http.util.Args;
 
 /**
+ * Builder for {@link HttpUriRequest} instances.
+ * <p/>
+ * Please note that this class treats parameters differently depending on composition
+ * of the request: if the request has a content entity explicitly set with
+ * {@link #setEntity(org.apache.http.HttpEntity)} or it is not an entity enclosing method
+ * (such as POST or PUT), parameters will be added to the query component of the request URI.
+ * Otherwise, parameters will be added as a URL encoded {@link UrlEncodedFormEntity entity}.
+ *
  * @since 4.3
  */
 @NotThreadSafe
@@ -293,8 +301,7 @@ public class RequestBuilder {
             }
         }
         if (entity == null) {
-            final InternalRequest request = new InternalRequest(method);
+            result = new InternalRequest(method);
-            result = request;
         } else {
             final InternalEntityEclosingRequest request = new InternalEntityEclosingRequest(method);
             request.setEntity(entity);

httpclient/src/main/java/org/apache/http/client/utils/DateUtils.java

@@ -45,8 +45,7 @@ import org.apache.http.util.Args;
  * other headers.  This class handles dates as defined by RFC 2616 section
  * 3.3.1 as well as some other common non-standard formats.
  *
- *
+ * @since 4.3
- * @since 4.0
  */
 @Immutable
 public final class DateUtils {

httpclient/src/main/java/org/apache/http/client/utils/HttpClientUtils.java

@@ -36,7 +36,7 @@ import org.apache.http.client.methods.CloseableHttpResponse;
 import org.apache.http.util.EntityUtils;
 
 /**
- * Static helpers for dealing with {@link HttpResponse}s.
+ * Convenience methods for closing response and client objects.
  *
  * @since 4.2
  */

httpclient/src/main/java/org/apache/http/client/utils/URIBuilder.java

@@ -40,7 +40,7 @@ import org.apache.http.conn.util.InetAddressUtils;
 import org.apache.http.message.BasicNameValuePair;
 
 /**
- * {@link URI} builder for HTTP requests.
+ * Builder for {@link URI} instances.
  *
  * @since 4.2
  */

httpclient/src/main/java/org/apache/http/impl/client/FutureRequestExecutionService.java

@@ -41,7 +41,6 @@ import org.apache.http.protocol.HttpContext;
 /**
  * HttpAsyncClientWithFuture wraps calls to execute with a {@link HttpRequestFutureTask}
  * and schedules them using the provided executor service. Scheduled calls may be cancelled.
- * Similar to the non-blockcing HttpAsyncClient, a callback handler api is provided.
  */
 @ThreadSafe
 public class FutureRequestExecutionService implements Closeable {