hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r731381 - in /httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http: ./ protocol/
Date Sun, 04 Jan 2009 22:59:40 GMT
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>*&lt;uri&gt;</code></li>
  *   <li><code>&lt;uri&gt;*</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>*&lt;uri&gt;</code></li>
  *   <li><code>&lt;uri&gt;*</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;



Mime
View raw message