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