From ee1fec2a8c402d5dd039e745450db1c57716c53d Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Fri, 16 Aug 2013 10:16:48 +0000 Subject: [PATCH] Javadoc updates git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1514638 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/http/client/RequestDirector.java | 3 + .../org/apache/http/client/HttpClient.java | 56 -------- .../http/client/config/RequestConfig.java | 117 ++++++++++++++++ .../http/client/entity/EntityBuilder.java | 126 ++++++++++++++++++ .../http/client/methods/Configurable.java | 3 + .../http/client/methods/RequestBuilder.java | 11 +- .../apache/http/client/utils/DateUtils.java | 3 +- .../http/client/utils/HttpClientUtils.java | 2 +- .../apache/http/client/utils/URIBuilder.java | 2 +- .../client/FutureRequestExecutionService.java | 1 - 10 files changed, 261 insertions(+), 63 deletions(-) rename httpclient/src/main/{java => java-deprecated}/org/apache/http/client/RequestDirector.java (98%) diff --git a/httpclient/src/main/java/org/apache/http/client/RequestDirector.java b/httpclient/src/main/java-deprecated/org/apache/http/client/RequestDirector.java similarity index 98% rename from httpclient/src/main/java/org/apache/http/client/RequestDirector.java rename to httpclient/src/main/java-deprecated/org/apache/http/client/RequestDirector.java index 7613aced5..195c1e60b 100644 --- a/httpclient/src/main/java/org/apache/http/client/RequestDirector.java +++ b/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 { diff --git a/httpclient/src/main/java/org/apache/http/client/HttpClient.java b/httpclient/src/main/java/org/apache/http/client/HttpClient.java index a7ce67140..0cac54c90 100644 --- a/httpclient/src/main/java/org/apache/http/client/HttpClient.java +++ b/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. - *

- * The usual execution flow can be demonstrated by the code snippet below: - * 

- * 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();
- * }
- *
* * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/client/config/RequestConfig.java b/httpclient/src/main/java/org/apache/http/client/config/RequestConfig.java index 417b1fb49..9bb457d4a 100644 --- a/httpclient/src/main/java/org/apache/http/client/config/RequestConfig.java +++ b/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. + *

+ * 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. + *

+ * '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. + *

+ * Default: false + */ public boolean isExpectContinueEnabled() { return expectContinueEnabled; } + /** + * Returns HTTP proxy to be used for request execution. + *

+ * Default: null + */ public HttpHost getProxy() { return proxy; } + /** + * Returns local address to be used for request execution. + *

+ * On machines with multiple network interfaces, this parameter + * can be used to select the network interface from which the + * connection originates. + *

+ * Default: null + */ 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. + *

+ * Default: true + */ public boolean isStaleConnectionCheckEnabled() { return staleConnectionCheckEnabled; } + /** + * Determines the name of the cookie specification to be used for HTTP state + * management. + *

+ * Default: null + */ public String getCookieSpec() { return cookieSpec; } + /** + * Determines whether redirects should be handled automatically. + *

+ * Default: true + */ public boolean isRedirectsEnabled() { return redirectsEnabled; } + /** + * Determines whether relative redirects should be rejected. HTTP specification + * requires the location value be an absolute URI. + *

+ * Default: true + */ 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 + *

+ * Default: false + */ 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. + *

+ * Default: 50 + */ public int getMaxRedirects() { return maxRedirects; } + /** + * Determines whether authentication should be handled automatically. + *

+ * Default: true + */ public boolean isAuthenticationEnabled() { return authenticationEnabled; } + /** + * Determines the order of preference for supported authentication schemes + * when authenticating with the target host. + *

+ * Default: null + */ public Collection getTargetPreferredAuthSchemes() { return targetPreferredAuthSchemes; } + /** + * Determines the order of preference for supported authentication schemes + * when authenticating with the proxy host. + *

+ * Default: null + */ public Collection 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. + *

+ * A timeout value of zero is interpreted as an infinite timeout. + * A negative value is interpreted as undefined (system default). + *

+ * Default: -1 + */ 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. + *

+ * A timeout value of zero is interpreted as an infinite timeout. + * A negative value is interpreted as undefined (system default). + *

+ * Default: -1 + */ public int getConnectTimeout() { return connectTimeout; } + /** + * Defines the socket timeout (SO_TIMEOUT) in milliseconds, + * which is the timeout for waiting for data or, put differently, + * a maximum period inactivity between two consecutive data packets). + *

+ * A timeout value of zero is interpreted as an infinite timeout. + * A negative value is interpreted as undefined (system default). + *

+ * Default: -1 + */ public int getSocketTimeout() { return socketTimeout; } diff --git a/httpclient/src/main/java/org/apache/http/client/entity/EntityBuilder.java b/httpclient/src/main/java/org/apache/http/client/entity/EntityBuilder.java index 9544829be..5e1b39e84 100644 --- a/httpclient/src/main/java/org/apache/http/client/entity/EntityBuilder.java +++ b/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. + *

+ * 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: + *

+ * * @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 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 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 true if entity is to be chunk coded, false otherwise. + */ public boolean isChunked() { return chunked; } + /** + * Makes entity chunk coded. + */ public EntityBuilder chunked() { this.chunked = true; return this; } + /** + * Returns true if entity is to be GZIP compressed, false 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) { diff --git a/httpclient/src/main/java/org/apache/http/client/methods/Configurable.java b/httpclient/src/main/java/org/apache/http/client/methods/Configurable.java index 7b31a5a87..42f098ec0 100644 --- a/httpclient/src/main/java/org/apache/http/client/methods/Configurable.java +++ b/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(); } diff --git a/httpclient/src/main/java/org/apache/http/client/methods/RequestBuilder.java b/httpclient/src/main/java/org/apache/http/client/methods/RequestBuilder.java index 31ec24be1..1c0196e10 100644 --- a/httpclient/src/main/java/org/apache/http/client/methods/RequestBuilder.java +++ b/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. + *

+ * 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 = request; + result = new InternalRequest(method); } else { final InternalEntityEclosingRequest request = new InternalEntityEclosingRequest(method); request.setEntity(entity); diff --git a/httpclient/src/main/java/org/apache/http/client/utils/DateUtils.java b/httpclient/src/main/java/org/apache/http/client/utils/DateUtils.java index e39aaf33f..86f3c7eb3 100644 --- a/httpclient/src/main/java/org/apache/http/client/utils/DateUtils.java +++ b/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.0 + * @since 4.3 */ @Immutable public final class DateUtils { diff --git a/httpclient/src/main/java/org/apache/http/client/utils/HttpClientUtils.java b/httpclient/src/main/java/org/apache/http/client/utils/HttpClientUtils.java index fcbb3e692..a3df7fc24 100644 --- a/httpclient/src/main/java/org/apache/http/client/utils/HttpClientUtils.java +++ b/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 */ diff --git a/httpclient/src/main/java/org/apache/http/client/utils/URIBuilder.java b/httpclient/src/main/java/org/apache/http/client/utils/URIBuilder.java index efc78a211..169465769 100644 --- a/httpclient/src/main/java/org/apache/http/client/utils/URIBuilder.java +++ b/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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/client/FutureRequestExecutionService.java b/httpclient/src/main/java/org/apache/http/impl/client/FutureRequestExecutionService.java index be0efa5e0..8e03fa3b2 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/FutureRequestExecutionService.java +++ b/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 {