TBD

The Abdera2 Client is a generic HTTP Client interface that extends the Apache HTTP Components 4.x Client and makes it easier to use and adds additional functionality. Examples of the additional functionality provided by the Abdera2 Client include automatic handling of Content-Encodings, support for complex HTTP Headers such as Web Linking, WWW-Authenticate, Cache-Control and Preference, and support for asynchronous HTTP requests utilizing Futures.

Creating and using a simple client:

The Session object is the primary interface through which requests are processed. In addition to GET, there are methods for each of the primary HTTP methods as well as mechanisms for invoking extension HTTP methods such as PATCH.

New in Abdera2 is the ability to perform non-blocking HTTP requests by leveraging the mechanisms provided by the java.util.concurrent.* package. Developers may choose to either provide a callback Listener that will be invoked when the request completes, or receive a Future whose value will be set once the response has been received.

Non-blocking requests using a Future: future = session.get("http://example.org/foo", exec); ]]>

Non-blocking requests using a Listener: () { public void onResponse(ClientResponse resp) { // do something with the Response }}); ]]>

Note that when using a Listener, the client will automatically handle the release of the ClientResponse object when the onResponse method return.

The RequestOptions class can be used to customize many details of an individual request. In Abdera2, unlike previous versions of Abdera, instances of the RequestOptions class are threadsafe and immutable, and are created using the same fluent factory API used throughout the rest of Abdera2.

Using RequestOptions to request a non-cached version of a resource:

The range of options supported by the RequestOptions class is extensive. Refer to the javadocs for complete details.

Abdera2 leverages the Apache HTTP Component Clients support for Basic and Digest authentication. To specify the authentication credentials for a domain with a specific realm, call the addCredentials method on the Client object:

Many applications choose to use Form-based authentication rather than leveraging the existing HTTP Authentication model. For those, login and logout is performed by sending particular HTTP requests to the server. Abdera2 adds basic support for simple Form authentication using the doFormLogin() method on the Session object.

The doFormLogin method will return true if the response returns a successful status code (e.g. 2xx). If custom behavior, additional form fields, or specific response handling is required, then the login request will need to be handled like any other HTTP request using the appropriate methods on the session object. Abdera2 also supports the use of custom authentication schemes leveraging the extensibility of the WWW-Authenticate and Authorization headers. Custom Authorization header values may be set using the RequestOptions class:

The Abdera2 Client fully supports conditional HTTP Requests using EntityTags. Conditional request options can be set using the RequestOptions class:

An example conditional request using If-None-Match:

A conditional request using If-Modified-Since:

The HTTP Prefer Header is a proposed new HTTP header that may be used to request that a server apply optional processing behaviors to a request.

Adding Preferences to a request: