HTTPCLIENT-764: javadoc improvements
Contributed by Sam Berlin <sberlin at gmail.com> git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@652020 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
parent
ff21903817
commit
e9f73a72b7
|
@ -37,8 +37,20 @@ import org.apache.http.client.utils.URLEncodedUtils;
|
|||
import org.apache.http.entity.StringEntity;
|
||||
import org.apache.http.protocol.HTTP;
|
||||
|
||||
/**
|
||||
* An entity composed of a list of url-encoded pairs.
|
||||
* This is typically useful while sending an HTTP POST request.
|
||||
*/
|
||||
public class UrlEncodedFormEntity extends StringEntity {
|
||||
|
||||
/**
|
||||
* Constructs a new {@link UrlEncodedFormEntity} with the list
|
||||
* of parameters in the specified encoding.
|
||||
*
|
||||
* @param parameters list of name/value pairs
|
||||
* @param encoding encoding the name/value pairs be encoded with
|
||||
* @throws UnsupportedEncodingException if the encoding isn't supported
|
||||
*/
|
||||
public UrlEncodedFormEntity (
|
||||
final List <NameValuePair> parameters,
|
||||
final String encoding) throws UnsupportedEncodingException {
|
||||
|
@ -47,6 +59,13 @@ public class UrlEncodedFormEntity extends StringEntity {
|
|||
setContentType(URLEncodedUtils.CONTENT_TYPE);
|
||||
}
|
||||
|
||||
/**
|
||||
* Constructs a new {@link UrlEncodedFormEntity} with the list
|
||||
* of parameters with the default encoding of {@link HTTP#DEFAULT_CONTENT_CHARSET}
|
||||
*
|
||||
* @param parameters list of name/value pairs
|
||||
* @throws UnsupportedEncodingException if the default encoding isn't supported
|
||||
*/
|
||||
public UrlEncodedFormEntity (
|
||||
final List <NameValuePair> parameters) throws UnsupportedEncodingException {
|
||||
super(URLEncodedUtils.format(parameters, HTTP.DEFAULT_CONTENT_CHARSET),
|
||||
|
|
|
@ -34,10 +34,24 @@ package org.apache.http.client.methods;
|
|||
import java.net.URI;
|
||||
import java.net.URISyntaxException;
|
||||
|
||||
/**
|
||||
* HTTP DELETE method
|
||||
* <p>
|
||||
* The HTTP DELETE method is defined in section 9.7 of
|
||||
* <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>:
|
||||
* <blockquote>
|
||||
* The DELETE method requests that the origin server delete the resource
|
||||
* identified by the Request-URI. [...] The client cannot
|
||||
* be guaranteed that the operation has been carried out, even if the
|
||||
* status code returned from the origin server indicates that the action
|
||||
* has been completed successfully.
|
||||
* </blockquote>
|
||||
*/
|
||||
public class HttpDelete extends HttpRequestBase {
|
||||
|
||||
public final static String METHOD_NAME = "DELETE";
|
||||
|
||||
|
||||
public HttpDelete() {
|
||||
super();
|
||||
}
|
||||
|
|
|
@ -49,8 +49,16 @@ import org.apache.http.HttpRequest;
|
|||
*/
|
||||
public interface HttpUriRequest extends HttpRequest {
|
||||
|
||||
/**
|
||||
* Returns the HTTP method this request uses, such as <code>GET</code>,
|
||||
* <code>PUT</code>, <code>POST</code>, or other.
|
||||
*/
|
||||
String getMethod();
|
||||
|
||||
/**
|
||||
* Returns the URI this request uses, such as
|
||||
* <code>http://example.org/path/to/file</code>.
|
||||
*/
|
||||
URI getURI();
|
||||
|
||||
}
|
||||
|
|
|
@ -58,7 +58,15 @@ public interface ClientPNames {
|
|||
* This parameter expects a value of type {@link String}.
|
||||
* </p>
|
||||
*/
|
||||
public static final String CONNECTION_MANAGER_FACTORY = "http.connection-manager.factory";
|
||||
public static final String CONNECTION_MANAGER_FACTORY_CLASS_NAME = "http.connection-manager.factory-class-name";
|
||||
|
||||
/**
|
||||
* Defines the factory to create a default {@link org.apache.http.conn.ClientConnectionManager}.
|
||||
* <p>
|
||||
* This parameters expects a value of type {@link org.apache.http.conn.ClientConnectionManagerFactory}.
|
||||
* </p>
|
||||
*/
|
||||
public static final String CONNECTION_MANAGER_FACTORY = "http.connection-manager.factory-object";
|
||||
|
||||
/**
|
||||
* Defines whether redirects should be handled automatically
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
/*
|
||||
* $HeadURL:$
|
||||
* $Revision:$
|
||||
* $Date:$
|
||||
* $HeadURL$
|
||||
* $Revision$
|
||||
* $Date$
|
||||
*
|
||||
* ====================================================================
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
|
@ -35,6 +35,7 @@ import java.util.Collection;
|
|||
|
||||
import org.apache.http.Header;
|
||||
import org.apache.http.HttpHost;
|
||||
import org.apache.http.conn.ClientConnectionManagerFactory;
|
||||
import org.apache.http.params.HttpAbstractParamBean;
|
||||
import org.apache.http.params.HttpParams;
|
||||
|
||||
|
@ -48,7 +49,11 @@ public class ClientParamBean extends HttpAbstractParamBean {
|
|||
params.setLongParameter(ClientPNames.CONNECTION_MANAGER_TIMEOUT, timeout);
|
||||
}
|
||||
|
||||
public void setConnectionManagerFactory (final String factory) {
|
||||
public void setConnectionManagerFactoryClassName (final String factory) {
|
||||
params.setParameter(ClientPNames.CONNECTION_MANAGER_FACTORY_CLASS_NAME, factory);
|
||||
}
|
||||
|
||||
public void setConnectionManagerFactory(ClientConnectionManagerFactory factory) {
|
||||
params.setParameter(ClientPNames.CONNECTION_MANAGER_FACTORY, factory);
|
||||
}
|
||||
|
||||
|
|
|
@ -34,8 +34,42 @@ import java.net.URISyntaxException;
|
|||
|
||||
import org.apache.http.HttpHost;
|
||||
|
||||
/**
|
||||
* A collection of utilities for {@link URI URIs}, to workaround
|
||||
* bugs within the class or for ease-of-use features.
|
||||
*/
|
||||
public class URIUtils {
|
||||
|
||||
/**
|
||||
* Constructs a {@link URI} using all the parameters. This should be
|
||||
* used instead of
|
||||
* {@link URI#URI(String, String, String, int, String, String, String)}
|
||||
* or any of the other URI multi-argument URI constructors.
|
||||
*
|
||||
* See <a
|
||||
* href="https://issues.apache.org/jira/browse/HTTPCLIENT-730">HTTPCLIENT-730</a>
|
||||
* for more information.
|
||||
*
|
||||
* @param scheme
|
||||
* Scheme name
|
||||
* @param host
|
||||
* Host name
|
||||
* @param port
|
||||
* Port number
|
||||
* @param path
|
||||
* Path
|
||||
* @param query
|
||||
* Query
|
||||
* @param fragment
|
||||
* Fragment
|
||||
*
|
||||
* @throws URISyntaxException
|
||||
* If both a scheme and a path are given but the path is
|
||||
* relative, if the URI string constructed from the given
|
||||
* components violates RFC 2396, or if the authority
|
||||
* component of the string is present but cannot be parsed
|
||||
* as a server-based authority
|
||||
*/
|
||||
public static URI createURI(
|
||||
final String scheme,
|
||||
final String host,
|
||||
|
@ -73,6 +107,22 @@ public class URIUtils {
|
|||
return new URI(buffer.toString());
|
||||
}
|
||||
|
||||
/**
|
||||
* A convenience method for creating a new {@link URI} whose scheme, host
|
||||
* and port are taken from the target host, but whose path, query and
|
||||
* fragment are taken from the existing URI. The fragment is only used if
|
||||
* dropFragment is false.
|
||||
*
|
||||
* @param uri
|
||||
* Contains the path, query and fragment to use.
|
||||
* @param target
|
||||
* Contains the scheme, host and port to use.
|
||||
* @param dropFragment
|
||||
* True if the fragment should not be copied.
|
||||
*
|
||||
* @throws URISyntaxException
|
||||
* If the resulting URI is invalid.
|
||||
*/
|
||||
public static URI rewriteURI(
|
||||
final URI uri,
|
||||
final HttpHost target,
|
||||
|
@ -99,6 +149,11 @@ public class URIUtils {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A convenience method for
|
||||
* {@link URIUtils#rewriteURI(URI, HttpHost, boolean)} that always keeps the
|
||||
* fragment.
|
||||
*/
|
||||
public static URI rewriteURI(
|
||||
final URI uri,
|
||||
final HttpHost target) throws URISyntaxException {
|
||||
|
|
|
@ -46,12 +46,28 @@ import org.apache.http.message.BasicNameValuePair;
|
|||
import org.apache.http.protocol.HTTP;
|
||||
import org.apache.http.util.EntityUtils;
|
||||
|
||||
/**
|
||||
* A collection of utilities for encoding URLs.
|
||||
*/
|
||||
public class URLEncodedUtils {
|
||||
|
||||
public static final String CONTENT_TYPE = "application/x-www-form-urlencoded";
|
||||
private static final String PARAMETER_SEPARATOR = "&";
|
||||
private static final String NAME_VALUE_SEPARATOR = "=";
|
||||
|
||||
/**
|
||||
* Returns a list of {@link NameValuePair NameValuePairs} as built from the
|
||||
* URI's query portion. For example, a URI of
|
||||
* http://example.org/path/to/file?a=1&b=2&c=3 would return a list of three
|
||||
* NameValuePairs, one for a=1, one for b=2, and one for c=3.
|
||||
* <p>
|
||||
* This is typically useful while parsing an HTTP PUT.
|
||||
*
|
||||
* @param uri
|
||||
* uri to parse
|
||||
* @param encoding
|
||||
* encoding to use while parsing the query
|
||||
*/
|
||||
public static List <NameValuePair> parse (final URI uri, final String encoding) {
|
||||
List <NameValuePair> result = Collections.emptyList();
|
||||
final String query = uri.getRawQuery();
|
||||
|
@ -62,6 +78,18 @@ public class URLEncodedUtils {
|
|||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a list of {@link NameValuePair NameValuePairs} as parsed from an
|
||||
* {@link HttpEntity}. The encoding is taken from the entity's
|
||||
* Content-Encoding header.
|
||||
* <p>
|
||||
* This is typically used while parsing an HTTP POST.
|
||||
*
|
||||
* @param entity
|
||||
* The entity to parse
|
||||
* @throws IOException
|
||||
* If there was an exception getting the entity's data.
|
||||
*/
|
||||
public static List <NameValuePair> parse (
|
||||
final HttpEntity entity) throws IOException {
|
||||
List <NameValuePair> result = Collections.emptyList();
|
||||
|
@ -77,11 +105,29 @@ public class URLEncodedUtils {
|
|||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if the entity's Content-Type header is
|
||||
* <code>application/x-www-form-urlencoded</code>.
|
||||
*/
|
||||
public static boolean isEncoded (final HttpEntity entity) {
|
||||
final Header contentType = entity.getContentType();
|
||||
return (contentType != null && contentType.getValue().equalsIgnoreCase(CONTENT_TYPE));
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds all parameters within the Scanner to the list of
|
||||
* <code>parameters</code>, as encoded by <code>encoding</code>. For
|
||||
* example, a scanner containing the string <code>a=1&b=2&c=3</code> would
|
||||
* add the {@link NameValuePair NameValuePairs} a=1, b=2, and c=3 to the
|
||||
* list of parameters.
|
||||
*
|
||||
* @param parameters
|
||||
* List to add parameters to.
|
||||
* @param scanner
|
||||
* Input that contains the parameters to parse.
|
||||
* @param encoding
|
||||
* Encoding to use when decoding the parameters.
|
||||
*/
|
||||
public static void parse (
|
||||
final List <NameValuePair> parameters,
|
||||
final Scanner scanner,
|
||||
|
@ -100,6 +146,13 @@ public class URLEncodedUtils {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a String that is suitable for use as an <code>application/x-www-form-urlencoded</code>
|
||||
* list of parameters in an HTTP PUT or HTTP POST.
|
||||
*
|
||||
* @param parameters The parameters to include.
|
||||
* @param encoding The encoding to use.
|
||||
*/
|
||||
public static String format (
|
||||
final List <NameValuePair> parameters,
|
||||
final String encoding) {
|
||||
|
|
|
@ -40,7 +40,7 @@ import org.apache.http.entity.HttpEntityWrapper;
|
|||
|
||||
/**
|
||||
* An entity that releases a {@link ManagedClientConnection connection}.
|
||||
* A {@link ManagedClientConnection ManagedClientConnection} will
|
||||
* A {@link ManagedClientConnection} will
|
||||
* typically <i>not</i> return a managed entity, but you can replace
|
||||
* the unmanaged entity in the response with a managed one.
|
||||
*
|
||||
|
|
|
@ -64,7 +64,7 @@ public interface ClientConnectionManager {
|
|||
|
||||
/**
|
||||
* Returns a new {@link ClientConnectionRequest}, from which a
|
||||
* {@link ManagedClientConnection} can be obtained, or the request can be
|
||||
* {@link ManagedClientConnection} can be obtained or the request can be
|
||||
* aborted.
|
||||
*/
|
||||
ClientConnectionRequest requestConnection(HttpRoute route, Object state)
|
||||
|
|
|
@ -35,6 +35,7 @@ import org.apache.http.conn.scheme.SchemeRegistry;
|
|||
import org.apache.http.params.HttpParams;
|
||||
|
||||
/**
|
||||
* A factory for creating new {@link ClientConnectionManager} instances.
|
||||
*
|
||||
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
|
||||
*
|
||||
|
|
|
@ -34,6 +34,10 @@ import java.net.ConnectException;
|
|||
|
||||
import org.apache.http.HttpHost;
|
||||
|
||||
/**
|
||||
* A {@link ConnectException} that specifies the {@link HttpHost} that was
|
||||
* being connected to.
|
||||
*/
|
||||
public class HttpHostConnectException extends ConnectException {
|
||||
|
||||
private static final long serialVersionUID = -3194482710275220224L;
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
/*
|
||||
* $HeadURL:$
|
||||
* $Revision:$
|
||||
* $Date:$
|
||||
* $HeadURL$
|
||||
* $Revision$
|
||||
* $Date$
|
||||
*
|
||||
* ====================================================================
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
|
@ -34,12 +34,20 @@ package org.apache.http.conn.params;
|
|||
import org.apache.http.params.HttpAbstractParamBean;
|
||||
import org.apache.http.params.HttpParams;
|
||||
|
||||
/**
|
||||
* Allows for setting parameters relating to connections on
|
||||
* {@link HttpParams}. This class ensures that the values set on the params
|
||||
* are type-safe.
|
||||
*/
|
||||
public class ConnConnectionParamBean extends HttpAbstractParamBean {
|
||||
|
||||
public ConnConnectionParamBean (final HttpParams params) {
|
||||
super(params);
|
||||
}
|
||||
|
||||
/**
|
||||
* @see ConnConnectionPNames#MAX_STATUS_LINE_GARBAGE
|
||||
*/
|
||||
public void setMaxStatusLineGarbage (final int maxStatusLineGarbage) {
|
||||
params.setIntParameter(ConnConnectionPNames.MAX_STATUS_LINE_GARBAGE, maxStatusLineGarbage);
|
||||
}
|
||||
|
|
|
@ -34,16 +34,23 @@ package org.apache.http.conn.params;
|
|||
import org.apache.http.params.HttpAbstractParamBean;
|
||||
import org.apache.http.params.HttpParams;
|
||||
|
||||
/**
|
||||
* Allows for setting parameters relating to connection managers on
|
||||
* {@link HttpParams}. This class ensures that the values set on the params
|
||||
* are type-safe.
|
||||
*/
|
||||
public class ConnManagerParamBean extends HttpAbstractParamBean {
|
||||
|
||||
public ConnManagerParamBean (final HttpParams params) {
|
||||
super(params);
|
||||
}
|
||||
|
||||
/** @see ConnManagerPNames#MAX_TOTAL_CONNECTIONS */
|
||||
public void setMaxTotalConnections (final int maxConnections) {
|
||||
params.setIntParameter(ConnManagerPNames.MAX_TOTAL_CONNECTIONS, maxConnections);
|
||||
}
|
||||
|
||||
/** @see ConnManagerPNames#MAX_CONNECTIONS_PER_ROUTE */
|
||||
public void setConnectionsPerRoute(final ConnPerRouteBean connPerRoute) {
|
||||
params.setParameter(ConnManagerPNames.MAX_CONNECTIONS_PER_ROUTE, connPerRoute);
|
||||
}
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
/*
|
||||
* $HeadURL:$
|
||||
* $Revision:$
|
||||
* $Date:$
|
||||
* $HeadURL$
|
||||
* $Revision$
|
||||
* $Date$
|
||||
*
|
||||
* ====================================================================
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
|
@ -38,20 +38,28 @@ import org.apache.http.conn.routing.HttpRoute;
|
|||
import org.apache.http.params.HttpAbstractParamBean;
|
||||
import org.apache.http.params.HttpParams;
|
||||
|
||||
/**
|
||||
* Allows for setting parameters relating to connection routes on
|
||||
* {@link HttpParams}. This class ensures that the values set on the params
|
||||
* are type-safe.
|
||||
*/
|
||||
public class ConnRouteParamBean extends HttpAbstractParamBean {
|
||||
|
||||
public ConnRouteParamBean (final HttpParams params) {
|
||||
super(params);
|
||||
}
|
||||
|
||||
/** @see ConnRoutePNames#DEFAULT_PROXY */
|
||||
public void setDefaultProxy (final HttpHost defaultProxy) {
|
||||
params.setParameter(ConnRoutePNames.DEFAULT_PROXY, defaultProxy);
|
||||
}
|
||||
|
||||
/** @see ConnRoutePNames#LOCAL_ADDRESS */
|
||||
public void setLocalAddress (final InetAddress address) {
|
||||
params.setParameter(ConnRoutePNames.LOCAL_ADDRESS, address);
|
||||
}
|
||||
|
||||
/** @see ConnRoutePNames#FORCED_ROUTE */
|
||||
public void setForcedRoute (final HttpRoute route) {
|
||||
params.setParameter(ConnRoutePNames.FORCED_ROUTE, route);
|
||||
}
|
||||
|
|
|
@ -41,8 +41,6 @@ import org.apache.http.params.HttpParams;
|
|||
|
||||
/**
|
||||
* The default class for creating sockets.
|
||||
* This class just uses the {@link java.net.Socket socket} API
|
||||
* in Java 1.4 or greater.
|
||||
*
|
||||
* @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
|
||||
* @author Michael Becke
|
||||
|
|
|
@ -33,6 +33,9 @@ package org.apache.http.conn.util;
|
|||
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* A collection of utilities relating to InetAddresses.
|
||||
*/
|
||||
public class InetAddressUtils {
|
||||
|
||||
private InetAddressUtils() {
|
||||
|
|
|
@ -152,17 +152,20 @@ public class DefaultHttpClient extends AbstractHttpClient {
|
|||
new Scheme("https", SSLSocketFactory.getSocketFactory(), 443));
|
||||
|
||||
ClientConnectionManager connManager = null;
|
||||
|
||||
HttpParams params = getParams();
|
||||
String className = (String) params.getParameter(
|
||||
ClientPNames.CONNECTION_MANAGER_FACTORY);
|
||||
|
||||
ClientConnectionManagerFactory factory = null;
|
||||
|
||||
// Try first getting the factory directly as an object.
|
||||
factory = (ClientConnectionManagerFactory) params
|
||||
.getParameter(ClientPNames.CONNECTION_MANAGER_FACTORY);
|
||||
if (factory == null) { // then try getting its class name.
|
||||
String className = (String) params.getParameter(
|
||||
ClientPNames.CONNECTION_MANAGER_FACTORY_CLASS_NAME);
|
||||
if (className != null) {
|
||||
try {
|
||||
Class<?> clazz = Class.forName(className);
|
||||
ClientConnectionManagerFactory factory =
|
||||
(ClientConnectionManagerFactory) clazz.newInstance();
|
||||
connManager = factory.newInstance(params, registry);
|
||||
factory = (ClientConnectionManagerFactory) clazz.newInstance();
|
||||
} catch (ClassNotFoundException ex) {
|
||||
throw new IllegalStateException("Invalid class name: " + className);
|
||||
} catch (IllegalAccessException ex) {
|
||||
|
@ -170,9 +173,15 @@ public class DefaultHttpClient extends AbstractHttpClient {
|
|||
} catch (InstantiationException ex) {
|
||||
throw new InstantiationError(ex.getMessage());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if(factory != null) {
|
||||
connManager = factory.newInstance(params, registry);
|
||||
} else {
|
||||
connManager = new SingleClientConnManager(getParams(), registry);
|
||||
}
|
||||
|
||||
return connManager;
|
||||
}
|
||||
|
||||
|
|
|
@ -35,6 +35,9 @@ import java.net.URI;
|
|||
import java.util.HashSet;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* A collection of URIs that were used as redirects.
|
||||
*/
|
||||
public class RedirectLocations {
|
||||
|
||||
private final Set<URI> uris;
|
||||
|
@ -44,14 +47,23 @@ public class RedirectLocations {
|
|||
this.uris = new HashSet<URI>();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if this collection contains the given URI.
|
||||
*/
|
||||
public boolean contains(final URI uri) {
|
||||
return this.uris.contains(uri);
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a new URI to the list of redirects.
|
||||
*/
|
||||
public void add(final URI uri) {
|
||||
this.uris.add(uri);
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes a URI from the list of redirects.
|
||||
*/
|
||||
public boolean remove(final URI uri) {
|
||||
return this.uris.remove(uri);
|
||||
}
|
||||
|
|
|
@ -94,6 +94,7 @@ public abstract class AbstractClientConnAdapter
|
|||
/** The reusability marker. */
|
||||
private volatile boolean markedReusable;
|
||||
|
||||
/** True if the connection has been aborted. */
|
||||
private volatile boolean aborted;
|
||||
|
||||
/**
|
||||
|
|
|
@ -41,7 +41,7 @@ public interface PoolEntryRequest {
|
|||
|
||||
/**
|
||||
* Obtains a pool entry with a connection within the given timeout.
|
||||
* If {@link #abortRequest()} is called before this completes,
|
||||
* If {@link #abortRequest()} is called before this completes
|
||||
* an {@link InterruptedException} is thrown.
|
||||
*
|
||||
* @param timeout the timeout, 0 or negative for no timeout
|
||||
|
@ -53,7 +53,7 @@ public interface PoolEntryRequest {
|
|||
* @throws ConnectionPoolTimeoutException
|
||||
* if the timeout expired
|
||||
* @throws InterruptedException
|
||||
* if the calling thread was interrupted
|
||||
* if the calling thread was interrupted or the request was aborted
|
||||
*/
|
||||
BasicPoolEntry getPoolEntry(
|
||||
long timeout,
|
||||
|
|
Loading…
Reference in New Issue