RESTEasy Reference Guide

RESTEasy can automatically marshal and unmarshal several different message body types.

The JAX-RS specification lets you plug in your own readers and writers for request or response bodies. To do so, annotate a class with @Provider and specify the @Produces types for a reader. You must also implement a MessageBodyReader and a MessageBodyWriter interface.

javax.ws.rs.ext.Providers is a simple injectable interface that lets you locate MessageBodyReader s, MessageBodyWriter s, ContextResolver s and ExceptionMapper s. It also lets you implement multi-part providers (content types that embed other content types). public interface Providers * Get a message body reader that matches a set of criteria. The set of * readers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each reader's * {@link javax.ws.rs.Consumes}, ensuring the supplied value of * {@code type} is assignable to the generic type of the reader, and * eliminating those that do not match. * The list of matching readers is then ordered with those with the best * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*) * sorted first. Finally, the * {@link MessageBodyReader#isReadable} * method is called on each reader in order using the supplied criteria and * the first reader that returns {@code true} is selected and returned. * @param type the class of object that is to be written. * @param mediaType the media type of the data that will be read. * @param genericType the type of object to be produced. E.g. if the * message body is to be converted into a method parameter, this will be * the formal type of the method parameter as returned by * <code>Class.getGenericParameterTypes</code>. * @param annotations an array of the annotations on the declaration of the * artifact that will be initialized with the produced instance. E.g. if the * message body is to be converted into a method parameter, this will be * the annotations on that parameter returned by * <code>Class.getParameterAnnotations</code>. * @return a MessageBodyReader that matches the supplied criteria or null * if none is found. <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType); * Get a message body writer that matches a set of criteria. The set of * writers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each writer's * {@link javax.ws.rs.Produces}, ensuring the supplied value of * {@code type} is assignable to the generic type of the reader, and * eliminating those that do not match. * The list of matching writers is then ordered with those with the best * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) * sorted first. Finally, the * {@link MessageBodyWriter#isWriteable} * method is called on each writer in order using the supplied criteria and * the first writer that returns {@code true} is selected and returned. * @param mediaType the media type of the data that will be written. * @param type the class of object that is to be written. * @param genericType the type of object to be written. E.g. if the * message body is to be produced from a field, this will be * the declared type of the field as returned by * <code>Field.getGenericType</code>. * @param annotations an array of the annotations on the declaration of the * artifact that will be written. E.g. if the * message body is to be produced from a field, this will be * the annotations on that field returned by * <code>Field.getDeclaredAnnotations</code>. * @return a MessageBodyReader that matches the supplied criteria or null * if none is found. <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type, Type genericType, Annotation annotations[], MediaType mediaType); * Get an exception mapping provider for a particular class of exception. * Returns the provider whose generic type is the nearest superclass of * {@code type}. * @param type the class of exception * @return an {@link ExceptionMapper} for the supplied type or null if none * is found. <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type); * Get a context resolver for a particular type of context and media type. * The set of resolvers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each resolver's * {@link javax.ws.rs.Produces}, ensuring the generic type of the context * resolver is assignable to the supplied value of {@code contextType}, and * eliminating those that do not match. If only one resolver matches the * criteria then it is returned. If more than one resolver matches then the * list of matching resolvers is ordered with those with the best * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) * sorted first. A proxy is returned that delegates calls to * {@link ContextResolver#getContext(java.lang.Class)} to each matching context * resolver in order and returns the first non-null value it obtains or null * if all matching context resolvers return null. * @param contextType the class of context desired * @param mediaType the media type of data for which a context is required. * @return a matching context resolver instance or null if no matching * context providers are found. <T> ContextResolver<T> getContextResolver(Class<T> contextType, MediaType mediaType); You can inject an instance of Providers into MessageBodyReader or MessageBodyWriter like so: @Provider @Consumes("multipart/fixed") public class MultipartProvider implements MessageBodyReader { private @Context Providers providers;

RESTEasy provides the required JAXB provider support for XML. It has several additional annotations to make application coding simpler.

@XmlRootElement(name = "book")
public class Book {
   private String author;
   private String ISBN;
   private String title;
   public Book() {
   public Book(String author, String ISBN, String title) {
      this.author = author;
      this.ISBN = ISBN;
      this.title = title;
   @XmlElement
   public String getAuthor() {
      return author;
   public void setAuthor(String author) {
      this.author = author;
   @XmlElement
   public String getISBN() {
      return ISBN;
   public void setISBN(String ISBN) {
      this.ISBN = ISBN;
   @XmlAttribute
   public String getTitle() {
      return title;
   public void setTitle(String title) {
      this.title = title;
			The JAXB Book class would be marshaled to JSON using the BadgerFish Convention:
 {"book":
       "@title":"EJB 3.0",
       "author":{"$":"Bill Burke"},
       "ISBN":{"$":"596529260"}
			Element values are associated with a map. To find the value of the element, you must access the $ variable. You could access the book like this, in JavaScript:
 var data = eval("(" + xhr.responseText + ")");
 document.getElementById("zone").innerHTML = data.book.@title;
 document.getElementById("zone").innerHTML += data.book.author.$;
			To use the BadgerFish Convention you must use the @org.jboss.resteasy.annotations.providers.jaxb.json.BadgerFish annotation either on the JAXB class you are marshaling or unmarshaling, or on the JAX-RS resource method or parameter:
 @BadgerFish
 @XmlRootElement(name = "book")
 public class Book {...}
			To return a book on the JAX-RS method without polluting your JAXB classes with RESTEasy annotations, you can add the annotation to the JAX-RS method instead:
 @BadgerFish
 public Book getBook(...) {...}
			If your input is a Book, place it on the parameter:
 @POST
 public void newBook(@BadgerFish Book book) {...}
			The default Jettison Mapped Convention returns the following JSON:
 { "book" :
         "@title":"EJB 3.0",
         "author":"Bill Burke",
         "ISBN":596529260
			Note that title is prefixed with the @ character. Unlike the BadgerFish convention, this does not represent the value of element text, which makes it simpler (and a sensible default). To access this in JavaScript:
 var data = eval("(" + xhr.responseText + ")");
 document.getElementById("zone").innerHTML = data.book.@title;
 document.getElementById("zone").innerHTML += data.book.author;
			The Mapped Convention lets you adjust the JAXB mapping with the @org.jboss.resteasy.annotations.providers.jaxb.json.Mapped annotation. With this, you can provide an XML namespace to JSON namespace mapping. For example, if you define your JAXB namespace within your package-info.java class like so:
 @javax.xml.bind.annotation.XmlSchema(namespace="http://jboss.org/books")
 package org.jboss.resteasy.test.books;
			You must define a JSON-to-XML namespace mapping, or you will receive an exception:
java.lang.IllegalStateException: Invalid JSON namespace:
  http://jboss.org/books
at org.codehaus.jettison.mapped.MappedNamespaceConvention
  .getJSONNamespace(MappedNamespaceConvention.java:151)
at org.codehaus.jettison.mapped.MappedNamespaceConvention
  .createKey(MappedNamespaceConvention.java:158)
at org.codehaus.jettison.mapped.MappedXMLStreamWriter
  .writeStartElement(MappedXMLStreamWriter.java:241)
			The @Mapped annotation fixes this problem. Place the @Mapped annotation on your JAXB classes, your JAX-RS resource method, or on the parameter that you are unmarshaling.
 import org.jboss.resteasy.annotations.providers.jaxb.json.Mapped;
 import org.jboss.resteasy.annotations.providers.jaxb.json.XmlNsMap;
@Produces("application/json")
@Mapped(namespaceMap = {
        @XmlNsMap(namespace = "http://jboss.org/books", jsonName = "books")
public Book get() {...}
			You can also force @XmlAttributes to be marshaled as XMLElements.
            @Mapped(attributeAsElements={"title"})
            @XmlRootElement(name = "book")
            public class Book {...}
			To return a book on the JAX-RS method without polluting your JAXB classes with RESTEasy annotations, add the annotation to the JAX-RS method:
            @Mapped(attributeAsElements={"title"})
            public Book getBook(...) {...}
			If your input is a Book, place it on the parameter:
 @POST
 public void newBook(@Mapped(attributeAsElements={"title"}) Book book) {...}

@XmlRootElement(namespace = "http://jboss.org/Customer")
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer
   @XmlElement
   private String name;
   public Customer()
   public Customer(String name)
      this.name = name;
   public String getName()
      return name;
@Path("atom")
public static class AtomServer
   @Path("entry")
   @Produces("application/atom+xml")
   public Entry getEntry()
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setJAXBObject(new Customer("bill"));
      entry.setContent(content);
      return entry;
			The Content.setJAXBObject() method tells the content object that you are returning a Java JAXB object to be marshaled. If you use a base format other than XML (for example, application/atom+json), the attached JAXB object will be marshaled into that format.
			If your input is an Atom document, you can also extract JAXB objects from Content by using Content.getJAXBObject(Class class). The code that follows is an example of extracting a Customer object from the Content:
		

@Path("atom")
public static class AtomServer
   @Path("entry")
   @Produces("application/atom+xml")
   public void putCustomer(Entry entry)
      Content content = entry.getContent();
      Customer cust = content.getJAXBObject(Customer.class);
}

<repository>
      <id>jboss</id>
      <url>http://repository.jboss.org/maven2</url>
   </repository>
   <dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>abdera-atom-provider</artifactId>
      <version>...version...</version>
   </dependency>

import org.apache.abdera.Abdera;
import org.apache.abdera.factory.Factory;
import org.apache.abdera.model.Entry;
import org.apache.abdera.model.Feed;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.methods.PutMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;
import org.jboss.resteasy.plugins.providers.atom.AbderaEntryProvider;
import org.jboss.resteasy.plugins.providers.atom.AbderaFeedProvider;
import org.jboss.resteasy.test.BaseResourceTest;
import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.UriInfo;
import javax.xml.bind.JAXBContext;
import java.io.StringReader;
import java.io.StringWriter;
import java.util.Date;
 * @author <a href="mailto:[email protected]">Bill Burke</a>
 * @version $Revision: 1 $
public class AbderaTest extends BaseResourceTest
   @Path("atom")
   public static class MyResource
      private static final Abdera abdera = new Abdera();
      @Path("feed")
      @Produces(MediaType.APPLICATION_ATOM_XML)
      public Feed getFeed(@Context UriInfo uri) throws Exception
         Factory factory = abdera.getFactory();
         Assert.assertNotNull(factory);
         Feed feed = abdera.getFactory().newFeed();
         feed.setId("tag:example.org,2007:/foo");
         feed.setTitle("Test Feed");
         feed.setSubtitle("Feed subtitle");
         feed.setUpdated(new Date());
         feed.addAuthor("James Snell");
         feed.addLink("http://example.com");
         Entry entry = feed.addEntry();
         entry.setId("tag:example.org,2007:/foo/entries/1");
         entry.setTitle("Entry title");
         entry.setUpdated(new Date());
         entry.setPublished(new Date());
         entry.addLink(uri.getRequestUri().toString());
         Customer cust = new Customer("bill");
         JAXBContext ctx = JAXBContext.newInstance(Customer.class);
         StringWriter writer = new StringWriter();
         ctx.createmarshaler().marshal(cust, writer);
         entry.setContent(writer.toString(), "application/xml");
         return feed;
      @Path("feed")
      @Consumes(MediaType.APPLICATION_ATOM_XML)
      public void putFeed(Feed feed) throws Exception
         String content = feed.getEntries().get(0).getContent();
         JAXBContext ctx = JAXBContext.newInstance(Customer.class);
         Customer cust = (Customer) ctx.createUnmarshaler().unmarshal(new StringReader(content));
         Assert.assertEquals("bill", cust.getName());
      @Path("entry")
      @Produces(MediaType.APPLICATION_ATOM_XML)
      public Entry getEntry(@Context UriInfo uri) throws Exception
         Entry entry = abdera.getFactory().newEntry();
         entry.setId("tag:example.org,2007:/foo/entries/1");
         entry.setTitle("Entry title");
         entry.setUpdated(new Date());
         entry.setPublished(new Date());
         entry.addLink(uri.getRequestUri().toString());
         Customer cust = new Customer("bill");
         JAXBContext ctx = JAXBContext.newInstance(Customer.class);
         StringWriter writer = new StringWriter();
         ctx.createmarshaler().marshal(cust, writer);
         entry.setContent(writer.toString(), "application/xml");
         return entry;
      @Path("entry")
      @Consumes(MediaType.APPLICATION_ATOM_XML)
      public void putFeed(Entry entry) throws Exception
         String content = entry.getContent();
         JAXBContext ctx = JAXBContext.newInstance(Customer.class);
         Customer cust = (Customer) ctx.createUnmarshaler().unmarshal(new StringReader(content));
         Assert.assertEquals("bill", cust.getName());
   @Before
   public void setUp() throws Exception
      dispatcher.getProviderFactory().registerProvider(AbderaFeedProvider.class);
      dispatcher.getProviderFactory().registerProvider(AbderaEntryProvider.class);
      dispatcher.getRegistry().addPerRequestResource(MyResource.class);
   @Test
   public void testAbderaFeed() throws Exception
      HttpClient client = new HttpClient();
      GetMethod method = new GetMethod("http://localhost:8081/atom/feed");
      int status = client.executeMethod(method);
      Assert.assertEquals(200, status);
      String str = method.getResponseBodyAsString();
      PutMethod put = new PutMethod("http://localhost:8081/atom/feed");
      put.setRequestEntity(new StringRequestEntity(str, MediaType.APPLICATION_ATOM_XML, null));
      status = client.executeMethod(put);
      Assert.assertEquals(200, status);
   @Test
   public void testAbderaEntry() throws Exception
      HttpClient client = new HttpClient();
      GetMethod method = new GetMethod("http://localhost:8081/atom/entry");
      int status = client.executeMethod(method);
      Assert.assertEquals(200, status);
      String str = method.getResponseBodyAsString();
      PutMethod put = new PutMethod("http://localhost:8081/atom/entry");
      put.setRequestEntity(new StringRequestEntity(str, MediaType.APPLICATION_ATOM_XML, null));
      status = client.executeMethod(put);
      Assert.assertEquals(200, status);

/{pathparam1}/foo/bar/{pathparam2}

/*/foo/bar/*