ConverterService
Introduction
The converter service of an application handles the conversion between representations (received by a resource for example) and beans or POJOs. It can be used either programmatically or transparently thanks to annotated Restlet resources.
Description
Server-side usage
Let’s describe how this service is typically used with a ServerResource that supports GET and PUT methods as below:
@Get("json")
// Returns a json representation of a contact.
public Contact toJson(){
[...]
}
@Put()
// Handles a Web form in order to set the full state of the resource.
public void store(Form form){
[...]
}
In this case, the aim of the converter service is to:
- return a JSON representation of a contact
- convert a Web form into a Form object and pass it to the store method.
Client-side usage
On the client-side you can leverage the service either by creating a proxy of an annotated resource interface, via ClientResource.wrap(…) or ClientResource.create(…) methods. Otherwise, it is possible to invoke any web API and specify the excepted return type and let the service convert between beans and representations. Here is the list of related methods on ClientResource:
- delete(Class<T> resultClass) : T
- get(Class<T> resultClass) : T
- options(Class<T> resultClass) : T
- post(Object entity, Class<T> resultClass) : T
- put(Object entity, Class<T> resultClass) : T
For example if you want to retrieve an XML representation as a DOM document, you can just do:
ClientResource cr = new ClientResource("http://myapi.com/path/resource");
Document doc = cr.get(Document.class);
And that’s all you need to do, as long as you have the org.restlet.ext.xml.jar in your classpath!
Internals of the service
A converter service does not contain the conversion logic itself. It leverages a set of declared converters which are subclasses of ConverterHelper. A converter is a piece of code that handles:
- either the conversion of a Representation to an object
- or the conversion of an object to a Representation
- or both conversion
Conversion mainly relies on the media type of the given Representation (application/json, text/xml, etc.) and an instance of a specific class. For example, the default converter provided by the core module (org.restlet.jar) allows the conversion of Web forms (media type “application/x-www-form-urlencoded”) to org.restlet.data.Form instances and vice versa. The converter provided the FreeMarker extension is only able to generate Representations from a FreeMarker Template (class freemarker.template.Template).
A converter is declared using a simple text file located in the “META-INF/services” source directory. Its name is “org.restlet.engine.converter.ConverterHelper” and it contains generally a single line of text which is the full path of the converter class. For example, the FreeMarker extension contains in the “src/META-INF/services” directory such text file with the following line of text: “org.restlet.ext.freemarker.FreemarkerConverter”.
Available converters
Conversion from representations to objects
| Module | From Representations with media type | To Object |
|---|---|---|
| Core | APPLICATION_JAVA_OBJECT | java.lang.Object |
| Core | APPLICATION_JAVA_OBJECT_XML | java.lang.Object |
| Core | APPLICATION_WWW_FORM | org.restlet.Form |
| Core | any kind of Representations | java.lang.String, java.io.InputStream, java.io.Reader, java.nio.ReadableByteChannel |
| Atom | APPLICATION_ATOM | org.restlet.ext.atom.Feed |
| Atom | APPLICATION_ATOM_PUB | org.restlet.ext.atom.Service |
| GWT | APPLICATION_JAVA_OBJECT_GWT | an Object, org.restlet.ext.gwt.ObjectRepresentation |
| Jackson | APPLICATION_JSON | an Object |
| JAXB | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML | object supporting JAXB annotations, org.restlet.ext.JaxbRepresentation |
| JiBX | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML | JiBX bound object, org.restlet.ext.JibxRepresentation |
| JSON | APPLICATION_JSON | org.json.JSONArray, org.json.JSONObject, org.json.JSONTokener |
| RDF | TEXT_RDF_N3, TEXT_RDF_NTRIPLES, APPLICATION_RDF_TURTLE,APPLICATION_ALL_XML | org.restlet.ext.rdf.Graph |
| WADL | APPLICATION_WADL | org.restlet.ext.wadl.ApplicationInfo |
| XML | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML | org.w3c.dom.Document, org.restlet.ext.xml.DomRepresentation, org.restlet.ext.xml.SaxRepresentation |
| XStream | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML, APPLICATION_JSON | (requires Jettison dependency) java.lang.Object, org.restlet.ext.xstream.XStreamRepresentation |
Conversion from objects to representations
| Module | From Object | To Representations with media type |
|---|---|---|
| Core | java.lang.String, java.io.File, java.io.InputStream, java.io.Reader, StringRepresentation, FileRepresentation, InputStreamRepresentation, ReaderRepresentation, org.restlet.representation.Representation | any |
| Core | org.restlet.Form | APPLICATION_WWW_FORM |
| Core | java.io.Serializable | APPLICATION_JAVA_OBJECT, APPLICATION_JAVA_OBJECT_XML |
| Atom | org.restlet.ext.atom.Feed | APPLICATION_ATOM |
| Atom | org.restlet.ext.atom.Service | APPLICATION_ATOM_PUB |
| FreeMarker | freemarker.template.Template | any |
| GWT | an Object, org.restlet.ext.gwt.ObjectRepresentation | APPLICATION_JAVA_OBJECT_GWT |
| Jackson | an Object | APPLICATION_JSON |
| JavaMail | a javax.mail.Message | a org.restlet.ext.javamail.MessageRepresentation |
| JAXB | object supporting JAXB annotations, org.restlet.ext.JaxbRepresentation | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML |
| JiBX | JiBX bound object, org.restlet.ext.JibxRepresentation | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML |
| JSON | org.json.JSONArray, org.json.JSONObject, org.json.JSONTokener | APPLICATION_JSON |
| RDF | org.restlet.ext.rdf.Graph | TEXT_RDF_N3, TEXT_RDF_NTRIPLES, APPLICATION_RDF_TURTLE, APPLICATION_ALL_XML |
| ROME | com.sun.syndication..fedd.synd.SyndFeed | org.restlet.ext.rome.SyndFeedRepresentation |
| Velocity | org.apache.velocity.Template | any |
| WADL | org.restlet.ext.wadl.ApplicationInfo | APPLICATION_WADL |
| XML | org.w3c.dom.Document, org.restlet.ext.xml.DomRepresentation, org.restlet.ext.xml.SaxRepresentation | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML |
| XStream | an object | APPLICATION_ALL_XML, APPLICATION_XML, TEXT_XML, APPLICATION_JSON |