Date: 2005-01-15T05:42:40
Editor: RolandWeber
Wiki: Jakarta-HttpClient Wiki
Page: HttpClientApiRedesign
URL: http://wiki.apache.org/jakarta-httpclient/HttpClientApiRedesign
http-conn and first take on pipelining. See note at the end of the document.
Change Log:
------------------------------------------------------------------------------
@@ -52,7 +52,7 @@
a. {{{ BasicHttpResponse }}} class implementing {{{ HttpResponse }}}
interface
a. {{{ BasicHttpEntityEnclosingRequest }}} class implementing {{{
HttpEntityEnclosingRequest }}} interface
- * Http parser interface and the RFC 2616 compliant implementation of it. The
parser must only be able to parse well formed Http requests and responses.
+ * Http parser interface and the RFC 2616 compliant implementation of it. The
parser only has to be able to parse well formed Http requests and responses.
a. {{{ HttpParser }}} interface
a. {{{ NIOHttpParser }}} class based on NIO (makes use of {{{ SocketChannel
}}} and {{{ CharBuffer }}} )
@@ -151,6 +151,29 @@
a. {{{ NTLMScheme }}} class implementing {{{ AuthScheme }}}
a. {{{ AuthChallengeParser }}} class
+== http-conn ==
+
+possible package name: '''org.apache.http.connections'''
+
+depends on
+
+ * Java 1.4 (* pending user poll and committer vote)
+ * commons-logging (* avoid this dependency if technically feasible)
+ * http-common
+ * commons-pool (really needed? vote?)
+
+The rationale behind trying to avoid dependency on a logging framework is to
keep the component reusable by projects that have already standardized on a
certain logging framework.
+
+provides
+
+ * Http connection manager / connection pool interface and most common
implementations of it.
+
+ a. {{{ HttpConnectionManagerParams }}} class
+ a. {{{ HttpConnectionManager }}} interface
+ a. {{{ SimpleConnectionManager }}} class implementing {{{
HttpConnectionManager }}} interface
+ a. {{{ PoolingConnectionManager }}} class implementing {{{
HttpConnectionManager }}} interface
+
+
== http-async ==
possible package name: '''org.apache.http.async'''
@@ -162,19 +185,21 @@
* Java 1.4 (* pending user poll and committer vote)
* commons-logging (* avoid this dependency if technically feasible)
* http-common
+ * http-conn
The rationale behind trying to avoid dependency on a logging framework is to
keep the component reusable by projects that have already standardized on a
certain logging framework.
provides
- * asynchronous execution interface for HTTP requests. The {{{ HttpConnection
}}} for communication is passed as an argument when the interface is used.
Responses and errors are reported as callbacks.
+ * asynchronous execution interface for HTTP requests. Responses and errors
are reported as callbacks. Implementations will require an {{{ HttpConnection
}}} for communication. It is their responsibility to get it somehow.
a. {{{ HttpAsyncLink }}} interface for sending requests asynchronously
a. {{{ HttpAsyncCallback }}} interface
- * default implementation of the asynchronous execution interface. The default
is to spawn a new background thread that sends the request over the connection
and waits for a response. The callback interface is used by that thread.
+ * default implementation of the asynchronous execution interface.
a. {{{ StdAsyncLink }}} class implementing {{{ HttpAsyncLink }}}
+ The default implementation expects an {{{ HttpConnection }}} as a constructor
argument. It spawns a new background thread that sends the request over the
connection and waits for a response. The callback interface is invoked by that
thread.
* result lookup interface for HTTP responses.
@@ -185,6 +210,11 @@
a. {{{ StdAsyncCallbackHandler }}} class implementing {{{ HttpAsyncCallback
}}}, {{{ HttpAsyncResult }}}, {{{ HttpAsyncNotify }}}
+ * pipelining implementation of the asynchronous execution interface. See note
on Pipelining below.
+
+ a. {{{ PipeliningAsyncLink }}} class implementing {{{ HttpAsyncLink }}}
+ a. various helper classes to be used by {{{ PipeliningAsyncLink }}}
+
== http-client ==
possible package name: '''org.apache.http.httpclient'''
@@ -198,15 +228,9 @@
* http-common
* http-cookie
* http-auth
+ * http-conn
provides
-
- * Http connection manager / connection pool interface and most common
implementations of it.
-
- a. {{{ HttpConnectionManagerParams }}} class
- a. {{{ HttpConnectionManager }}} interface
- a. {{{ SimpleConnectionManager }}} class implementing {{{
HttpConnectionManager }}} interface
- a. {{{ PoolingConnectionManager }}} class implementing {{{
HttpConnectionManager }}} interface
* Http proxy support
@@ -271,3 +295,17 @@
* geronimo-network (appropriate? better options? shall we implement our own
network protocol stack? vote?)
ideas?
+
+= Notes =
+
+This chapter is for detailed explanatory notes that would mess up the
component descriptions if written inline.
+
+== Pipelining ==
+
+The idea behind the {{{ PipeliningAsyncLink }}} in '''http-async''' is to
start up a pair of background threads for each connection that is used. One
thread sends requests, the other receives the responses on the connection. When
a request is sent over the pipelining link, the class checks whether there is a
connection to that host. If so, it delegates the request to the corresponding
sender thread. Otherwise, it queues the request in a shared queue.
+
+If there is a request in the sharead queue, a new pair of background threads
can be started with a connection allocated from a connection manager. The
maximum number of connections used for pipelining can be configured lower than
the number of connections in the connection manager. This allows simultaneous
use of the synchronous and asynchronous interfaces for HTTP request processing,
without synchronous requests being delayed forever.
+
+Connections are released when a receiving thread detects that there are no
more responses pending on the connection, or when a communication error occurs.
When there are no more requests, connection release can be delayed. In case of
a communication error, requests that are queued on the sending thread are moved
to the shared queue, where they can be picked up again. The error itself is
reported to the callback interfaces for all requests already sent over the
connection for which no response has been received yet.
+
+Premature connection release can be enforced, for example based on the number
of requests sent through the pipeline or the time since the pipeline has been
created. This prevents clogging of the asynchronous link in cases where the
number of target hosts exceeds the maximum number of pipelines.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
