You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by jg...@apache.org on 2007/09/25 23:11:21 UTC
svn commit: r579382 - in /geronimo/sandbox/AsyncHttpClient/src/main:
java/org/apache/ahc/ java/org/apache/ahc/codec/ javadoc/
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>