RESTEasy JAX-RS

If you are using resteasy outside of JBoss AS 6, you will need to do a few manual steps to install and configure resteasy. RESTeasy is deployed as a WAR archive and thus depends on a Servlet container. We strongly suggest that you use Maven to build your WAR files as RESTEasy is split into a bunch of different modules. You can see an example Maven project in one of the examples in the examples/ directory

Also, when you download RESTeasy and unzip it you will see a lib/ directory that contains the libraries needed by resteasy. Copy these into your /WEB-INF/lib directory. Place your JAX-RS annotated class resources and providers within one or more jars within /WEB-INF/lib or your raw class files within /WEB-INF/classes.

RESTeasy is implemented as a Servlet and deployed within a WAR file. If you open up the WEB-INF/web.xml in one of the example projects of your RESTeasy download you will see this:

                
<web-app>
    <display-name>Archetype Created Web Application</display-name>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>
            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
        </servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

</web-app>

            

The Resteasy servlet is responsible for initializing some basic components of RESTeasy.

Resteasy receives configuration options from <context-param> elements.

The resteasy.servlet.mapping.prefix <context param> variable must be set if your servlet-mapping for the Resteasy servlet has a url-pattern other than /*. For example, if the url-pattern is

                <servlet-mapping>
                <servlet-name>Resteasy</servlet-name>
                <url-pattern>/restful-services/*</url-pattern>
                </servlet-mapping>
            

Then the value of resteasy-servlet.mapping.prefix must be:

                <context-param>
                <param-name>resteasy.servlet.mapping.prefix</param-name>
                <param-value>/restful-services</param-value>
                </context-param>
            

The javax.ws.rs.core.Application class is a standard JAX-RS class that you may implement to provide information on your deployment. It is simply a class the lists all JAX-RS root resources and providers.

                /**
                * Defines the components of a JAX-RS application and supplies additional
                * metadata. A JAX-RS application or implementation supplies a concrete
                * subclass of this abstract class.
                */
                public abstract class Application
                {
                private static final Set<Object> emptySet = Collections.emptySet();

                /**
                * Get a set of root resource and provider classes. The default lifecycle
                * for resource class instances is per-request. The default lifecycle for
                * providers is singleton.
                * <p/>
                * <p>Implementations should warn about and ignore classes that do not
                * conform to the requirements of root resource or provider classes.
                * Implementations should warn about and ignore classes for which
                * {@link #getSingletons()} returns an instance. Implementations MUST
                * NOT modify the returned set.</p>
                *
                * @return a set of root resource and provider classes. Returning null
                * is equivalent to returning an empty set.
                */
                public abstract Set<Class<?>> getClasses();

                /**
                * Get a set of root resource and provider instances. Fields and properties
                * of returned instances are injected with their declared dependencies
                * (see {@link Context}) by the runtime prior to use.
                * <p/>
                * <p>Implementations should warn about and ignore classes that do not
                * conform to the requirements of root resource or provider classes.
                * Implementations should flag an error if the returned set includes
                * more than one instance of the same class. Implementations MUST
                * NOT modify the returned set.</p>
                * <p/>
                * <p>The default implementation returns an empty set.</p>
                *
                * @return a set of root resource and provider instances. Returning null
                * is equivalent to returning an empty set.
                */
                public Set<Object> getSingletons()
                {
                return emptySet;
                }

                }
            

To use Application you must set a servlet init-param, javax.ws.rs.Application with a fully qualified class that implements Application. For example:

    
    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>
            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
        </servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
        </init-param>
    </servlet>  

If you have this set, you should probably turn off automatic scanning as this will probably result in duplicate classes being registered.

The initialization of RESTEasy can be performed within a ServletContextListener instead of within the Servlet. You may need this if you are writing custom Listeners that need to interact with RESTEasy at boot time. An example of this is the RESTEasy Spring integration that requires a Spring ServletContextListener. The org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap class is a ServletContextListener that configures an instance of an ResteasyProviderFactory and Registry. You can obtain instances of a ResteasyProviderFactory and Registry from the ServletContext attributes org.jboss.resteasy.spi.ResteasyProviderFactory and org.jboss.resteasy.spi.Registry. From these instances you can programmatically interact with RESTEasy registration interfaces.

            
<web-app>
   <listener>
      <listener-class>
         org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
      </listener-class>
   </listener>

  <!-- ** INSERT YOUR LISTENERS HERE!!!! -->

   <servlet>
      <servlet-name>Resteasy</servlet-name>
      <servlet-class>
         org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
      </servlet-class>
   </servlet>

   <servlet-mapping>
      <servlet-name>Resteasy</servlet-name>
      <url-pattern>/resteasy/*</url-pattern>
   </servlet-mapping>

</web-app>

        

The downside of running Resteasy as a Servlet is that you cannot have static resources like .html and .jpeg files in the same path as your JAX-RS services. Resteasy allows you to run as a Filter instead. If a JAX-RS resource is not found under the URL requested, Resteasy will delegate back to the base servlet container to resolve URLs.

            
<web-app>
    <filter>
        <filter-name>Resteasy</filter-name>
        <filter-class>
            org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
        </filter-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>Resteasy</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

</web-app>
        

Resteasy is bundled with JBoss AS 7. You will likely have the need to upgrade Resteasy in AS7. The Resteasy distribution comes with a zip file called resteasy-jboss-modules-2.3.7.Final.zip. In the top level directory of JBoss AS 7 (the one with the modules/ directory), unzip this file. You should be patched with the latest and greatest Resteasy after this.

RESTEasy is bundled with JBoss AS 7 and completely integrated as per the requirements of Java EE 6. First you must at least provide an empty web.xml file. You can of course deploy any custom servlet, filter or security constraint you want to within your web.xml, but the least amount of work is to create an empty web.xml file. Also, resteasy context-params are available if you want to tweak turn on/off any specific resteasy feature.

                
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
</web-app>

            

Since we're not using a jax-rs servlet mapping, we must define an Application class that is annotated with the @ApplicationPath annotation. If you return any empty set for by classes and singletons, your WAR will be scanned for JAX-RS annotation resource and provider classes.

            import javax.ws.rs.ApplicationPath;
            import javax.ws.rs.core.Application;

            @ApplicationPath("/root-path")
            public class MyApplication extends Application
            {
            }
        

The Resteasy distribution has ported the "Restful Java" O'Reilly workbook examples to AS7. You can find these under the directory examples/oreilly-workbook-as7.

RESTEasy supports logging via java.util.logging, Log4j, or Slf4j. How it picks which framework to delegate to is expressed in the following algorithm:

The logging categories are still a work in progress, but the initial set should make it easier to troubleshoot issues. Currently, the framework has defined the following log categories:

The @Path annotation is not limited to simple path expressions. You also have the ability to insert regular expressions into @Path's value. For example:

@Path("/resources)
public class MyResource {

   @GET
   @Path("{var:.*}/stuff")
   public String get() {...}
}

The following GETs will route to the getResource() method:

GET /resources/stuff
GET /resources/foo/stuff
GET /resources/on/and/on/stuff

The format of the expression is:

"{" variable-name [ ":" regular-expression ] "}"

The regular-expression part is optional. When the expression is not provided, it defaults to a wildcard matching of one particular segment. In regular-expression terms, the expression defaults to

"([]*)"

For example:

@Path("/resources/{var}/stuff")

will match these:

GET /resources/foo/stuff
GET /resources/bar/stuff

but will not match:

GET /resources/a/bunch/of/stuff

There are a few more complicated uses of @PathParams not discussed in the previous section.

You are allowed to specify one or more path params embedded in one URI segment. Here are some examples:

1. @Path("/aaa{param}bbb")
2. @Path("/{name}-{zip}")
3. @Path("/foo{name}-{zip}bar")

So, a URI of "/aaa111bbb" would match #1. "/bill-02115" would match #2. "foobill-02115bar" would match #3.

We discussed before how you can use regular expression patterns within @Path values.

@GET
@Path("/aaa{param:b+}/{many:.*}/stuff")
public String getIt(@PathParam("param") String bs, @PathParam("many") String many) {...}

For the following requests, lets see what the values of the "param" and "many" @PathParams would be:

The specification has a very simple abstraction for examining a fragment of the URI path being invoked on javax.ws.rs.core.PathSegment:

public interface PathSegment {

    /**
     * Get the path segment.
     * <p>
     * @return the path segment
     */
    String getPath();
    /**
     * Get a map of the matrix parameters associated with the path segment
     * @return the map of matrix parameters
     */
    MultivaluedMap<String, String> getMatrixParameters();
    
}

You can have Resteasy inject a PathSegment instead of a value with your @PathParam.

   @GET
   @Path("/book/{id}")
   public String getBook(@PathParam("id") PathSegment id) {...}

This is very useful if you have a bunch of @PathParams that use matrix parameters. The idea of matrix parameters is that they are an arbitrary set of name-value pairs embedded in a uri path segment. The PathSegment object gives you access to these parameters. See also MatrixParam.

A matrix parameter example is:

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

The basic idea of matrix parameters is that it represents resources that are addressable by their attributes as well as their raw id.

Some clients, like browsers, cannot use the Accept and Accept-Language headers to negotiation the representation's media type or language. RESTEasy allows you to map file name suffixes like (.xml, .txt, .en, .fr) to media types and languages. These file name suffixes take the place and override any Accept header sent by the client. You configure this using the resteasy.media.type.mappings and resteasy.language.mappings context-param variables within your web.xml

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <context-param>
        <param-name>resteasy.media.type.mappings</param-name>
        <param-value>html : text/html, json : application/json, xml : application/xml</param-value>
    </context-param>

   <context-param>
        <param-name>resteasy.language.mappings</param-name>
        <param-value> en : en-US, es : es, fr : fr</param-name>
   </context-param>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

Mappings are a comma delimited list of suffix/mediatype or suffix/language mappings. Each mapping is delimited by a ':'. So, if you invoked GET /foo/bar.xml.en, this would be equivalent to invoking the following request:

GET /foo/bar
Accept: application/xml
Accept-Language: en-US

The mapped file suffixes are stripped from the target URL path before the request is dispatched to a corresponding JAX-RS resource.

RESTEasy can do content negotiation based in a parameter in query string. To enable this, the web.xml can be configured like follow:

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <context-param>
        <param-name>resteasy.media.type.param.mapping</param-name>
        <param-value>someName</param-value>
    </context-param>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

The param-value is the name of the query string parameter that RESTEasy will use in the place of the Accept header.

Invoking http://service.foo.com/resouce?someName=application/xml, will give the application/xml media type the highest priority in the content negotiation.

In cases where the request contains both the parameter and the Accept header, the parameter will be more relevant.

It is possible to left the param-value empty, what will cause the processor to look for a parameter named 'accept'.

Resteasy can automatically marshal and unmarshal a few different message bodies.

The JAX-RS specification allows you to plug in your own request/response body reader and writers. To do this, you annotate a class with @Provider and specify the @Produces types for a writer and @Consumes types for a reader. You must also implement a MessageBodyReader/Writer interface respectively. Here is an example.

The Resteasy ServletContextLoader will automatically scan your WEB-INF/lib and classes directories for classes annotated with @Provider or you can manually configure them in web.xml. See Installation/Configuration

javax.ws.rs.ext.Providers is a simple injectable interface that allows you to look up MessageBodyReaders, Writers, ContextResolvers, and ExceptionMappers. It is very useful, for instance, for implementing multipart providers. Content types that embed other random 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&#47;* > *&#47;*)
    * 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&#47;* > *&#47;*)
    * 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);
}

         

A Providers instance is injectable into MessageBodyReader or Writers:

            @Provider
            @Consumes("multipart/fixed")
            public class MultipartProvider implements MessageBodyReader {

            private @Context Providers providers;

            ...

            }
         

Resteasy's JAXB providers have a pluggable way to decorate Marshaller and Unmarshaller instances. The way it works is that you can write an annotation that can trigger the decoration of a Marshaller or Unmarshaller. Your decorators can do things like set Marshaller or Unmarshaller properties, set up validation, stuff like that. Here's an example. Let's say we want to have an annotation that will trigger pretty-printing, nice formatting, of an XML document. If we were doing raw JAXB, we would set a property on the Marshaller of Marshaller.JAXB_FORMATTED_OUTPUT. Let's write a Marshaller decorator.

First we define a annotation:

 import org.jboss.resteasy.annotations.Decorator;

 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 @Decorator(processor = PrettyProcessor.class, target = Marshaller.class)
 public @interface Pretty {}
 

To get this to work, we must annotate our @Pretty annotation with a meta-annotation called @Decorator. The target() attribute must be the JAXB Marshaller class. The processor() attribute is a class we will write next.

 
 import org.jboss.resteasy.core.interception.DecoratorProcessor;
 import org.jboss.resteasy.annotations.DecorateTypes;

 import javax.xml.bind.Marshaller;
 import javax.xml.bind.PropertyException;
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.Produces;
 import java.lang.annotation.Annotation;

 /**
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */
 @DecorateTypes({"text/*+xml", "application/*+xml"})
 public class PrettyProcessor implements DecoratorProcessor<Marshaller, Pretty>
 {
    public Marshaller decorate(Marshaller target, Pretty annotation,
                  Class type, Annotation[] annotations, MediaType mediaType)
    {
       target.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    }
 }
 
 

The processor implementation must implement the DecoratorProcessor interface and should also be annotated with @DecorateTypes. This annotation specifies what media types the processor can be used with. Now that we've defined our annotation and our Processor, we can use it on our JAX-RS resource methods or JAXB types as follows:

   @GET
   @Pretty
   @Produces("application/xml")
   public SomeJAXBObject get() {...}
 

If you are confused, check the Resteasy source code for the implementation of @XmlHeader

You should not use this feature unless you know what you're doing.

Based on the class you are marshalling/unmarshalling, RESTEasy will, by default create and cache JAXBContext instances per class type. If you do not want RESTEasy to create JAXBContexts, you can plug-in your own by implementing an instance of javax.ws.rs.ext.ContextResolver

 public interface ContextResolver<T>
 {
T getContext(Class<?> type);
 }

 @Provider
 @Produces("application/xml")
 public class MyJAXBContextResolver implements ContextResolver<JAXBContext>
 {
JAXBContext getContext(Class<?> type)
{
   if (type.equals(WhateverClassIsOverridedFor.class)) return JAXBContext.newInstance()...;
}
 }
         

You must provide a @Produces annotation to specify the media type the context is meant for. You must also make sure to implement ContextResolver<JAXBContext>. This helps the runtime match to the correct context resolver. You must also annotate the ContextResolver class with @Provider.

There are multiple ways to make this ContextResolver available.

Resteasy is required to provide JAXB provider support for XML. It has a few extra annotations that can help code your app.

RESTEasy allows you to marshall JAXB annotated POJOs to and from JSON. This provider wraps the Jettison JSON library to accomplish this. You can obtain more information about Jettison and how it works from:

http://jettison.codehaus.org/

To use this integration with Jettision you need to import the resteasy-jettison-provider Maven module. Older versions of RESTEasy used to include this within the resteasy-jaxb-provider but we decided to modularize it more.

Jettison has two mapping formats. One is BadgerFish the other is a Jettison Mapped Convention format. The Mapped Convention is the default mapping.

For example, consider this JAXB class:

 @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;
}
 }
         

This is how the JAXB Book class would be marshalled to JSON using the BadgerFish Convention

 {"book":
    {
       "@title":"EJB 3.0",
       "author":{"$":"Bill Burke"},
       "ISBN":{"$":"596529260"}
    }
 }
 

Notice that element values have a map associated with them and to get to the value of the element, you must access the "$" variable. Here's an example of accessing the book 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 on the JAXB class you are marshalling/unmarshalling, or, on the JAX-RS resource method or parameter:

 @BadgerFish
 @XmlRootElement(name = "book")
 public class Book {...}
 

If you are returning a book on the JAX-RS method and you don't want to (or can't) pollute your JAXB classes with RESTEasy annotations, add the annotation to the JAX-RS method:

 @BadgerFish
 @GET
 public Book getBook(...) {...}
 

If a Book is your input then you put it on the parameter:

 @POST
 public void newBook(@BadgerFish Book book) {...}
 

The default Jettison Mapped Convention would return JSON that looked like this:

 { "book" :
      {
         "@title":"EJB 3.0",
         "author":"Bill Burke",
         "ISBN":596529260
       }
 }
 

Notice that the @XmlAttribute "title" is prefixed with the '@' character. Unlike BadgerFish, the '$' does not represent the value of element text. This format is a bit simpler than the BadgerFish convention which is why it was chose as a default. Here's an example of accessing 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 allows you to fine tune the JAXB mapping using the @org.jboss.resteasy.annotations.providers.jaxb.json.Mapped annotation. You can provide an XML Namespace to JSON namespace mapping. For example, if you defined your JAXB namespace within your package-info.java class like this:

 @javax.xml.bind.annotation.XmlSchema(namespace="http://jboss.org/books")
 package org.jboss.resteasy.test.books;
 

You would have to define a JSON to XML namespace mapping or you would receive an exception of something like this:

 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)
 

To fix this problem you need another annotation, @Mapped. You use the @Mapped annotation on your JAXB classes, on your JAX-RS resource method, or on the parameter you are unmarshalling

 import org.jboss.resteasy.annotations.providers.jaxb.json.Mapped;
 import org.jboss.resteasy.annotations.providers.jaxb.json.XmlNsMap;

 ...

@GET
@Produces("application/json")
@Mapped(namespaceMap = {
        @XmlNsMap(namespace = "http://jboss.org/books", jsonName = "books")
})
public Book get() {...}

 

Besides mapping XML to JSON namespaces, you can also force @XmlAttribute's to be marshaled as XMLElements.

            @Mapped(attributeAsElements={"title"})
            @XmlRootElement(name = "book")
            public class Book {...}
         

If you are returning a book on the JAX-RS method and you don't want to (or can't) pollute your JAXB classes with RESTEasy annotations, add the annotation to the JAX-RS method:

            @Mapped(attributeAsElements={"title"})
            @GET
            public Book getBook(...) {...}
         

If a Book is your input then you put it on the parameter:

 @POST
 public void newBook(@Mapped(attributeAsElements={"title"}) Book book) {...}
 

RESTEasy supports the FastinfoSet mime type with JAXB annotated classes. Fast infoset documents are faster to serialize and parse, and smaller in size, than logically equivalent XML documents. Thus, fast infoset documents may be used whenever the size and processing time of XML documents is an issue. It is configured the same way the XML JAXB provider is so really no other documentation is needed here.

To use this integration with Fastinfoset you need to import the resteasy-fastinfoset-provider Maven module. Older versions of RESTEasy used to include this within the resteasy-jaxb-provider but we decided to modularize it more.

RESTEasy will automatically marshal arrays, java.util.Set's, and java.util.List's of JAXB objects to and from XML, JSON, Fastinfoset (or any other new JAXB mapper Restasy comes up with).

 @XmlRootElement(name = "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("/")
 public class MyResource
 {
   @PUT
   @Path("array")
   @Consumes("application/xml")
   public void putCustomers(Customer[] customers)
   {
      Assert.assertEquals("bill", customers[0].getName());
      Assert.assertEquals("monica", customers[1].getName());
   }

   @GET
   @Path("set")
   @Produces("application/xml")
   public Set<Customer> getCustomerSet()
   {
      HashSet<Customer> set = new HashSet<Customer>();
      set.add(new Customer("bill"));
      set.add(new Customer("monica"));

      return set;
   }


   @PUT
   @Path("list")
   @Consumes("application/xml")
   public void putCustomers(List<Customer> customers)
   {
      Assert.assertEquals("bill", customers.get(0).getName());
      Assert.assertEquals("monica", customers.get(1).getName());
   }
 }
 
 

The above resource can publish and receive JAXB objects. It is assumed that are wrapped in a collection element

 <collection>
<customer><name>bill</name></customer>
<customer><name>monica</name></customer>
 <collection>
 
 

You can change the namespace URI, namespace tag, and collection element name by using the @org.jboss.resteasy.annotations.providers.jaxb.Wrapped annotation on a parameter or method

 @Target({ElementType.PARAMETER, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Wrapped
 {
String element() default "collection";

String namespace() default "http://jboss.org/resteasy";

String prefix() default "resteasy";
 }
 

So, if we wanted to output this XML

 <foo:list xmlns:foo="http://foo.org">
<customer><name>bill</name></customer>
<customer><name>monica</name></customer>
 </foo:list>
 
 

We would use the @Wrapped annotation as follows:

   @GET
   @Path("list")
   @Produces("application/xml")
   @Wrapped(element="list", namespace="http://foo.org", prefix="foo")
   public List<Customer> getCustomerSet()
   {
      List<Customer> list = new ArrayList<Customer>();
      list.add(new Customer("bill"));
      list.add(new Customer("monica"));

      return list;
   }
 
 

RESTEasy will automatically marshal maps of JAXB objects to and from XML, JSON, Fastinfoset (or any other new JAXB mapper Restasy comes up with). Your parameter or method return type must be a generic with a String as the key and the JAXB object's type.

@XmlRootElement(namespace = "http://foo.com")
public static class Foo
{
   @XmlAttribute
   private String name;

   public Foo()
   {
   }

   public Foo(String name)
   {
      this.name = name;
   }

   public String getName()
   {
      return name;
   }
}

@Path("/map")
public static class MyResource
{
   @POST
   @Produces("application/xml")
   @Consumes("application/xml")
   public Map<String, Foo> post(Map<String, Foo> map)
   {
      Assert.assertEquals(2, map.size());
      Assert.assertNotNull(map.get("bill"));
      Assert.assertNotNull(map.get("monica"));
      Assert.assertEquals(map.get("bill").getName(), "bill");
      Assert.assertEquals(map.get("monica").getName(), "monica");
      return map;
   }
 }
 
 

The above resource can publish and receive JAXB objects within a map. By default, they are wrapped in a "map" element in the default namespace. Also, each "map" element has zero or more "entry" elements with a "key" attribute.

 <map>
<entry key="bill" xmlns="http://foo.com">
    <foo name="bill"/>
</entry>
<entry key="monica" xmlns="http://foo.com">
    <foo name="monica"/>
</entry>
 </map>
 
 

You can change the namespace URI, namespace prefix and map, entry, and key element and attribute names by using the @org.jboss.resteasy.annotations.providers.jaxb.WrappedMap annotation on a parameter or method

 @Target({ElementType.PARAMETER, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface WrappedMap
 {
/**
 * map element name
 */
String map() default "map";

/**
 * entry element name *
 */
String entry() default "entry";

/**
 * entry's key attribute name
 */
String key() default "key";

String namespace() default "";

String prefix() default "";
 }
 

So, if we wanted to output this XML

 <hashmap>
<hashentry hashkey="bill" xmlns:foo="http://foo.com">
    <foo:foo name="bill"/>
</hashentry>
 </map>
 
 

We would use the @WrappedMap annotation as follows:

@Path("/map")
public static class MyResource
{
   @GET
   @Produces("application/xml")
   @WrappedMap(map="hashmap", entry="hashentry", key="hashkey")
   public Map<String, Foo> get()
   {
      ...
      return map;
   }
 
 

Some objects models use abstract classes and interfaces heavily. Unfortunately, JAXB doesn't work with interfaces that are root elements and RESTEasy can't unmarshal parameters that are interfaces or raw abstract classes because it doesn't have enough information to create a JAXBContext. For example:

 public interface IFoo {}

 @XmlRootElement
 public class RealFoo implements IFoo {}

 @Path("/jaxb")
 public class MyResource {

@PUT
@Consumes("application/xml")
public void put(IFoo foo) {...}
 }
 

In this example, you would get an error from RESTEasy of something like "Cannot find a MessageBodyReader for...". This is because RESTEasy does not know that implementations of IFoo are JAXB classes and doesn't know how to create a JAXBContext for it. As a workaround, RESTEasy allows you to use the JAXB annotation @XmlSeeAlso on the interface to correct the problem. (NOTE, this will not work with manual, hand-coded JAXB).

 @XmlSeeAlso(RealFoo.class)
 public interface IFoo {}
 

The extra @XmlSeeAlso on IFoo allows RESTEasy to create a JAXBContext that knows how to unmarshal RealFoo instances.

RESTEasy has defined a simple object model in Java to represent Atom and uses JAXB to marshal and unmarshal it. The main classes are in the org.jboss.resteasy.plugins.providers.atom package and are Feed, Entry, Content, and Link. If you look at the source, you'd see that these are annotated with JAXB annotations. The distribution contains the javadocs for this project and are a must to learn the model. Here is a simple example of sending an atom feed using the Resteasy API.

import org.jboss.resteasy.plugins.providers.atom.Content;
import org.jboss.resteasy.plugins.providers.atom.Entry;
import org.jboss.resteasy.plugins.providers.atom.Feed;
import org.jboss.resteasy.plugins.providers.atom.Link;
import org.jboss.resteasy.plugins.providers.atom.Person;

@Path("atom")
public class MyAtomService
{

   @GET
   @Path("feed")
   @Produces("application/atom+xml")
   public Feed getFeed() throws URISyntaxException
   {
      Feed feed = new Feed();
      feed.setId(new URI("http://example.com/42"));
      feed.setTitle("My Feed");
      feed.setUpdated(new Date());
      Link link = new Link();
      link.setHref(new URI("http://localhost"));
      link.setRel("edit");
      feed.getLinks().add(link);
      feed.getAuthors().add(new Person("Bill Burke"));
      Entry entry = new Entry();
      entry.setTitle("Hello World");
      Content content = new Content();
      content.setType(MediaType.TEXT_HTML_TYPE);
      content.setText("Nothing much");
      entry.setContent(content);
      feed.getEntries().add(entry);
      return feed;
   }
}

      

Because Resteasy's atom provider is JAXB based, you are not limited to sending atom objects using XML. You can automatically re-use all the other JAXB providers that Resteasy has like JSON and fastinfoset. All you have to do is have "atom+" in front of the main subtype. i.e. @Produces("application/atom+json") or @Consumes("application/atom+fastinfoset")

The org.jboss.resteasy.plugins.providers.atom.Content class allows you to unmarshal and marshal JAXB annotated objects that are the body of the content. Here's an example of sending an Entry with a Customer object attached as the body of the entry's content.

@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
{
   @GET
   @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 is used to tell the content object you are sending back a Java JAXB object and want it marshalled appropriately. If you are using a different base format other than XML, i.e. "application/atom+json", this attached JAXB object will be marshalled into that same format.

If you have an atom document as your input, you can also extract JAXB objects from Content using the Content.getJAXBObject(Class clazz) method. Here is an example of an input atom document and extracting a Customer object from the content.

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

If your Jackson classes are annotated with JAXB annotations and you have the resteasy-jaxb-provider in your classpath, you may trigger the Jettision JAXB marshalling code. To turn off the JAXB json marshaller use the @org.jboss.resteasy.annotations.providers.jaxb.IgnoreMediaTypes("application/*+json") on your classes.

When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in any multipart mime type. org.jboss.resteasy.plugins.providers.multipart.MultipartInput

package org.jboss.resteasy.plugins.providers.multipart;

public interface MultipartInput
{
   List<InputPart> getParts();

   String getPreamble();

   // You must call close to delete any temporary files created
   // Otherwise they will be deleted on garbage collection or on JVM exit
   void close();
}

public interface InputPart
{
   MultivaluedMap<String, String> getHeaders();

   String getBodyAsString();

   <T> T getBody(Class<T> type, Type genericType) throws IOException;

   <T> T getBody(org.jboss.resteasy.util.GenericType<T> type) throws IOException;

   MediaType getMediaType();

   boolean isContentTypeFromMessage();
}
      

MultipartInput is a simple interface that allows you to get access to each part of the multipart message. Each part is represented by an InputPart interface. Each part has a set of headers associated with it You can unmarshall the part by calling one of the getBody() methods. The Type genericType parameter can be null, but the Class type parameter must be set. Resteasy will find a MessageBodyReader based on the media type of the part as well as the type information you pass in. The following piece of code is unmarshalling parts which are XML into a JAXB annotated class called Customer.

   @Path("/multipart")
   public class MyService
   {
      @PUT
      @Consumes("multipart/mixed")
      public void put(MultipartInput input)
      {
         List<Customer> customers = new ArrayList...;
         for (InputPart part : input.getParts())
         {
            Customer cust = part.getBody(Customer.class, null);
            customers.add(cust);
         }
         input.close();
      }
   }

Sometimes you may want to unmarshall a body part that is sensitive to generic type metadata. In this case you can use the org.jboss.resteasy.util.GenericType class. Here's an example of unmarshalling a type that is sensitive to generic type metadata.

   @Path("/multipart")
   public class MyService
   {
      @PUT
      @Consumes("multipart/mixed")
      public void put(MultipartInput input)
      {
         for (InputPart part : input.getParts())
         {
            List<Customer> cust = part.getBody(new GenericType>List>Customer<<() {});
         }
         input.close();
      }
   }

Use of GenericType is required because it is really the only way to obtain generic type information at runtime.

If your body parts are uniform, you do not have to manually unmarshall each and every part. You can just provide a java.util.List as your input parameter. It must have the type it is unmarshalling with the generic parameter of the List type declaration. Here's an example again of unmarshalling a list of customers.

   @Path("/multipart")
   public class MyService
   {
      @PUT
      @Consumes("multipart/mixed")
      public void put(List<Customer> customers)
      {
         ...
      }
   }

When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in multipart/form-data mime type. "multipart/form-data" is often found in web application HTML Form documents and is generally used to upload files. The form-data format is the same as other multipart formats, except that each inlined piece of content has a name associated with it. The interface used for form-data input is org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput

public interface MultipartFormDataInput extends MultipartInput
{
   @Deprecated
   Map<String, InputPart> getFormData();

   Map<String, List<InputPart>> getFormDataMap();

   <T> T getFormDataPart(String key, Class<T> rawType, Type genericType) throws IOException;

   <T> T getFormDataPart(String key, GenericType<T> type) throws IOException;
}

It works in much the same way as MultipartInput described earlier in this chapter.

With form-data, if your body parts are uniform, you do not have to manually unmarshall each and every part. You can just provide a java.util.Map as your input parameter. It must have the type it is unmarshalling with the generic parameter of the List type declaration. Here's an example of of unmarshalling a Map of Customer objects which are JAXB annotated classes.

   @Path("/multipart")
   public class MyService
   {
      @PUT
      @Consumes("multipart/form-data")
      public void put(Map<String, Customer> customers)
      {
         ...
      }
   }

When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in multipart/related mime type. A multipart/related is used to indicate that message parts should not be considered individually but rather as parts of an aggregate whole. One example usage for multipart/related is to send a web page complete with images in a single message. Every multipart/related message has a root/start part that references the other parts of the message. The parts are identified by their "Content-ID" headers. multipart/related is defined by RFC 2387. The interface used for related input is org.jboss.resteasy.plugins.providers.multipart.MultipartRelatedInput

public interface MultipartRelatedInput extends MultipartInput
{
   String getType();

   String getStart();

   String getStartInfo();

   InputPart getRootPart();

   Map<String, InputPart> getRelatedMap();
}

It works in much the same way as MultipartInput described earlier in this chapter.

RESTEasy provides a simple API to output multipart data.

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartOutput
{
   public OutputPart addPart(Object entity, MediaType mediaType)

   public OutputPart addPart(Object entity, GenericType type, MediaType mediaType)

   public OutputPart addPart(Object entity, Class type, Type genericType, MediaType mediaType)

   public List<OutputPart> getParts()

   public String getBoundary()

   public void setBoundary(String boundary)
}

public class OutputPart
{
   public MultivaluedMap<String, Object> getHeaders()

   public Object getEntity()

   public Class getType()

   public Type getGenericType()

   public MediaType getMediaType()
}

When you want to output multipart data it is as simple as creating a MultipartOutput object and calling addPart() methods. Resteasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/mixed" format back to the calling client. The parts are Customer objects which are JAXB annotated and will be marshalling into "application/xml".

   @Path("/multipart")
   public class MyService
   {
      @GET
      @Produces("multipart/mixed")
      public MultipartOutput get()
      {
         MultipartOutput output = new MultipartOutput();
         output.addPart(new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
         output.addPart(new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
         return output;
      }

If your body parts are uniform, you do not have to manually marshall each and every part or even use a MultipartOutput object.. You can just provide a java.util.List. It must have the generic type it is marshalling with the generic parameter of the List type declaration. You must also annotate the method with the @PartType annotation to specify what media type each part is. Here's an example of sending back a list of customers back to a client. The customers are JAXB objects

   @Path("/multipart")
   public class MyService
   {
      @GET
      @Produces("multipart/mixed")
      @PartType("application/xml")
      public List<Customer> get()
      {
         ...
      }
   }

RESTEasy provides a simple API to output multipart/form-data.

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartFormDataOutput extends MultipartOutput
{
   public OutputPart addFormData(String key, Object entity, MediaType mediaType)

   public OutputPart addFormData(String key, Object entity, GenericType type, MediaType mediaType)

   public OutputPart addFormData(String key, Object entity, Class type, Type genericType, MediaType mediaType)

   public Map<String, OutputPart> getFormData()
}

When you want to output multipart/form-data it is as simple as creating a MultipartFormDataOutput object and calling addFormData() methods. Resteasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/form-data" format back to the calling client. The parts are Customer objects which are JAXB annotated and will be marshalling into "application/xml".

   @Path("/form")
   public class MyService
   {
      @GET
      @Produces("multipart/form-data")
      public MultipartFormDataOutput get()
      {
         MultipartFormDataOutput output = new MultipartFormDataOutput();
         output.addPart("bill", new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
         output.addPart("monica", new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
         return output;
      }

If your body parts are uniform, you do not have to manually marshall each and every part or even use a MultipartFormDataOutput object.. You can just provide a java.util.Map. It must have the generic type it is marshalling with the generic parameter of the Map type declaration. You must also annotate the method with the @PartType annotation to specify what media type each part is. Here's an example of sending back a list of customers back to a client. The customers are JAXB objects

   @Path("/multipart")
   public class MyService
   {
      @GET
      @Produces("multipart/form-data")
      @PartType("application/xml")
      public Map<String, Customer> get()
      {
         ...
      }
   }

RESTEasy provides a simple API to output multipart/related.

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartRelatedOutput extends MultipartOutput
{
   public OutputPart getRootPart()

   public OutputPart addPart(Object entity, MediaType mediaType,
      String contentId, String contentTransferEncoding)

   public String getStartInfo()

   public void setStartInfo(String startInfo)
}

When you want to output multipart/related it is as simple as creating a MultipartRelatedOutput object and calling addPart() methods. The first added part will be used as the root part of the multipart/related message. Resteasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/related" format back to the calling client. We are sending a html with 2 images.

@Path("/related")
public class MyService
{
   @GET
   @Produces("multipart/related")
   public MultipartRelatedOutput get()
   {
      MultipartRelatedOutput output = new MultipartRelatedOutput();
      output.setStartInfo("text/html");

      Map<String, String> mediaTypeParameters = new LinkedHashMap<String, String>();
      mediaTypeParameters.put("charset", "UTF-8");
      mediaTypeParameters.put("type", "text/html");
      output
         .addPart(
            "<html><body>\n"
            + "This is me: <img src='cid:http://example.org/me.png' />\n"
            + "<br />This is you: <img src='cid:http://example.org/you.png' />\n"
            + "</body></html>",
            new MediaType("text", "html", mediaTypeParameters),
            "<mymessage.xml@example.org>", "8bit");
      output.addPart("// binary octets for me png",
            new MediaType("image", "png"), "<http://example.org/me.png>",
            "binary");
      output.addPart("// binary octets for you png", new MediaType(
            "image", "png"),
            "<http://example.org/you.png>", "binary");
      client.putRelated(output);
      return output;
   }
}

If you have a exact knowledge of your multipart/form-data packets, you can map them to and from a POJO class to and from multipart/form-data using the @org.jboss.resteasy.annotations.providers.multipart.MultipartForm annotation and the JAX-RS @FormParam annotation. You simple define a POJO with at least a default constructor and annotate its fields and/or properties with @FormParams. These @FormParams must also be annotated with @org.jboss.resteasy.annotations.providers.multipart.PartType if you are doing output. For example:

   public class CustomerProblemForm {
      @FormParam("customer")
      @PartType("application/xml")
      private Customer customer;

      @FormParam("problem")
      @PartType("text/plain")
      private String problem;

      public Customer getCustomer() { return customer; }
      public void setCustomer(Customer cust) { this.customer = cust; }
      public String getProblem() { return problem; }
      public void setProblem(String problem) { this.problem = problem; }
   }

After defining your POJO class you can then use it to represent multipart/form-data. Here's an example of sending a CustomerProblemForm using the RESTEasy client framework

   @Path("portal")
   public interface CustomerPortal {

      @Path("issues/{id}")
      @Consumes("multipart/form-data")
      @PUT
      public void putProblem(@MultipartForm CustomerProblemForm,
                             @PathParam("id") int id);
   }

   {
       CustomerPortal portal = ProxyFactory.create(CustomerPortal.class, "http://example.com");
       CustomerProblemForm form = new CustomerProblemForm();
       form.setCustomer(...);
       form.setProblem(...);

       portal.putProblem(form, 333);
   }

You see that the @MultipartForm annotation was used to tell RESTEasy that the object has @FormParam and that it should be marshalled from that. You can also use the same object to receive multipart data. Here is an example of the server side counterpart of our customer portal.

   @Path("portal")
   public class CustomerPortalServer {

      @Path("issues/{id})
      @Consumes("multipart/form-data")
      @PUT
      public void putIssue(@MultipartForm CustoemrProblemForm,
                           @PathParam("id") int id) {
         ... write to database...
      }
   }

There are a lot of frameworks doing multipart parsing automatically with the help of filters and interceptors. Like org.jboss.seam.web.MultipartFilter in Seam or org.springframework.web.multipart.MultipartResolver in Spring. However the incoming multipart request stream can be parsed only once. Resteasy users working with multipart should make sure that nothing parses the stream before Resteasy gets it.

By default if no Content-Type header is present in a part, "text/plain; charset=us-ascii" is used as fallback. This is the value defined by the MIME RFC. However for example some web clients (like most, if not all, web browsers) do not send Content-Type headers for all fields in a multipart/form-data request (only for the file parts). This can cause character encoding and unmarshalling errors on the server side. To correct this there is an option to define an other, non-rfc compliant fallback value. This can be done dynamically per request with the PreProcessInterceptor infrastructure of RESTEasy. In the following example we will set "*/*; charset=UTF-8" as the new default fallback:

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements
		PreProcessInterceptor {

	public ServerResponse preProcess(HttpRequest request,
			ResourceMethod method) throws Failure, WebApplicationException {
		request.setAttribute(InputPart.DEFAULT_CONTENT_TYPE_PROPERTY,
				"*/*; charset=UTF-8");
		return null;
	}

}

Using an interceptor and the InputPart.DEFAULT_CONTENT_TYPE_PROPERTY attribute allows setting a default Content-Type, but it is also possible to override the Content-Type, if any, in any input part by calling org.jboss.resteasy.plugins.providers.multipart.InputPart.setMediaType(). For example:

@POST
@Path("query")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.TEXT_PLAIN)
public Response setMediaType(MultipartInput input) throws IOException
{
   List<InputPart> parts = input.getParts();
   InputPart part = parts.get(0);
   part.setMediaType(MediaType.valueOf("application/foo+xml"));
   String s = part.getBody(String.class, null);
   ...
}

Sometimes, a part may have a Content-Type header with no charset parameter. If the InputPart.DEFAULT_CONTENT_TYPE_PROPERTY property is set and the value has a charset parameter, that value will be appended to an existing Content-Type header that has no charset parameter. It is also possible to specify a default charset using the constant InputPart.DEFAULT_CHARSET_PROPERTY (actual value "resteasy.provider.multipart.inputpart.defaultCharset"):

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements
		PreProcessInterceptor {

	public ServerResponse preProcess(HttpRequest request,
			ResourceMethod method) throws Failure, WebApplicationException {
		request.setAttribute(InputPart.DEFAULT_CHARSET_PROPERTY, "UTF-8");
		return null;
	}

}

If both InputPart.DEFAULT_CONTENT_TYPE_PROPERTY and InputPart.DEFAULT_CHARSET_PROPERTY are set, then the value of InputPart.DEFAULT_CHARSET_PROPERTY will override any charset in the value of InputPart.DEFAULT_CONTENT_TYPE_PROPERTY.

package org.jboss.resteasy.spi;

public interface StringConverter<T>
{
   T fromString(String str);
   String toString(T value);
}



   

You implement this interface to provide your own custom string marshalling. It is registered within your web.xml under the resteasy.providers context-param (See Installation and Configuration chapter). You can do it manually by calling the ResteasyProviderFactory.addStringConverter() method. Here's a simple example of using a StringConverter:

   import org.jboss.resteasy.client.ProxyFactory;
   import org.jboss.resteasy.spi.StringConverter;
   import org.jboss.resteasy.test.BaseResourceTest;
   import org.junit.Assert;
   import org.junit.Before;
   import org.junit.Test;

   import javax.ws.rs.HeaderParam;
   import javax.ws.rs.MatrixParam;
   import javax.ws.rs.PUT;
   import javax.ws.rs.Path;
   import javax.ws.rs.PathParam;
   import javax.ws.rs.QueryParam;
   import javax.ws.rs.ext.Provider;

   public class StringConverterTest extends BaseResourceTest
   {
      public static class POJO
      {
         private String name;

         public String getName()
         {
            return name;
         }

         public void setName(String name)
         {
            this.name = name;
         }
      }

      @Provider
      public static class POJOConverter implements StringConverter<POJO>
      {
         public POJO fromString(String str)
         {
            System.out.println("FROM STRNG: " + str);
            POJO pojo = new POJO();
            pojo.setName(str);
            return pojo;
         }

         public String toString(POJO value)
         {
            return value.getName();
         }
      }

      @Path("/")
      public static class MyResource
      {
         @Path("{pojo}")
         @PUT
         public void put(@QueryParam("pojo")POJO q, @PathParam("pojo")POJO pp,
                         @MatrixParam("pojo")POJO mp, @HeaderParam("pojo")POJO hp)
         {
            Assert.assertEquals(q.getName(), "pojo");
            Assert.assertEquals(pp.getName(), "pojo");
            Assert.assertEquals(mp.getName(), "pojo");
            Assert.assertEquals(hp.getName(), "pojo");
         }
      }

      @Before
      public void setUp() throws Exception
      {
         dispatcher.getProviderFactory().addStringConverter(POJOConverter.class);
         dispatcher.getRegistry().addPerRequestResource(MyResource.class);
      }

      @Path("/")
      public static interface MyClient
      {
         @Path("{pojo}")
         @PUT
         void put(@QueryParam("pojo")POJO q, @PathParam("pojo")POJO pp,
                  @MatrixParam("pojo")POJO mp, @HeaderParam("pojo")POJO hp);
      }

      @Test
      public void testIt() throws Exception
      {
         MyClient client = ProxyFactory.create(MyClient.class, "http://localhost:8081");
         POJO pojo = new POJO();
         pojo.setName("pojo");
         client.put(pojo, pojo, pojo, pojo);
      }
   }

   

org.jboss.resteasy.spi.StringParameterUnmarshaller is sensitive to the annotations placed on the parameter or field you are injecting into. It is created per injector. The setAnnotations() method is called by resteasy to initialize the unmarshaller.

package org.jboss.resteasy.spi;

public interface StringParameterUnmarshaller<T>
{
   void setAnnotations(Annotation[] annotations);
   T fromString(String str);
}

You can add this by creating and registering a provider that implements this interface. You can also bind them using a meta-annotation called org.jboss.resteasy.annotationsStringParameterUnmarshallerBinder. Here's an example of formatting a java.util.Date based @PathParam

public class StringParamUnmarshallerTest extends BaseResourceTest
{
   @Retention(RetentionPolicy.RUNTIME)
   @StringParameterUnmarshallerBinder(DateFormatter.class)
   public @interface DateFormat
   {
      String value();
   }

   public static class DateFormatter implements StringParameterUnmarshaller<Date>
   {
      private SimpleDateFormat formatter;

      public void setAnnotations(Annotation[] annotations)
      {
         DateFormat format = FindAnnotation.findAnnotation(annotations, DateFormat.class);
         formatter = new SimpleDateFormat(format.value());
      }

      public Date fromString(String str)
      {
         try
         {
            return formatter.parse(str);
         }
         catch (ParseException e)
         {
            throw new RuntimeException(e);
         }
      }
   }

   @Path("/datetest")
   public static class Service
   {
      @GET
      @Produces("text/plain")
      @Path("/{date}")
      public String get(@PathParam("date") @DateFormat("MM-dd-yyyy") Date date)
      {
         System.out.println(date);
         Calendar c = Calendar.getInstance();
         c.setTime(date);
         Assert.assertEquals(3, c.get(Calendar.MONTH));
         Assert.assertEquals(23, c.get(Calendar.DAY_OF_MONTH));
         Assert.assertEquals(1977, c.get(Calendar.YEAR));
         return date.toString();
      }
   }

   @BeforeClass
   public static void setup() throws Exception
   {
      addPerRequestResource(Service.class);
   }

   @Test
   public void testMe() throws Exception
   {
      ClientRequest request = new ClientRequest(generateURL("/datetest/04-23-1977"));
      System.out.println(request.getTarget(String.class));
   }
}

In the example a new annotation is defined called @DateFormat. This annotation class is annotated with the meta-annotation StringParameterUnmarshallerBinder with a reference to the DateFormmater classes.

The Service.get() method has a @PathParam parameter that is also annotated with @DateFormat. The application of @DateFormat triggers the binding of the DateFormatter. The DateFormatter will now be run to unmarshal the path parameter into the date paramter of the get() method.

ExceptionMappers are custom, application provided, components that can catch thrown application exceptions and write specific HTTP responses. The are classes annotated with @Provider and that implement this interface

         package javax.ws.rs.ext;

         import javax.ws.rs.core.Response;

         /**
         * Contract for a provider that maps Java exceptions to
         * {@link javax.ws.rs.core.Response}. An implementation of this interface must
         * be annotated with {@link Provider}.
         *
         * @see Provider
         * @see javax.ws.rs.core.Response
         */
         public interface ExceptionMapper<E>
         {

         /**
         * Map an exception to a {@link javax.ws.rs.core.Response}.
         *
         * @param exception the exception to map to a response
         * @return a response mapped from the supplied exception
         */
         Response toResponse(E exception);
         }
      

When an application exception is thrown it will be caught by the JAX-RS runtime. JAX-RS will then scan registered ExceptionMappers to see which one support marshalling the exception type thrown. Here is an example of ExceptionMapper

         @Provider
         public class EJBExceptionMapper implements ExceptionMapper<javax.ejb.EJBException>
         {

         Response toResponse(EJBException exception) {
         return Response.status(500).build();
         }

         }
      

You register ExceptionMappers the same way you do MessageBodyReader/Writers. By scanning, through the resteasy provider context-param (if you're deploying via a WAR file), or programmatically through the ResteasyProviderFactory class.

Resteasy has a set of built-in exceptions that are thrown by it when it encounters errors during dispatching or marshalling. They all revolve around specific HTTP error codes. You can find them in RESTEasy's javadoc under the package org.jboss.resteasy.spi. Here's a list of them:

You may override Resteasy built-in exceptions by writing an ExceptionMapper for the exception. For that matter, you can write an ExceptionMapper for any thrown exception including WebApplicationException

Resteasy provides an extension to JAX-RS that allows you to automatically set Cache-Control headers on a successful GET request. It can only be used on @GET annotated methods. A successful @GET request is any request that returns 200 OK response.

package org.jboss.resteasy.annotations.cache;

public @interface Cache
{
   int maxAge() default -1;
   int sMaxAge() default -1;
   boolean noStore() default false;
   boolean noTransform() default false;
   boolean mustRevalidate() default false;
   boolean proxyRevalidate() default false;
   boolean isPrivate() default false;
}

public @interface NoCache
{
   String[] fields() default {};
}

   

While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to say that you don't want anything cached i.e. Cache-Control: nocache.

These annotations can be put on the resource class or interface and specifies a default cache value for each @GET resource method. Or they can be put individually on each @GET resource method.

Resteasy has the ability to set up a client-side, browser-like, cache. You can use it with the Client Proxy Framework, or with raw ClientRequests. This cache looks for Cache-Control headers sent back with a server response. If the Cache-Control headers specify that the client is allowed to cache the response, Resteasy caches it within local memory. The cache obeys max-age requirements and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the original response. See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.

It is very simple to enable caching. Here's an example of using the client cache with the Client Proxy Framework

@Path("/orders")
public interface OrderServiceClient {

   @Path("{id}")
   @GET
   @Produces("application/xml")
   public Order getOrder(@PathParam("id") String id);
}

To create a proxy for this interface and enable caching for that proxy requires only a few simple steps:

import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.cache.CacheFactory;
import org.jboss.resteasy.client.cache.LightweightBrowserCache;

public static void main(String[] args) throws Exception
{
      RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
      OrderServiceClient proxy = ProxyFactory.create(OrderServiceClient.class, generateBaseUrl());

      // This line enables caching
      LightweightBrowserCache cache = CacheFactory.makeCacheable(proxy);
}

If you are using the ClientRequest class to make invocations rather than the proxy framework, it is just as easy

import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.cache.CacheFactory;
import org.jboss.resteasy.client.cache.LightweightBrowserCache;

public static void main(String[] args) throws Exception
{
      RegisterBuiltin.register(ResteasyProviderFactory.getInstance());

      // This line enables caching
      LightweightBrowserCache cache = new LightweightBrowserCache();

      ClientRequest request = new ClientRequest("http://example.com/orders/333");
      CacheFactory.makeCacheable(request, cache);
}

The LightweightBrowserCache, by default, has a maximum 2 megabytes of caching space. You can change this programmatically by callings its setMaxBytes() method. If the cache gets full, the cache completely wipes itself of all cached data. This may seem a bit draconian, but the cache was written to avoid unnecessary synchronizations in a concurrent environment where the cache is shared between multiple threads. If you desire a more complex caching solution or if you want to plug in a thirdparty cache please contact our resteasy-developers list and discuss it with the community.

Resteasy has a server-side, local, in-memory cache that can sit in front of your JAX-RS services. It automatically caches marshalled responses from HTTP GET JAX-RS invocations if, and only if your JAX-RS resource method sets a Cache-Control header. When a GET comes in, the Resteasy Server Cache checks to see if the URI is stored in the cache. If it does, it returns the already marshalled response without invoking your JAX-RS method. Each cache entry has a max age to whatever is specified in the Cache-Control header of the initial request. The cache also will automatically generate an ETag using an MD5 hash on the response body. This allows the client to do HTTP 1.1 cache revalidation with the IF-NONE-MATCH header. The cache is also smart enough to perform revalidation if there is no initial cache hit, but the jax-rs method still returns a body that has the same ETag.

Starting in Resteasy 2.3, the cache is also automatically invalidated for a particular URI that has PUT, POST, or DELETE invoked on it. You can also obtain a reference to the cache by injecting a org.jboss.resteasy.plugins.cache.ServerCache via the @Context annotation

    @Context
    ServerCache cache;

    @GET
    public String get(@Context ServerCache cache) {...}

To set up the server-side cache, there are a few simple steps you have to perform. If you are using Maven you must depend on the resteasy-cache-core artifact:

<dependency>
   <groupId>org.jboss.resteasy</groupId>
   <artifactId>resteasy-cache-core</artifactId>
   <version>2.3.7.Final</version>
</dependency>

The next thing you have to do is to add a ServletContextListener, org.jboss.resteasy.plugins.cache.server.ServletServerCache. This must be specified after the ResteasyBootstrap listener in your web.xml file.

<web-app>
    <listener>
        <listener-class>
            org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
        </listener-class>
    </listener>

    <context-param>
        <param-name>resteasy.server.cache.maxsize</param-name>
        <param-value>1000</param-value>
    </context-param>

    <context-param>
        <param-name>resteasy.server.cache.eviction.wakeup.interval</param-name>
        <param-value>5000</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.jboss.resteasy.plugins.cache.server.ServletServerCache
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>
            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
        </servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/rest-services/*</url-pattern>
    </servlet-mapping>

</web-app>

The cache implementation is based on the JBoss Cache project: http://jboss.org/jbosscache. There are two context-param configuration variables that you can set. resteasy.server.cache.maxsize sets the number of elements that can be cached. The resteasy.server.cache.eviction.wakeup.interval sets the rate at which the background eviction thread runs to purge the cache of stale entries.

MessageBodyReader and Writer interceptors work off of the same principles. They wrap around the invocation of MessageBodyReader.readFrom() or MessageBodyWriter.writeTo(). You can use them to wrap the Output or InputStream. For example, the Resteasy GZIP support has interceptors that create and override the default Output and InputStream with a GzipOutpuStream or GzipInputStream so that gzip encoding can work. You could use them to append headers to the response (or on the client side, the outgoing request).

To implement one you implement the org.jbos.resteasy.spi.interception.MessageBodyReaderInterceptor or MessageBodyWriterInterceptor

public interface MessageBodyReaderInterceptor
{
   Object read(MessageBodyReaderContext context) throws IOException, WebApplicationException;

}

public interface MessageBodyWriterInterceptor
{
   void write(MessageBodyWriterContext context) throws IOException, WebApplicationException;

}

            

Interceptors are driven by the MessageBodyWriterContext or MessageBodyReaderContext. The interceptors and the MessageBodyReader or Writer is invoked in one big Java call stack. You must call MessageBodyReaderContext.proceed() or MessageBodyWriterContext.proceed() to go to the next interceptor or, if there are no more interceptors to invoke, the readFrom() or writeTo() method of the MessageBodyReader or MessageBodyWriter. This wrapping allows you to modify things before they get to the Reader or Writer then clean up after proceed() returns. The Context objects also have methods to modify the parameters going to the Reader or Writer.

public interface MessageBodyReaderContext
{
   Class getType();

   void setType(Class type);

   Type getGenericType();

   void setGenericType(Type genericType);

   Annotation[] getAnnotations();

   void setAnnotations(Annotation[] annotations);

   MediaType getMediaType();

   void setMediaType(MediaType mediaType);

   MultivaluedMap<String, String> getHeaders();

   InputStream getInputStream();

   void setInputStream(InputStream is);

   Object proceed() throws IOException, WebApplicationException;
}

public interface MessageBodyWriterContext
{
   Object getEntity();

   void setEntity(Object entity);

   Class getType();

   void setType(Class type);

   Type getGenericType();

   void setGenericType(Type genericType);

   Annotation[] getAnnotations();

   void setAnnotations(Annotation[] annotations);

   MediaType getMediaType();

   void setMediaType(MediaType mediaType);

   MultivaluedMap<String, Object> getHeaders();

   OutputStream getOutputStream();

   public void setOutputStream(OutputStream os);

   void proceed() throws IOException, WebApplicationException;
}

MessageBodyReaderInterceptors and MessageBodyWriterInterceptors can be used on the serverside or client side. They must be annotated with @org.jboss.resteasy.annotations.interception.ServerInterceptor or @org.jboss.resteasy.annotations.interception.ClientInterceptor so that resteasy knows whether or not to add them to the interceptor list. If you do not annotate your interceptor classes with one or both of these annotations, you will receive a deployment error. They also should be annotated with @Provider. Lets look at an example:

@Provider
@ServerInterceptor
public class MyHeaderDecorator implements MessageBodyWriterInterceptor {

    public void write(MessageBodyWriterContext context) throws IOException, WebApplicationException
    {
       context.getHeaders().add("My-Header", "custom");
       context.proceed();
    }
}

Here we have a server side interceptor that adds a header value to the response. You see that it is annotated with @Provider and @ServerInterceptor. It must modify the header before calling context.proceed() as the response may be committed after the MessageBodyReader runs. Remember, you MUST call context.proceed(). If you don't, your invocation will not happen.

The org.jboss.resteasy.spi.interception.PreProcessInterceptor runs after a JAX-RS resource method is found to invoke on, but before the actual invocation happens. They are only usable on the server, but still must be annotated with @ServerInterceptor. They can be used to implement security features or can preempt the Java request. The Resteasy security implementation uses this type of interceptor to abort requests before the actually happen if the user does not pass authorization. The Resteasy caching framework also uses this to return cached responses to avoid invoking methods again. Here's what the interceptor interface looks like:

    public interface PreProcessInterceptor
    {
       ServerResponse preProcess(HttpRequest request, ResourceMethod method) throws Failure, WebApplicationException;
    }

PreProcessInterceptors run in sequence and do not wrap the actual JAX-RS invocation. Here's some pseudo code that illustrates how they work:

    for (PreProcessInterceptor interceptor : preProcessInterceptors) {
       ServerResponse response = interceptor.preProcess(request, method);
       if (response != null) return response;
    }
    executeJaxrsMethod(...);

If the preProcess() method returns a ServerResponse then the underlying JAX-RS method will not get invoked and the runtime will process the response and return to the client.

The org.jboss.resteasy.spi.interception.PostProcessInterceptor runs after the JAX-RS method was invoked but before MessageBodyWriters are invoked. They can only be used on the server side. Use them if you need to set a response header when there might not be any MessageBodyWriter invoked. They are there for symmetry with PreProcessInterceptor. They do not wrap anything and are invoked in order like PreProcessInterceptors are.

    public interface PostProcessInterceptor
    {
       void postProcess(ServerResponse response);
    }
    

org.jboss.resteasy.spi.interception.ClientExecutionInterceptor classes only are usable on the client side. They run after the MessageBodyWriter and after the ClientRequest has been totally built on the client side. They wrap around the actually HTTP invocation that goes to the server. Resteasy GZIP support uses them to set the Accept header to contain "gzip, deflate" before the request goes out. The Resteasy client cache uses it to check to see if its cache contains the resource before going over the wire. These interceptors must be annotated with @ClientInterceptor and @Provider.

    public interface ClientExecutionInterceptor
    {
       ClientResponse execute(ClientExecutionContext ctx) throws Exception;
    }

    public interface ClientExecutionContext
    {
       ClientRequest getRequest();

       ClientResponse proceed() throws Exception;
    }
    

The work work in the same pattern as MessageBodyReader/WriterInterceptors in that you must call proceed() unless you want to abort the invocation.

By default, any registered interceptor will be invoked for any request you do. By default, every request will use your interceptors. You can fine tune this by having your interceptors implement the org.jboss.resteasy.spi.AcceptedByMethod interface:

    public interface AcceptedByMethod
    {
       public boolean accept(Class declaring, Method method);
    }

If your interceptor implements this interface, Resteasy will invoke the accept() method. If this method returns true, Resteasy will add that interceptor to the JAX-RS method's call chain. If it returns false then it won't be added to the call chain. For example:

@Provider
@ServerInterceptor
public class MyHeaderDecorator implements MessageBodyWriterInterceptor, AcceptedByMethod {

    public boolean accept(Class declaring, Method method) {
       return method.isAnnotationPresent(GET.class);
    }

   public void write(MessageBodyWriterContext context) throws IOException, WebApplicationException
   {
      context.getHeaders().add("My-Header", "custom");
      context.proceed();
   }
}
        

In this example, our accept() method checks to see if the @GET annotation is present on our JAX-RS method. If it is, then this interceptor will be applied to that method's call chain.

Registering interceptors is easy. Since they are a @Provider, (you remembered to annotate it right?) they can be listed in the resteasy.providers context-param in web.xml or returned as a class or object in the Application.getClasses() or Application.getSingletons() method.

Some interceptors are very sensitive in which order they are invoked. For example, you always want your security interceptor invoked first. Other interceptor's behavior might be triggered by a different interceptor that adds a header. By default, you have no control over the order in which registered interceptors are invoked. There is a way to specify interceptor precedence though.

You do not specify interceptor precedence by listing interceptor classes. Instead, there are precedence families and a particular interceptor class is associated with a family via the @org.jboss.resteasy.annotations.interception.Precedence annotation. We did this because some of the built in interceptors included with Resteasy are very sensitive to ordering. By specifying precedence through a family structure, we can protect these built in interceptors. An advantage to this approach is that configuration is also a lot easier too for you.

These are the families and the order in which they are executed:

    SECURITY
    HEADER_DECORATOR
    ENCODER
    REDIRECT
    DECODER

Any interceptor not associated with a precedence family will be invoked last. SECURITY usually involves PreProcessInterceptors. They should be invoked first because you want to do as little as possible before your invocation is authorized. HEADER_DECORATORs are interceptors that add headers to a response or an outgoing request. They need to come next because these added headers may effect the behavior of other interceptors. ENCODER interceptors change the OutputStream. For example, the GZIP interceptor creates a GZIPOutputStream to wrap the real OutputStream for compression. REDIRECT interceptors usually are used in PreProcessInterceptors as they may reroute the request and totally bypas the JAX-RS method. DECODER interceptors wrap the InputStream. For example, the GZIP interceptor decoder wraps the InputStream in a GzipInputStream instance.

To marry your custom interceptors to a particular family you annotate it with the @org.jboss.resteasy.annotations.interception.Precendence annotation.

@Provider
@ServerInterceptor
@ClientInterceptor
@Precedence("ENCODER")
public class MyCompressionInterceptor implements MessageBodyWriterInterceptor {...}

For complete type safety, there are convenience annotations in the org.jbos.resteasy.annotations.interception package: @DecoredPrecedence, @EncoderPrecedence, @HeaderDecoratorPrecedence, @RedirectPrecedence, @SecurityPrecedence. Use these instead of the @Precedence annotation

To use Resteasy's Asynchronous HTTP apis with Tomcat 6 or JBoss 4.2.3, you must use a special Restasy Servlet and configure Tomcat (or JBoss Web in JBoss 4.2.3) to use the NIO transport. First edit Tomcat's (or JBoss Web's) server.xml file. Comment out the vanilla HTTP adapter and add this:

<Connector port="8080" address="${jboss.bind.address}"
   emptySessionPath="true" protocol="org.apache.coyote.http11.Http11NioProtocol"
   enableLookups="false" redirectPort="6443" acceptorThreadCount="2" pollerThreadCount="10"
/>
      

Your deployed Resteasy applications must also use a different Resteasy servlet, org.jboss.resteasy.plugins.server.servlet.Tomcat6CometDispatcherServlet. This class is available within the async-http-tomcat-xxx.jar or within the Maven repository under the async-http-tomcat6 artifact id. web.xml

<servlet>
   <servlet-name>Resteasy</servlet-name>
   <servlet-class>org.jboss.resteasy.plugins.server.servlet.Tomcat6CometDispatcherServlet</servlet-class>
</servlet>
      

Our Servlet 3.0 support has only been tested with JBoss AS 6 M4 (trunk SVN as of 7/12/2010).

Your deployed Resteasy applications must also use a different Resteasy servlet, org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher. This class is available within the async-http-servlet-3.0-xxx.jar or within the Maven repository under the async-http-servlet-3.0 artifact id. web.xml:

   <servlet>
      <servlet-name>Resteasy</servlet-name>
      <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher</servlet-class>
      <async-supported>true</async-supported>
   </servlet>
      

There's also a Filter30Dispatcher class if you want to use Resteasy as a filter. If you are running within JBoss AS 6 M4 or higher, you do not have to add this config to your web.xml if you are relying on the app server to do automatic scanning and have web.xml empty.

The JBossWeb container shipped with JBoss AS 5.0.x and higher requires you to install the JBoss Native plugin to enable asynchronous HTTP processing. Please see the JBoss Web documentation on how to do this.

Your deployed Resteasy applications must also use a different Resteasy servlet, org.jboss.resteasy.plugins.server.servlet.JBossWebDispatcherServlet. This class is available within the async-http-jbossweb-xxx.jar or within the Maven repository under the async-http-jbossweb artifact id. web.xml:

<servlet>
   <servlet-name>Resteasy</servlet-name>
   <servlet-class>org.jboss.resteasy.plugins.server.servlet.JBossWebDispatcherServlet</servlet-class>
</servlet>
      

While HTTP is a synchronous protocol it does have a faint idea of asynchronous invocations. The HTTP 1.1 response code 202, "Accepted" means that the server has received and accepted the response for processing, but the processing has not yet been completed. The Resteasy Asynchronous Job Service builds around this idea.

POST http://example.com/myservice?asynch=true

For example, if you make the above post with the asynch query parameter set to true, Resteasy will return a 202, "Accepted" response code and run the invocation in the background. It also sends back a Location header with a URL pointing to where the response of the background method is located.

HTTP/1.1 202 Accepted
Location: http://example.com/asynch/jobs/3332334

The URI will have the form of:

/asynch/jobs/{job-id}?wait={millisconds}|nowait=true

You can perform the GET, POST, and DELETE operations on this job URL. GET returns whatever the JAX-RS resource method you invoked returned as a response if the job was completed. If the job has not completed, this GET will return a response code of 202, Accepted. Invoking GET does not remove the job, so you can call it multiple times. When Resteasy's job queue gets full, it will evict the least recently used job from memory. You can manually clean up after yourself by calling DELETE on the URI. POST does a read of the JOB response and will remove the JOB it has been completed.

Both GET and POST allow you to specify a maximum wait time in milliseconds, a "wait" query parameter. Here's an example:

POST http://example.com/asynch/jobs/122?wait=3000

If you do not specify a "wait" parameter, the GET or POST will not wait at all if the job is not complete.

NOTE!! While you can invoke GET, DELETE, and PUT methods asynchronously, this breaks the HTTP 1.1 contract of these methods. While these invocations may not change the state of the resource if invoked more than once, they do change the state of the server as new Job entries with each invocation. If you want to be a purist, stick with only invoking POST methods asynchronously.

Security NOTE! Resteasy role-based security (annotations) does not work with the Asynchronous Job Service. You must use XML declarative security within your web.xml file. Why? It is impossible to implement role-based security portably. In the future, we may have specific JBoss integration, but will not support other environments.

Resteasy also supports the notion of fire and forget. This will also return a 202, Accepted response, but no Job will be created. This is as simple as using the oneway query parameter instead of asynch. For example:

POST http://example.com/myservice?oneway=true

Security NOTE! Resteasy role-based security (annotations) does not work with the Asynchronous Job Service. You must use XML declaritive security within your web.xml file. Why? It is impossible to implement role-based security portably. In the future, we may have specific JBoss integration, but will not support other environments.

You must enable the Asynchronous Job Service in your web.xml file as it is not turned on by default.

<web-app>
    <!-- enable the Asynchronous Job Service -->
    <context-param>
        <param-name>resteasy.async.job.service.enabled</param-name>
        <param-value>true</param-value>
    </context-param>

    <!-- The next context parameters are all optional.  
         Their default values are shown as example param-values -->

    <!-- How many jobs results can be held in memory at once? -->
    <context-param>
        <param-name>resteasy.async.job.service.max.job.results</param-name>
        <param-value>100</param-value>
    </context-param>

    <!-- Maximum wait time on a job when a client is querying for it -->
    <context-param>
        <param-name>resteasy.async.job.service.max.wait</param-name>
        <param-value>300000</param-value>
    </context-param>

    <!-- Thread pool size of background threads that run the job -->
    <context-param>
        <param-name>resteasy.async.job.service.thread.pool.size</param-name>
        <param-value>100</param-value>
    </context-param>

    <!-- Set the base path for the Job uris -->
    <context-param>
        <param-name>resteasy.async.job.service.base.path</param-name>
        <param-value>/asynch/jobs</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>
            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
        </servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

</web-app>

For Maven users, you must use the resteasy-spring artifact. Otherwise, the jar is available in the downloaded distribution.

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-spring</artifactId>
    <version>whatever version you are using</version>
</dependency>

RESTeasy comes with its own Spring ContextLoaderListener that registers a RESTeasy specific BeanPostProcessor that processes JAX-RS annotations when a bean is created by a BeanFactory. What does this mean? RESTeasy will automatically scan for @Provider and JAX-RS resource annotations on your bean class and register them as JAX-RS resources.

Here is what you have to do with your web.xml file

<web-app>
   <display-name>Archetype Created Web Application</display-name>

   <listener>
      <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
   </listener>

   <listener>
      <listener-class>org.jboss.resteasy.plugins.spring.SpringContextLoaderListener</listener-class>
   </listener>

   <servlet>
      <servlet-name>Resteasy</servlet-name>
      <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
   </servlet>

   <servlet-mapping>
      <servlet-name>Resteasy</servlet-name>
      <url-pattern>/*</url-pattern>
   </servlet-mapping>


</web-app>

The SpringContextLoaderListener must be declared after ResteasyBootstrap as it uses ServletContext attributes initialized by it.

If you do not use a Spring ContextLoaderListener to create your bean factories, then you can manually register the RESTeasy BeanFactoryPostProcessor by allocating an instance of org.jboss.resteasy.plugins.spring.SpringBeanProcessor. You can obtain instances of a ResteasyProviderFactory and Registry from the ServletContext attributes org.jboss.resteasy.spi.ResteasyProviderFactory and org.jboss.resteasy.spi.Registry. (Really the string FQN of these classes). There is also a org.jboss.resteasy.plugins.spring.SpringBeanProcessorServletAware, that will automatically inject references to the Registry and ResteasyProviderFactory from the Servlet Context. (that is, if you have used RestasyBootstrap to bootstrap Resteasy).

Our Spring integration supports both singletons and the "prototype" scope. RESTEasy handles injecting @Context references. Constructor injection is not supported though. Also, with the "prototype" scope, RESTEasy will inject any @*Param annotated fields or setters before the request is dispatched.

NOTE: You can only use auto-proxied beans with our base Spring integration. You will have undesirable affects if you are doing handcoded proxying with Spring, i.e., with ProxyFactoryBean. If you are using auto-proxied beans, you will be ok.

RESTEasy can also integrate with the Spring DispatcherServlet. The advantages of using this are that you have a simpler web.xml file, you can dispatch to either Spring controllers or Resteasy from under the same base URL, and finally, the most important, you can use Spring ModelAndView objects as return arguments from @GET resource methods. Setup requires you using the Spring DispatcherServlet in your web.xml file, as well as importing the springmvc-resteasy.xml file into your base Spring beans xml file. Here's an example web.xml file:

<web-app>
   <display-name>Archetype Created Web Application</display-name>

   <servlet>
      <servlet-name>Spring</servlet-name>
      <servlet-class>org.springframework.web.servlet.DispatcherServlet;</servlet-class>
   </servlet>

   <servlet-mapping>
      <servlet-name>Spring</servlet-name>
      <url-pattern>/*</url-pattern>
   </servlet-mapping>


</web-app>

Then within your main Spring beans xml, import the springmvc-resteasy.xml file

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
    http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
">

    <!-- Import basic SpringMVC Resteasy integration -->
    <import resource="classpath:springmvc-resteasy.xml"/>
....

Sometimes you are interested not only in the response body of a client request, but also either the response code and/or response headers. The Client-Proxy framework has two ways to get at this information

You may return a javax.ws.rs.core.Response.Status enumeration from your method calls:

@Path("/")
public interface MyProxy {
   @POST
   Response.Status updateSite(MyPojo pojo);
}
            

Internally, after invoking on the server, the client proxy internals will convert the HTTP response code into a Response.Status enum.

If you are interested in everything, you can get it with the org.jboss.resteasy.spi.ClientResponse interface:

/**
 * Response extension for the RESTEasy client framework. Use this, or Response
 * in your client proxy interface method return type declarations if you want
 * access to the response entity as well as status and header information.
 *
 * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
 * @version $Revision: 1 $
 */
public abstract class ClientResponse<T> extends Response
{
   /**
    * This method returns the same exact map as Response.getMetadata() except as a map of strings 
    * rather than objects.
    *
    * @return
    */
   public abstract MultivaluedMap<String, String> getHeaders();

   public abstract Response.Status getResponseStatus();

   /**
    * Unmarshal the target entity from the response OutputStream.  You must have type information
    * set via <T> otherwise, this will not work.
    * <p/>
    * This method actually does the reading on the OutputStream.  It will only do the read once.  
    * Afterwards, it will cache the result and return the cached result.
    *
    * @return
    */
   public abstract T getEntity();

   /**
    * Extract the response body with the provided type information
    * <p/>
    * This method actually does the reading on the OutputStream.  It will only do the read once.  
    * Afterwards, it will cache the result and return the cached result.
    *
    * @param type
    * @param genericType
    * @param <T2>
    * @return
    */
   public abstract <T2> T2 getEntity(Class<T2> type, Type genericType);

   /**
    * Extract the response body with the provided type information.  GenericType is a trick used to
    * pass in generic type information to the resteasy runtime.
    * <p/>
    * For example:
    * <pre>
    * List<String> list = response.getEntity(new GenericType<List<String>() {});
    * <p/>
    * <p/>
    * This method actually does the reading on the OutputStream.  It will only do the read once.  Afterwards, it will
    * cache the result and return the cached result.
    *
    * @param type
    * @param <T2>
    * @return
    */
   public abstract <T2> T2 getEntity(GenericType<T2> type);
}

        

All the getEntity() methods are deferred until you invoke them. In other words, the response OutputStream is not read until you call one of these methods. The empty parameter getEntity() method can only be used if you have templated the ClientResponse within your method declaration. Resteasy uses this generic type information to know what type to unmarshal the raw OutputStream into. The other two getEntity() methods that take parameters, allow you to specify which Object types you want to marshal the response into. These methods allow you to dynamically extract whatever types you want at runtime. Here's an example:

@Path("/")
public interface LibraryService {

   @GET
   @Produces("application/xml")
   ClientResponse<LibraryPojo> getAllBooks();
}

We need to include the LibraryPojo in ClientResponse's generic declaration so that the client proxy framework knows how to unmarshal the HTTP response body.

It is generally possible to share an interface between the client and server. In this scenario, you just have your JAX-RS services implement an annotated interface and then reuse that same interface to create client proxies to invoke on the client-side. One caveat to this is when your JAX-RS methods return a Response object. The problem on the client is that the client does not have any type information with a raw Response return type declaration. There are two ways of getting around this. The first is to use the @ClientResponseType annotation.

import org.jboss.resteasy.annotations.ClientResponseType;
import javax.ws.rs.core.Response;

@Path("/")
public interface MyInterface {

   @GET
   @ClientResponseType(String.class)
   @Produces("text/plain")
   public Response get();
}

This approach isn't always good enough. The problem is that some MessageBodyReaders and Writers need generic type information in order to match and service a request.

@Path("/")
public interface MyInterface {

   @GET
   @Produces("application/xml")
   public Response getMyListOfJAXBObjects();
}

In this case, your client code can cast the returned Response object to a ClientResponse and use one of the typed getEntity() methods.

MyInterface proxy = ProxyFactory.create(MyInterface.class, "http://localhost:8081");
ClientResponse<List<MyJaxbClass>> response = (ClientResponse)proxy.getMyListOfJAXBObjects();
List<MyJaxbClass> list = response.getEntity(new GenericType<List<MyJaxbClass>>());

If you are using the Client Framework and your proxy methods return something other than a ClientResponse, then the default client error handling comes into play. Any response code that is greater than 399 will automatically cause a org.jboss.resteasy.client.ClientResponseFailure exception

   @GET
   ClientResponse<String> get() // will throw an exception if you call getEntity()

   @GET
   MyObject get(); // will throw a ClientResponseFailure on response code > 399

In cases where Client Proxy methods do not return Response or ClientResponse, it may be not be desirable for the Client Proxy Framework to throw generic ClientResponseFailure exceptions. In these scenarios, where more fine-grained control of thrown Exceptions is required, the ClientErrorInterceptor API may be used.

public static T getClientService(final Class clazz, final String serverUri)
{
	ResteasyProviderFactory pf = ResteasyProviderFactory.getInstance();
	pf.addClientErrorInterceptor(new DataExceptionInterceptor());

	System.out.println("Generating REST service for: " + clazz.getName());
	return ProxyFactory.create(clazz, serverUri);
}

ClientErrorInterceptor provides a hook into the proxy ClientResponse request lifecycle. If a Client Proxy method is called, resulting in a client exception, and the proxy return type is not Response or ClientResponse, registered interceptors will be given a chance to process the response manually, or throw a new exception. If all interceptors successfully return, RestEasy will re-throw the original encountered exception. Note, however, that the response input stream may need to be reset before additional reads will succeed.

public class ExampleInterceptor implements ClientErrorInterceptor
{
	public void handle(ClientResponse response) throws RuntimeException
	{
		try
		{
			BaseClientResponse r = (BaseClientResponse) response;
			InputStream stream = r.getStreamFactory().getInputStream();
			stream.reset();
			
			String data = response.getEntity(String.class);
		
		
			if(FORBIDDEN.equals(response.getResponseStatus()))
			{
				throw new MyCustomException("This exception will be thrown "
					+ "instead of the ClientResponseFailure");
			}
		
		}
		catch (IOException e)
		{
			//...
		}
		// If we got here, and this method returns successfully, 
		// RESTEasy will throw the original ClientResponseFailure
	}
}

Resteasy has a manual API for invoking requests: org.jboss.resteasy.client.ClientRequest See the Javadoc for the full capabilities of this class. Here is a simple example:

   ClientRequest request = new ClientRequest("http://localhost:8080/some/path");
   request.header("custom-header", "value");

   // We're posting XML and a JAXB object
   request.body("application/xml", someJaxb);

   // we're expecting a String back
   ClientResponse<String> response = request.post(String.class);
   
   if (response.getStatus() == 200) // OK!
   {
      String str = response.getEntity();
   }

When using spring you can generate a REST client proxy from an interface with the help of org.jboss.resteasy.client.spring.RestClientProxyFactoryBean.

<bean id="echoClient" class="org.jboss.resteasy.client.spring.RestClientProxyFactoryBean"
    p:serviceInterface="a.b.c.Echo" p:baseUri="http://server.far.far.away:8080/echo" />

Network communication between the client and server is handled in Resteasy, by default, by HttpClient (4.x) from the Apache HttpComponents project. In general, the interface between the Resteasy Client Framework and the network is found in an implementation of org.jboss.resteasy.client.ClientExecutor, and org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor, which uses HttpClient (4.x), is the default implementation. Resteasy also ships with the following client executors, all found in the org.jboss.resteasy.client.core.executors package:

The choice of a default executor may be overriden by calling ClientRequest.setDefaultExecutorClass():

ClientRequest.setDefaultExecutorClass("org.bluemonkeydiamond.MyClientExecutor");
     

and a client executor may be passed to a specific ClientRequest:

ClientExecutor executor = new MyClientExecutor();
ClientRequest request = new ClientRequest("http://localhost:8081/customer", executor);
     

or to a specific proxy:

ClientExecutor executor = new MyClientExecutor();
SimpleClient client = ProxyFactory.create(SimpleClient.class, "http://localhost:8081/customer", executor);
     

Resteasy and HttpClient make reasonable default decisions so that it is possible to use the client framework without ever referencing HttpClient, but for some applications it may be necessary to drill down into the HttpClient details. ApacheHttpClient4Executor can be supplied with an instance of org.apache.http.client.HttpClient and an instance of org.apache.http.protocol.HttpContext, which can carry additional configuration details into the HttpClient layer. For example, authentication may be configured as follows:

// Configure HttpClient to authenticate preemptively
// by prepopulating the authentication data cache.
 
// 1. Create AuthCache instance
AuthCache authCache = new BasicAuthCache();
 
// 2. Generate BASIC scheme object and add it to the local auth cache
BasicScheme basicAuth = new BasicScheme();
authCache.put("com.bluemonkeydiamond.sippycups", basicAuth);
 
// 3. Add AuthCache to the execution context
BasicHttpContext localContext = new BasicHttpContext();
localContext.setAttribute(ClientContext.AUTH_CACHE, authCache);
 
// 4. Create client executor and proxy
httpClient = new DefaultHttpClient();
ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor(httpClient, localContext);
client = ProxyFactory.create(BookStoreService.class, url, executor);
     

One default decision made by HttpClient and adopted by Resteasy is the use of org.apache.http.impl.conn.SingleClientConnManager, which manages a single socket at any given time and which supports the use case in which one or more invocations are made serially from a single thread. For multithreaded applications, SingleClientConnManager may be replaced by org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager:

ClientConnectionManager cm = new ThreadSafeClientConnManager();
HttpClient httpClient = new DefaultHttpClient(cm);
ClientExecutor executor = new ApacheHttpClient4Executor(httpClient);
client = ProxyFactory.create(BookStoreService.class, url, executor);
     

If an entity is very large, a file, for example, ApacheHttpClient4Executor can be configured to store it in the file system, instead of attempting to keep it all in memory, if the size of the entity exceeds a certain threshold. The threshold is expressed in either bytes, kilobytes, megabytes, or gigabytes, and the unit used by an instance of ApacheHttpClient4Executor can be configured by calling the ApacheHttpClient4Executor method

public void setFileUploadMemoryUnit(String pMemoryUnit);
     

where the value of pMemoryUnit may be one of

public static final String BYTE_MEMORY_UNIT = "BY";
public static final String KILOBYTE_MEMORY_UNIT = "KB";
public static final String MEGABYTE_MEMORY_UNIT = "MB";
public static final String GIGABYTE_MEMORY_UNIT = "GB";
     

The default unit is megabytes. The threshold, expressed in terms of the configured unit, can be configured by calling the ApacheHttpClient4Executor method

public void setFileUploadInMemoryThresholdLimit(int pInMemoryThresholdLimit);
     

The default value is 1, i.e., the default threshold is 1 megabyte. The directory in which entities are stored can be configured by calling the ApacheHttpClient4Executor method

public void setFileUploadTempFileDir(File pTempFileDir);
     

The default directory is the value of System.getProperty("java.io.tmpdir").

To use the buffering facility, then, create an instance of ApacheHttpClient4Executor, configure it, and pass it to a ClientRequest or a proxy:

ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();
executor.setFileUploadMemoryUnit(ApacheHttpClient4Executor.GIGABYTE_MEMORY_UNIT);
executor.setFileUploadInMemoryThresholdLimit(4);
ClientRequest request = new ClientRequest("http://localhost:8081/hello/", executor);