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:
Oleg Kalnichevski 2008-04-27 21:23:31 +00:00
parent ff21903817
commit e9f73a72b7
20 changed files with 248 additions and 35 deletions

View File

@ -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),

View File

@ -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();
}

View File

@ -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();
}

View File

@ -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

View File

@ -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);
}

View File

@ -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&nbsp;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 {

View File

@ -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) {

View File

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

View File

@ -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)

View File

@ -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>
*

View File

@ -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;

View File

@ -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);
}

View File

@ -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);
}

View File

@ -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);
}

View File

@ -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

View File

@ -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() {

View File

@ -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;
}

View File

@ -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);
}

View File

@ -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;
/**

View File

@ -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,