You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2008/12/29 12:48:54 UTC
svn commit: r729871 - in
/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http:
./ params/ protocol/
Author: olegk
Date: Mon Dec 29 03:48:54 2008
New Revision: 729871
URL: http://svn.apache.org/viewvc?rev=729871&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpRequestInterceptor.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponseInterceptor.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParamBean.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpParams.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParamBean.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpContext.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpProcessor.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpContext.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpProcessor.java
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpRequestInterceptor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpRequestInterceptor.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpRequestInterceptor.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpRequestInterceptor.java Mon Dec 29 03:48:54 2008
@@ -35,11 +35,20 @@
import org.apache.http.protocol.HttpContext;
-
/**
- * Processes a request.
- * Provides the ability to process a request before it is sent
- * to the server or after it has received on the server side.
+ * HTTP protocol interceptor is a routine that implements a specific aspect of
+ * the HTTP protocol. Usually protocol interceptors are expected to act upon
+ * one specific header or a group of related headers of the incoming message
+ * or populate the outgoing message with one specific header or a group of
+ * related headers. Protocol
+ * <p>
+ * Interceptors can also manipulate content entities enclosed with messages.
+ * Usually this is accomplished by using the 'Decorator' pattern where a wrapper
+ * entity class is used to decorate the original entity.
+ * <p>
+ * Protocol interceptors must be implemented as thread-safe. Similarly to
+ * servlets, protocol interceptors should not use instance variables unless
+ * access to those variables is synchronized.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponseInterceptor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponseInterceptor.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponseInterceptor.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponseInterceptor.java Mon Dec 29 03:48:54 2008
@@ -36,13 +36,22 @@
import org.apache.http.protocol.HttpContext;
/**
- * Processes a response.
- * Provides the ability to process a response before it is sent
- * to the client or after it has been received on the client side.
+ * HTTP protocol interceptor is a routine that implements a specific aspect of
+ * the HTTP protocol. Usually protocol interceptors are expected to act upon
+ * one specific header or a group of related headers of the incoming message
+ * or populate the outgoing message with one specific header or a group of
+ * related headers. Protocol
+ * <p>
+ * Interceptors can also manipulate content entities enclosed with messages.
+ * Usually this is accomplished by using the 'Decorator' pattern where a wrapper
+ * entity class is used to decorate the original entity.
+ * <p>
+ * Protocol interceptors must be implemented as thread-safe. Similarly to
+ * servlets, protocol interceptors should not use instance variables unless
+ * access to those variables is synchronized.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
- *
* <!-- empty lines above to avoid 'svn diff' context problems -->
* @version $Revision$
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParamBean.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParamBean.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParamBean.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpConnectionParamBean.java Mon Dec 29 03:48:54 2008
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -31,6 +31,11 @@
package org.apache.http.params;
+/**
+ * This is a Java Bean class that can be used to wrap an instance of
+ * {@link HttpParams} and manipulate HTTP connection parameters using Java Beans
+ * conventions.
+ */
public class HttpConnectionParamBean extends HttpAbstractParamBean {
public HttpConnectionParamBean (final HttpParams params) {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpParams.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpParams.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpParams.java Mon Dec 29 03:48:54 2008
@@ -32,8 +32,23 @@
package org.apache.http.params;
/**
- * Represents a collection of HTTP protocol and framework parameters.
- *
+ *
+ * HttpParams interface represents a collection of immutable values that define
+ * a runtime behavior of a component. HTTP parameters should be simple objects:
+ * integers, doubles, strings, collections and objects that remain immutable
+ * at runtime. HttpParams is expected to be used in the 'write once - ready
+ * many' mode. Once initialized HTTP parameters are not expected to mutate in
+ * the course of HTTP message processing.
+ * <p>
+ * The purpose of this intreface is to define a behavior of other components.
+ * Usually each complex component has its own HTTP parameter collection.
+ * <p>
+ * Instances of this interface can be linked together to form a hierarchy.
+ * In the simplest form one set of parameters can use content of another one
+ * to obtain default values of parameters not present in the local set.
+ *
+ * @see DefaultedHttpParams
+ *
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
* @version $Revision$
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParamBean.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParamBean.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParamBean.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParamBean.java Mon Dec 29 03:48:54 2008
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -33,6 +33,11 @@
import org.apache.http.HttpVersion;
+/**
+ * This is a Java Bean class that can be used to wrap an instance of
+ * {@link HttpParams} and manipulate HTTP protocol parameters using Java Beans
+ * conventions.
+ */
public class HttpProtocolParamBean extends HttpAbstractParamBean {
public HttpProtocolParamBean (final HttpParams params) {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/HttpProtocolParams.java Mon Dec 29 03:48:54 2008
@@ -36,13 +36,8 @@
import org.apache.http.protocol.HTTP;
/**
- * This class implements an adaptor around the {@link HttpParams} interface
- * to simplify manipulation of the HTTP protocol specific parameters.
- * <br/>
- * Note that the <i>implements</i> relation to {@link CoreProtocolPNames}
- * is for compatibility with existing application code only. References to
- * the parameter names should use the interface, not this class.
- *
+ * Utility class for accessing protocol parameters in {@link HttpParams}.
+ *
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
* @version $Revision$
@@ -53,15 +48,16 @@
*/
public final class HttpProtocolParams implements CoreProtocolPNames {
- /**
- */
private HttpProtocolParams() {
super();
}
/**
- * Returns the charset to be used for writing HTTP headers.
- * @return The charset
+ * Obtains value of the {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET} parameter.
+ * If not set, defaults to <code>US-ASCII</code>.
+ *
+ * @param HTTP parameters.
+ * @return HTTP element charset.
*/
public static String getHttpElementCharset(final HttpParams params) {
if (params == null) {
@@ -76,8 +72,10 @@
}
/**
- * Sets the charset to be used for writing HTTP headers.
- * @param charset The charset
+ * Sets value of the {@link CoreProtocolPNames#HTTP_ELEMENT_CHARSET} parameter.
+ *
+ * @param HTTP parameters.
+ * @param HTTP element charset.
*/
public static void setHttpElementCharset(final HttpParams params, final String charset) {
if (params == null) {
@@ -87,9 +85,11 @@
}
/**
- * Returns the default charset to be used for writing content body,
- * when no charset explicitly specified.
- * @return The charset
+ * Obtains value of the {@link CoreProtocolPNames#HTTP_CONTENT_CHARSET} parameter.
+ * If not set, defaults to <code>ISO-8859-1</code>.
+ *
+ * @param HTTP parameters.
+ * @return HTTP content charset.
*/
public static String getContentCharset(final HttpParams params) {
if (params == null) {
@@ -104,9 +104,10 @@
}
/**
- * Sets the default charset to be used for writing content body,
- * when no charset explicitly specified.
- * @param charset The charset
+ * Sets value of the {@link CoreProtocolPNames#HTTP_CONTENT_CHARSET} parameter.
+ *
+ * @param HTTP parameters.
+ * @param HTTP content charset.
*/
public static void setContentCharset(final HttpParams params, final String charset) {
if (params == null) {
@@ -116,9 +117,11 @@
}
/**
- * Returns {@link ProtocolVersion protocol version} to be used per default.
- *
- * @return {@link ProtocolVersion protocol version}
+ * Obtains value of the {@link CoreProtocolPNames#PROTOCOL_VERSION} parameter.
+ * If not set, defaults to {@link HttpVersion#HTTP_1_1}.
+ *
+ * @param HTTP parameters.
+ * @return HTTP protocol version.
*/
public static ProtocolVersion getVersion(final HttpParams params) {
if (params == null) {
@@ -133,10 +136,10 @@
}
/**
- * Assigns the {@link ProtocolVersion protocol version} to be used by the
- * HTTP methods that this collection of parameters applies to.
- *
- * @param version the {@link ProtocolVersion protocol version}
+ * Sets value of the {@link CoreProtocolPNames#PROTOCOL_VERSION} parameter.
+ *
+ * @param HTTP parameters.
+ * @param HTTP protocol version.
*/
public static void setVersion(final HttpParams params, final ProtocolVersion version) {
if (params == null) {
@@ -145,6 +148,13 @@
params.setParameter(CoreProtocolPNames.PROTOCOL_VERSION, version);
}
+ /**
+ * Obtains value of the {@link CoreProtocolPNames#USER_AGENT} parameter.
+ * If not set, returns <code>null</code>.
+ *
+ * @param HTTP parameters.
+ * @return User agent string.
+ */
public static String getUserAgent(final HttpParams params) {
if (params == null) {
throw new IllegalArgumentException("HTTP parameters may not be null");
@@ -152,6 +162,12 @@
return (String) params.getParameter(CoreProtocolPNames.USER_AGENT);
}
+ /**
+ * Sets value of the {@link CoreProtocolPNames#USER_AGENT} parameter.
+ *
+ * @param HTTP parameters.
+ * @param User agent string.
+ */
public static void setUserAgent(final HttpParams params, final String useragent) {
if (params == null) {
throw new IllegalArgumentException("HTTP parameters may not be null");
@@ -159,6 +175,13 @@
params.setParameter(CoreProtocolPNames.USER_AGENT, useragent);
}
+ /**
+ * Obtains value of the {@link CoreProtocolPNames#USE_EXPECT_CONTINUE} parameter.
+ * If not set, returns <code>false</code>.
+ *
+ * @param HTTP parameters.
+ * @return User agent string.
+ */
public static boolean useExpectContinue(final HttpParams params) {
if (params == null) {
throw new IllegalArgumentException("HTTP parameters may not be null");
@@ -167,10 +190,17 @@
(CoreProtocolPNames.USE_EXPECT_CONTINUE, false);
}
+ /**
+ * Sets value of the {@link CoreProtocolPNames#USE_EXPECT_CONTINUE} parameter.
+ *
+ * @param HTTP parameters.
+ * @param User agent string.
+ */
public static void setUseExpectContinue(final HttpParams params, boolean b) {
if (params == null) {
throw new IllegalArgumentException("HTTP parameters may not be null");
}
params.setBooleanParameter(CoreProtocolPNames.USE_EXPECT_CONTINUE, b);
}
+
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpContext.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpContext.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpContext.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpContext.java Mon Dec 29 03:48:54 2008
@@ -35,7 +35,10 @@
import java.util.Map;
/**
- * Default implementation of the {@link HttpContext HttpContext}.
+ * Default implementation of {@link HttpContext}.
+ * <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/protocol/BasicHttpProcessor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpProcessor.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpProcessor.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/BasicHttpProcessor.java Mon Dec 29 03:48:54 2008
@@ -43,8 +43,8 @@
import org.apache.http.HttpResponseInterceptor;
/**
- * Keeps lists of interceptors for processing requests and responses.
- *
+ * Default implementation of {@link HttpProcessor}.
+ *
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
* @author Andrea Selva
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ExecutionContext.java Mon Dec 29 03:48:54 2008
@@ -31,8 +31,10 @@
package org.apache.http.protocol;
+import org.apache.http.HttpConnection;
+
/**
- * {@link HttpContext Context} attribute names for protocol execution.
+ * {@link HttpContext} attribute names for protocol execution.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -41,12 +43,42 @@
* @since 4.0
*/
public interface ExecutionContext {
-
+
+ /**
+ * Attribute name of a {@link HttpConnection} object that represents
+ * the actual HTTP connection.
+ */
public static final String HTTP_CONNECTION = "http.connection";
+
+ /**
+ * Attribute name of a {@link HttpRequest} object that represents
+ * the actual HTTP request.
+ */
public static final String HTTP_REQUEST = "http.request";
+
+ /**
+ * Attribute name of a {@link HttpResponse} object that represents the
+ * actual HTTP response.
+ */
public static final String HTTP_RESPONSE = "http.response";
+
+ /**
+ * Attribute name of a {@link HttpHost} object that represents the
+ * connection target.
+ */
public static final String HTTP_TARGET_HOST = "http.target_host";
+
+ /**
+ * Attribute name of a {@link HttpHost} object that represents the
+ * connection proxy.
+ */
public static final String HTTP_PROXY_HOST = "http.proxy_host";
+
+ /**
+ * Attribute name of a {@link Boolean} object that represents the
+ * the flag indicating whether the actual request has been fully transmitted
+ * to the target host.
+ */
public static final String HTTP_REQ_SENT = "http.request_sent";
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpContext.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpContext.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpContext.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpContext.java Mon Dec 29 03:48:54 2008
@@ -31,13 +31,19 @@
package org.apache.http.protocol;
+import java.util.HashMap;
+
/**
- * A context for executing a request.
- * The context is used to tie together the request, the response,
- * and optional application data. It is also used for internal data.
- * Attribute names starting with the prefix "http." are
- * {@link #RESERVED_PREFIX reserved} for internal data.
- *
+ * HttpCotext represents execution state of an HTTP process. It is a structure
+ * that can be used to map an attribute name to an attribute value. Internally
+ * HTTP context implementations are usually backed by a {@link HashMap}.
+ * <p>
+ * The primary purpose of the HTTP context is to facilitate information sharing
+ * among various logically related components. HTTP context can be used
+ * to store a processing state for one message or several consecutive messages.
+ * Multiple logically related messages can participate in a logical session
+ * if the same context is reused between consecutive messages.
+ *
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
* @version $Revision$
@@ -49,10 +55,28 @@
/** The prefix reserved for use by HTTP components. "http." */
public static final String RESERVED_PREFIX = "http.";
+ /**
+ * Obtains attribute with the given name.
+ *
+ * @param id the attribute name.
+ * @return attribute value, or <code>null</code> if not set.
+ */
Object getAttribute(String id);
+ /**
+ * Sets value of the attribute with the given name.
+ *
+ * @param id the attribute name.
+ * @param obj the attribute value.
+ */
void setAttribute(String id, Object obj);
+ /**
+ * Removes attribute with the given name from the context.
+ *
+ * @param id the attribute name.
+ * @return attribute value, or <code>null</code> if not set.
+ */
Object removeAttribute(String id);
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpProcessor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpProcessor.java?rev=729871&r1=729870&r2=729871&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpProcessor.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpProcessor.java Mon Dec 29 03:48:54 2008
@@ -35,12 +35,20 @@
import org.apache.http.HttpResponseInterceptor;
/**
- * Performs interceptor processing of requests and responses.
- * Specific interceptors typically interpret or update message headers,
- * and they may wrap the message entity for example to implement a
- * specific transport or content encoding.
- * A <code>HttpProcessor</code> typically maintains a list of
- * interceptors that will be applied to a request or response.
+ * HTTP protocol processor is a collection of protocol interceptors that
+ * implements the 'Chain of Responsibility' pattern, where each individual
+ * protocol interceptor is expected to work on a particular aspect of the HTTP
+ * protocol the interceptor is responsible for.
+ * <p>
+ * Usually the order in which interceptors are executed should not matter as
+ * long as they do not depend on a particular state of the execution context.
+ * If protocol interceptors have interdependencies and therefore must be
+ * executed in a particular order, they should be added to the protocol
+ * processor in the same sequence as their expected execution order.
+ * <p>
+ * Protocol interceptors must be implemented as thread-safe. Similarly to
+ * servlets, protocol interceptors should not use instance variables unless
+ * access to those variables is synchronized.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
* @author <a href="mailto:rolandw at apache.org">Roland Weber</a>