Deserialization

essential uses consumers to deserialize request body content other than form parameters. Different consumer methods are responsible for one or more media types. Which consumer method to choose depends on the media type specified in the Content-Type header of the request.

Please note that only requests using the HTTP methods POST and PUT may contain a request body and so only these request methods can contain complex input data.

JAXB consumer

The JAXB consumer is essential's default consumer. It is used for deserializing from XML and JSON if no other consumer has been assigned by resource annotations or configuration. A consumer's behaviour can be fine-tuned by setting the deserialization properties of the controller configuration:

• io.xml.in.*: not used by common JAXB Unmarshallers
• io.json.in.*: properties for deserializing JSON to Object

Using JAXB consumers, your classes should be annotated with the proper JAXB annotations.

Implementing custom consumers

You can create custom consumers to deserialize input of media types which are not naturally supported by essential or implement your own deserialization strategies for already supported media types. Resource implementations can delegate the deserialization process to your custom consumers using the @Consumer annotation.

A consumer is nothing more than a collection of serialization methods, each responsible for a certain set of media types. The consumer methods must follow a certain method signature concept and have to be annotated with the @Consumes annotation.

The annotation's values represent the media types which can be processed by this method.

A consumer method can have any kind of name but must follow this method signatures:

• public Object myMethod(Class<?> type, InputStream is, String charset)

The type parameter indicates the class of the resulting object. The input stream is the request body input stream handed over to the consumer method. Also the request body charset from the Content-Type header is handed over. If the charset is not specified in the Content-Type header then UTF-8 encoding will be assumed and handed over to the consumer method.

Finally, let's have a look on essential's JAXB consumer structure to get a better understanding of how a consumer works:

public class JaxbConsumer extends Consumer {

    public JaxbConsumer(Configuration config) {
        super(config);
    }

    @Consumes( { "text/xml", "application/xml" } )
    public Object xml(Class<?> type, InputStream input, String charset) {
        // XML deserialization process
    }

    @Consumes( { "text/json", "application/json" } )
    public Object json(Class<?> type, InputStream input, String charset) {
        // JSON deserialization process
    }
}

• The class JaxbConsumer inherits the consumer methods of class Consumer
• The constructor expects the controller's configuration object and forwards it to its super class (optional)
• The method xml() promotes to be responsible for deserializing the media types text/xml and application/xml
• The method json() promotes to be responsible for deserializing the media types text/json and application/json