Chapter 8. JAX-RS Entity Providers

A method isWriteable should return true if the MessageBodyWriter<T> is able to write the given type. Method does not decide only based on the Java type of the entity but also on annotations attached to the entity and the requested representation media type.

Parameters type and genericType both define the entity, where type is a raw Java type (for example, a java.util.List class) and genericType is a ParameterizedType including generic information (for example List<String>).

Parameter annotations contains annotations that are either attached to the resource method and/or annotations that are attached to the entity by building response like in the following piece of code:

@Path("resource")
public static class AnnotatedResource {

    @GET
    public Response get() {
        Annotation annotation = AnnotatedResource.class
                            .getAnnotation(Path.class);
        return Response.ok()
                .entity("Entity", new Annotation[] {annotation}).build();
    }
}

In the example above, the MessageBodyWriter<T> would get annotations parameter containing a JAX-RS @GET annotation as it annotates the resource method and also a @Path annotation as it is passed in the response (but not because it annotates the resource; only resource method annotations are included). In the case of MyResource and method getMyBean the annotations would contain the @GET and the @Produces annotation.

The last parameter of the isWriteable method is the mediaType which is the media type attached to the response entity by annotating the resource method with a @Produces annotation or the request media type specified in the JAX-RS Client API. In our example, the media type passed to providers for the resource MyResource and method getMyBean would be "application/xml".

In our implementation of the isWriteable method, we just check that the type is MyBean. Please note, that this method might be executed multiple times by Jersey runtime as Jersey needs to check whether this provider can be used for a particular combination of entity Java type, media type, and attached annotations, which may be potentially a performance hog. You can limit the number of execution by properly defining the @Produces annotation on the MessageBodyWriter<T>. In our case thanks to @Produces annotation, the provider will be considered as writeable (and the method isWriteable might be executed) only if the media type of the outbound message is "application/xml". Additionally, the provider will only be considered as possible candidate and its isWriteable method will be executed, if the generic type of the provider is either a sub class or super class of type parameter.

Once a message body writer is selected as the most appropriate (see the Section 8.3, “Entity Provider Selection” for more details on entity provider selection), its writeTo method is invoked. This method receives parameters with the same meaning as in isWriteable as well as a few additional ones.

In addition to the parameters already introduced, the writeTo method defies also httpHeaders parameter, that contains HTTP headers associated with the outbound message.

Another new parameter, myBean, contains the entity instance to be serialized (the type of entity corresponds to generic type of MessageBodyWriter<T>). Related parameter entityStream contains the entity output stream to which the method should serialize the entity. In our case we use JAXB to marshall the entity into the entityStream. Note, that the entityStream is not closed at the end of method; the stream will be closed by Jersey.

The method is deprecated since JAX-RS 2.0 and Jersey 2 ignores the return value. In JAX-RS 1.0 the method could return the size of the entity that would be then used for "Content-Length" response header. In Jersey 2.0 the "Content-Length" parameter is computed automatically using an internal outbound entity buffering. For details about configuration options of outbound entity buffering see the javadoc of MessageProperties, property OUTBOUND_CONTENT_LENGTH_BUFFER which configures the size of the buffer.

Before testing the MyBeanMessageBodyWriter, the writer must be registered as a custom JAX-RS extension provider. It should either be added to your application ResourceConfig, or returned from your custom Application sub-class, or annotated with @Provider annotation to leverage JAX-RS provider auto-discovery feature.

After registering the MyBeanMessageBodyWriter and MyResource class in our application, the request can be initiated (in this example from Client API).

WebTarget webTarget = // initialize web target to the context root
            // of example application
Response response = webTarget.path("resource")
                        .request(MediaType.APPLICATION_XML).get();
System.out.println(response.getStatus());
String myBeanXml = response.readEntity(String.class);
System.out.println(myBeanXml);

The client code initiates the GET which will be matched to the resource method MyResource.getMyBean(). The response entity is de-serialized as a String.

The result of console output is:

200
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><myBean>
<anyString>Hello World!</anyString><anyNumber>42</anyNumber></myBean>

The returned status is 200 and the entity is stored in the response in a XML format. Next, we will look at how the Jersey de-serializes this XML document into a MyBean consumed by our POST resource method.

It defines the method isReadable() which has a very simliar meaning as method isWriteable() in MessageBodyWriter<T>. The method returns true if it is able to de-serialize the given type. The annotations parameter contains annotations that are attached to the entity parameter in the resource method. In our POST resource method postMyBean the entity parameter myBean is not annotated, therefore no annotation will be passed to the isReadable. The mediaType parameter contains the entity media type. The media type, in our case, must be consumable by the POST resource method, which is specified by placing a JAX-RS @Consumes annotation to the method. The resource method postMyBean() is annotated with @Consumes("application/xml"), therefore for purpose of de-serialization of entity for the postMyBean() method, only requests with entities represented as "application/xml" media type will match the method. However, this method might be executed for entity types that are sub classes or super classes of the declared generic type on the MessageBodyReader<T> will be also considered. It is a responsibility of the isReadable method to decide whether it is able to de-serialize the entity and type comparison is one of the basic decision steps.

The readForm() method gets the parameters with the same meaning as in isReadable(). The additional entityStream parameter provides a handle to the entity input stream from which the entity bytes should be read and de-serialized into a Java entity which is then returned from the method. Our MyBeanMessageBodyReader de-serializes the incoming XML data into an instance of MyBean using JAXB.

Now let's send a test request using the JAX-RS Client API.

final MyBean myBean = new MyBean("posted MyBean", 11);
Response response = webTarget.path("resource").request("application/xml")
        .post(Entity.entity(myBean, "application/xml"));

System.out.println(response.getStatus());
final String responseEntity = response.readEntity(String.class);
System.out.println(responseEntity);

The console output is:

200
posted MyBean

Both, MessageBodyReader<T> and MessageBodyWriter<T> can be registered in a configuration of JAX-RS Client API components typically without any need to change their code. The example Example 8.10, “MessageBodyReader registered on a JAX-RS client” is a variation on the Example 8.5, “Client code testing MyBeanMessageBodyWriter” listed in one of the previous sections.

Client client = ClientBuilder.newBuilder()
    .register(MyBeanMessageBodyReader.class).build();

Response response = client.target("http://example/comm/resource")
    .request(MediaType.APPLICATION_XML).get();
System.out.println(response.getStatus());
MyBean myBean = response.readEntity(MyBean.class);
System.out.println(myBean);

The code above registers MyBeanMessageBodyReader to the Client configuration using a ClientBuilder which means that the provider will be used for any WebTarget produced by the client instance.

Then, using the fluent chain of method invocations, a resource target pointing to our MyResource is defined, a HTTP GET request is invoked. The response entity is then read as an instance of a MyBean type by invoking the response.readEntity method, that internally locates the registered MyBeanMessageBodyReader and uses it for entity de-serialization.

The console output for the example is:

200
MyBean{anyString='Hello World!', anyNumber=42}