Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

15.13. RESTEasy JAXB

15.13.1. Create a JAXB Decorator

Summary

RESTEasy's JAXB providers have a pluggable way to decorate Marshaller and Unmarshaller instances. An annotation is created that can trigger either a Marshaller or Unmarshaller instance. This topic covers the steps to create a JAXB decorator with RESTEasy.

Procedure 15.8. Create a JAXB Decorator with RESTEasy

  1. Create the Processor Class

    1. Create a class that implements DecoratorProcessor<Target, Annotation>. The target is either the JAXB Marshaller or Unmarshaller class. The annotation is created in step two.
    2. Annotate the class with @DecorateTypes, and declare the MIME Types the decorator should decorate.
    3. Set properties or values within the decorate function.

    Example 15.25. Example Processor Class

    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;
    
    @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);
        }
    }
    
  2. Create the Annotation

    1. Create a custom interface that is annotated with the @Decorator annotation.
    2. Declare the processor and target for the @Decorator annotation. The processor is created in step one. The target is either the JAXB Marshaller or Unmarshaller class.

    Example 15.26. Example 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 {}
    
  3. Add the annotation created in step two to a function so that either the input or output is decorated when it is marshalled.
Result

The JAXB decorator has been created and applied within the JAX-RS web service.

15.13.2. JAXB and XML Provider

RESTEasy facilitates JAXB provider support for XML.
@XmlHeader and @Stylesheet

RESTEasy provides setting an XML header using the @org.jboss.resteasy.annotations.providers.jaxb.XmlHeader annotation. For example:

@XmlRootElement
public static class Thing
{
   private String name;

   public String getName()
   {
      return name;
   }

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

@Path("/test")
public static class TestService
{

   @GET
   @Path("/header")
   @Produces("application/xml")
   @XmlHeader("<?xml-stylesheet type='text/xsl' href='${baseuri}foo.xsl' ?>")
   public Thing get()
   {
      Thing thing = new Thing();
      thing.setName("bill");
      return thing;
   }
}
The @XmlHeader ensures that the XML output has an XML-stylesheet header.

RESTEasy has a convenience annotation for stylesheet headers. For example:
@XmlRootElement
public static class Thing
{
   private String name;

   public String getName()
   {
      return name;
   }

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

@Path("/test")
public static class TestService
{

   @GET
   @Path("/stylesheet")
   @Produces("application/xml")
   @Stylesheet(type="text/css", href="${basepath}foo.xsl")
   @Junk
   public Thing getStyle()
   {
      Thing thing = new Thing();
      thing.setName("bill");
      return thing;
   }
}

15.13.3. JAXB and JSON Provider

RESTEasy allows you to marshal JAXB annotated POJOs to and from JSON. This provider wraps the Jettison JSON library to accomplish this task. For more information about Jettison and how it works, refer to: http://jettison.codehaus.org/.
<dependency>
	<groupId>org.jboss.resteasy</groupId>
	<artifactId>resteasy-jettison-provider</artifactId>
	<version>${version.org.jboss.resteasy}</version>
	<scope>provided</scope>
</dependency>
Jettison has two mapping formats. One is BadgerFish the other is a Jettison mapped convention format. The mapped convention is the default. For more details on the JAXB + JSON Provider integration with Jettison, refer to: http://docs.jboss.org/resteasy/docs/2.3.7.Final/userguide/html_single/index.html