hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r733879 - in /httpcomponents/httpcore/trunk: module-main/src/main/java/org/apache/http/params/ module-main/src/main/java/org/apache/http/protocol/ module-nio/src/main/java/org/apache/http/impl/nio/reactor/ module-nio/src/main/java/org/apach...
Date Mon, 12 Jan 2009 19:55:55 GMT
Author: olegk
Date: Mon Jan 12 11:55:23 2009
New Revision: 733879

URL: http://svn.apache.org/viewvc?rev=733879&view=rev
Log:
Javadoc updates

Added:
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html
Modified:
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html
    httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java
    httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html Mon Jan 12 11:55:23 2009
@@ -34,7 +34,7 @@
 -->
 </head>
 <body>
-The parameterization framework for HTTP components.
-
+The parameterization framework for HTTP components. This package also provides 
+core protocol and I/O parameters.
 </body>
 </html>

Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html Mon Jan 12 11:55:23 2009
@@ -34,79 +34,8 @@
 -->
 </head>
 <body>
-HTTP protocol execution framework.
-
-Apart from simply sending and receiving messages, there are a lot
-of things to consider when communicating with HTTP. Many details
-such as transport encodings or connection management are handled
-by setting up or interpreting
-{@link org.apache.http.Header headers} in the messages.
-In order to relieve applications from the responsibility of
-implementing these nitty-gritty details of the protocol,
-HTTP components provides an execution framework that sets up
-some of the headers before sending a message, and interprets
-headers when a message has been received.
-<br/>
-An HTTP {@link org.apache.http.protocol.HttpProcessor processor}
-typically keeps lists of so-called interceptors that will be executed
-before a message is sent and after it has been received.
-An application should initialize a processor, set up the lists
-with the required and desired processors, and then communicate
-through that processor. There are four kinds of interceptors,
-depending on whether they act on
-{@link org.apache.http.HttpRequestInterceptor requests} or
-{@link org.apache.http.HttpResponseInterceptor responses},
-on the client or server side:
-
-<table border="1" cellpadding="5">
-<tr><th></th>
-    <th>Client</th>
-    <th>Server</th>
-</tr>
-<tr><th>Request</th>
-    <td>prepares headers before a request is sent</td>
-    <td>interprets headers when a request is received</td>
-</tr>
-<tr><th>Response</th>
-    <td>interprets headers when a response is received</td>
-    <td>prepares headers before a response is sent</td>
-</tr>
-</table>
-
-<p>
-{@link org.apache.http.protocol.HttpRequestExecutor HttpRequestExecutor}
-is a processor for the client side,
-{@link org.apache.http.protocol.HttpService HttpService}
-for the server side.
-On the client side, a {@link org.apache.http.protocol.HttpContext context}
-is used to tie together a request, the response to it, and other data
-that might be associated with the request execution. It is passed to
-the request executor whenever needed.
-</p>
-
-<p>
-<font size="+1">
-<i>
-Information about required and recommended interceptors for the
-client side will be provided elsewhere. For the time being, please
-refer to the comments in the example applications or ask on
-one of the mailing lists.
-</i>
-</font>
-</p>
-
-<p>
-<b>Note:</b>
-If you want to develop a server-side application, we recommend that
-you implement your application as a servlet running in a servlet engine
-like <a href="http://tomcat.apache.org/">Tomcat</a> or full-blown
-JSEE container like <a href="http://geronimo.apache.org/">Geronimo</a>.
-If you prefer to implement a server-side application based on our
-{@link org.apache.http.protocol.HttpService HttpService}, we'll
-assume that you know what you're doing and that you don't need
-help in figuring out which interceptors need to be configured.
-</p>
-
-
+HTTP protocol execution framework. This package contains common protocol
+aspects implemented as protocol interceptors  as well as protocol handler 
+implementations based on classic (blocking) I/O model. 
 </body>
 </html>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java Mon Jan 12 11:55:23 2009
@@ -52,6 +52,11 @@
 import org.apache.http.nio.reactor.IOReactorStatus;
 import org.apache.http.nio.reactor.IOSession;
 
+/**
+ * Generic implementation of {@link IOReactor} that can used as a subclass 
+ * for more specialized I/O reactors. It is based on a single {@link Selector}
+ * instance.
+ */
 public abstract class AbstractIOReactor implements IOReactor {
 
     private volatile IOReactorStatus status;
@@ -63,6 +68,11 @@
     private final Queue<IOSession> closedSessions;
     private final Queue<ChannelEntry> newChannels;
     
+    /**
+     * Creates new AbstractIOReactor instance.
+     * @param selectTimeout the select timeout.
+     * @throws IOReactorException in case if a non-recoverable I/O error. 
+     */
     public AbstractIOReactor(long selectTimeout) throws IOReactorException {
         super();
         if (selectTimeout <= 0) {
@@ -81,28 +91,83 @@
         this.status = IOReactorStatus.INACTIVE;
     }
 
+    /**
+     * Triggered when the key signals {@link SelectionKey#OP_ACCEPT} readiness.
+     * 
+     * @param key the selection key.
+     */
     protected abstract void acceptable(SelectionKey key);
     
+    /**
+     * Triggered when the key signals {@link SelectionKey#OP_CONNECT} readiness.
+     * 
+     * @param key the selection key.
+     */
     protected abstract void connectable(SelectionKey key);
 
+    /**
+     * Triggered when the key signals {@link SelectionKey#OP_READ} readiness.
+     * 
+     * @param key the selection key.
+     */
     protected abstract void readable(SelectionKey key);
 
+    /**
+     * Triggered when the key signals {@link SelectionKey#OP_WRITE} readiness.
+     * 
+     * @param key the selection key.
+     */
     protected abstract void writable(SelectionKey key);
     
+    /**
+     * Triggered to verify whether the key has not timed out.
+     * 
+     * @param key the selection key.
+     * @param current time as long value.
+     */
     protected abstract void timeoutCheck(SelectionKey key, long now);
 
+    /**
+     * Triggered to validate keys currently registered with the selector.
+     * 
+     * @param keys all selection keys registered with the selector.
+     */
     protected abstract void validate(Set<SelectionKey> keys);
     
+    /**
+     * Triggered when new session has been created.
+     * 
+     * @param key the selection key.
+     * @param session new I/O session.
+     */
     protected abstract void sessionCreated(SelectionKey key, IOSession session);
     
-    protected abstract IOSession getSession(SelectionKey key);
-    
+    /**
+     * Triggered when a session has been closed.
+     * 
+     * @param session closed I/O session.
+     */
     protected abstract void sessionClosed(IOSession session);
     
+    /**
+     * Obtains {@link IOSession} instance associated with the given selection
+     * key.
+     * 
+     * @param key the selection key.
+     * @return I/O session.
+     */
+    protected abstract IOSession getSession(SelectionKey key);
+    
     public IOReactorStatus getStatus() {
         return this.status;
     }
 
+    /**
+     * Adds new channel entry. The channel will be asynchronously registered
+     * with the selector.
+     *  
+     * @param channelEntry the channel entry.
+     */
     public void addChannel(final ChannelEntry channelEntry) {
         if (channelEntry == null) {
             throw new IllegalArgumentException("Channel entry may not be null");
@@ -183,7 +248,12 @@
         }
         selectedKeys.clear();
     }
-
+    
+    /**
+     * Processes new event on the given selection key.
+     * 
+     * @param key the selection key that triggered an event.
+     */
     protected void processEvent(final SelectionKey key) {
         try {
             if (key.isAcceptable()) {
@@ -205,6 +275,11 @@
         }
     }
 
+    /**
+     * Queues the given I/O session to be processed asynchronously as closed.
+     *  
+     * @param session the closed I/O session.
+     */
     protected void queueClosedSession(final IOSession session) {
         if (session != null) {
             this.closedSessions.add(session);
@@ -282,6 +357,9 @@
         }
     }
 
+    /**
+     * Closes out all I/O sessions maintained by this I/O reactor.
+     */
     protected void closeSessions() {
         synchronized (this.sessions) {
             for (Iterator<IOSession> it = this.sessions.iterator(); it.hasNext(); ) {
@@ -291,6 +369,10 @@
         }
     }
     
+    /**
+     * Closes out all new channels pending registration with the selector of 
+     * this I/O reactor.
+     */
     protected void closeNewChannels() throws IOReactorException {
         ChannelEntry entry;
         while ((entry = this.newChannels.poll()) != null) {
@@ -306,6 +388,10 @@
         }
     }
     
+    /**
+     * Closes out all active channels registered with the selector of 
+     * this I/O reactor.
+     */
     protected void closeActiveChannels() throws IOReactorException {
         Set<SelectionKey> keys = this.selector.keys();
         for (Iterator<SelectionKey> it = keys.iterator(); it.hasNext(); ) {
@@ -324,6 +410,9 @@
         }
     }
     
+    /**
+     * Attempts graceful shutdown of this I/O reactor.
+     */
     public void gracefulShutdown() {
         if (this.status != IOReactorStatus.ACTIVE) {
             // Already shutting down
@@ -333,6 +422,9 @@
         this.selector.wakeup();
     }
         
+    /**
+     * Attempts force-shutdown of this I/O reactor.
+     */
     public void hardShutdown() throws IOReactorException {
         if (this.status == IOReactorStatus.SHUT_DOWN) {
             // Already shut down
@@ -343,6 +435,13 @@
         closeActiveChannels();
     }
     
+    /**
+     * Blocks for the given period of time in milliseconds awaiting 
+     * the completion of the reactor shutdown.
+     *  
+     * @param timeout the maximum wait time.
+     * @throws InterruptedException if interrupted.
+     */
     public void awaitShutdown(long timeout) throws InterruptedException {
         synchronized (this.shutdownMutex) {
             long deadline = System.currentTimeMillis() + timeout;

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java Mon Jan 12 11:55:23 2009
@@ -33,11 +33,27 @@
 
 import java.nio.channels.SocketChannel;
 
+/**
+ * {@link SocketChannel} entry maintained by the I/O reactor. If the channel
+ *  represents an outgoing client connection, this entry also contains the
+ *  original {@link SessionRequestImpl} used to request it.
+ *  
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
 public class ChannelEntry {
 
     private final SocketChannel channel;
     private final SessionRequestImpl sessionRequest;
     
+    /**
+     * Creates new ChannelEntry.
+     * 
+     * @param channel the channel
+     * @param sessionRequest original session request. Can be <code>null</code>
+     *   if the channel represents an incoming server-side connection.
+     */
     public ChannelEntry(final SocketChannel channel, final SessionRequestImpl sessionRequest) {
         super();
         if (channel == null) {
@@ -47,14 +63,33 @@
         this.sessionRequest = sessionRequest;
     }
 
+    /**
+     * Creates new ChannelEntry.
+     * 
+     * @param channel the channel.
+     */
     public ChannelEntry(final SocketChannel channel) {
         this(channel, null);
     }
 
+    /**
+     * Returns the original session request, if available. If the channel
+     * entry represents an incoming server-side connection, returns 
+     * <code>null</code>.
+     * 
+     * @return the original session request, if client-side channel,
+     *  <code>null</code> otherwise. 
+     */
     public SessionRequestImpl getSessionRequest() {
         return this.sessionRequest;
     }
 
+    /**
+     * Returns the original session request attachment, if available.
+     * 
+     * @return the original session request attachment, if available,
+     *  <code>null</code> otherwise. 
+     */
     public Object getAttachment() {
         if (this.sessionRequest != null) {
             return this.sessionRequest.getAttachment();
@@ -63,6 +98,11 @@
         }
     }
 
+    /**
+     * Returns the channel.
+     * 
+     * @return the channel.
+     */
     public SocketChannel getChannel() {
         return this.channel;
     }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html Mon Jan 12 11:55:23 2009
@@ -34,8 +34,8 @@
 -->
 </head>
 <body>
-NIO based implementations of HttpCore interfaces.
-This includes default implementations for the interfaces in
-{@link org.apache.http.nio org.apache.http.nio}.
+Default implementations for interfaces in 
+{@link org.apache.http.nio org.apache.http.nio} including default 
+I/O reactor implementations and support for SSL/TLS transport security. 
 </body>
 </html>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -81,13 +81,19 @@
     public void consumeContent() throws IOException {
     }
 
+    /**
+     * Obtains entity's content as {@link InputStream}.
+     * 
+     *  @throws IllegalStateException if content of the entity has not been
+     *    fully received or has already been consumed. 
+     */
     @Override
     public InputStream getContent() throws IOException {
         if (!this.finished) {
             throw new IllegalStateException("Entity content has not been fully received");
         }
         if (this.consumed) {
-            throw new IllegalStateException("Entity content has not been consumed");
+            throw new IllegalStateException("Entity content has been consumed");
         }
         this.consumed = true;
         return new ContentInputStream(this.buffer);

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -38,7 +38,7 @@
 import org.apache.http.nio.IOControl;
 
 /**
- * A non-blocking {@link HttpEntity} that allows content to be consumed from a 
+ * A non-blocking {@link HttpEntity} that allows content to be streamed from a 
  * {@link ContentDecoder}.
  *
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
@@ -50,6 +50,9 @@
      * {@link IOControl} instance passed as a parameter to the method can be 
      * used to suspend input events if the entity is temporarily unable to 
      * allocate more storage to accommodate all incoming content. 
+     * 
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
      */
     void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java Mon Jan 12 11:55:23 2009
@@ -36,11 +36,20 @@
 import org.apache.http.entity.BasicHttpEntity;
 import org.apache.http.nio.util.ContentInputBuffer;
 
+/**
+ * HTTP entity wrapper whose content is provided by a 
+ * {@link ContentInputBuffer}. 
+ */
 public class ContentBufferEntity extends BasicHttpEntity {
 
-    /** The wrapped entity. */
     private HttpEntity wrappedEntity;
     
+    /**
+     * Creates new instance of ContentBufferEntity.
+     * 
+     * @param entity the original entity.
+     * @param buffer the content buffer.
+     */
     public ContentBufferEntity(final HttpEntity entity, final ContentInputBuffer buffer) {
         super();
         if (entity == null) {

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java Mon Jan 12 11:55:23 2009
@@ -36,6 +36,9 @@
 
 import org.apache.http.nio.util.ContentInputBuffer;
 
+/**
+ * {@link InputStream} adaptor for {@link ContentInputBuffer}. 
+ */
 public class ContentInputStream extends InputStream {
 
     private final ContentInputBuffer buffer;

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -43,8 +43,12 @@
 
     /**
      * Notification that content is available to be read from the decoder.
+     * 
+     * @param decoder content decoder.
+     * @param ioctrl I/O control of the underlying connection.
      */
-    void contentAvailable(ContentDecoder decoder, IOControl ioctrl) throws IOException;
+    void contentAvailable(ContentDecoder decoder, IOControl ioctrl) 
+        throws IOException;
 
     /**
      * Notification that any resources allocated for reading can be released.

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java Mon Jan 12 11:55:23 2009
@@ -36,6 +36,9 @@
 
 import org.apache.http.nio.util.ContentOutputBuffer;
 
+/**
+ * {@link OutputStream} adaptor for {@link ContentOutputBuffer}.
+ */
 public class ContentOutputStream extends OutputStream {
 
     private final ContentOutputBuffer buffer;

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java Mon Jan 12 11:55:23 2009
@@ -43,8 +43,9 @@
 import org.apache.http.nio.protocol.AsyncNHttpServiceHandler;
 
 /**
- * An entity whose content is retrieved from a byte array.
- *
+ * A simple self contained, repeatable non-blocking entity that retrieves 
+ * its content from a byte array.
+ * 
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
  *
  * @version $Revision$

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java Mon Jan 12 11:55:23 2009
@@ -45,8 +45,11 @@
 import org.apache.http.nio.IOControl;
 
 /**
- * An entity whose content is retrieved from from a file.
- *
+ * A self contained, repeatable non-blocking entity that retrieves its content 
+ * from a file. This class is mostly used to stream large files of different 
+ * types, so one needs to supply the content type of the file to make sure 
+ * the content can be correctly recognized and processed by the recipient.
+ * 
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
  *
  * @version $Revision$
@@ -60,6 +63,17 @@
     private long idx = -1;
     private boolean useFileChannels;
 
+    /**
+     * Creates new instance of NFileEntity from the given source {@link File}
+     * with the given content type. If <code>useFileChannels</code> is set to
+     * <code>true</code>, the entity will try to use {@link FileContentEncoder}
+     * interface to stream file content directly from the file channel.
+     * 
+     * @param file the source file.
+     * @param contentType the content type of the file.
+     * @param useFileChannels flag whether the direct transfer from the file
+     *   channel should be attempted. 
+     */
     public NFileEntity(final File file, final String contentType, boolean useFileChannels) {
         if (file == null) {
             throw new IllegalArgumentException("File may not be null");

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java Mon Jan 12 11:55:23 2009
@@ -43,6 +43,10 @@
 import org.apache.http.nio.ContentEncoder;
 import org.apache.http.nio.IOControl;
 
+/**
+ * {@link ProducingNHttpEntity} compatibility adaptor for blocking HTTP 
+ * entities. 
+ */
 public class NHttpEntityWrapper
     extends HttpEntityWrapper implements ProducingNHttpEntity {
 
@@ -55,6 +59,9 @@
         this.buffer = ByteBuffer.allocate(4096);
     }
 
+    /**
+     * This method throws {@link UnsupportedOperationException}. 
+     */
     @Override
     public InputStream getContent() throws IOException, UnsupportedOperationException {
         throw new UnsupportedOperationException("Does not support blocking methods");
@@ -65,6 +72,9 @@
         return true;
     }
 
+    /**
+     * This method throws {@link UnsupportedOperationException}. 
+     */
     @Override
     public void writeTo(OutputStream out) throws IOException, UnsupportedOperationException {
         throw new UnsupportedOperationException("Does not support blocking methods");

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java Mon Jan 12 11:55:23 2009
@@ -45,8 +45,9 @@
 import org.apache.http.protocol.HTTP;
 
 /**
- * An entity whose content is retrieved from a string.
- *
+ * A simple, self contained, repeatable non-blocking entity that retrieves 
+ * its content from a {@link String} object.
+ * 
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
  *
  * @version $Revision$

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -38,7 +38,8 @@
 import org.apache.http.nio.IOControl;
 
 /**
- * An {@link HttpEntity} that writes content to a {@link ContentEncoder}.
+ * An {@link HttpEntity} that can stream content out into a 
+ * {@link ContentEncoder}.
  *
  * @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
  */
@@ -49,9 +50,12 @@
      * {@link IOControl} instance passed as a parameter to the method can be 
      * used to suspend output events if the entity is temporarily unable to 
      * produce more content.
-     * <b/>
+     * <p>
      * When all content is finished, this <b>MUST</b> call {@link ContentEncoder#complete()}.
      * Failure to do so could result in the entity never being written.
+     * 
+     * @param encoder content encoder.
+     * @param ioctrl I/O control of the underlying connection.
      */
     void produceContent(ContentEncoder encoder, IOControl ioctrl) throws IOException;
 

Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,52 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html $
+ * $Revision: 726457 $
+ * $Date: 2008-12-14 15:55:26 +0100 (Sun, 14 Dec 2008) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+Representations for non-blocking HTTP message entities.
+
+An {@link org.apache.http.HttpEntity entity} is the optional content of a
+{@link org.apache.http.HttpMessage message}.
+This package provides a basic selection of entity implementations 
+that can obtain content from
+{@link org.apache.http.nio.entity.NByteArrayEntity byte array},
+{@link org.apache.http.nio.entity.NStringEntity string},
+{@link org.apache.http.nio.entity.NFileEntity file}, or through an
+{@link org.apache.http.nio.entity.NHttpEntityWrapper compatibility adaptor}
+for blocking HTTP entities.
+If a message is received from an open non-blocking connection, usually it is 
+represented by 
+{@link org.apache.http.nio.entity.ConsumingNHttpEntity consuming} entity.
+</body>
+</html>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java Mon Jan 12 11:55:23 2009
@@ -31,9 +31,8 @@
 
 package org.apache.http.nio.params;
 
-
 /**
- * Parameter names for reactors in HttpNIO.
+ * Parameter names for I/O reactors.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  * 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java Mon Jan 12 11:55:23 2009
@@ -34,12 +34,7 @@
 import org.apache.http.params.HttpParams;
 
 /**
- * This class implements an adaptor around the {@link HttpParams} interface
- * to simplify manipulation of the NIO reactor specific parameters.
- * <br/>
- * Note that the <i>implements</i> relation to {@link NIOReactorPNames}
- * is for compatibility with existing application code only. References to
- * the parameter names should use the interface, not this class.
+ * Utility class for accessing I/O reactor parameters in {@link HttpParams}.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  * 

Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,39 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html $
+ * $Revision: 496070 $
+ * $Date: 2007-01-14 13:18:34 +0100 (Sun, 14 Jan 2007) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+HTTP parameters for I/O reactors based on NIO model.
+</body>
+</html>

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java Mon Jan 12 11:55:23 2009
@@ -57,14 +57,14 @@
  * blocking I/O by storing the full content of HTTP messages in memory. 
  * The {@link HttpRequestExecutionHandler#handleResponse(HttpResponse, HttpContext)}
  * method will fire only when the entire message content has been read into a 
- * in-memory buffer. Please note that request execution / reponse processing 
- * take place the main I/O thread and therefore {@link HttpRequestExecutionHandler}
- * methods should not block indefinitely.
- * <p/>
- * When using this protocol handelr {@link HttpEntity}'s content can be 
- * generated / consumed using standard {@link InputStream} / {@link OutputStream} 
+ * in-memory buffer. Please note that request execution / response processing 
+ * take place the main I/O thread and therefore 
+ * {@link HttpRequestExecutionHandler} methods should not block indefinitely.
+ * <p>
+ * When using this protocol handler {@link HttpEntity}'s content can be 
+ * generated / consumed using standard {@link InputStream}/{@link OutputStream} 
  * classes.
- * <p/>
+ * <p>
  * IMPORTANT: This protocol handler should be used only when dealing with HTTP 
  * messages that are known to be limited in length.
  * 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java Mon Jan 12 11:55:23 2009
@@ -65,11 +65,11 @@
  * an in-memory buffer. Please note that request processing take place the 
  * main I/O thread and therefore individual HTTP request handlers should not 
  * block indefinitely. 
- * <p/>
- * When using this protocol handelr {@link HttpEntity}'s content can be 
- * generated / consumed using standard {@link InputStream} / {@link OutputStream} 
+ * <p>
+ * When using this protocol handler {@link HttpEntity}'s content can be 
+ * generated / consumed using standard {@link InputStream}/{@link OutputStream} 
  * classes.
- * <p/>
+ * <p>
  * IMPORTANT: This protocol handler should be used only when dealing with HTTP 
  * messages that are known to be limited in length.
  *

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java Mon Jan 12 11:55:23 2009
@@ -37,21 +37,49 @@
 import org.apache.http.nio.NHttpConnection;
 
 /**
- * Event listener used by HTTP protocol layer to report fatal
- * exceptions and events that may need to be logged.
+ * Event listener used by the HTTP protocol layer to report fatal exceptions 
+ * and events that may need to be logged using a logging toolkit.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  */
 public interface EventListener {
 
+    /**
+     * Triggered when an I/O error caused a connection to be terminated.
+     * 
+     * @param ex the I/O exception. 
+     * @param conn the connection.
+     */
     void fatalIOException(IOException ex, NHttpConnection conn);
 
+    /**
+     * Triggered when an HTTP protocol error caused a connection to be 
+     * terminated.
+     * 
+     * @param ex the protocol exception. 
+     * @param conn the connection.
+     */
     void fatalProtocolException(HttpException ex, NHttpConnection conn);
 
+    /**
+     * Triggered when a new connection has been established.
+     * 
+     * @param conn the connection.
+     */
     void connectionOpen(NHttpConnection conn);
 
+    /**
+     * Triggered when a connection has been terminated.
+     * 
+     * @param conn the connection.
+     */
     void connectionClosed(NHttpConnection conn);
 
+    /**
+     * Triggered when a connection has timed out.
+     * 
+     * @param conn the connection.
+     */
     void connectionTimeout(NHttpConnection conn);
     
 }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java Mon Jan 12 11:55:23 2009
@@ -55,7 +55,7 @@
      * <p>The attachment object is the same object which was passed 
      * to the connecting I/O reactor when the connection request was 
      * made. The attachment may optionally contain some state information
-     * required in order to correctly initalize the HTTP context.
+     * required in order to correctly initialize the HTTP context.
      * 
      * @see ConnectingIOReactor#connect
      * 

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java Mon Jan 12 11:55:23 2009
@@ -40,12 +40,61 @@
 import org.apache.http.nio.entity.ConsumingNHttpEntity;
 import org.apache.http.protocol.HttpContext;
 
+/**
+ * NHttpRequestHandler represents a routine for asynchronous processing of 
+ * a specific group of non-blocking 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>
+ *
+ * @version $Revision$
+ * 
+ * @since 4.0
+ */
 public interface NHttpRequestHandler {
 
+    /**
+     * Triggered when a request is received with an entity. This method should
+     * return a {@link ConsumingNHttpEntity} that will be used to consume the
+     * entity. <code>null</code> is a valid response value, and will indicate
+     * that the entity should be silently ignored.
+     * <p>
+     * After the entity is fully consumed,
+     * {@link #handle(HttpRequest, HttpResponse, NHttpResponseTrigger, HttpContext)}
+     * is called to notify a full request & entity are ready to be processed.
+     * 
+     * @param request the entity enclosing request.
+     * @param context the execution context.
+     * @return non-blocking HTTP entity.
+     * @throws IOException in case of an I/O error.
+     * @throws HttpException in case of HTTP protocol violation or a processing 
+     *   problem.
+     */
     ConsumingNHttpEntity entityRequest(HttpEntityEnclosingRequest request,
             HttpContext context)
         throws HttpException, IOException;
 
+    /**
+     * Initiates processing of the request. This method does not have to submit 
+     * a response immediately. It can defer transmission of the HTTP response 
+     * back to the client without blocking the I/O thread by delegating the 
+     * process of handling the HTTP request to a worker thread. The worker 
+     * thread in its turn can use the instance of {@link NHttpResponseTrigger} 
+     * passed as a parameter to submit a response as at a later point of time 
+     * once content of the response becomes available.
+     * 
+     * @param request the HTTP request.
+     * @param response the HTTP response.
+     * @param trigger the response trigger.
+     * @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,
             NHttpResponseTrigger trigger, HttpContext context)
         throws HttpException, IOException;

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -37,14 +37,20 @@
 
 /**
  * Maintains a map of HTTP request handlers keyed by a request URI pattern.
- * {@link NHttpRequestHandler} instances can be looked up by request URI
- * using the {@link NHttpRequestHandlerResolver} 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 NHttpRequestHandler} 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>
  *
  * @version $Revision$
  */
@@ -56,14 +62,30 @@
         matcher = new UriPatternMatcher();
     }
 
+    /**
+     * Registers the given {@link NHttpRequestHandler} 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 NHttpRequestHandler handler) {
         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<String, ? extends NHttpRequestHandler> map) {
         matcher.setHandlers(map);
     }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
 /*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -32,15 +32,24 @@
 package org.apache.http.nio.protocol;
 
 /**
- * Interface to be implemented by objects that can resolve
- * {@link NHttpRequestHandler} instances by request URI.
+ * HttpRequestHandlerResolver can be used to resolve an instance of 
+ * {@link NHttpRequestHandler} 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>
  *
- * @version $Revision:$
+ * @version $Revision$
  */
 public interface NHttpRequestHandlerResolver {
 
+    /**
+     * 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.
+     */
     NHttpRequestHandler lookup(String requestURI);
 
 }

Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java Mon Jan 12 11:55:23 2009
@@ -40,12 +40,12 @@
  * Callback interface to submit HTTP responses asynchronously.
  * <p/>
  * The {@link NHttpRequestHandler#handle(org.apache.http.HttpRequest, HttpResponse, NHttpResponseTrigger, org.apache.http.protocol.HttpContext)} 
- * method does not have to submit a response immediately. I can defer 
- * transmittion of the HTTP response back to the client without blocking the 
+ * method does not have to submit a response immediately. It can defer 
+ * transmission of the HTTP response back to the client without blocking the 
  * I/O thread by delegating the process of handling the HTTP request to a worker 
  * thread. The worker thread in its turn can use the instance of 
  * {@link NHttpResponseTrigger} passed as a parameter to submit a response as at
- * a later point of time once the response becomes avaialble.
+ * a later point of time once the response becomes available.
  */
 public interface NHttpResponseTrigger {
 

Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,40 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html $
+ * $Revision: 496070 $
+ * $Date: 2007-01-14 13:18:34 +0100 (Sun, 14 Jan 2007) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+Non-blocking HTTP protocol execution framework. This package contains protocol 
+handler implementations based on NIO model. 
+</body>
+</html>



Mime
View raw message