Jersey(1.19.1) - Client API, Overview of the API

To utilize the client API it is first necessary to create an instance of a Client, for example:

Client c = Client.create();

Configuring a Client and WebResource

The client instance can then be configured by setting properties on the map returned from the getProperties methods or by calling the specific setter methods, for example the following configures the client to perform automatic redirection for appropriate responses:

c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);

which is equivalent to the following:

c.setFollowRedirects(true);

Alternatively it is possible to create a Client instance using a ClientConfig object for example:

ClientConfig cc = new DefaultClientConfig();
cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Client c = Client.create(cc);

Once a client instance is created and configured it is then possible to obtain a WebResource instance, which will inherit the configuration declared on the client instance. For example, the following creates a reference to a Web resource with the URI “http://localhost:8080/xyz”:

WebResource r = c.resource("http://localhost:8080/xyz");

and redirection will be configured for responses to requests invoked on the Web resource.

Client instances are expensive resources. It is recommended a configured instance is reused for the creation of Web resources. The creation of Web resources, the building of requests and receiving of responses are guaranteed to be thread safe. Thus a Client instance and WebResource instances may be shared between multiple threads.

In the above cases a WebResource instance will utilize HttpUrlConnection or HttpsUrlConnection, if the URI scheme of the WebResource is “http” or “https” respectively.

Building a request

Requests to a Web resource are built using the builder pattern (see RequestBuilder) where the terminating method corresponds to an HTTP method (see UniformInterface). For example,

String response = r.accept(MediaType.APPLICATION_JSON_TYPE, MediaType.APPLICATION_XML_TYPE)
                   .header("X-FOO", "BAR")
                   .get(String.class);

The above sends a GET request with an Accept header of application/json, application/xml and a non-standard header X-FOO of BAR.

If the request has a request entity (or representation) then an instance of a Java type can be declared in the terminating HTTP method, for PUT, POST and DELETE requests. For example, the following sends a POST request:

String request = "content";
String response = r.accept(MediaType.APPLICATION_JSON_TYPE, MediaType.APPLICATION_XML_TYPE)
                    .header("X-FOO", "BAR")
                    .post(String.class, request);

where the String "content" will be serialized as the request entity (see the section "Java instances and types for representations" section for further details on the supported Java types). The Content-Type of the request entity may be declared using the type builder method as follows:

String response = r.accept(MediaType.APPLICATION_JSON_TYPE, MediaType.APPLICATION_XML_TYPE)
                   .header("X-FOO", "BAR")
                   .type(MediaType.TEXT_PLAIN_TYPE)
                   .post(String.class, request);

or alternatively the request entity and type may be declared using the entity method as follows:

String response = r.accept(MediaType.APPLICATION_JSON_TYPE, MediaType.APPLICATION_XML_TYPE)
                   .header("X-FOO", "BAR")
                   .entity(request, MediaType.TEXT_PLAIN_TYPE)
                   .post(String.class);

Receiving a response

If the response has a entity (or representation) then the Java type of the instance required is declared in the terminating HTTP method. In the above examples a response entity is expected and an instance of String is requested. The response entity will be de-serialized to a String instance.

If response meta-data is required then the Java type ClientResponse can be declared from which the response status, headers and entity may be obtained. For example, the following gets both the entity tag and response entity from the response:

ClientResponse response = r.get(ClientResponse.class);
EntityTag e = response.getEntityTag();
String entity = response.getEntity(String.class);

If the ClientResponse type is not utilized and the response status is greater than or equal to 300 then the runtime exception UniformInterfaceException is thrown. This exception may be caught and the ClientResponse obtained as follows:

try {
    String entity = r.get(String.class);
} catch (UniformInterfaceException ue) {
    ClientResponse response = ue.getResponse();
}

Creating new WebResources from a WebResource

A new WebResource can be created from an existing WebResource by building from the latter's URI. Thus it is possible to build the request URI before building the request. For example, the following appends a new path segment and adds some query parameters:

WebResource r = c.resource("http://localhost:8080/xyz");

MultivaluedMap<String, String> params = new MultivaluedMapImpl();
params.add("foo", "x");
params.add("bar", "y");

String response = r.path("abc")
                   .queryParams(params)
                   .get(String.class);

that results in a GET request to the URI "http://localhost:8080/xyz/abc?foo=x&bar=y".

Java instances and types for representations

All the Java types for representations supported by the Jersey server side for requests and responses are also supported on the client side. This includes the standard Java types as specified by JAX-RS in addition to JSON, Atom and Multipart MIME as supported by Jersey.

To process a response entity (or representation) as a stream of bytes use InputStream as follows:

InputStream in = r.get(InputStream.class);
// Read from the stream
in.close();

Note that it is important to close the stream after processing so that resources are freed up.

To POST a file use File as follows:

File f = ...
String response = r.post(String.class, f);

Refer to the JAXB sample to see how JAXB with XML and JSON can be utilized with the client API (more specifically, see the unit tests).