Overview

Jersey is a JAX-RS (JSR-311) implementation. JAX-RS is a specification that provides a series of annotations and classes which make it possible to build RESTful services. The Mule Jersey transport makes it possible to deploy these annotated classes inside Mule 2.0.

In addition to the annotation capabilities, Jersey contains many useful features:

The ability to integrate with XML data-binding frameworks such as JAXB
The ability to produce/consume JSON easily
The ability to integrate with the JSP presentation tier
Integration with Abdera for Atom support.

Classpath Settings

Mule Standalone

To set up the Mule classpath to run Jersey services, you must first download the Mule Jersey transport distribution. Then simply take all the JARs inside the distribution and put them in MULE_HOME/lib/user.

Maven

If you are using Maven, you can use the MuleForge repositories and add a dependency to Jersey that way. First add the MuleForge repository to your POM:

<repositories>
    <repository>
      <id>muleforge</id>
      <name>MuleForge Repository</name>
      <url>http://repository.muleforge.org</url>
    </repository>
</repositories>

Then add the dependency:

<dependencies>
  <dependency>
    <groupId>org.mule.transports</groupId>
    <artifactId>mule-transport-jersey</artifactId>
    <version>1.0</version>
  </dependency>
</dependencies>

Writing a service

Writing JAX-RS services is an expansive topic and will not be covered in this guide. However, the Jersey website has an excellent set of samples and the [JAX-RS specification|] is helpful as well.

We will, however, take a look at a simple hello world service.

The first step to create a JAX-RS service is to create a class which represents your HTTP resource. In our case we'll create a "HelloWorldResource" class. Methods on this class will be called in response to GET/POST/DELETE/PUT invocations on specific URLs.

The @Path annotation allows you to bind a class/resource to a specific URL. In the sample below we're binding the HelloWorldResource class to the "/helloworld" URL.

package org.mule.transport.jersey;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.ProduceMime;
import javax.ws.rs.PathParam;

@Path("/helloworld")
public class HelloWorldResource {

    @GET
    @ProduceMime("text/plain")
    @Path("/{name}")
    public String sayHelloWithUri(@PathParam("name") String name) {
        return "Hello " + name;
    }
}

Looking at the "sayHelloWithUri" method we see several annotations involved:

@GET specifies that this method is only called on @GET requests to the URL.
@ProduceMime specifies that this method is producing a resource with a mime type of "text/plain".
@Path binds this method to the URL "/helloworld/{name}". The {name} is a URI template. Anything in this portion of the URL will be mapped to a URI parameter named "name" (see below)
@PathParam binds the first parameter of the method to the URI parameter in that path named "name".

Configuring a service

Once you've written your service, you simply need to create an endpoint on a "jersey:http://...." URL. Below is a very simple configuration which does this:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://www.mulesource.org/schema/mule/core/2.0"
       xmlns:jersey="http://www.mulesource.org/schema/mule/jersey/2.0"
       xmlns:vm="http://www.mulesource.org/schema/mule/vm/2.0"
       xsi:schemaLocation="
               http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
               http://www.mulesource.org/schema/mule/core/2.0 http://www.mulesource.org/schema/mule/core/2.0/mule.xsd
               http://www.mulesource.org/schema/mule/jersey/2.0 http://www.mulesource.org/schema/mule/jersey/2.0/mule-jersey.xsd
               http://www.mulesource.org/schema/mule/vm/2.0 http://www.mulesource.org/schema/mule/vm/2.0/mule-vm.xsd">
    
    <model name="BasicJerseyTest">
    
        <service name="helloWorldResource">
            <inbound>
                <inbound-endpoint address="jersey:http://localhost:63081/" synchronous="true"/>
            </inbound>
            <component class="org.mule.transport.jersey.HelloWorldResource"/>
        </service>
        
    </model>

</mule>

Further help

If you encounter any further bugs or wish to suggest improvements, please contact the mailing list. The Jersey mailing lists are a great source of help as well.