hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Jakarta-httpclient Wiki] Update of "HttpClientApiRedesign" by OlegKalnichevski
Date Thu, 01 Jun 2006 16:34:18 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-httpclient Wiki" for change
notification.

The following page has been changed by OlegKalnichevski:
http://wiki.apache.org/jakarta-httpclient/HttpClientApiRedesign

------------------------------------------------------------------------------
- ##language:en
+ Obsolete. Removed.
  
- = GOALS =
- 
-  * Transform HttpClient from a client-side monolithic library into a toolset of loosely
coupled components.
-  * Provide a more modular structure enabling the users to assemble custom client- and server-side
HTTP services.
-  * Resolve the deficiencies of the 3.0 API.
-  * Support the standards listed in the ReferenceMaterials.
-  * Support the listed UseCases.
- 
- = COMPONENT STRUCTURE =
- 
- This is a purely logical distinction. The below listed components may be
- distributed separately or as a part of a larger package (jar).
- 
- == http-core ==
- 
- Package name: '''org.apache.http'''
- 
- depends on 
- 
-  * Java 1.3
- 
- provides
- 
-  * Http header primitives as defined in RFC 822
-    
-    a. {{{ Header }}} class
-    a. {{{ HeaderElement }}} class
- 
-  * Http request line and Http status line primitives as defined in RFC 2616
- 
-    a. {{{ HttpVersion }}} class
-    a. {{{ HttpStatus }}} class
-    a. {{{ HttpRequestLine }}} class
-    a. {{{ HttpStatusLine }}} class
- 
-  * Http parameter primitives (see preference architecture in 3.0 API)
- 
-    a. {{{ HttpParams }}} interface
-    a. {{{ DefaultHttpParams }}} class implementing {{{ HttpParams }}} interface
-    a. {{{ HttpConnectionParams }}} adaptor class providing easy access to TCP/IP specific
parameters
-    a. {{{ HttpProtocolParams }}} adaptor class providing easy access to HTTP protocol specific
parameters
- 
-  * Http request and Http response interfaces as defined in RFC 2616
- 
-    a. {{{ HttpMessage }}} interface. This interface represents an abstract HTTP message
-    a. {{{ HttpRequest }}} interface extending {{{ HttpMessage }}}. This interface represents
an HTTP request
-    a. {{{ HttpResponse }}} interface extending  {{{ HttpMessage }}}. This interface represents
an HTTP response
-    a. {{{ HttpEntityEnclosingRequest }}} interface extending  {{{ HttpRequest }}}. This
interface represents an HTTP response that can enclose a request entity
- 
-  * generic implementations of the Http request and response interfaces
-  
-    a. {{{ BasicHttpMessage }}} class implementing {{{ HttpMessage }}} interface
-    a. {{{ BasicHttpRequest }}} class extending {{{ BasicHttpMessage }}} and implementing
{{{ HttpRequest }}}
-    a. {{{ BasicHttpResponse }}} class extending {{{ BasicHttpMessage }}} and implementing
{{{ HttpResponse }}}, {{{ HttpEntityEnclosingMessage }}}
-    a. {{{ BasicHttpEntityEnclosingRequest }}} class extending {{{ BasicHttpRequest }}} and
implementing {{{ HttpEntityEnclosingRequest }}}
- 
-  * Http data transmitter and receiver interfaces and their RFC 2616 compliant implementation.
Data transmitters and receivers are capable of sending and receiving the most primitive data
types such as array of bytes and lines of text.
- 
-    a. {{{ HttpDataTransmitter }}} interface
-    a. {{{ HttpDataReceiver }}} interface
-    a. {{{ SocketHttpDataTransmitter }}} class implementing the {{{ HttpDataTransmitter }}}
interface
-    a. {{{ SocketHttpDataReceiver }}} class implementing {{{ HttpDataReceiver }}} interface
- 
-  * Http entity interfaces for sending and receiving entities in Http messages
- 
-    a. {{{ HttpEntity }}} interface. This interface represents an immutable entity
-    a. {{{ HttpMutableEntity }}} interface. Classes implementing this interface can be used
to assemble incoming entities either on the client or server side
-    a. {{{ BasicHttpEntity }}} class implementing {{{ HttpMutableEntity }}} interface
-    a. {{{ ByteArrayEntity }}} class implementing {{{ HttpEntity }}} interface. This class
represents an outgoing entity backed by a byte array
-    a. {{{ StringEntity }}} class implementing {{{ HttpEntity }}} interface. This class represents
an outgoing entity backed by a string
-    a. {{{ InputStreamEntity }}} class implementing {{{ HttpEntity }}} interface. This class
represents an outgoing entity backed by a input stream
- 
-  * Http connection interface including a simple dependency mechanism to inject an Http parser
implementation, and a generic implementation of Http connection
- 
-    a. {{{ HttpConnection }}} interface. Defines basic properties of a HTTP connection
-    a. {{{ HttpClientConnection }}} interface extends {{{ HttpConnection }}}. Sends Http
requests / receives Http responses
-    a. {{{ HttpServerConnection }}} interface extends {{{ HttpConnection }}}. Receives Http
requests / sends Http responses
-    a. {{{ DefaultHttpClientConnection }}} class implements {{{ HttpClientConnection }}}
-    a. {{{ DefaultHttpServerConnection }}} class implements {{{ HttpServerConnection }}}
-    a. {{{ HttpHost }}} class
- 
-  * Input / output classes
-    
-    a. {{{ ChunkedInputStream }}} class represents an input stream whose content is chunk-coded

-    a. {{{ ChunkedOutputStream }}} class represents an output stream whose content is chunk-coded

-    a. {{{ ContentLengthInputStream }}} class represents an input stream whose content is
delimited with a length value
-    a. {{{ ContentLengthOutputStream }}} class represents an output stream whose content
is delimited with a length value
-    a. {{{ IdentityOutputStream }}} class
- 
-  * Http interceptors allowing for request pre-processing and response post-processing without
having to subclass a given {{{ HttpRequest }}} or {{{ HttpResponse }}} implementing classes
-    
-    a. {{{ HttpRequestInterceptor }}} interface
-    a. {{{ HttpResponseInterceptor }}} interface
- 
-  * Http method executor capable of executing http requests and receiving Http responses.
This class also is capable of retrying failed requests and handling followup requests through
generic interfaces. It DOES NOT provide connection pooling/management facilities, and DOES
NOT implement redirects and authentication itself.
- 
-    a. {{{ HttpRequestExecutor }}} class
-    a. {{{ HttpContext }}} interface to access all kinds of data related to the execution
of a request
-    a. {{{ HttpRequestRetryHandler }}} interface, to decide whether to retry after a communication
error
-    a. {{{ HttpSequenceHandler }}} interface, to generate followup requests if required
- 
-  * implementations of context, retry handler and sequence handler
- 
-    a. {{{ BasicHttpContext }}} class implementing {{{ HttpContext }}}
-    a. {{{ DefaultHttpRequestRetryHandler }}} class implementing {{{ HttpRequestRetryHandler
}}} interface
-    a. {{{ DefaultRedirectSequenceHandler }}} class implementing {{{ HttpSequenceHandler
}}}, to handle 30x responses
-    a. {{{ SequenceHandlerChain }}} class implementing {{{ HttpSequenceHandler }}}, to manage
a list of sequence handlers
- 
-  * Most common Http request types: GET, POST, PUT, HEAD, TRACE
- 
-    a. {{{ HttpGet }}} class implementing {{{ HttpRequest }}} interface
-    a. {{{ HttpPost }}} class implementing {{{ HttpRequest }}} and {{{ HttpEntityEnclosingRequest
}}} interfaces
-    a. {{{ HttpPut }}} class implementing {{{ HttpRequest }}} and {{{ HttpEntityEnclosingRequest
}}} interfaces
-    a. {{{ HttpHead }}} class implementing {{{ HttpRequest }}} interface
-    a. {{{ HttpTrace }}} class implementing {{{ HttpRequest }}} interface
- 
-  * Basic Http proxy support
- 
-    a. {{{ HttpConnectRequest }}} class implementing {{{ HttpRequest }}} interface
-    a. {{{ ProxyHost }}} class
- 
-  * Http proxy chain support
- 
-    a. {{{ ProxyChain }}}  interface
-    a. {{{ SimpleProxyChain }}} class implementing {{{ ProxyChain }}}. List of {{{ HttpProxyHost
}}} objects.
-    a. {{{ SingleProxy }}} class implementing {{{ ProxyChain }}}. For use when a single proxy
server is used.
- 
- == http-nio ==
- 
- Package name: '''org.apache.http.nio'''
- 
- depends on 
- 
-  * Java 1.4
-  * http-core
- 
- provides
- 
-  * Non-blocking Http client and server connections (tbd)
-       
- == http-cookie ==
- 
- possible package name: '''org.apache.http.cookie'''
- 
- depends on 
- 
-  * Java 1.3
-  * http-core
- 
- provides
- 
-  * Http cookie interface as defined in RFC2965 and RFC2109 and compatible with Netscape
cookie draft and servlet specification. Generic Http cookie implementation.
- 
-    a. {{{ HttpCookie }}} interface
-    a. {{{ Cookie class }}} (client side cookie)
-    a. {{{ SetCookie }}} class (Server side cookie)
- 
-  * Cookie store interface
- 
-    a. {{{ CookieStore }}} interface
-    a. {{{ InMemoryCookieStore }}} class implementing {{{ CookieStore }}} interface
- 
-  * Http cookie specification interface that defines the contract for cookie parsing, validation,
formatting and matching.
- 
-    a. {{{ HttpCookieSpec }}} interface
-    a. {{{ CompatibilityCookieSpec }}} class 
-    a. {{{ RFC2965CookieSpec }}} class as defined in RFC 2965
-    a. {{{ RFC2109CookieSpec }}} class as defined in RFC 2109
-    a. {{{ NetscapeCookieSpec }}} class as defined in the Netscape cookie draft 
- 
- == http-auth ==
- 
- possible package name: '''org.apache.http.auth'''
- 
- depends on 
- 
-  * Java 1.3
-  * commons-codec
-  * http-core
- 
- provides
- 
-  * Http credentials primitives
-    
-    a. {{{ Credentials }}} interface
-    a. {{{ BasicCredentials }}} class implementing {{{ Credentials }}} interface
-    a. {{{ WindowsCredentials }}} class implementing {{{ Credentials }}} interface
-    a. {{{ CredentialsProvider }}} interface
-    a. {{{ StdCredentialsProvider }}} class implementing {{{ CredentialsProvider }}} interface
- 
-  * Http authentication primitives. Authentication schemes should be able to be produce and
respond to authentication challenges (both client and server side)
- 
-    a. {{{ AuthScheme }}} interface
-    a. {{{ BasicScheme }}} class implementing {{{ AuthScheme }}}
-    a. {{{ DigestScheme }}} class implementing {{{ AuthScheme }}}
-    a. {{{ NTLMScheme }}} class implementing {{{ AuthScheme }}}
-    a. {{{ AuthChallengeParser }}} class
- 
-  * Handling of 401 and 407 responses
- 
-    a. {{{ StdAuthChallengeHandler }}} class implementing {{{ HttpSequenceHandler }}} interface
-    a. {{{ AuthorizationFilter }}} class implementing {{{ HttpFilter }}}, to insert authorization
headers into requests
-    a. {{{ AuthorizationContext }}} class for data sharing between the sequence handler and
the filter. Made available through the {{{ HttpContext }}} for a request.
- 
- 
- == http-conn ==
- 
- possible package name: '''org.apache.http.connections'''
- 
- depends on 
- 
-  * Java 1.4
-  * commons-logging (* see notes)
-  * http-core
-  * commons-pool (really needed? vote?)
- 
- 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'''
- 
- The purpose of this component is to provide an asynchronous alternative to the synchronous
{{{ HttpMethodExecutor }}} in '''http-common'''.
- 
- depends on 
- 
-  * Java 1.4
-  * commons-logging (* see notes)
-  * http-core
-  * http-conn
- 
- provides
- 
-  * asynchronous execution interface for HTTP requests. Responses and errors are reported
as callbacks. Implementations will require an {{{ HttpClientConnection }}} for communication.
It is their responsibility to get it somehow.
- 
-    a. {{{ HttpAsyncLink }}} interface for sending requests asynchronously
-    a. {{{ HttpAsyncCallback }}} interface
- 
-  * representation for asynchronous requests in progress. Needed as identifier to cancel
a specific execution. Suitable as key in a map. A base class can be derived for specific implementations
of {{{ HttpAsyncLink }}}.
- 
-    a. {{{ HttpAsyncHandle }}} interface
-    a. {{{ BasicAsyncHandle }}} class implementing {{{ HttpAsyncHandle }}}
- 
-  * result lookup interface for HTTP responses.
- 
-    a. {{{ HttpAsyncResult }}} interface for checking whether the response is available,
and getting it
-    a. {{{ HttpAsyncNotify }}} interface extending {{{ HttpAsyncResult }}} with a wait/notify
mechanism
- 
-  * default implementations of callback handler and result provider. The callback handler
uses an {{{ HttpRequestRetryHandler }}} to retry failed requests, but does not handle redirects
nor authentication challenges.
- 
-    a. {{{ StdAsyncCallbackHandler }}} class implementing {{{ HttpAsyncCallback }}}
-    a. {{{ StdAsyncResult }}} class implementing {{{ HttpAsyncResult }}}
-    a. {{{ StdAsyncNotify }}} class extending {{{ StdAsyncResult }}} and implementing {{{
HttpAsyncNotify }}}
- 
-  * minimal implementation of the asynchronous execution interface.
- 
-    a. {{{ SimpleAsyncLink }}} class implementing {{{ HttpAsyncLink }}}
-    a. {{{ SimpleAsyncHandle }}} class extending {{{ BasicAsyncHandle }}} (maybe as an inner
class)
- 
-  The minimal implementation spawns a new thread that sends the request over a connection
and waits for a response. The callback interface is invoked by that thread. The connection
is passed to the constructor. The minimal implementation handles at most one request at a
time and therefore does not have to maintain a request queue. It can be used by applications
that want to use a single connection asynchronously and handle synchronization themselves.
- 
-  * standard implementation of the asynchronous execution interface.
- 
-    a. {{{ StdAsyncLink }}} class implementing {{{ HttpAsyncLink }}}
-    a. {{{ StdAsyncHandle }}} class extending {{{ BasicAsyncHandle }}} (maybe as an inner
class)
- 
-  The standard implementation spawns a new thread that alternately sends requests over a
client connection and waits for a response. Unlike {{{ SimpleAsyncLink}}}, it maintains a
queue of requests to be processed. It can be used by multiple threads simultaneously. It supports
persistent use of a connection, but not pipelining. The constructor gets either a client connection,
or a connection manager.
- 
-  * pipelining implementation of the asynchronous execution interface. See note on Pipelining
below.
- 
-    a. {{{ PipeliningAsyncLink }}} class implementing {{{ HttpAsyncLink }}}
-    a. {{{ PipeliningAsyncHandle }}} class extending {{{ BasicAsyncHandle }}} (maybe as an
inner class)
-    a. {{{ PipeliningParams }}} class
-    a. various helper classes to be used by {{{ PipeliningAsyncLink }}}
- 
-  * request queueing, for use by {{{ StdAsyncLink }}} and in particular {{{ PipeliningAsyncLink
}}}
- 
-    a. {{{ HttpRequestQueue }}} interface
-    a. {{{ StdHttpReqQueue }}} class implementing {{{ HttpRequestQueue }}}
-  In addition to the usual queueing operations, this interface provides methods for dequeueing
bunches of requests targetting the same host. It also includes a conditional queueing operation
that enqueues a request only if it targets the same host as other requests in the queue. See
note on Pipelining below.
- 
- 
- == http-client ==
- 
- possible package name: '''org.apache.http.httpclient'''
- 
- depends on 
- 
-  * Java 1.4
-  * commons-logging (* see notes)
-  * commons-codec
-  * http-core
-  * http-cookie
-  * http-auth
-  * http-conn
- 
- provides
- 
-  * Http agent primitives
-    
-    a. {{{ HttpClientParams }}} class
-    a. {{{ HttpHostParams }}} class
-    a. {{{ HostConfig }}} class
-    a. {{{ HttpClient }}} class. Sets up the {{{ HttpContext }}} for method executions. Supports
a simple dependency injection mechanism to inject {{{ HttpConnectionManager }}}, {{{ HttpSequenceHandler
}}}, {{{ HttpFilter }}}, {{{ CookieStore }}} and possibly other dependencies.
- 
-  * Complex entity types, based on commons-codec
- 
-    a. {{{ FormDataEntity }}} class extending {{{ BasicHttpEntity }}} and implementing {{{
HttpIncomingEntity }}}, {{{ HttpOutgoingEntity }}}
-    a. {{{ MultipartIcEntity }}} class extending {{{ BasicHttpEntity }}} and implementing
{{{ HttpIncomingEntity }}}
-    a. {{{ MultipartOgEntity }}} class extending {{{ BasicHttpEntity }}} and implementing
{{{ HttpOutgoingEntity }}}
- 
- 
- == http-client-3-compat ==
- 
- depends on 
- 
-  * Java 1.4
-  * commons-logging
-  * commons-codec
-  * http-core
-  * http-cookie
-  * http-auth
-  * http-conn
-  * http-client
- 
- Provided there are any volunteers to maintain it.
- 
- == http-spider ==
- 
- A web crawler of a sort. Provided there is a healthy community around it.
- 
- depends on 
- 
-  * Java 1.4
-  * commons-logging (* see notes)
-  * commons-codec
-  * http-core
-  * http-cookie
-  * http-auth
-  * http-client
- 
- ideas?
- 
- = Notes =
- 
- This chapter is for detailed explanatory notes that would mess up the component descriptions
if written inline.
- 
- == * Logging toolkit ==
- 
- Avoid dependency on a logging toolkit whenever technically feasible. 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.
- 
- Consider using Apache Logging UGLI as an alternative to Jakarta Commons Logging. [http://issues.apache.org/bugzilla/show_bug.cgi?id=32937
PR# 32937]
- 
- == 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 shared 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.
- 
- [http://issues.apache.org/bugzilla/show_bug.cgi?id=22628 PR #22628]
- 
- == Http filters as common aspects ==
- 
- One of the fundamental flaws of the 2.0 and 3.0 API is the rigid hierarchy of classes representing
HTTP methods. One has to extends all the classes in order to implement a common behavior across
all the available type of HTTP methods. 
- 
- A better approach may be to introduce common aspects shared by all types of HTTP methods
as a set of filters. HTTP method executor would be able to apply a number of preprocessing
filters to every request prior to sending it to the target server and a number of postprocessing
filters to every response received. This design would allow for flexible introduction of crosscutting
aspects to all standard types of methods as well as custom ones without class extension. For
instance, filters may be employed to generate 'Host', 'Agent', 'Cookie' request headers and
to extract cookies set by the target server from 'Set-Cookie' response headers. Similar approach
may be used on the server side. This design would enable decoupling of client- and server-side
aspects from the {{{ HttpRequest }}} and {{{ HttpResponse }}} primitives, thus making them
more reusable.
- 

---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org


Mime
View raw message