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 2009/01/04 23:59:40 UTC
svn commit: r731381 - in
/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http:
./ protocol/
Author: olegk
Date: Sun Jan 4 14:59:39 2009
New Revision: 731381
URL: http://svn.apache.org/viewvc?rev=731381&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/protocol/HttpExpectationVerifier.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestExecutor.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandler.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerRegistry.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerResolver.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestInterceptorList.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpResponseInterceptorList.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpService.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestConnControl.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestContent.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestDate.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestExpectContinue.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestTargetHost.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestUserAgent.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseConnControl.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseContent.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseDate.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseServer.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/UriPatternMatcher.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=731381&r1=731380&r2=731381&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 Sun Jan 4 14:59:39 2009
@@ -69,8 +69,8 @@
* @param request the request to preprocess
* @param context the context for the request
*
- * @throws IOException in case of an IO problem
- * @throws HttpException in case of a protocol or other problem
+ * @throws HttpException in case of an HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void process(HttpRequest request, HttpContext context)
throws HttpException, IOException;
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=731381&r1=731380&r2=731381&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 Sun Jan 4 14:59:39 2009
@@ -68,8 +68,8 @@
* @param response the response to postprocess
* @param context the context for the request
*
- * @throws IOException in case of an IO problem
- * @throws HttpException in case of a protocol or other problem
+ * @throws HttpException in case of an HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void process(HttpResponse response, HttpContext context)
throws HttpException, IOException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpExpectationVerifier.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpExpectationVerifier.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpExpectationVerifier.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpExpectationVerifier.java Sun Jan 4 14:59:39 2009
@@ -67,6 +67,22 @@
*/
public interface HttpExpectationVerifier {
+ /**
+ * Verifies whether the given request meets the server's expectations.
+ * <p>
+ * If the request fails to meet particular criteria, this method can
+ * trigger a terminal response back to the client by setting the status
+ * code of the response object to a value greater or equal to
+ * <code>200</code>. In this case the client will not have to transmit
+ * the request body. If the request meets expectations this method can
+ * terminate without modifying the response object. Per default the status
+ * code of the response object will be set to <code>100</code>.
+ *
+ * @param request the HTTP request.
+ * @param response the HTTP response.
+ * @param context the HTTP context.
+ * @throws HttpException in case of an HTTP protocol violation.
+ */
void verify(HttpRequest request, HttpResponse response, HttpContext context)
throws HttpException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestExecutor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestExecutor.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestExecutor.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestExecutor.java Sun Jan 4 14:59:39 2009
@@ -35,6 +35,7 @@
import java.net.ProtocolException;
import org.apache.http.HttpClientConnection;
+import org.apache.http.HttpEntity;
import org.apache.http.HttpEntityEnclosingRequest;
import org.apache.http.HttpException;
import org.apache.http.HttpRequest;
@@ -45,9 +46,15 @@
import org.apache.http.params.CoreProtocolPNames;
/**
- * Sends HTTP requests and receives the responses.
- * Takes care of request preprocessing and response postprocessing
- * by the respective interceptors.
+ * HttpRequestExecutor is a client side HTTP protocol handler based on the
+ * blocking I/O model that implements the essential requirements of the HTTP
+ * protocol for the client side message processing, as described by RFC 2616.
+ * <br>
+ * HttpRequestExecutor relies on {@link HttpProcessor} to generate mandatory
+ * protocol headers for all outgoing messages and apply common, cross-cutting
+ * message transformations to all incoming and outgoing messages. Application
+ * specific processing can be implemented outside HttpRequestExecutor once the
+ * request has been executed and a response has been received.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -67,8 +74,6 @@
/**
* Decide whether a response comes with an entity.
* The implementation in this class is based on RFC 2616.
- * Unknown methods and response codes are supposed to
- * indicate responses with an entity.
* <br/>
* Derived executors can override this method to handle
* methods and response codes not specified in RFC 2616.
@@ -90,15 +95,16 @@
}
/**
- * Synchronously send a request and obtain the response.
+ * Sends the request and obtain a response.
*
- * @param request the request to send. It will be preprocessed.
- * @param conn the open connection over which to send
+ * @param request the request to execute.
+ * @param conn the connection over which to execute the request.
*
- * @return the response to the request, postprocessed
+ * @return the response to the request.
*
- * @throws HttpException in case of a protocol or processing problem
- * @throws IOException in case of an I/O problem
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
*/
public HttpResponse execute(
final HttpRequest request,
@@ -134,14 +140,16 @@
}
/**
- * Prepare a request for sending.
+ * Pre-process the given request using the given protocol processor and
+ * initiates the process of request execution.
*
* @param request the request to prepare
* @param processor the processor to use
* @param context the context for sending the request
*
- * @throws HttpException in case of a protocol or processing problem
- * @throws IOException in case of an I/O problem
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
*/
public void preProcess(
final HttpRequest request,
@@ -157,11 +165,13 @@
if (context == null) {
throw new IllegalArgumentException("HTTP context may not be null");
}
+ context.setAttribute(ExecutionContext.HTTP_REQUEST, request);
processor.process(request, context);
}
/**
- * Send a request over a connection.
+ * Send the given request over the given connection.
+ * <p>
* This method also handles the expect-continue handshake if necessary.
* If it does not have to handle an expect-continue handshake, it will
* not use the connection for reading or anything else that depends on
@@ -177,8 +187,9 @@
* handshake, or
* <code>null</code> if the expect-continue handshake is not used
*
- * @throws HttpException in case of a protocol or processing problem
- * @throws IOException in case of an I/O problem
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
*/
protected HttpResponse doSendRequest(
final HttpRequest request,
@@ -196,6 +207,8 @@
}
HttpResponse response = null;
+
+ context.setAttribute(ExecutionContext.HTTP_CONNECTION, conn);
context.setAttribute(ExecutionContext.HTTP_REQ_SENT, Boolean.FALSE);
conn.sendRequestHeader(request);
@@ -243,7 +256,7 @@
}
/**
- * Wait for and receive a response.
+ * Waits for and receives a response.
* This method will automatically ignore intermediate responses
* with status code 1xx.
*
@@ -251,10 +264,11 @@
* @param conn the connection over which the request was sent
* @param context the context for receiving the response
*
- * @return the final response, not yet post-processed
+ * @return the terminal response, not yet post-processed
*
- * @throws HttpException in case of a protocol or processing problem
- * @throws IOException in case of an I/O problem
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
*/
protected HttpResponse doReceiveResponse(
final HttpRequest request,
@@ -289,18 +303,21 @@
}
/**
- * Finish a response.
- * This includes post-processing of the response object.
- * It does <i>not</i> read the response entity, if any.
- * It does <i>not</i> allow for immediate re-use of the
- * connection over which the response is coming in.
+ * Post-processes the given response using the given protocol processor and
+ * completes the process of request execution.
+ * <p>
+ * This method does <i>not</i> read the response entity, if any.
+ * The connection over which content of the response entity is being
+ * streamed from cannot be reused until {@link HttpEntity#consumeContent()}
+ * has been invoked.
*
- * @param response the response object to finish
+ * @param response the response object to post-process
* @param processor the processor to use
* @param context the context for post-processing the response
*
- * @throws HttpException in case of a protocol or processing problem
- * @throws IOException in case of an I/O problem
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
*/
public void postProcess(
final HttpResponse response,
@@ -316,6 +333,7 @@
if (context == null) {
throw new IllegalArgumentException("HTTP context may not be null");
}
+ context.setAttribute(ExecutionContext.HTTP_RESPONSE, response);
processor.process(response, context);
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandler.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandler.java Sun Jan 4 14:59:39 2009
@@ -38,6 +38,12 @@
import org.apache.http.HttpResponse;
/**
+ * HttpRequestHandler represents a routine for processing of a specific group
+ * of HTTP requests. Protocol handlers are designed to take care of protocol
+ * specific aspects, whereas individual request handlers are expected to take
+ * care of application specific HTTP processing. The main purpose of a request
+ * handler is to generate a response object with a content entity to be sent
+ * back to the client in response to the given request
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -47,6 +53,17 @@
*/
public interface HttpRequestHandler {
+ /**
+ * Handles the request and produces a response to be sent back to
+ * the client.
+ *
+ * @param request the HTTP request.
+ * @param response the HTTP response.
+ * @param context the HTTP execution context.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
+ */
void handle(HttpRequest request, HttpResponse response, HttpContext context)
throws HttpException, IOException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerRegistry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerRegistry.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerRegistry.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerRegistry.java Sun Jan 4 14:59:39 2009
@@ -35,14 +35,18 @@
/**
* Maintains a map of HTTP request handlers keyed by a request URI pattern.
- * {@link HttpRequestHandler} instances can be looked up by request URI
- * using the {@link HttpRequestHandlerResolver} interface.<br/>
+ * <br>
* Patterns may have three formats:
* <ul>
* <li><code>*</code></li>
* <li><code>*<uri></code></li>
* <li><code><uri>*</code></li>
* </ul>
+ * <br>
+ * This class can be used to resolve an instance of
+ * {@link HttpRequestHandler} matching a particular request URI. Usually the
+ * resolved request handler will be used to process the request with the
+ * specified request URI.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -56,14 +60,36 @@
matcher = new UriPatternMatcher();
}
+ /**
+ * Registers the given {@link HttpRequestHandler} as a handler for URIs
+ * matching the given pattern.
+ *
+ * @param pattern the pattern to register the handler for.
+ * @param handler the handler.
+ */
public void register(final String pattern, final HttpRequestHandler handler) {
+ if (pattern == null) {
+ throw new IllegalArgumentException("URI request pattern may not be null");
+ }
+ if (handler == null) {
+ throw new IllegalArgumentException("Request handler may not be null");
+ }
matcher.register(pattern, handler);
}
+ /**
+ * Removes registered handler, if exists, for the given pattern.
+ *
+ * @param pattern the pattern to unregister the handler for.
+ */
public void unregister(final String pattern) {
matcher.unregister(pattern);
}
+ /**
+ * Sets handlers from the given map.
+ * @param map the map containing handlers keyed by their URI patterns.
+ */
public void setHandlers(final Map map) {
matcher.setHandlers(map);
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerResolver.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerResolver.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerResolver.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestHandlerResolver.java Sun Jan 4 14:59:39 2009
@@ -32,8 +32,10 @@
package org.apache.http.protocol;
/**
- * Interface to be implemented by objects that can resolve
- * {@link HttpRequestHandler} instances by request URI.
+ * HttpRequestHandlerResolver can be used to resolve an instance of
+ * {@link HttpRequestHandler} matching a particular request URI. Usually the
+ * resolved request handler will be used to process the request with the
+ * specified request URI.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -41,6 +43,13 @@
*/
public interface HttpRequestHandlerResolver {
+ /**
+ * Looks up a handler matching the given request URI.
+ *
+ * @param requestURI the request URI
+ * @return HTTP request handler or <code>null</code> if no match
+ * is found.
+ */
HttpRequestHandler lookup(String requestURI);
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestInterceptorList.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestInterceptorList.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestInterceptorList.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpRequestInterceptorList.java Sun Jan 4 14:59:39 2009
@@ -51,29 +51,24 @@
/**
* Appends a request interceptor to this list.
*
- * @param itcp the request interceptor to add
+ * @param interceptor the request interceptor to add
*/
- void addRequestInterceptor(HttpRequestInterceptor itcp)
- ;
-
+ void addRequestInterceptor(HttpRequestInterceptor interceptor);
/**
* Inserts a request interceptor at the specified index.
*
- * @param itcp the request interceptor to add
+ * @param interceptor the request interceptor to add
* @param index the index to insert the interceptor at
*/
- void addRequestInterceptor(HttpRequestInterceptor itcp, int index);
-
+ void addRequestInterceptor(HttpRequestInterceptor interceptor, int index);
/**
* Obtains the current size of this list.
*
* @return the number of request interceptors in this list
*/
- int getRequestInterceptorCount()
- ;
-
+ int getRequestInterceptorCount();
/**
* Obtains a request interceptor from this list.
@@ -84,16 +79,12 @@
* @return the interceptor at the given index, or
* <code>null</code> if the index is out of range
*/
- HttpRequestInterceptor getRequestInterceptor(int index)
- ;
-
+ HttpRequestInterceptor getRequestInterceptor(int index);
/**
* Removes all request interceptors from this list.
*/
- void clearRequestInterceptors()
- ;
-
+ void clearRequestInterceptors();
/**
* Removes all request interceptor of the specified class
@@ -102,7 +93,6 @@
*/
void removeRequestInterceptorByClass(Class clazz);
-
/**
* Sets the request interceptors in this list.
* This list will be cleared and re-initialized to contain
@@ -110,11 +100,9 @@
* If the argument list includes elements that are not request
* interceptors, the behavior is implementation dependent.
*
- * @param itcps the list of request interceptors
+ * @param list the list of request interceptors
*/
- void setInterceptors(List itcps)
- ;
-
+ void setInterceptors(List list);
-} // interface HttpRequestInterceptorList
+}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpResponseInterceptorList.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpResponseInterceptorList.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpResponseInterceptorList.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpResponseInterceptorList.java Sun Jan 4 14:59:39 2009
@@ -31,12 +31,10 @@
package org.apache.http.protocol;
-
import java.util.List;
import org.apache.http.HttpResponseInterceptor;
-
/**
* Provides access to an ordered list of response interceptors.
* Lists are expected to be built upfront and used read-only afterwards
@@ -53,28 +51,24 @@
/**
* Appends a response interceptor to this list.
*
- * @param itcp the response interceptor to add
+ * @param interceptor the response interceptor to add
*/
- void addResponseInterceptor(HttpResponseInterceptor itcp)
- ;
+ void addResponseInterceptor(HttpResponseInterceptor interceptor);
/**
* Inserts a response interceptor at the specified index.
*
- * @param itcp the response interceptor to add
+ * @param interceptor the response interceptor to add
* @param index the index to insert the interceptor at
*/
- void addResponseInterceptor(HttpResponseInterceptor itcp, int index);
-
+ void addResponseInterceptor(HttpResponseInterceptor interceptor, int index);
/**
* Obtains the current size of this list.
*
* @return the number of response interceptors in this list
*/
- int getResponseInterceptorCount()
- ;
-
+ int getResponseInterceptorCount();
/**
* Obtains a response interceptor from this list.
@@ -85,17 +79,13 @@
* @return the interceptor at the given index, or
* <code>null</code> if the index is out of range
*/
- HttpResponseInterceptor getResponseInterceptor(int index)
- ;
-
+ HttpResponseInterceptor getResponseInterceptor(int index);
/**
* Removes all response interceptors from this list.
*/
- void clearResponseInterceptors()
- ;
+ void clearResponseInterceptors();
-
/**
* Removes all response interceptor of the specified class
*
@@ -103,7 +93,6 @@
*/
void removeResponseInterceptorByClass(Class clazz);
-
/**
* Sets the response interceptors in this list.
* This list will be cleared and re-initialized to contain
@@ -111,11 +100,9 @@
* If the argument list includes elements that are not response
* interceptors, the behavior is implementation dependent.
*
- * @param itcps the list of response interceptors
+ * @param list the list of response interceptors
*/
- void setInterceptors(List itcps)
- ;
-
+ void setInterceptors(List list);
-} // interface HttpResponseInterceptorList
+}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpService.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpService.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpService.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/HttpService.java Sun Jan 4 14:59:39 2009
@@ -53,7 +53,21 @@
import org.apache.http.util.EncodingUtils;
/**
- * Minimalistic server-side implementation of an HTTP processor.
+ * HttpService is a server side HTTP protocol handler based in the blocking
+ * I/O model that implements the essential requirements of the HTTP protocol
+ * for the server side message processing as described by RFC 2616.
+ * <br>
+ * HttpService relies on {@link HttpProcessor} to generate mandatory protocol
+ * headers for all outgoing messages and apply common, cross-cutting message
+ * transformations to all incoming and outgoing messages, whereas individual
+ * {@link HttpRequestHandler}s are expected to take care of application specific
+ * content generation and processing.
+ * <br>
+ * HttpService relies on {@link HttpRequestHandler} to resolve matching request
+ * handler for a particular request URI of an incoming HTTP request.
+ * <br>
+ * HttpService can use optional {@link HttpExpectationVerifier} to ensure that
+ * incoming requests meet server's expectations.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -87,7 +101,7 @@
public void setHttpProcessor(final HttpProcessor processor) {
if (processor == null) {
- throw new IllegalArgumentException("HTTP processor may not be null.");
+ throw new IllegalArgumentException("HTTP processor may not be null");
}
this.processor = processor;
}
@@ -122,6 +136,16 @@
this.params = params;
}
+ /**
+ * Handles receives one HTTP request over the given connection within the
+ * given execution context and sends a response back to the client.
+ *
+ * @param conn the active connection to the client
+ * @param context the actual execution context.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
+ */
public void handleRequest(
final HttpServerConnection conn,
final HttpContext context) throws IOException, HttpException {
@@ -213,7 +237,15 @@
conn.close();
}
}
-
+
+ /**
+ * Handles the given exception and generates an HTTP response to be sent
+ * back to the client to inform about the exceptional condition encountered
+ * in the course of the request processing.
+ *
+ * @param ex the exception.
+ * @param response the HTTP response.
+ */
protected void handleException(final HttpException ex, final HttpResponse response) {
if (ex instanceof MethodNotSupportedException) {
response.setStatusCode(HttpStatus.SC_NOT_IMPLEMENTED);
@@ -230,6 +262,23 @@
response.setEntity(entity);
}
+ /**
+ * The default implementation of this method attempts to resolve an
+ * {@link HttpRequestHandler} for the request URI of the given request
+ * and, if found, executes its
+ * {@link HttpRequestHandler#handle(HttpRequest, HttpResponse, HttpContext)}
+ * method.
+ * <p>
+ * Super-classes can override this method in order to provide a custom
+ * implementation of the request processing logic.
+ *
+ * @param request the HTTP request.
+ * @param response the HTTP response.
+ * @param context the execution context.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
+ */
protected void doService(
final HttpRequest request,
final HttpResponse response,
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestConnControl.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestConnControl.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestConnControl.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestConnControl.java Sun Jan 4 14:59:39 2009
@@ -38,7 +38,10 @@
import org.apache.http.HttpRequestInterceptor;
/**
- * A request interceptor that suggests connection keep-alive to the server.
+ * RequestConnControl is responsible for adding <code>Connection</code> header
+ * to the outgoing requests, which is essential for managing persistence of
+ * <code>HTTP/1.0</code> connections. This interceptor is recommended for
+ * client side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestContent.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestContent.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestContent.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestContent.java Sun Jan 4 14:59:39 2009
@@ -43,8 +43,13 @@
import org.apache.http.ProtocolException;
/**
- * A request interceptor that decides about the transport encoding.
- *
+ * RequestContent is the most important interceptor for outgoing requests.
+ * It is responsible for delimiting content length by adding
+ * <code>Content-Length</code> or <code>Transfer-Content</code> headers based
+ * on the properties of the enclosed entity and the protocol version.
+ * This interceptor is required for correct functioning of client side protocol
+ * processors.
+
* @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/protocol/RequestDate.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestDate.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestDate.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestDate.java Sun Jan 4 14:59:39 2009
@@ -39,8 +39,9 @@
import org.apache.http.HttpRequestInterceptor;
/**
- * A request interceptor that adds a Date header.
- * For use on the client side.
+ * RequestDate interceptor is responsible for adding <code>Date</code> header
+ * to the outgoing requests This interceptor is optional for client side
+ * protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestExpectContinue.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestExpectContinue.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestExpectContinue.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestExpectContinue.java Sun Jan 4 14:59:39 2009
@@ -43,7 +43,9 @@
import org.apache.http.params.HttpProtocolParams;
/**
- * A request interceptor that enables the expect-continue handshake.
+ * RequestExpectContinue is responsible for enabling the 'expect-continue'
+ * handshake by adding <code>Expect</code> header. This interceptor is
+ * recommended for client side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestTargetHost.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestTargetHost.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestTargetHost.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestTargetHost.java Sun Jan 4 14:59:39 2009
@@ -45,7 +45,8 @@
import org.apache.http.ProtocolException;
/**
- * A request interceptor that sets the Host header for HTTP/1.1 requests.
+ * RequestTargetHost is responsible for adding <code>Host</code> header. This
+ * interceptor is required for client side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestUserAgent.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestUserAgent.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestUserAgent.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/RequestUserAgent.java Sun Jan 4 14:59:39 2009
@@ -39,7 +39,8 @@
import org.apache.http.params.HttpProtocolParams;
/**
- * A request interceptor that adds a User-Agent header.
+ * RequestUserAgent is responsible for adding <code>User-Agent</code> header.
+ * This interceptor is recommended for client side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseConnControl.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseConnControl.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseConnControl.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseConnControl.java Sun Jan 4 14:59:39 2009
@@ -44,8 +44,10 @@
import org.apache.http.ProtocolVersion;
/**
- * A response interceptor that suggests connection keep-alive to the client.
- * For use on the server side.
+ * ResponseConnControl is responsible for adding <code>Connection</code> header
+ * to the outgoing responses, which is essential for managing persistence of
+ * <code>HTTP/1.0</code> connections. This interceptor is recommended for
+ * server side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseContent.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseContent.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseContent.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseContent.java Sun Jan 4 14:59:39 2009
@@ -43,8 +43,12 @@
import org.apache.http.ProtocolException;
/**
- * A response interceptor that sets up entity-related headers.
- * For use on the server side.
+ * ResponseContent is the most important interceptor for outgoing responses.
+ * It is responsible for delimiting content length by adding
+ * <code>Content-Length</code> or <code>Transfer-Content</code> headers based
+ * on the properties of the enclosed entity and the protocol version.
+ * This interceptor is required for correct functioning of server side protocol
+ * processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseDate.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseDate.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseDate.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseDate.java Sun Jan 4 14:59:39 2009
@@ -39,9 +39,10 @@
import org.apache.http.HttpStatus;
/**
- * A response interceptor that adds a Date header.
- * For use on the server side.
- *
+ * ResponseDate is responsible for adding <code>Date<c/ode> header to the
+ * outgoing responses. This interceptor is recommended for server side protocol
+ * processors.
+ *
* @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/protocol/ResponseServer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseServer.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseServer.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/ResponseServer.java Sun Jan 4 14:59:39 2009
@@ -39,8 +39,8 @@
import org.apache.http.params.CoreProtocolPNames;
/**
- * A response interceptor that adds a Server header.
- * For use on the server side.
+ * ResponseServer is responsible for adding <code>Server</code> header. This
+ * interceptor is recommended for server side protocol processors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/UriPatternMatcher.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/UriPatternMatcher.java?rev=731381&r1=731380&r2=731381&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/UriPatternMatcher.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/UriPatternMatcher.java Sun Jan 4 14:59:39 2009
@@ -37,13 +37,16 @@
/**
* Maintains a map of objects keyed by a request URI pattern.
- * Instances can be looked up by request URI.<br/>
+ * <br>
* Patterns may have three formats:
* <ul>
* <li><code>*</code></li>
* <li><code>*<uri></code></li>
* <li><code><uri>*</code></li>
* </ul>
+ * <br>
+ * This class can be used to resolve an object matching a particular request
+ * URI.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -51,38 +54,58 @@
*/
public class UriPatternMatcher {
- private final Map handlerMap;
+ private final Map map;
public UriPatternMatcher() {
super();
- this.handlerMap = new HashMap();
+ this.map = new HashMap();
}
- public void register(final String pattern, final Object handler) {
+ /**
+ * Registers the given object for URIs matching the given pattern.
+ *
+ * @param pattern the pattern to register the handler for.
+ * @param obj the object.
+ */
+ public void register(final String pattern, final Object obj) {
if (pattern == null) {
throw new IllegalArgumentException("URI request pattern may not be null");
}
- if (handler == null) {
- throw new IllegalArgumentException("HTTP request handelr may not be null");
- }
- this.handlerMap.put(pattern, handler);
+ this.map.put(pattern, obj);
}
+ /**
+ * Removes registered object, if exists, for the given pattern.
+ *
+ * @param pattern the pattern to unregister.
+ */
public void unregister(final String pattern) {
if (pattern == null) {
return;
}
- this.handlerMap.remove(pattern);
+ this.map.remove(pattern);
}
+ /**
+ * Sets objects from the given map.
+ * @param map the map containing objects keyed by their URI patterns.
+ * <br>
+ * TODO: deprecate and rename to setObjects()
+ */
public void setHandlers(final Map map) {
if (map == null) {
throw new IllegalArgumentException("Map of handlers may not be null");
}
- this.handlerMap.clear();
- this.handlerMap.putAll(map);
+ this.map.clear();
+ this.map.putAll(map);
}
+ /**
+ * Looks up an object matching the given request URI.
+ *
+ * @param requestURI the request URI
+ * @return object or <code>null</code> if no match is found.
+ */
public Object lookup(String requestURI) {
if (requestURI == null) {
throw new IllegalArgumentException("Request URI may not be null");
@@ -94,18 +117,18 @@
}
// direct match?
- Object handler = this.handlerMap.get(requestURI);
+ Object handler = this.map.get(requestURI);
if (handler == null) {
// pattern match?
String bestMatch = null;
- for (Iterator it = this.handlerMap.keySet().iterator(); it.hasNext();) {
+ for (Iterator it = this.map.keySet().iterator(); it.hasNext();) {
String pattern = (String) it.next();
if (matchUriRequestPattern(pattern, requestURI)) {
// we have a match. is it any better?
if (bestMatch == null
|| (bestMatch.length() < pattern.length())
|| (bestMatch.length() == pattern.length() && pattern.endsWith("*"))) {
- handler = this.handlerMap.get(pattern);
+ handler = this.map.get(pattern);
bestMatch = pattern;
}
}
@@ -114,6 +137,14 @@
return handler;
}
+ /**
+ * Tests if the given request URI matches the given pattern.
+ *
+ * @param pattern the pattern
+ * @param requestUri the request URI
+ * @return <code>true</code> if the request URI matches the pattern,
+ * <code>false</code> otherwise.
+ */
protected boolean matchUriRequestPattern(final String pattern, final String requestUri) {
if (pattern.equals("*")) {
return true;