Mailing-List: contact scm-help@geronimo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@geronimo.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r579382 - in /geronimo/sandbox/AsyncHttpClient/src/main:
 java/org/apache/ahc/ java/org/apache/ahc/codec/ javadoc/
Date: Tue, 25 Sep 2007 21:11:21 -0000
To: scm@geronimo.apache.org
From: jgenender@apache.org
Message-Id: <20070925211127.AAD501A9832@eris.apache.org>

Author: jgenender
Date: Tue Sep 25 14:11:20 2007
New Revision: 579382

URL: http://svn.apache.org/viewvc?rev=579382&view=rev
Log:
Some javadoc

Modified:
    geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClient.java
    geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClientCallback.java
    geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/codec/HttpDecoder.java
    geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/package.html
    geronimo/sandbox/AsyncHttpClient/src/main/javadoc/overview.html

Modified: geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClient.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClient.java?rev=579382&r1=579381&r2=579382&view=diff
==============================================================================
--- geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClient.java (original)
+++ geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClient.java Tue Sep 25 14:11:20 2007
@@ -35,35 +35,70 @@
 import java.util.concurrent.ExecutorService;
 
 /**
- * Main class to use for sending asyncronous HTTP requests to servers.
+ * Main class to use for sending asynchronous HTTP requests to servers.
  * Only one or a few of these objects should be used in an application since
- * it manages the threads and requests to multiple seperate servers/sockets.
+ * it manages the threads and requests to multiple separate servers/sockets.
  */
 public class AsyncHttpClient {
 
+    /** The Constant DEFAULT_CONNECTION_TIMEOUT. */
     public static final int DEFAULT_CONNECTION_TIMEOUT = 30000;
+    
+    /** The Constant DEFAULT_SSL_PROTOCOL. */
     public static final String DEFAULT_SSL_PROTOCOL = "TLS";
 
+    /** The ssl protocol. */
     private String sslProtocol = DEFAULT_SSL_PROTOCOL;
 
+    /** The connection timeout. */
     private int connectionTimeout = DEFAULT_CONNECTION_TIMEOUT;
+    
+    /** The connector. */
     private SocketConnector connector;
+    
+    /** The thread pool. */
     private static ExecutorService threadPool;
+    
+    /** The HttpIoHandler handler. */
     private HttpIoHandler handler = new HttpIoHandler();
+    
+    /** The ssl filter. */
     private SSLFilter sslFilter;
 
+    /**
+     * Instantiates a new AsyncHttpClient.  It will use a single threaded model and is good for
+     * use in one-off connections.
+     */
     public AsyncHttpClient() {
         this(DEFAULT_CONNECTION_TIMEOUT, null);
     }
 
+    /**
+     * Instantiates a new AsyncHttpClient.  This will take a thread pool (ExecutorService) to use
+     * for processing connections.
+     * 
+     * @param executor the executor
+     */
     public AsyncHttpClient(ExecutorService executor) {
         this(DEFAULT_CONNECTION_TIMEOUT, executor);
     }
 
+    /**
+     * Instantiates a new AsyncHttpClient.  Uses a single thread model by default and allows you to specify
+     * a connection timeout.
+     * 
+     * @param connectionTimeout the connection timeout in milliseconds.
+     */
     public AsyncHttpClient(int connectionTimeout) {
         this(connectionTimeout, null);
     }
 
+    /**
+     * Instantiates a new AsyncHttpClient.  Allows you to specify a connection timeout and an ExecutorService.
+     * 
+     * @param connectionTimeout the connection timeout in milliseconds.
+     * @param executor the ExceutorService to use to process connections.
+     */
     public AsyncHttpClient(int connectionTimeout, ExecutorService executor) {
         this.connectionTimeout = connectionTimeout;
 
@@ -80,6 +115,12 @@
 
     }
 
+    /**
+     * Sends a request.
+     * 
+     * @param message the <code>HttpRequestMessage</code> to send to the remote server.
+     * @see HttpRequestMessage
+     */
     public void sendRequest(HttpRequestMessage message) {
         if (threadPool != null && threadPool.isShutdown()) {
             throw new IllegalStateException("AsyncHttpClient has been destroyed and cannot be reused.");
@@ -90,14 +131,28 @@
         future.addListener(new FutureListener(this, message));
     }
 
+    /**
+     * Gets the connection timeout.
+     * 
+     * @return the connection timeout in milliseconds
+     */
     public int getConnectionTimeout() {
         return connectionTimeout;
     }
 
+    /**
+     * Sets the connection timeout.
+     * 
+     * @param connectionTimeout the new connection timeout in milliseconds
+     */
     public void setConnectionTimeout(int connectionTimeout) {
         this.connectionTimeout = connectionTimeout;
     }
 
+    /**
+     * Shuts down the AsyncHttpClient object and shuts any associated thread pools.  SHould always be called when the application is
+     * done using the object or a hang can occur.
+     */
     public void destroyAll() {
         handler.destroy();
 
@@ -110,17 +165,34 @@
         }
     }
 
-    //If connected, this listener will add the SSL Filter
+    /**
+     * The listener interface for receiving connection events. Its main purpose is to notify the
+     * callback of any exceptions that may have occurred, or to handle the session and inject
+     * the proper SSL filter if the connection is to be used for <code>https</code>.  If a good
+     * connection occurs, it is also responsible for sending the request.
+     */
     class FutureListener implements IoFutureListener {
 
+        /** The request. */
         HttpRequestMessage request;
+        
+        /** The client. */
         AsyncHttpClient client;
 
+        /**
+         * Instantiates a new future listener for a connection.
+         * 
+         * @param client the <code>AsyncHttpClient</code> client object
+         * @param request the <code>HttpRequestMessage</code> request that is to be sent.
+         */
         public FutureListener(AsyncHttpClient client, HttpRequestMessage request) {
             this.client = client;
             this.request = request;
         }
 
+        /* (non-Javadoc)
+         * @see org.apache.mina.common.IoFutureListener#operationComplete(org.apache.mina.common.IoFuture)
+         */
         public void operationComplete(IoFuture future) {
             ConnectFuture connFuture = (ConnectFuture) future;
             if (connFuture.isConnected()) {
@@ -164,6 +236,13 @@
             }
         }
 
+        /**
+         * Creates the client ssl context.
+         * 
+         * @return the SSL context
+         * 
+         * @throws GeneralSecurityException the general security exception
+         */
         private SSLContext createClientSSLContext() throws GeneralSecurityException {
             SSLContext context = SSLContext.getInstance(sslProtocol);
             context.init(null, TrustManagerFactoryImpl.X509_MANAGERS, null);

Modified: geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClientCallback.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClientCallback.java?rev=579382&r1=579381&r2=579382&view=diff
==============================================================================
--- geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClientCallback.java (original)
+++ geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/AsyncHttpClientCallback.java Tue Sep 25 14:11:20 2007
@@ -21,9 +21,40 @@
 
 import org.apache.ahc.codec.HttpResponseMessage;
 
+/**
+ * The Interface AsyncHttpClientCallback.  This callback that should be implemented to receive notifications
+ * from the <code>AsyncHttpClient</code>.  The callback implementation is passed as a parameter to a
+ * {@link org.apache.ahc.codec.HttpRequestMessage HttpRequestMessage}.  Each message should have its own 
+ * callback implementation.
+ * @see org.apache.ahc.codec.HttpRequestMessage
+ */
 public interface AsyncHttpClientCallback {
+    
+    /**
+     * Message response event.  Occurs when the {@link AsyncHttpClient} receives a response from the server.
+     * 
+     * @param message the {@link org.apache.ahc.codec.HttpResponseMessage HttpRequestMessage} message response
+     */
     void onResponse(HttpResponseMessage message);
+    
+    /**
+     * Exception event. Occurs when the {@link AsyncHttpClient} receives any type of Exception from the connection
+     * through the response.
+     * 
+     * @param cause the cause of the Exception
+     */
     void onException(Throwable cause);
+    
+    /**
+     * Closed event. Occurs when the {@link AsyncHttpClient} closes the connection.  This can occur if
+     * the remote server closes the connection,after an Exception occurred, after a response is sent, or
+     * during the handling of a redirect response.  This simply signals that the socket has closed.
+     */
     void onClosed();
+    
+    /**
+     * Timeout event.  Occurs when the {@link AsyncHttpClient} times out while waiting for a response from a
+     * remote server.
+     */
     void onTimeout();
 }

Modified: geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/codec/HttpDecoder.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/codec/HttpDecoder.java?rev=579382&r1=579381&r2=579382&view=diff
==============================================================================
--- geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/codec/HttpDecoder.java (original)
+++ geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/codec/HttpDecoder.java Tue Sep 25 14:11:20 2007
@@ -27,6 +27,9 @@
 import org.apache.ahc.util.DateUtil;
 import org.apache.mina.common.ByteBuffer;
 
+/**
+ * Utility class for helping to decode the HTTP Protocol
+ */
 public class HttpDecoder {
 
     public static final String CHUNKED = "chunked";
@@ -56,9 +59,15 @@
     private static final byte LF = 10;
 
 
-
     private CharsetDecoder decoder = Charset.defaultCharset().newDecoder();
 
+    /**
+     * Finds a line from a ByteBuffer that ends with a CR/LF and returns the line as a String
+     *
+     * @param in ByteBuffer containing data
+     * @return a <code>String</code> representing the decoded line
+     * @throws Exception for any Exception that is encountered
+     */
     public String decodeLine(ByteBuffer in) throws Exception {
         int beginPos = in.position();
         int limit = in.limit();
@@ -95,6 +104,14 @@
         return result;
     }
 
+    /**
+     * Decodes the status code and message from a HTTP response and places the values in a
+     * <code>HttpResponseMessage</code> object.
+     * @param line <code>String</code> containing <code>HTTP/1.<i>X</i> <i>Message</i></code>
+     * @param msg the <code>HttpResponseMessage</code> for which to place the result
+     * @throws Exception on any Exception that may occur
+     * @see HttpResponseMessage
+     */
     public void decodeStatus(String line, HttpResponseMessage msg) throws Exception {
         String magic = line.substring(0, 8);
         if (!magic.equals("HTTP/1.1") && !magic.equals("HTTP/1.0")) {

Modified: geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/package.html
URL: http://svn.apache.org/viewvc/geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/package.html?rev=579382&r1=579381&r2=579382&view=diff
==============================================================================
--- geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/package.html (original)
+++ geronimo/sandbox/AsyncHttpClient/src/main/java/org/apache/ahc/package.html Tue Sep 25 14:11:20 2007
@@ -21,6 +21,6 @@
   -->
 </head>
 <body bgcolor="white">
-<h2>The primary user components for the AsyncHttpClient API</h2>
+<h2>The primary user components for the AsyncHttpClient API.</h2>
 </body>
 </html>

Modified: geronimo/sandbox/AsyncHttpClient/src/main/javadoc/overview.html
URL: http://svn.apache.org/viewvc/geronimo/sandbox/AsyncHttpClient/src/main/javadoc/overview.html?rev=579382&r1=579381&r2=579382&view=diff
==============================================================================
--- geronimo/sandbox/AsyncHttpClient/src/main/javadoc/overview.html (original)
+++ geronimo/sandbox/AsyncHttpClient/src/main/javadoc/overview.html Tue Sep 25 14:11:20 2007
@@ -1,31 +1,39 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
 <head>
-<!--
-  ~  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.
-  -->
+    <!--
+    ~  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.
+    -->
     <title>The AsyncHttpClient is a high performance HTTP client API that is based on the Java NIO networking
-API.</title>
+        API.</title>
 </head>
 <body bgcolor="white">
-<h1>The AsyncHttpClient is a high performance HTTP client API that is based on the Java NIO networking
-API.</h1>
+<h1>The AsyncHttpClient is a high performance HTTP client API that is based on the Java NIO networking API.</h1>
 This API is based on the <a href="http://mina.apache.org">Apache MINA</a> framework to provide a high
-performance networking library based on the HTTP protocol.
+performance networking library based on the HTTP protocol. The AsyncHttpClient utilizes the Java NIO and
+mutlithreaded capabilities to be able to handle many concurrent outbound connections without having threads
+sitting in a wait state. There are numerous applications this API can be good for, such as gaming applications
+or web servers that need to access 3rd party web components and operate under heavy load. The major
+implication for this API is the ability to effectively and efficiently make use of threads while waiting for
+responses from the server.
+<h2>Usage</h2>
+Using the AsyncHttpClient is generally simple. In your application, you typically want to create a single
+instance of the AsyncHttpClient and use it throughout the life cycle of your application. The AsyncHttpClient
+only needs to be created once and reused to send multiple connections to multiple servers.
 </body>
 </html>