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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
