Jersey 1.19.1 User Guide

Create the following Java class in your project:

  1     // The Java class will be hosted at the URI path "/helloworld"
  2     @Path("/helloworld")
  3     public class HelloWorldResource {
  4 
  5         // The Java method will process HTTP GET requests
  6         @GET
  7         // The Java method will produce content identified by the MIME Media
  8         // type "text/plain"
  9         @Produces("text/plain")
 10         public String getClichedMessage() {
 11             // Return some cliched textual content
 12             return "Hello World";
 13         }
 14     }

The HelloWorldResource class is a very simple Web resource. The URI path of the resource is "/helloworld" (line 2), it supports the HTTP GET method (line 6) and produces cliched textual content (line 12) of the MIME media type "text/plain" (line 9).

Notice the use of Java annotations to declare the URI path, the HTTP method and the media type. This is a key feature of JSR 311.

The root resource will be deployed using the Grizzly Web container.

Create the following Java class in your project:

  1 import com.sun.jersey.api.container.grizzly2.GrizzlyServerFactory;
  2 import com.sun.jersey.api.core.DefaultResourceConfig;
  3 import com.sun.jersey.api.core.PackagesResourceConfig;
  4 import com.sun.jersey.api.core.ResourceConfig;
  5 import org.glassfish.grizzly.http.server.HttpServer;
  6 
  7 import javax.ws.rs.core.UriBuilder;
  8 import java.io.IOException;
  9 import java.net.URI;
 10 import java.util.HashMap;
 11 import java.util.Map;
 12 import java.util.Map.Entry;
 13 
 14 public class Main {
 15 
 16     private static URI getBaseURI() {
 17         return UriBuilder.fromUri("http://localhost/").port(9998).build();
 18     }
 19 
 20     public static final URI BASE_URI = getBaseURI();
 21 
 22     protected static HttpServer startServer() throws IOException {
 23         System.out.println("Starting grizzly...");
 24         ResourceConfig rc = new PackagesResourceConfig("com.sun.jersey.samples.helloworld.resources");
 25         return GrizzlyServerFactory.createHttpServer(BASE_URI, rc);
 26     }
 27 
 28     public static void main(String[] args) throws IOException {
 29         HttpServer httpServer = startServer();
 30         System.out.println(String.format("Jersey app started with WADL available at "
 31                 + "%sapplication.wadl\nTry out %shelloworld\nHit enter to stop it...",
 32                 BASE_URI, BASE_URI));
 33         System.in.read();
 34         httpServer.stop();
 35     }
 36 }

The Main class deploys the HelloWorldResource using the Grizzly Web container.

Line 24 creates an initialization parameter that informs the Jersey runtime where to search for root resource classes to be deployed. In this case it assumes the root resource class in the package com.sun.jersey.samples.helloworld.resources (or in a sub-package of).

Line 25 deploys the root resource to the base URI "http://localhost:9998/" and returns a Grizzly HttpServer. The complete URI of the Hello World root resource is "http://localhost:9998/helloworld".

Notice that no deployment descriptors were needed and the root resource was setup in a few statements of Java code.

Goto the URI http://localhost:9998/helloworld in your favourite browser.

Or, from the command line use curl:

> curl http://localhost:9998/helloworld

The example code presented above is shipped as the HelloWorld sample in the Java.Net maven repository.

For developers wishing to get started by deploying a Web application an equivalent sample, as a Web application, is shipped as the HelloWorld-WebApp sample.

Root resource classes are POJOs (Plain Old Java Objects) that are annotated with @Path have at least one method annotated with @Path or a resource method designator annotation such as @GET, @PUT, @POST, @DELETE. Resource methods are methods of a resource class annotated with a resource method designator. This section shows how to use Jersey to annotate Java objects to create RESTful web services.

The following code example is a very simple example of a root resource class using JAX-RS annotations. The example code shown here is from one of the samples that ships with Jersey, the zip file of which can be found in the maven repository here.

  1 package com.sun.ws.rest.samples.helloworld.resources;
  2 
  3 import javax.ws.rs.GET;
  4 import javax.ws.rs.Produces;
  5 import javax.ws.rs.Path;
  6 
  7 // The Java class will be hosted at the URI path "/helloworld"
  8 @Path("/helloworld")
  9 public class HelloWorldResource {
 10 
 11     // The Java method will process HTTP GET requests
 12     @GET
 13     // The Java method will produce content identified by the MIME Media
 14     // type "text/plain"
 15     @Produces("text/plain")
 16     public String getClichedMessage() {
 17         // Return some cliched textual content
 18         return "Hello World";
 19     }
 20 }

Let's look at some of the JAX-RS annotations used in this example.

@Path("/users/{username}")

  1 @Path("/users/{username}")
  2 public class UserResource {
  3 
  4     @GET
  5     @Produces("text/xml")
  6     public String getUser(@PathParam("username") String userName) {
  7         ...
  8     }
  9 }

@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")

  1 @PUT
  2 public Response putContainer() {
  3     System.out.println("PUT CONTAINER " + container);
  4 
  5     URI uri =  uriInfo.getAbsolutePath();
  6     Container c = new Container(container, uri.toString());
  7 
  8     Response r;
  9     if (!MemoryStore.MS.hasContainer(c)) {
 10         r = Response.created(uri).build();
 11     } else {
 12         r = Response.noContent().build();
 13     }
 14 
 15     MemoryStore.MS.createContainer(c);
 16     return r;
 17 }

  1 @Path("/myResource")
  2 @Produces("text/plain")
  3 public class SomeResource {
  4     @GET
  5     public String doGetAsPlainText() {
  6         ...
  7     }
  8 
  9     @GET
 10     @Produces("text/html")
 11     public String doGetAsHtml() {
 12         ...
 13     }
 14 }

Accept: text/plain

Accept: text/plain;q=0.9, text/html

  1 @GET
  2 @Produces({"application/xml", "application/json"})
  3 public String doGetAsXmlOrJson() {
  4     ...
  5 }

  1 @POST
  2 @Consumes("text/plain")
  3 public void postClichedMessage(String message) {
  4     // Store the message
  5 }

JAX-RS provides a deployment agnostic abstract class Application for declaring root resource and provider classes, and root resource and provider singleton instances. A Web service may extend this class to declare root resource and provider classes. For example,

  1 public class MyApplication extends Application {
  2     public Set<Class<?>> getClasses() {
  3         Set<Class<?>> s = new HashSet<Class<?>>();
  4         s.add(HelloWorldResource.class);
  5         return s;
  6     }
  7 }

Alternatively it is possible to reuse one of Jersey's implementations that scans for root resource and provider classes given a classpath or a set of package names. Such classes are automatically added to the set of classes that are returned by getClasses. For example, the following scans for root resource and provider classes in packages "org.foo.rest", "org.bar.rest" and in any sub-packages of those two:

  1 public class MyApplication extends PackagesResourceConfig {
  2     public MyApplication() {
  3         super("org.foo.rest;org.bar.rest");
  4     }
  5 }

There are multiple deployment options for the class that implements Application interface in the Servlet 3.0 container. For simple deployments, no web.xml is needed at all. Instead, an @ApplicationPath annotation can be used to annotate the user defined application class and specify the the base resource URI of all application resources:

  1 @ApplicationPath("resources")
  2 public class MyApplication extends PackagesResourceConfig {
  3     public MyApplication() {
  4         super("org.foo.rest;org.bar.rest");
  5     }    
  6     ...
  7 }

You also need to set maven-war-plugin attribute failOnMissingWebXml to false in pom.xml when building .war without web.xml file using maven:

  1 <plugins>
  2  ...
  3  <plugin>
  4    <groupId>org.apache.maven.plugins</groupId>
  5    <artifactId>maven-war-plugin</artifactId>
  6    <version>2.1.1</version>    
  7    <configuration>
  8        <failOnMissingWebXml>false</failOnMissingWebXml>        
  9    </configuration>
 10    </plugin>
 11  ...
 12  </plugins>

Another deployment option is to declare JAX-RS application details in the web.xml. This is usually suitable in case of more complex deployments, e.g. when security model needs to be properly defined or when additional initialization parameters have to be passed to Jersey runtime. JAX-RS 1.1 specifies that a fully qualified name of the class that implements Application may be declared in the <servlet-name> element of the JAX-RS application's web.xml. This is supported in a Web container implementing Servlet 3.0 as follows:

  1 <web-app>
  2     <servlet>
  3         <servlet-name>org.foo.rest.MyApplication</servlet-name>
  4     </servlet>
  5     ...
  6     <servlet-mapping>
  7         <servlet-name>org.foo.rest.MyApplication</servlet-name>
  8         <url-pattern>/resources</url-pattern>
  9     </servlet-mapping>
 10     ...
 11 </web-app>

Note that the <servlet-class> element is omitted from the servlet declaration. This is a correct declaration utilizing the Servlet 3.0 extension mechanism. Also note that <servlet-mapping> is used to define the base resource URI.

When running in a Servlet 2.x then instead it is necessary to declare the Jersey specific servlet and pass the Application implementation class name as one of the servlet's init-param entries:

  1 <web-app>
  2     <servlet>
  3         <servlet-name>Jersey Web Application</servlet-name>
  4         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  5         <init-param>
  6             <param-name>javax.ws.rs.Application</param-name>
  7             <param-value>org.foo.rest.MyApplication</param-value>
  8         </init-param>
  9         ...
 10     </servlet>
 11     ...
 12 </web-app>

Alternatively a simpler approach is to let Jersey choose the PackagesResourceConfig implementation automatically by declaring the packages as follows:

  1 <web-app>
  2     <servlet>
  3         <servlet-name>Jersey Web Application</servlet-name>
  4         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  5         <init-param>
  6             <param-name>com.sun.jersey.config.property.packages</param-name>
  7             <param-value>org.foo.rest;org.bar.rest</param-value>
  8         </init-param>
  9         ...
 10     </servlet>
 11     ...
 12 </web-app>

JAX-RS also provides the ability to obtain a container specific artifact from an Application instance. For example, Jersey supports using Grizzly as follows:

SelectorThread st = RuntimeDelegate.createEndpoint(new MyApplication(), SelectorThread.class);

Jersey also provides Grizzly helper classes to deploy the ServletThread instance at a base URL for in-process deployment.

The Jersey samples provide many examples of Servlet-based and Grizzly-in-process-based deployments.

Parameters of a resource method may be annotated with parameter-based annotations to extract information from a request. A previous example presented the use @PathParam to extract a path parameter from the path component of the request URL that matched the path declared in @Path.

@QueryParam is used to extract query parameters from the Query component of the request URL. The following example is an extract from the sparklines sample:

  1 @Path("smooth")
  2 @GET
  3 public Response smooth(
  4         @DefaultValue("2") @QueryParam("step") int step,
  5         @DefaultValue("true") @QueryParam("min-m") boolean hasMin,
  6         @DefaultValue("true") @QueryParam("max-m") boolean hasMax,
  7         @DefaultValue("true") @QueryParam("last-m") boolean hasLast,           
  8         @DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,
  9         @DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,
 10         @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor
 11         ) { ... }

If a query parameter "step" exists in the query component of the request URI then the "step" value will be will extracted and parsed as a 32 bit signed integer and assigned to the step method parameter. If "step" does not exist then a default value of 2, as declared in the @DefaultValue annotation, will be assigned to the step method parameter. If the "step" value cannot be parsed as a 32 bit signed integer then a HTTP 404 (Not Found) response is returned. User defined Java types such as ColorParam may be used, which as implemented as follows:

  1 public class ColorParam extends Color {
  2     public ColorParam(String s) {
  3         super(getRGB(s));
  4     }
  5 
  6     private static int getRGB(String s) {
  7         if (s.charAt(0) == '#') {
  8             try {
  9                 Color c = Color.decode("0x" + s.substring(1));
 10                 return c.getRGB();
 11             } catch (NumberFormatException e) {
 12                 throw new WebApplicationException(400);
 13             }
 14         } else {
 15             try {
 16                 Field f = Color.class.getField(s);
 17                 return ((Color)f.get(null)).getRGB();
 18             } catch (Exception e) {
 19                 throw new WebApplicationException(400);
 20             }
 21         }
 22     }
 23 }

In general the Java type of the method parameter may:

Sometimes parameters may contain more than one value for the same name. If this is the case then types in 4) may be used to obtain all values.

If the @DefaultValue is not used in conjunction with @QueryParam and the query parameter is not present in the request then value will be an empty collection for List, Set or SortedSet, null for other object types, and the Java-defined default for primitive types.

The @PathParam and the other parameter-based annotations, @MatrixParam, @HeaderParam, @CookieParam, @FormParam obey the same rules as @QueryParam. @MatrixParam extracts information from URL path segments. @HeaderParam extracts information from the HTTP headers. @CookieParam extracts information from the cookies declared in cookie related HTTP headers.

@FormParam is slightly special because it extracts information from a request representation that is of the MIME media type "application/x-www-form-urlencoded" and conforms to the encoding specified by HTML forms, as described here. This parameter is very useful for extracting information that is POSTed by HTML forms, for example the following extracts the form parameter named "name" from the POSTed form data:

  1 @POST
  2 @Consumes("application/x-www-form-urlencoded")
  3 public void post(@FormParam("name") String name) {
  4     // Store the message
  5 }

If it is necessary to obtain a general map of parameter name to values then, for query and path parameters it is possible to do the following:

  1 @GET
  2 public String get(@Context UriInfo ui) {
  3     MultivaluedMap<String, String> queryParams = ui.getQueryParameters();
  4     MultivaluedMap<String, String> pathParams = ui.getPathParameters();
  5 }

For header and cookie parameters the following:

  1 @GET
  2 public String get(@Context HttpHeaders hh) {
  3     MultivaluedMap<String, String> headerParams = hh.getRequestHeaders();
  4     Map<String, Cookie> pathParams = hh.getCookies();
  5 }

In general @Context can be used to obtain contextual Java types related to the request or response. For form parameters it is possible to do the following:

  1 @POST
  2 @Consumes("application/x-www-form-urlencoded")
  3 public void post(MultivaluedMap<String, String> formParams) {
  4     // Store the message
  5 }

Previous sections on @Produces and @Consumes referred to MIME media types of representations and showed resource methods that consume and produce the Java type String for a number of different media types. However, String is just one of many Java types that are required to be supported by JAX-RS implementations.

Java types such as byte[], java.io.InputStream, java.io.Reader and java.io.File are supported. In addition JAXB beans are supported. Such beans are JAXBElement or classes annotated with @XmlRootElement or @XmlType. The samples jaxb and json-from-jaxb show the use of JAXB beans.

Unlike method parameters that are associated with the extraction of request parameters, the method parameter associated with the representation being consumed does not require annotating. A maximum of one such unannotated method parameter may exist since there may only be a maximum of one such representation sent in a request.

The representation being produced corresponds to what is returned by the resource method. For example JAX-RS makes it simple to produce images that are instance of File as follows:

  1 @GET
  2 @Path("/images/{image}")
  3 @Produces("image/*")
  4 public Response getImage(@PathParam("image") String image) {
  5     if (!isSafeToOpenFile(image)) {
  6         throw new IllegalArgumentException("Cannot open the image file.");
  7     }
  8 
  9     File f = new File(image);
 10 
 11     if (!f.exists()) {
 12         throw new WebApplicationException(404);
 13     }
 14 
 15     String mt = new MimetypesFileTypeMap().getContentType(f);
 16     return Response.ok(f, mt).build();
 17 }

A File type can also be used when consuming, a temporary file will be created where the request entity is stored.

The Content-Type (if not set, see next section) can be automatically set from the MIME media types declared by @Produces if the most acceptable media type is not a wild card (one that contains a *, for example "application/" or "/*"). Given the following method:

  1 @GET
  2 @Produces({"application/xml", "application/json"})
  3 public String doGetAsXmlOrJson() {
  4     ...
  5 }

if "application/xml" is the most acceptable then the Content-Type of the response will be set to "application/xml".

Sometimes it is necessary to return additional information in response to a HTTP request. Such information may be built and returned using Response and Response.ResponseBuilder. For example, a common RESTful pattern for the creation of a new resource is to support a POST request that returns a 201 (Created) status code and a Location header whose value is the URI to the newly created resource. This may be achieved as follows:

  1 @POST
  2 @Consumes("application/xml")
  3 public Response post(String content) {
  4     URI createdUri = ...
  5     create(content);
  6     return Response.created(createdUri).build();
  7 }

In the above no representation produced is returned, this can be achieved by building an entity as part of the response as follows:

  1 @POST
  2 @Consumes("application/xml")
  3 public Response post(String content) {
  4     URI createdUri = ...
  5     String createdContent = create(content);
  6     return Response.created(createdUri).entity(createdContent).build();
  7 }

Response building provides other functionality such as setting the entity tag and last modified date of the representation.

@Path may be used on classes and such classes are referred to as root resource classes. @Path may also be used on methods of root resource classes. This enables common functionality for a number of resources to be grouped together and potentially reused.

The first way @Path may be used is on resource methods and such methods are referred to as sub-resource methods. The following example shows the method signatures for a root resource class from the jmaki-backend sample:

  1 @Singleton
  2 @Path("/printers")
  3 public class PrintersResource {
  4 
  5     @GET
  6     @Produces({"application/json", "application/xml"})
  7     public WebResourceList getMyResources() { ... }
  8    
  9     @GET @Path("/list")
 10     @Produces({"application/json", "application/xml"})
 11     public WebResourceList getListOfPrinters() { ... }
 12 
 13     @GET @Path("/jMakiTable")
 14     @Produces("application/json")
 15     public PrinterTableModel getTable() { ... }
 16 
 17     @GET @Path("/jMakiTree")
 18     @Produces("application/json")
 19     public TreeModel getTree() { ... }
 20 
 21     @GET @Path("/ids/{printerid}")
 22     @Produces({"application/json", "application/xml"})
 23     public Printer getPrinter(@PathParam("printerid") String printerId) { ... }
 24 
 25     @PUT @Path("/ids/{printerid}")
 26     @Consumes({"application/json", "application/xml"})
 27     public void putPrinter(@PathParam("printerid") String printerId,  Printer printer) { ... }
 28 
 29     @DELETE @Path("/ids/{printerid}")
 30     public void deletePrinter(@PathParam("printerid") String printerId) { ... }
 31 }

If the path of the request URL is "printers" then the resource methods not annotated with @Path will be selected. If the request path of the request URL is "printers/list" then first the root resource class will be matched and then the sub-resource methods that match "list" will be selected, which in this case is the sub-resource method getListOfPrinters. So in this example hierarchical matching on the path of the request URL is performed.

The second way @Path may be used is on methods not annotated with resource method designators such as @GET or @POST. Such methods are referred to as sub-resource locators. The following example shows the method signatures for a root resource class and a resource class from the optimistic-concurrency sample:

  1 @Path("/item")
  2 public class ItemResource {
  3     @Context UriInfo uriInfo;
  4 
  5     @Path("content")
  6     public ItemContentResource getItemContentResource() {
  7         return new ItemContentResource();
  8     }
  9 
 10     @GET
 11     @Produces("application/xml")
 12     public Item get() { ... }
 13 }
 14 
 15 public class ItemContentResource {
 16 
 17     @GET
 18     public Response get() { ... }
 19 
 20     @PUT
 21     @Path("{version}")
 22     public void put(
 23             @PathParam("version") int version,
 24             @Context HttpHeaders headers,
 25             byte[] in) { ... }
 26 }

The root resource class ItemResource contains the sub-resource locator method getItemContentResource that returns a new resource class. If the path of the request URL is "item/content" then first of all the root resource will be matched, then the sub-resource locator will be matched and invoked, which returns an instance of the ItemContentResource resource class. Sub-resource locators enable reuse of resource classes.

In addition the processing of resource classes returned by sub-resource locators is performed at runtime thus it is possible to support polymorphism. A sub-resource locator may return different sub-types depending on the request (for example a sub-resource locator could return different sub-types dependent on the role of the principle that is authenticated).

Note that the runtime will not manage the life-cycle or perform any field injection onto instances returned from sub-resource locator methods. This is because the runtime does not know what the life-cycle of the instance is.

A very important aspects of REST is hyperlinks, URIs, in representations that clients can use to transition the Web service to new application states (this is otherwise known as "hypermedia as the engine of application state"). HTML forms present a good example of this in practice.

Building URIs and building them safely is not easy with java.net.URI, which is why JAX-RS has the UriBuilder class that makes it simple and easy to build URIs safely.

UriBuilder can be used to build new URIs or build from existing URIs. For resource classes it is more than likely that URIs will be built from the base URI the web service is deployed at or from the request URI. The class UriInfo provides such information (in addition to further information, see next section).

The following example shows URI building with UriInfo and UriBuilder from the bookmark sample:

  1 @Path("/users/")
  2 public class UsersResource {
  3 
  4     @Context UriInfo uriInfo;
  5 
  6     ...
  7 
  8     @GET
  9     @Produces("application/json")
 10     public JSONArray getUsersAsJsonArray() {
 11         JSONArray uriArray = new JSONArray();
 12         for (UserEntity userEntity : getUsers()) {
 13             UriBuilder ub = uriInfo.getAbsolutePathBuilder();
 14             URI userUri = ub.
 15                     path(userEntity.getUserid()).
 16                     build();
 17             uriArray.put(userUri.toASCIIString());
 18         }
 19         return uriArray;
 20     }
 21 }

UriInfo is obtained using the @Context annotation, and in this particular example injection onto the field of the root resource class is performed, previous examples showed the use of @Context on resource method parameters.

UriInfo can be used to obtain URIs and associated UriBuilder instances for the following URIs: the base URI the application is deployed at; the request URI; and the absolute path URI, which is the request URI minus any query components.

The getUsersAsJsonArray method constructs a JSONArrray where each element is a URI identifying a specific user resource. The URI is built from the absolute path of the request URI by calling UriInfo.getAbsolutePathBuilder(). A new path segment is added, which is the user ID, and then the URI is built. Notice that it is not necessary to worry about the inclusion of '/' characters or that the user ID may contain characters that need to be percent encoded. UriBuilder takes care of such details.

UriBuilder can be used to build/replace query or matrix parameters. URI templates can also be declared, for example the following will build the URI "http://localhost/segment?name=value":

  1 UriBuilder.fromUri("http://localhost/").
  2     path("{a}").
  3     queryParam("name", "{value}").
  4     build("segment", "value");

Previous sections have shown how to return HTTP responses and it is possible to return HTTP errors using the same mechanism. However, sometimes when programming in Java it is more natural to use exceptions for HTTP errors.

The following example shows the throwing of a NotFoundException from the bookmark sample:

  1 @Path("items/{itemid}/")
  2 public Item getItem(@PathParam("itemid") String itemid) {
  3     Item i = getItems().get(itemid);
  4     if (i == null)
  5         throw new NotFoundException("Item, " + itemid + ", is not found");
  6 
  7     return i;
  8 }

This exception is a Jersey specific exception that extends WebApplicationException and builds a HTTP response with the 404 status code and an optional message as the body of the response:

  1 public class NotFoundException extends WebApplicationException {
  2 
  3     /**
  4      * Create a HTTP 404 (Not Found) exception.
  5      */
  6     public NotFoundException() {
  7         super(Responses.notFound().build());
  8     }
  9 
 10     /**
 11      * Create a HTTP 404 (Not Found) exception.
 12      * @param message the String that is the entity of the 404 response.
 13      */
 14     public NotFoundException(String message) {
 15         super(Response.status(Responses.NOT_FOUND).
 16                 entity(message).type("text/plain").build());
 17     }
 18 
 19 }

In other cases it may not be appropriate to throw instances of WebApplicationException, or classes that extend WebApplicationException, and instead it may be preferable to map an existing exception to a response. For such cases it is possible to use the ExceptionMapper<E extends Throwable> interface. For example, the following maps the EntityNotFoundException to a HTTP 404 (Not Found) response:

  1 @Provider
  2 public class EntityNotFoundMapper implements
  3         ExceptionMapper<javax.persistence.EntityNotFoundException> {
  4     public Response toResponse(javax.persistence.EntityNotFoundException ex) {
  5         return Response.status(404).
  6             entity(ex.getMessage()).
  7             type("text/plain").
  8             build();
  9     }
 10 }

The above class is annotated with @Provider, this declares that the class is of interest to the JAX-RS runtime. Such a class may be added to the set of classes of the Application instance that is configured. When an application throws an EntityNotFoundException the toResponse method of the EntityNotFoundMapper instance will be invoked.

Conditional GETs are a great way to reduce bandwidth, and potentially server-side performance, depending on how the information used to determine conditions is calculated. A well-designed web site may return 304 (Not Modified) responses for the many of the static images it serves.

JAX-RS provides support for conditional GETs using the contextual interface Request.

The following example shows conditional GET support from the sparklines sample:

  1 public SparklinesResource(
  2         @QueryParam("d") IntegerList data,
  3         @DefaultValue("0,100") @QueryParam("limits") Interval limits,
  4         @Context Request request,
  5         @Context UriInfo ui) {
  6     if (data == null)
  7         throw new WebApplicationException(400);
  8 
  9     this.data = data;
 10 
 11     this.limits = limits;
 12 
 13     if (!limits.contains(data))
 14         throw new WebApplicationException(400);
 15 
 16     this.tag = computeEntityTag(ui.getRequestUri());
 17     if (request.getMethod().equals("GET")) {
 18         Response.ResponseBuilder rb = request.evaluatePreconditions(tag);
 19         if (rb != null)
 20             throw new WebApplicationException(rb.build());
 21     }
 22 }

The constructor of the SparklinesResouce root resource class computes an entity tag from the request URI and then calls the request.evaluatePreconditions with that entity tag. If a client request contains an If-None-Match header with a value that contains the same entity tag that was calculated then the evaluatePreconditions returns a pre-filled out response, with the 304 status code and entity tag set, that may be built and returned. Otherwise, evaluatePreconditions returns null and the normal response can be returned.

Notice that in this example the constructor of a resource class can be used perform actions that may otherwise have to be duplicated to invoked for each resource method.

By default the life-cycle of root resource classes is per-request, namely that a new instance of a root resource class is created every time the request URI path matches the root resource. This makes for a very natural programming model where constructors and fields can be utilized (as in the previous section showing the constructor of the SparklinesResource class) without concern for multiple concurrent requests to the same resource.

In general this is unlikely to be a cause of performance issues. Class construction and garbage collection of JVMs has vastly improved over the years and many objects will be created and discarded to serve and process the HTTP request and return the HTTP response.

Instances of singleton root resource classes can be declared by an instance of Application.

Jersey supports two further life-cycles using Jersey specific annotations. If a root resource class is annotated with @Singleton then only one instance is created per-web application. If a root resource class is annotated with @PerSession then one instance is created per web session and stored as a session attribute.

Security information is available by obtaining the SecurityContext using @Context, which is essentially the equivalent functionality available on the HttpServletRequest.

SecurityContext can be used in conjunction with sub-resource locators to return different resources if the user principle is included in a certain role. For example, a sub-resource locator could return a different resource if a user is a preferred customer:

  1 @Path("basket")
  2 public ShoppingBasketResource get(@Context SecurityContext sc) {
  3     if (sc.isUserInRole("PreferredCustomer") {
  4        return new PreferredCustomerShoppingBaskestResource();
  5     } else {
  6        return new ShoppingBasketResource();
  7     }
  8 }

Previous sections have presented examples of annotated types, mostly annotated method parameters but also annotated fields of a class, for the injection of values onto those types.

This section presents the rules of injection of values on annotated types. Injection can be performed on fields, constructor parameters, resource/sub-resource/sub-resource locator method parameters and bean setter methods. The following presents an example of all such injection cases:

  1 @Path("id: \d+")
  2 public class InjectedResource {
  3     // Injection onto field
  4     @DefaultValue("q") @QueryParam("p")
  5     private String p;
  6 
  7     // Injection onto constructor parameter
  8     public InjectedResource(@PathParam("id") int id) { ... }
  9 
 10     // Injection onto resource method parameter
 11     @GET
 12     public String get(@Context UriInfo ui) { ... }
 13 
 14     // Injection onto sub-resource resource method parameter
 15     @Path("sub-id")
 16     @GET
 17     public String get(@PathParam("sub-id") String id) { ... }
 18 
 19     // Injection onto sub-resource locator method parameter
 20     @Path("sub-id")
 21     public SubResource getSubResource(@PathParam("sub-id") String id) { ... }
 22 
 23     // Injection using bean setter method
 24     @HeaderParam("X-header")
 25     public void setHeader(String header) { ... }
 26 }

There are some restrictions when injecting on to resource classes with a life-cycle other than per-request. In such cases it is not possible to injected onto fields for the annotations associated with extraction of request parameters. However, it is possible to use the @Context annotation on fields, in such cases a thread local proxy will be injected.

The @FormParam annotation is special and may only be utilized on resource and sub-resource methods. This is because it extracts information from a request entity.

Previous sections have introduced the use of @Context. Chapter 5 of the JAX-RS specification presents all the standard JAX-RS Java types that may be used with @Context.

When deploying a JAX-RS application using servlet then ServletConfig, ServletContext, HttpServletRequest and HttpServletResponse are available using @Context.

For a list of the annotations specified by JAX-RS see Appendix A of the specification.

This section introduces the client API and some features such as filters and how to use them with security features in the JDK. The Jersey client API is a high-level Java based API for interoperating with RESTful Web services. It makes it very easy to interoperate with RESTful Web services and enables a developer to concisely and efficiently implement a reusable client-side solution that leverages existing and well established client-side HTTP implementations.

The Jersey client API can be utilized to interoperate with any RESTful Web service, implemented using one of many frameworks, and is not restricted to services implemented using JAX-RS. However, developers familiar with JAX-RS should find the Jersey client API complementary to their services, especially if the client API is utilized by those services themselves, or to test those services.

The goals of the Jersey client API are threefold:

The Jersey Client API supports a pluggable architecture to enable the use of different underlying HTTP client implementations. Two such implementations are supported and leveraged: the Http(s)URLConnection classes supplied with the JDK; and the Apache HTTP client.

The uniform interface constraint bounds the architecture of RESTful Web services so that a client, such as a browser, can utilize the same interface to communicate with any service. This is a very powerful concept in software engineering that makes Web-based search engines and service mash-ups possible. It induces properties such as:

Further constraints are required:

The above process repeated over and again should be familiar to anyone who has used a browser to fill in HTML forms and follow links. That same process is applicable to non-browser based clients.

Many existing Java-based client APIs, such as the Apache HTTP client API or java.net.HttpURLConnection supplied with the JDK place too much focus on the Client-Server constraint for the exchanges of request and responses rather than a resource, identified by a URI, and the use of a fixed set of HTTP methods.

A resource in the Jersey client API is an instance of the Java class WebResource, and encapsulates a URI. The fixed set of HTTP methods are methods on WebResource or if using the builder pattern (more on this later) are the last methods to be called when invoking an HTTP method on a resource. The representations are Java types, instances of which, may contain links that new instances of WebResource may be created from.

Since a resource is represented as a Java type it makes it easy to configure, pass around and inject in ways that is not so intuitive or possible with other client-side APIs.

The Jersey Client API reuses many aspects of the JAX-RS and the Jersey implementation such as:

Some APIs, like the Apache HTTP client or java.net.HttpURLConnection, can be rather hard to use and/or require too much code to do something relatively simple.

This is why the Jersey Client API provides support for wrapping HttpURLConnection and the Apache HTTP client. Thus it is possible to get the benefits of the established implementations and features while getting the ease of use benefit.

It is not intuitive to send a POST request with form parameters and receive a response as a JAXB object with such an API. For example with the Jersey API this is very easy:

  1 Form f = new Form();
  2 f.add("x", "foo");
  3 f.add("y", "bar");
  4 
  5 Client c = Client.create();
  6 WebResource r = c.resource("http://localhost:8080/form");
  7 
  8 JAXBBean bean = r.
  9     type(MediaType.APPLICATION_FORM_URLENCODED_TYPE)
 10     .accept(MediaType.APPLICATION_JSON_TYPE)
 11     .post(JAXBBean.class, f);

In the above code a Form is created with two parameters, a new WebResource instance is created from a Client then the Form instance is POSTed to the resource, identified with the form media type, and the response is requested as an instance of a JAXB bean with an acceptable media type identifying the Java Script Object Notation (JSON) format. The Jersey client API manages the serialization of the Form instance to produce the request and de-serialization of the response to consume as an instance of a JAXB bean.

If the code above was written using HttpURLConnection then the developer would have to write code to serialize the form sent in the POST request and de-serialize the response to the JAXB bean. In addition further code would have to be written to make it easy to reuse the same resource “http://localhost:8080/form” that is encapsulated in the WebResource type.

Refer to the dependencies chapter, and specifically the Core client section, for details on the dependencies when using the Jersey client with Maven and Ant.

Refer to the Java API documentation for details on the Jersey client API packages and classes.

Refer to the Java API Apache HTTP client documentation for details on how to use the Jersey client API with the Apache HTTP client.

To utilize the client API it is first necessary to create an instance of a Client, for example:

    Client c = Client.create();

    c.getProperties().put(
        ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);

    c.setFollowRedirects(true);

    ClientConfig cc = new DefaultClientConfig();
    cc.getProperties().put(
        ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
    Client c = Client.create(cc);

    WebResource r = c.resource("http://localhost:8080/xyz");

    String response = r.accept(
        MediaType.APPLICATION_JSON_TYPE,
        MediaType.APPLICATION_XML_TYPE).
        header("X-FOO", "BAR").
        get(String.class);

    String request = "content";
    String response = r.accept(
        MediaType.APPLICATION_JSON_TYPE,
        MediaType.APPLICATION_XML_TYPE).
        header("X-FOO", "BAR").
        post(String.class, request);

    String response = r.accept(
         MediaType.APPLICATION_JSON_TYPE,
         MediaType.APPLICATION_XML_TYPE).
         header("X-FOO", "BAR").
         type(MediaType.TEXT_PLAIN_TYPE).
         post(String.class, request);

    String response = r.accept(
         MediaType.APPLICATION_JSON_TYPE,
         MediaType.APPLICATION_XML_TYPE).
         header("X-FOO", "BAR").
         entity(request, MediaType.TEXT_PLAIN_TYPE).
         post(String.class);

    ClientResponse response = r.get(ClientResponse.class);
    EntityTag e = response.getEntityTag();
    String entity = response.getEntity(String.class);

    try {
        String entity = r.get(String.class);
    } catch (UniformInterfaceException ue) {
        ClientResponse response = ue.getResponse();
    }

    WebResource r = c.resource("http://localhost:8080/xyz");

    MultivaluedMap<String, String> params = new MultivaluedMapImpl();
    params.add("foo", "x");
    params.add("bar", "y");
    
    String response = r.path("abc").
        queryParams(params).
        get(String.class);

    InputStream in = r.get(InputStream.class);
    // Read from the stream
    in.close();

    File f = ...
    String response = r.post(String.class, f);

The support for new application-defined representations as Java types requires the implementation of the same provider-based interfaces as for the server side JAX-RS API, namely MessageBodyReader and MessageBodyWriter, respectively, for request and response entities (or inbound and outbound representations). Refer to the entity provider sample for such implementations utilized on the server side.

Classes or implementations of the provider-based interfaces need to be registered with a ClientConfig and passed to the Client for creation. The following registers a provider class MyReader which will be instantiated by Jersey:

    ClientConfig cc = new DefaultClientConfig();
    cc.getClasses().add(MyReader.class);
    Client c = Client.create(cc);

The following registers an instance or singleton of MyReader:

    ClientConfig cc = new DefaultClientConfig();
    MyReader reader = ...
    cc.getSingletons().add(reader);
    Client c = Client.create(cc);

Filtering requests and responses can provide useful functionality that is hidden from the application layer of building and sending requests, and processing responses. Filters can read/modify the request URI, headers and entity or read/modify the response status, headers and entity.

The Client and WebResource classes extend from Filterable and that enables the addition of ClientFilter instances. A WebResource will inherit filters from its creator, which can be a Client or another WebResource. Additional filters can be added to a WebResource after it has been created. For requests, filters are applied in reverse order, starting with the WebResource filters and then moving to the inherited filters. For responses, filters are applied in order, starting with inherited filters and followed by the filters added to the WebResource. All filters are applied in the order in which they were added. For instance, in the following example the Client has two filters added, filter1 and filter2, in that order, and the WebResource has one filter added, filter3:

    ClientFilter filter1 = ...
    ClientFilter filter2 = ...
    Client c = Client.create();
    c.addFilter(filter1);
    c.addFilter(filter2);
    
    ClientFilter filter3 = ...
    WebResource r = c.resource(...);
    r.addFilter(filter3);

After a request has been built the request is filtered by filter3, filter2 and filter1 in that order. After the response has been received the response is filtered by filter1, filter2 and filter3 in that order, before the response is returned.

Filters are implemented using the “russian doll” stack-based pattern where a filter is responsible for calling the next filter in the ordered list of filters (or the next filter in the “chain” of filters). The basic template for a filter is as follows:

    class AppClientFilter extends ClientFilter {
        public ClientResponse handle(ClientRequest cr) {
            // Modify the request
            ClientRequest mcr = modifyRequest(cr);
            // Call the next filter
            ClientResponse resp = getNext().handle(mcr);
            // Modify the response
            return modifyResponse(resp);
        }
    }

The filter modifies the request (if required) by creating a new ClientRequest or modifying the state of the passed ClientRequest before calling the next filter. The call to the next request will return the response, a ClientResponse. The filter modifies the response (if required) by creating a new ClientResponse or modifying the state of the returned ClientResponse. Then the filter returns the modified response. Filters are re-entrant and may be called by multiple threads performing requests and processing responses.

The Jersey client API was originally developed to aid the testing of the Jersey server-side, primarily to make it easier to write functional tests in conjunction with the JUnit framework for execution and reporting. It is used extensively and there are currently over 1000 tests.

Embedded servers, Grizzly and a special in-memory server, are utilized to deploy the test-based services. Many of the Jersey samples contain tests that utilize the client API to server both for testing and examples of how to use the API. The samples utilize Grizzly or embedded Glassfish to deploy the services.

The following code snippets are presented from the single unit test HelloWorldWebAppTest of the helloworld-webapp sample. The setUp method, called before a test is executed, creates an instance of the Glassfish server, deploys the application, and a WebResource instance that references the base resource:

    @Override
    protected void setUp() throws Exception {
        super.setUp();

        // Start Glassfish
        glassfish = new GlassFish(BASE_URI.getPort());
        
        // Deploy Glassfish referencing the web.xml
        ScatteredWar war = new ScatteredWar(
            BASE_URI.getRawPath(), new File("src/main/webapp"),
            new File("src/main/webapp/WEB-INF/web.xml"),
            Collections.singleton(
                new File("target/classes").
                    toURI().toURL()));
        glassfish.deploy(war);
        
        Client c = Client.create();
        r = c.resource(BASE_URI);
    }

The tearDown method, called after a test is executed, stops the Glassfish server.

    @Override
   protected void tearDown() throws Exception {
        super.tearDown();
        glassfish.stop();
   }

The testHelloWorld method tests that the response to a GET request to the Web resource returns “Hello World”:

    public void testHelloWorld() throws Exception {
       String responseMsg = r.path("helloworld").
           get(String.class);
       assertEquals("Hello World", responseMsg);
   }

Note the use of the path method on the WebResource to build from the base WebResource.

Jersey currently support several low level data types: StreamSource, SAXSource, DOMSource and Document. You can use these types as return type or method (resource) parameter. Lets say we want to test this feature and we have helloworld sample as starting point. All we need to do is add methods (resources) which consumes and produces XML and types mentioned above will be used.

  1     @Path("1")
  2     @POST
  3     public StreamSource get1(StreamSource streamSource) {
  4         return streamSource;
  5     }
  6 
  7     @Path("2")
  8     @POST
  9     public SAXSource get2(SAXSource saxSource) {
 10         return saxSource;
 11     }
 12 
 13     @Path("3")
 14     @POST
 15     public DOMSource get3(DOMSource domSource) {
 16         return domSource;
 17     }
 18 
 19     @Path("4")
 20     @POST
 21     public Document get4(Document document) {
 22         return document;
 23     }

Both MessageBodyReaders and MessageBodyWriters are used in this case, all we need is do POST request with some XML document as a request entity. I want to keep this as simple as possible so I'm going to send only root element with no content: "<test />". You can create Jersey client to do that or use some other tool, for example curl as I did. (curl -v http://localhost:9998/helloworld/1 -d "<test />"). You should get exactly same XML from our service as is present in the request; in this case, XML headers are added to response but content stays. Feel free to iterate through all resources.

Good start for people which already have some experience with JAXB annotations is JAXB sample. You can see various usecases there. This text is mainly meant for those who don't have prior experience with JAXB. Don't expect that all possible annotations and their combinations will be covered in this chapter, JAXB (JSR 222 implementation) is pretty complex and comprehensive. But if you just want to know how you can interchange XML messages with your REST service, you are looking at right chapter.

Lets start with simple example. Lets say we have class Planet and service which produces "Planets"

  1 @XmlRootElement
  2 public class Planet {
  3     public int id;
  4     public String name;
  5     public double radius;
  6 }
  7             

  1 @Path("planet")
  2 public class Resource {
  3 
  4     @GET
  5     @Produces(MediaType.APPLICATION_XML)
  6     public Planet getPlanet() {
  7         Planet p = new Planet();
  8         p.id = 1;
  9         p.name = "Earth";
 10         p.radius = 1.0;
 11 
 12         return p;
 13     }
 14 }            

You can see there is some extra annotation declared on Planet class. Concretely XmlRootelement. What it does? This is a JAXB annotation which maps java class to XML element. We don't need specify anything else, because Planet is very simple class and all fields are public. In this case, XML element name will be derived from class name or you can set name property: @XmlRootElement(name="yourName").

Our resource class will respond to GET /planet with

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                <planet>
                        <id>1</id>
                        <name>Earth</name>
                        <radius>1.0</radius>
                </planet>
            

which might be exactly what we want... or not. Or we might not really care, because we can use Jersey client for making requests to this resource and this is easy as: Planet planet = webResource.path("planet").accept(MediaType.APPLICATION_XML_TYPE).get(Planet.class);. There is pre-created WebResource object which points to our applications context root and we simpli add path (in our clase its "planet"), accept header (not mandatory, but service could provide different content based on this header; for example text/html can be served for web browsers) and at the end we specify that we are expecting Planet class via GET request.

There may be need for not just producing XML, we might want to consume it as well.

  1     @POST
  2     @Consumes(MediaType.APPLICATION_XML)
  3     public void setPlanet(Planet p) {
  4         System.out.println("setPlanet " + p);
  5     }
  6                     

After valid request is made (with Jersey client you can do webResource.path("planet").post(p);), service will print out string representation of Planet, which can look like Planet{id=2, name='Mars', radius=1.51}.

If there is a need for some other (non default) XML representation, other JAXB annotations would need to be used. This process is usually simplified by generating java source from XML Schema which is done by xjc. Xjc is XML to java compiler and is part of JAXB. See JAXB home page for further details.

Sometimes you can't / don't want to add JAXB annotations to source code and you still want to have resources consuming and producing XML representation of your classes. In this case, JAXBElement class should help you. Let's redo planet resource but this time we won't have XmlRootElement annotation on Planet class.

  1 @Path("planet")
  2 public class Resource {
  3 
  4     @GET
  5     @Produces(MediaType.APPLICATION_XML)
  6     public JAXBElement<Planet> getPlanet() {
  7         Planet p = new Planet();
  8         p.id = 1;
  9         p.name = "Earth";
 10         p.radius = 1.0;
 11 
 12         return new JAXBElement<Planet>(new QName("planet"), Planet.class, p);
 13     }
 14 
 15     @POST
 16     @Consumes(MediaType.APPLICATION_XML)
 17     public void setPlanet(JAXBElement<Planet> p) {
 18         System.out.println("setPlanet " + p.getValue());
 19     }
 20 }            

As you can see, everything is little more complicated with JAXBElement. This is because now you need to explicitly set element name for Planet class XML representation. Client side is even more ugly than server side because you can't do JAXBElement<Planet>.class so Jersey client API provides way how to workaround it by declaring subclass of GenericType.

  1         // GET
  2         GenericType<JAXBElement<Planet>> planetType = new GenericType<JAXBElement<Planet>>() {};
  3 
  4         Planet planet = (Planet) webResource.path("planet").accept(MediaType.APPLICATION_XML_TYPE).get(planetType).getValue();
  5         System.out.println("### " + planet);
  6 
  7         // POST
  8         Planet p = new Planet();
  9         // ...
 10 
 11         webResource.path("planet").post(new JAXBElement<Planet>(new QName("planet"), Planet.class, p));           

In some scenarios you can take advantage of using custom JAXBContext. Creating JAXBContext is expensive operation and if you already have one created, same instance can be used by Jersey. Other possible usecase for this is when you need to set some specific things to JAXBContext, for example set different classloader.

  1 @Provider
  2 public class PlanetJAXBContextProvider implements ContextResolver<JAXBContext> {
  3     private JAXBContext context = null;
  4 
  5     public JAXBContext getContext(Class<?> type) {
  6         if(type != Planet.class)
  7             return null; // we don't support nothing else than Planet
  8 
  9         if(context == null) {
 10             try {
 11                 context = JAXBContext.newInstance(Planet.class);
 12             } catch (JAXBException e) {
 13                 // log warning/error; null will be returned which indicates that this
 14                 // provider won't/can't be used.
 15             }
 16         }
 17         return context;
 18     }
 19 }
 20         

Sample above shows simple JAXBContext creation, all you need to do is put this @Provider annotated class somewhere where Jersey can find it. Users sometimes have problems with using provider classes on client side, so just for reminder - you have to declare them in client config (cliend does not anything like package scanning done by server).

  1                 ClientConfig cc = new DefaultClientConfig();
  2                 cc.getClasses().add(PlanetJAXBContextProvider.class);
  3                 Client c = Client.create(cc);
  4             

POJO suppport represents the easiest way to convert your Java Objects to JSON and back. It is based on the Jackson library.

To use this approach, you will need to turn the JSONConfiguration.FEATURE_POJO_MAPPING feature on. This could be done in web.xml using the following servlet init parameter:

  1         <init-param>
  2             <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
  3             <param-value>true</param-value>
  4         </init-param>

The following snippet shows how to use the POJO mapping feature on the client side:

  1   ClientConfig clientConfig = new DefaultClientConfig();
  2   clientConfig.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, Boolean.TRUE);
  3   Client client = Client.create(clientConfig);

Jackson JSON processor could be futher controlled via providing custom Jackson ObjectMapper instance. This could be handy if you need to redefine the default Jackson behaviour and to fine-tune how your JSON data structures look like. Detailed description of all Jackson features is out of scope of this guide. The example bellow gives you a hint on how to wire your ObjectMapper instance into your Jersey application.

Download https://maven.java.net/service/local/artifact/maven/redirect?r=releases&g=com.sun.jersey.samples&a=jacksonjsonprovider&v=1.19.1&c=project&e=zip to get a complete example using POJO based JSON support.

Taking this approach will save you a lot of time, if you want to easily produce/consume both JSON and XML data format. Because even then you will still be able to use a unified Java model. Another advantage is simplicity of working with such a model, as JAXB leverages annotated POJOs and these could be handled as simple Java beans.

A disadvantage of JAXB based approach could be if you need to work with a very specific JSON format. Then it could be difficult to find a proper way to get such a format produced and consumed. This is a reason why a lot of configuration options are provided, so that you can control how things get serialized out and deserialized back.

Following is a very simple example of how a JAXB bean could look like.

  1 @XmlRootElement
  2 public class MyJaxbBean {
  3   public String name;
  4   public int age;
  5       
  6   public MyJaxbBean() {} // JAXB needs this
  7 
  8   public MyJaxbBean(String name, int age) {
  9     this.name = name;
 10     this.age = age;
 11   }
 12 }

Using the above JAXB bean for producing JSON data format from you resource method, is then as simple as:

  1 @GET @Produces("application/json")
  2 public MyJaxbBean getMyBean() {
  3    return new MyJaxbBean("Agamemnon", 32);
  4 }

Notice, that JSON specific mime type is specified in @Produces annotation, and the method returns an instance of MyJaxbBean, which JAXB is able to process. Resulting JSON in this case would look like:

    {"name":"Agamemnon", "age":"32"}

  1 @XmlRootElement
  2 public class MyJaxbBean {
  3   
  4     @XmlElement(name="king")
  5     public String name;
  6   
  7     @XmlTransient
  8     public int age;
  9  
 10     // several lines removed       
 11 }

  1 @Provider
  2 public class JAXBContextResolver implements ContextResolver<JAXBContext> {
  3 
  4     private JAXBContext context;
  5     private Class[] types = {MyJaxbBean.class};
  6 
  7     public JAXBContextResolver() throws Exception {
  8         this.context = 
  9 	  new JSONJAXBContext( (1)
 10 	    JSONConfiguration.natural().build(), types); (2)
 11     }
 12 
 13     public JAXBContext getContext(Class<?> objectType) {
 14         for (Class type : types) {
 15             if (type == objectType) {
 16                 return context;
 17             }
 18         }
 19         return null;
 20     }
 21 }

  1 @XmlRootElement
  2 public class Address {
  3     public String street;
  4     public String town;
  5 
  6     public Address(){}
  7 
  8     public Address(String street, String town) {
  9         this.street = street;
 10         this.town = town;
 11     }
 12 }

  1 @XmlRootElement
  2 public class Contact {
  3 
  4     public int id;
  5     public String name;
  6     public List<Address> addresses;
  7 
  8     public Contact() {};
  9 
 10     public Contact(int id, String name, List<Address> addresses) {
 11         this.name = name;
 12         this.id = id;
 13         this.addresses = 
 14 	        (addresses != null) ? new LinkedList<Address>(addresses) : null;
 15     }
 16 }

final Address[] addresses = {new Address("Long Street 1", "Short Village")};
Contact contact = new Contact(2, "Bob", Arrays.asList(addresses));

JSONConfiguration.mapped().build()

  1 { "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":{"street":"Long Street 1"
  4                     ,"town":"Short Village"}}

contact.addresses.add(new Address("Short Street 1000", "Long Village"));

  1 { "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":[{"street":"Long Street 1","town":"Short Village"}
  4               ,{"street":"Short Street 1000","town":"Long Village"}]}

JSONConfiguration.mapped().arrays("addresses").build()

JSONConfiguration.mapped().arrays("addresses").nonStrings("id").build()

  ...
  @XmlAttribute
  public int id;
  ...

{"@id":"2" ...

JSONConfiguration.mapped().attributeAsElement("id").build()

JSONConfiguration.mapped().rootUnwrapping(false).build()

  1 {"contact":{ "id":"2" 
  2  ,"name":"Bob"
  3  ,"addresses":{"street":"Long Street 1"
  4                     ,"town":"Short Village"}}}

  1         Map<String,String> ns2json = new HashMap<String, String>();
  2         ns2json.put("http://example.com", "example");
  3         context = new JSONJAXBContext(
  4 	      JSONConfiguration.mapped()
  5 	           .xml2JsonNs(ns2json).build(), types);

JSONConfiguration.natural().build()

  1 { "id":2
  2  ,"name":"Bob"
  3  ,"addresses":[{"street":"Long Street 1"
  4                      ,"town":"Short Village"}]}

JSONConfiguration.natural().rootUnwrapping(false).build()

JSONConfiguration.mappedJettison().build()

  1 { "contact:{"id":2
  2               ,"name":"Bob"
  3               ,"addresses":{"street":"Long Street 1"
  4                                  ,"town":"Short Village"}}

  ...
  @XmlElement(namespace="http://example.com")
  public int id;
  ...

  1         Map<String,String> ns2json = new HashMap<String, String>();
  2         ns2json.put("http://example.com", "example");
  3         context = new JSONJAXBContext(
  4 	      JSONConfiguration.mappedJettison()
  5 	           .xml2JsonNs(ns2json).build(), types);

  1 { "contact:{"example.id":2
  2               ,"name":"Bob"
  3               ,"addresses":{"street":"Long Street 1"
  4                                  ,"town":"Short Village"}}

JSONConfiguration.badgerFish().build()

  1 {"contact":{"id":{"$":"2"}
  2               ,"name":{"$":"Bob"}
  3               ,"addresses":{"street":{"$":"Long Street 1"}
  4                                  ,"town":{"$":"Short Village"}}}}

Using this approach means you will be using JSONObject and/or JSONArray classes for your data representations. These classes are actually taken from Jettison project, but conform to the description provided at http://www.json.org/java/index.html.

The biggest advantage here is, that you will gain full control over the JSON format produced and consumed. On the other hand, dealing with your data model objects will probably be a bit more complex, than when taking the JAXB based approach. Differencies are depicted at the following code snipets.

MyJaxbBean myBean = new MyJaxbBean("Agamemnon", 32);

Above you construct a simple JAXB bean, which could be written in JSON as {"name":"Agamemnon", "age":32}

Now to build an equivalent JSONObject (in terms of resulting JSON expression), you would need several more lines of code.

  1 JSONObject myObject = new JSONObject();
  2 myObject.JSONObject myObject = new JSONObject();
  3 try {
  4   myObject.put("name", "Agamemnon");
  5   myObject.put("age", 32);
  6 } catch (JSONException ex) {
  7   LOGGER.log(Level.SEVERE, "Error ...", ex);
  8 }

Links are added to representations using the @Ref annotation on entity class fields. The Jersey runtime is responsible for injecting the appropriate URI into the field prior to serialization by a message body writer. E.g. consider the following resource and entity classes:

@Path("widgets")
public class WidgetsResource {
  @GET
  public Widgets get() {
    return new Widgets();
  }
}
        
public class Widgets {
  @Ref(resource=WidgetsResource.class)
  URI u;
}

After a call to WidgetsResource#get, the Jersey runtime will inject the value "/context/widgets"^[1] into the returned Widgets instance. If an absolute URI is desired instead of an absolute path then the annotation can be changed to @Ref(resource=WidgetsResource.class, style=ABSOLUTE).

The above usage works nicely when there's already a URI template on a class that you want to reuse. If there's no such template available then you can use a literal value instead of a reference. E.g. the following is equivalent to the earlier example: @Ref(value="widgets", style=ABSOLUTE).

Referenced or literal templates may contain parameters. Two forms of parameters are supported:

Parameter values can be extracted from three implicit beans:

By default URI template parameter values are extracted from the implicit instance bean, i.e. the following two annotations are equivalent:

@Ref("widgets/{id}")
@Ref("widgets/${instance.id}")

The source for URI template parameter values can be changed using the @Binding annotation, E.g. the following two annotations are equivalent:

@Ref(value="widgets/{id}", bindings={
  @Binding(name="id" value="${resource.id}"}
)
@Ref("widgets/${resource.id}")

Link value injection can be made conditional by use of the condition property. The value of this property is a boolean EL expression and a link will only be injected if the condition expression evaluates to true. E.g.:

@Ref(value="widgets/${instance.id}/offers",
  condition="${instance.offers}")
URI offers;

In the above, a URI will only be injected into the offers field if the offers property of the instance is true.

HTTP Link headers can also be added to responses using annotations. Instead of annotating the fields of an entity class with @Ref, you instead annotate the entity class itself with @Link. E.g.:

@Link(
  value=@Ref("widgets/${resource.nextId}"),
  rel="next"
)

The above would insert a HTTP Link header into any response whose entity was thus annotated. The @Link annotation contains properties that map to the parameters of the HTTP Link header. The above specifies the link relation as next. All properties of the @Ref annotation may be used as described above.

Multiple link headers can be added by use of the @Links annotation which can contain multiple @Link annotations.

Declarative hyperlinking support is provided in the form of a filter. First, the application must declare a dependency on the jersey-server-linking module:

<dependency>
  <groupId>com.sun.jersey</groupId>
  <artifactId>jersey-server-linking</artifactId>
  <version>${jersey-version}</version>
</dependency>

Second the filter needs to be installed in the application either programmatically by adding:

com.sun.jersey.server.linking.LinkFilter

to the list defined by:

com.sun.jersey.spi.container.ContainerResponseFilters

or using a web.xml init parameter:

<init-param>
  <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
  <param-value>com.sun.jersey.server.linking.LinkFilter</param-value>
</init-param>

See the jersey-server-linking-sample for more details.

There are some significant breaking changes in Jersey 1.2. In prior Jersey versions users were able to select container factory just by specifying it in some property. That was convenient from user perspective but not good from build perspective. Former test framework artifact was dependent on all containers which is useless in most cases (usually you test only with one container).

Solution to this is modularization - make module for each test container. It has one drawback: users will have to have other dependency in their applications, for example if you want to test on embedded grizzly container, you will declare (only) dependency on jersey test framework grizzly module. You can declare multiple test containers this way and select one by defining property jersey.test.containerFactory.

Another change (non-breaking) is renaming Jersey parameters which control container factory, used port and host name for external container. Old properties are still working but users are encouraged to use new ones.

When you want test your resources in maven-based project, you need to add dependency on one of the Jersey Test Framework modules. You can take a look at helloworld sample pom file. There is declared dependency on:

                <dependency>
                <groupId>com.sun.jersey.jersey-test-framework</groupId>
                <artifactId>jersey-test-framework-grizzly2</artifactId>
                <version>${project.version}</version>
                <scope>test</scope>
                </dependency>

            

which means that Grizzly Web container (version 2.x) will be used for testing.

You can specify more than one module in dependencies and choose which module will be used by jersey.test.containerFactory property. Every module should contain at least one container factory.

Basically you can just add dependency on single module and its container factory would be used. Problem is when you specify module which has more than one container factory or multiple modules. If this happen, test framework will choose factory using following rules:

if("jersey.test.containerFactory" not specified)
    look for factories
    if(factories.count == 1)
        use found factory
    else
        if(com.sun.jersey.test.framework.spi.container.grizzly2.web.GrizzlyWebTestContainerFactory is present)
            use it // current default jersey test container factory
        else
            use first found and log warning
else
    use factory class specified in "jersey.test.containerFactory"

That means if your project depends on multiple test framework modules and you want to control which will be used, you have to declare which one in property called "jersey.test.containerFactory", for example like this: mvn clean install -Djersey.test.containerFactory=com.sun.jersey.test.framework.spi.container.inmemory.InMemoryTestContainerFactory

Jersey Test Framework uses JUnit version 4.X, so if you can write standard unit tests, you can easily create Jersey Test. You need to declare test as a descendant of JerseyTest class.

public class MainTest extends JerseyTest {

    public MainTest()throws Exception {
        super("com.sun.jersey.samples.helloworld.resources");
    }

    @Test
    public void testHelloWorld() {
        WebResource webResource = resource();
        String responseMsg = webResource.path("helloworld").get(String.class);
        assertEquals("Hello World", responseMsg);
    }

}

Note super call in constructor - it passes list of package names to scan (it really is a list, JerseyTest constructor has variable argument count). Another useful method is resource() which returns WebResource instance with URI set to base URI of your application. You can get preconfigured Jersey Client instance similarly by calling client() method.

Creating your own module is pretty straightforward, you just have to implement com.sun.jersey.test.framework.spi.container.TestContainerFactory and com.sun.jersey.test.framework.spi.container.TestContainer. TestContainer factory is there basically for returning TestContainer instance and TestContainer has self-explanatory methods: start(), stop(), getClient() and getBaseURI(). I recommend taking look at source code and read javadoc of these two classes, all you need is there.

You should be avare of another thing when implementing own jersey test framework module. If you want it to be usable by running just mvn clean install (when only your module is specified), you need to add META-INF/services/com.sun.jersey.test.framework.spi.container.TestContainerFactory file into your jar and put there your factory class (fully classified) name.

Since Jersey is Maven based project, executing tests without Maven can be painful. You have to have everything needed present on classpath and by everything is meant following list:

This is needed to run helloworld sample tests, if you want run something more complex or with different test container (grizzly is used here), you may need to add other application specific dependencies (and remove some as well).

As was already written above, Jersey test is descendant of standard unit test so it can be run same way. You can execute it by executing org.junit.runner.JUnitCore and passing your test class name as parameter, from ant (junit-task) or whatever you are used to.

OSGi support was added to the Jersey version 1.2. Since then, you should be able to utilize standard OSGi means to run Jersey based web applications in OSGi runtime as described in the OSGi Service Platform Enterprise Specification. The specification could be downloaded from http://www.osgi.org/Download/Release4V42.

The two supported ways of running an OSGi web application are

WAB is in fact just an OSGified WAR archive. Http Service feature allows you to publish Java EE Servlets in the OSGi runtime.

Two examples were added to the Jersey distribution to depict the above mentioned features and show how to use them with Jersey

Both examples are multi-module maven projects and both consist of an application OSGi bundle module and a test module. The tests are based on Pax Exam framework. Both examples also include a readme file containing instructions how to manually run the application using Apache Felix framework.

The rest of the chapter describes how to run the above mentioned examples on GlassFish 3.1.2 application server. Since GlassFish utilizes Apache Felix, an OSGi runtime comes out of the box with GlassFish. However, for security reasons, the OSGi shell has been turned off. You can explicitly enable it. Either by starting GlassFish with asadmin -Dglassfish.osgi.start.level.final=3 start-domain or by setting glassfish.osgi.start.level.final property to 3 in glassfish/config/osgi.properties file. Presuming you have the default GlassFish instance running, after enabling shell as described above, you should now be able to connect to the Felix console with

        telnet localhost 6666

You should then see Apache Felix prompt similar to following

Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
____________________________
Welcome to Apache Felix Gogo

g!

As mentioned above, WAB is just an OSGified WAR archive. Besides the ususal OSGi headers it must in addition contain a special header, Web-ContextPath, specifying the web application context path. Our WAB has (beside some other) the following headers present in the manifest

Web-ContextPath: helloworld
Webapp-Context: helloworld
Bundle-ClassPath: WEB-INF/classes
  

where the second one is ignored by GlassFish, but is needed by other containers not fully compliant with the OSGi Enterprise Specification mentioned above. The third manifest header worth mentioning is the Bundle-ClassPath specifying where to find the application Java classes within the bundle archive.

For more detailed information on the example please see the source code.

Following is the listing showing how to actually install and run the WAB on GlassFish. Be sure to replace <version> with the current Jersey version and <repository> with either snapshots or releases based on whether you depend on a snapshot or stable release version of Jersey respectively:

g! install https://maven.java.net/service/local/artifact/maven/redirect?r=<repository>&g=com.sun.jersey.samples.helloworld-osgi-webapp&a=war-bundle&v=<version>&e=war
Bundle ID: 246
g! start 246

In the above listing, the number 246 represents handler to the OSGi bundle you have just installed. Bundle numbers are allocated dynamically. It means, you might be given a different handler. It is important to always use the correct bundle number as specified by the Felix runtime in the "Bundle ID:" response.

After the WAB gets installed and activated by the above mentioned commands, you should be able to access the deployed Jersey resource at http://localhost:8080/helloworld/webresources/helloworld

OSGi Http Service support currently does not come out of the box with GlassFish, but is provided with a separate OSGi bundle, http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar. You will need to enable the feature first, by installing that bundle. After that, you can install and activate the Jersey application bundle. Following is the listing showing how both bundles could be installed and activated (Be sure to replace <version> with the current Jersey version and <repository> with either snapshots or releases based on whether you depend on a snapshot or stable release version of Jersey respectively):

g! install http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar
Bundle ID: 247
g! install https://maven.java.net/service/local/artifact/maven/redirect?r=<repository>&g=com.sun.jersey.samples.osgi-http-service&a=bundle&v=<version>&e=jar
Bundle ID: 248
g! start 247 248

Now you should be able to access the Jersey resource at http://localhost:8080/osgi/jersey-http-service/status

Finally, to close the Felix console session just press [Ctrl]-[d].

Maven developers require a dependency on the jersey-server module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey</groupId>
    <artifactId>jersey-server</artifactId>
    <version>1.19.1</version>
</dependency>

If you want to depend on Jersey snapshot versions the following repository needs to be added to the pom:

<repository>
    <id>snapshot-repository.java.net</id>
    <name>Java.net Snapshot Repository for Maven</name>
    <url>https://maven.java.net/content/repositories/snapshots/</url>
    <layout>default</layout>
</repository>

Non-maven developers require:

or, if using the jersey-bundle:

For Ant developers the Ant Tasks for Maven may be used to add the following to the ant document such that the dependencies do not need to be downloaded explicitly:

<artifact:dependencies pathId="dependency.classpath">
  <dependency groupId="com.sun.jersey"
              artifactId="jersey-server"
              version="1.19.1"/>
  <artifact:remoteRepository id="maven-repository.java.net"
                             url="http://maven.java.net/" />
  <artifact:remoteRepository id="maven1-repository.java.net"
                             url="http://download.java.net/maven/1"
                             layout="legacy" />
</artifact:dependencies>

The path id “dependency.classpath” may then be referenced as the classpath to be used for compiling or executing.

By default Jersey will utilize the ClasspathResourceConfig if an alternative is not specified.

Maven developers require a dependency on the jersey-client module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey</groupId>
    <artifactId>jersey-client</artifactId>
    <version>1.19.1</version>
</dependency>

Non-maven developers require:

or, if using the jersey-bundle:

The use of client with the Apache HTTP client to make HTTP request and receive HTTP responses requires a dependency on the jersey-apache-client module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey.contribs</groupId>
    <artifactId>jersey-apache-client</artifactId>
    <version>1.19.1</version>
</dependency>

By default WADL for resource classes is generated dynamically at runtime. WADL support requires a dependency on the JAXB reference implementation version 2.x or higher. Deploying an application for WADL support requires no additional dependences, since Java SE 6 ships with JAXB 2.x support.

The WADL ant task requires the same set of dependences as those for runtime WADL support.

Maven developers, using Spring 2.0.x or Spring 2.5.x, require a dependency on the jersey-spring module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey.contribs</groupId>
    <artifactId>jersey-spring</artifactId>
    <version>1.19.1</version>
</dependency>

See the Java documentation here on how to integrate Jersey-based Web applications with Spring.

Maven developers, using Guice 2.0, require a dependency on the jersey-guice module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey.contribs</groupId>
    <artifactId>jersey-guice</artifactId>
    <version>1.19.1</version>
</dependency>

See the Java documentation here on how to integrate Jersey-based Web applications with Guice.

The Jersey Guice support may also be used with GuiceyFruit, a set of extensions on top of Guice 2.0, such as support for Java EE artifacts like @PostConstruct/@PreDestroy, @Resource and @PersistenceContext. To avail of GuiceyFruit features exclude the guice dependency from the maven central repo and add the following:

<dependency>
    <groupId>org.guiceyfruit</groupId>
    <artifactId>guiceyfruit</artifactId>
    <version>2.0</version>
</dependency>
...
<repository>
    <id>guice-maven</id>
    <name>guice maven</name>
    <url>http://guiceyfruit.googlecode.com/svn/repo/releases/</url>
</repository>

NOTE that breaking changes have occurred between 1.1.1-ea and 1.1.2-ea. See the end of this section for details.

Jersey Test Framework allows you to test your RESTful Web Services on a wide range of containers. It supports light-weight containers such as Grizzly, Embedded GlassFish, and the Light Weight HTTP Server in addition to regular web containers such as GlassFish and Tomcat. Developers may plug in their own containers.

A developer may write tests using the Junit 4.x framework can extend from the abstract JerseyTest class.

Maven developers require a dependency on the jersey-test-framework-grizzly module. The following dependency needs to be added to the pom:

<dependency>
    <groupId>com.sun.jersey.jersey-test-framework</groupId>
    <artifactId>jersey-test-framework-grizzly</artifactId>
    <version>1.19.1</version>
    <scope>test</scope>
</dependency>

When utilizing an embedded container this framework can manage deployment and testing of your web services. However, the framework currently doesn't support instantiating and deploying on external containers.

The test framework provides the following test container factories:

The system property jersey.test.containerFactory is utilized to declare the default test container factory that shall be used for testing, the value of which is the fully qualified class name of a test container factory class. If the property is not declared then the GrizzlyWebTestContainerFactory is utilized as default test container factory.

To test a maven-based web project with an external container such as GlassFish, create the war file then deploy as follows (assuming that the pom file is set up for deployment):

mvn clean package -Dmaven.test.skip=true

Then execute the tests as follows:

mvn test \ -Djersey.test.containerFactory=com.sun.jersey.test.framework.spi.container.embedded.glassfish.external.ExternalTestContainerFactory \
-DJERSEY_HTTP_PORT=<HTTP_PORT>

Breaking changes from 1.1.1-ea to 1.1.2-ea

The maven project groupId has changed from com.sun.jersey.test.framework to com.sun.jersey

The extending of Jersey unit test and configuration has changed. See here for an example.

See the blog entry on Jersey Test Framework for detailed instructions on how to use 1.1.1-ea version of the framework in your application.

To override the version of Jersey distributed in GlassFish with a version of Jersey distributed in a war file ensure that class loader delegation is set to false in WEB-INF/sun-web.xml or WEB-INF/glassfish-web.xml. For example:

<sun-web-app error-url="">
    <context-root>/context</context-root>
    <class-loader delegate="false"/>
</sun-web-app>

In the GlassFish admin console, go to Configuration->JVM Settings, switch to the JVM Options tab and add the following option:

-Dcom.sun.enterprise.overrideablejavaxpackages=javax.ws.rs,javax.ws.rs.core,javax.ws.rs.ext

Restart GlassFish for new JVM settings to take effect.

The Jersey source code is available from the Subversion repository located at http://java.net/projects/jersey/sources/svn/show. You can also read more about how the top level of the `jersey' Subversion repository is structured at that same link.

To check out the trunk where active development on the next release occurs use the following command:

svn checkout https://svn.java.net/svn/jersey~svn/trunk/jersey jersey --username <username>

If you are new to Subversion, you may want to visit the Subversion Project website and read Version Control with Subversion.

Stable releases of Jersey are tagged in the location http://java.net/projects/jersey/sources/svn/show/tags.

The source code may be browsed using FishEye.

Java SE 6 or greater is required. Maven 2.2.1 or greater is recommended.

It is recommended to build the whole of Jersey after you have initially checked out the source code. To build all of Jersey use the following command from the checked out jersey directory:

mvn clean install

To skip all the tests do:

mvn -Dmaven.test.skip=true clean install

The following maven options are recommended:

-Xmx1048m -XX:PermSize=64M -XX:MaxPermSize=128M

Building the whole Jersey project including tests could take about an hour, depending on your system performance of course. Even if you have a pretty fast performant machine, this could be quite annoying. Especially if you just want to experiment with a limited amount of code. To avoid building the whole Jersey project tree, you can easily utilize the maven reactor plugin.

To build only the modules needed for the helloworld example, you can launch:

mvn reactor:make -Dmake.goals=clean,install -Dmake.folders=samples/helloworld

which takes less then 2 minutes on my machine. To switch testing off, when building the same set of modules, you will use:

mvn reactor:make -Dmake.goals=-Dmaven.test.skip,clean,install -Dmake.folders=samples/helloworld

Jersey contains many unit tests. Most of these are not really unit tests per-say and are functional tests using the JUnit test framework because it is very convientient for execution and reporting.

Some modules have specific tests but most tests associated with testing the jersey-core, jersey-client and jersey-server modules are located in the jersey-test module. This module can take some time to execute all the tests so it is recommended that you pick the appropriate tests to run related to the particular area that is being investigated. For example, using:

mvn -Dtest=<pattern> test

where pattern may be a comma separated set of names matching tests.

Jersey is built, tested and deployed on Solaris, Windows and Linux using an interal Hudson server. The Jersey Hudson jobs are available publically at http://hudson.glassfish.org/job/Jersey-trunk-multiplatform/.

NetBeans 6.8 or greater has excellent maven support. The Jersey maven modules can be loaded, built and tested in NetBeans without any additional project-specific requirements.