essential uses producers to serialize results to the response body stream. Different producer methods are responsible for one or more output media types. Which producer method to choose depends on the media type specified in the Accept header of the request.
It is possible to override the Accept header of the HTTP request by adding the desired media type to the request URL. For example: http://essential.craftforge.net/example/wine.xml. This works with .xml and .json.
The JAXB producer is essential's default producer. It will be used to serialize the response object to XML or JSON if no other producer has been assigned by resource annotations or configuration. A producer's behaviour can be fine tuned by setting up the serialization properties of the controller configuration.
Serialization properties:
Using the JAXB producer, your result objects' classes should be annotated with the proper JAXB annotations.
Custom producers are necessary if you want to implement custom serialization processes. Resource implementations can delegate the serialization process to custom producers using the @Producer annotation on resource methods or resource class.
Just like consumers - but the other way round, producers can be regarded as collections of serialization methods. Also here, every method is responsible for some media types. A methods' supported media types are declared within the @Produces annotation.
Moreover, the method signature must follow certain rules so the method can be invoked properly.
A producer method can have any kind of name but must follow this method signature:
The result parameter is the resource method result to be serialized by the producer method. The output stream is to be used for streaming the serialization output in the charset encoding specified in the Accept-Charset header. If this header is not specified then UTF-8 will be assumed and handed over to the producer method.
Finally, to improve the understanding of how a producer looks like, let's have a look on the structure of the JAXB producer:
public class JaxbProducer extends Producer {
public JaxbProducer(Configuration config) {
super(config);
}
@Produces({"text/xml", "application/xml"})
public void xml(Object result, OutputStream out, String charset) {
// XML serialization process
}
@Produces({"text/json", "application/json"})
public void json(Object result, OutputStream out, String charset) {
// JSON serialization process
}
}