Jersey 2.0.1 User Guide

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>

Now, to create a new Jersey project, based on Grizzly 2 container, from a maven archetype, execute the following in the directory where the new project should reside:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false -DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example -DarchetypeVersion=2.0.1

Feel free to adjust the group id, package name and artifact id of your new project in the line above, or you can change it after it gets generated by updating the project pom.xml

TODO

TODO: instructions on how to make simple edits to the newly created resource

TODO: instructions on how to run the project

TODO

Jersey codebase contains a number of useful samples on how to use various JAX-RS and Jersey features. Please refer to the [TODO: Examples] section of this guide for more information on those.

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.

                    package org.glassfish.jersey.examples.helloworld;

                    import javax.ws.rs.GET;
                    import javax.ws.rs.Path;
                    import javax.ws.rs.Produces;

                    @Path("helloworld")
                    public class HelloWorldResource {
                        public static final String CLICHED_MESSAGE = "Hello World!";

                    @GET
                    @Produces("text/plain")
                        public String getHello() {
                            return CLICHED_MESSAGE;
                        }
                    }
                

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

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

                        @Path("/users/{username}")
                        public class UserResource {

                        @GET
                        @Produces("text/xml")
                        public String getUser(@PathParam("username") String userName) {
                        ...
                        }
                        }
                    

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

                        @PUT
                        public Response putContainer() {
                            System.out.println("PUT CONTAINER " + container);

                            URI uri = uriInfo.getAbsolutePath();
                            Container c = new Container(container, uri.toString());

                            Response r;
                            if (!MemoryStore.MS.hasContainer(c)) {
                                r = Response.created(uri).build();
                            } else {
                                r = Response.noContent().build();
                            }

                            MemoryStore.MS.createContainer(c);
                            return r;
                        }
                    

                        @Path("/myResource")
                        @Produces("text/plain")
                        public class SomeResource {
                            @GET
                            public String doGetAsPlainText() {
                                ...
                            }

                            @GET
                            @Produces("text/html")
                            public String doGetAsHtml() {
                                ...
                            }
                        }
                    

                        @GET
                        @Produces({"application/xml", "application/json"})
                        public String doGetAsXmlOrJson() {
                            ...
                        }
                    

                        @GET
                        @Produces({"application/xml; qs=0.9", "application/json"})
                        public String doGetAsXmlOrJson() {
                            ...
                        }
                    

@POST
                        @Consumes("text/plain")
                        public void postClichedMessage(String message) {
                            // Store the message
                        }
                    

Parameters of a resource method may be annotated with parameter-based annotations to extract information from a request. One of the previous examples presented the use of @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:

                @Path("smooth")
                @GET
                public Response smooth(
                    @DefaultValue("2") @QueryParam("step") int step,
                    @DefaultValue("true") @QueryParam("min-m") boolean hasMin,
                    @DefaultValue("true") @QueryParam("max-m") boolean hasMax,
                    @DefaultValue("true") @QueryParam("last-m") boolean hasLast,
                    @DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,
                    @DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,
                    @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) {
                    ...
                }
            

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:

                public class ColorParam extends Color {

                    public ColorParam(String s) {
                        super(getRGB(s));
                    }

                    private static int getRGB(String s) {
                        if (s.charAt(0) == '#') {
                            try {
                                Color c = Color.decode("0x" + s.substring(1));
                                return c.getRGB();
                            } catch (NumberFormatException e) {
                                throw new WebApplicationException(400);
                            }
                        } else {
                            try {
                                Field f = Color.class.getField(s);
                                return ((Color)f.get(null)).getRGB();
                            } catch (Exception e) {
                                throw new WebApplicationException(400);
                            }
                        }
                    }
                }
            

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 5) 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 forList, 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:

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

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:

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

For header and cookie parameters the following:

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

In general @Context can be used to obtain contextual Java types related to the request or response.

Because form parameters (unlike others) are part of the message entity, it is possible to do the following:

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

I.e. you don't need to use the @Context annotation.

Another kind of injection is the @BeanParam which allows to inject the parameters described above into a single bean. A bean annotated with @BeanParam containing any fields and appropriate *param annotation(like @PathParam) will be initialized with corresponding request values in expected way as if these fields were in the resource class. Then instead of injecting request values like path param into a constructor parameters or class fields the @BeanParam can be used to inject such a bean into a resource or resource method. The @BeanParam is used this way to aggregate more request parameters into a single bean.

                public class MyBeanParam {
                    @PathParam("p")
                    private String pathParam;

                    @MatrixParam("m")
                    @Encoded
                    @DefaultValue("default")
                    private String matrixParam;

                    @HeaderParam("header")
                    private String headerParam;

                    private String queryParam;

                    public MyBeanParam(@QueryParam("q") String queryParam) {
                        this.queryParam = queryParam;
                    }

                    public String getPathParam() {
                        return pathParam;
                    }
                    ...
                }
            

                @POST
                public void post(@BeanParam MyBeanParam beanParam, String entity) {
                    final String pathParam = beanParam.getPathParam(); // contains injected path parameter "p"
                    ...
                }
            

The example shows aggregation of injections @PathParam, @QueryParam @MatrixParam and @HeaderParam into one single bean. The rules for injections inside the bean are the same as described above for these injections. The @DefaultValue is used to define the default value for matrix parameter matrixParam. Also the @Encoded annotation has the same behaviour as if it were used for injection in the resource method directly. Injecting the bean parameter into @Singleton resource class fields is not allowed (injections into method parameter must be used instead).

@BeanParam can contain all parameters injections injections (@PathParam, @QueryParam, @MatrixParam, @HeaderParam, @CookieParam, @FormParam). More beans can be injected into one resource or method parameters even if they inject the same request values. For example the following is possible:

                @POST
                public void post(@BeanParam MyBeanParam beanParam, @BeanParam AnotherBean anotherBean, @PathParam("p") pathParam,
                String entity) {
                    // beanParam.getPathParam() == pathParam
                    ...
                }
            

@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:

                    @Singleton
                    @Path("/printers")
                    public class PrintersResource {

                        @GET
                        @Produces({"application/json", "application/xml"})
                        public WebResourceList getMyResources() { ... }

                        @GET @Path("/list")
                        @Produces({"application/json", "application/xml"})
                        public WebResourceList getListOfPrinters() { ... }

                        @GET @Path("/jMakiTable")
                        @Produces("application/json")
                        public PrinterTableModel getTable() { ... }

                        @GET @Path("/jMakiTree")
                        @Produces("application/json")
                        public TreeModel getTree() { ... }

                        @GET @Path("/ids/{printerid}")
                        @Produces({"application/json", "application/xml"})
                        public Printer getPrinter(@PathParam("printerid") String printerId) { ... }

                        @PUT @Path("/ids/{printerid}")
                        @Consumes({"application/json", "application/xml"})
                        public void putPrinter(@PathParam("printerid") String printerId, Printer printer) { ... }

                        @DELETE @Path("/ids/{printerid}")
                        public void deletePrinter(@PathParam("printerid") String printerId) { ... }
                    }
                

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 methodgetListOfPrinters. 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:

                    @Path("/item")
                    public class ItemResource {
                        @Context UriInfo uriInfo;

                        @Path("content")
                        public ItemContentResource getItemContentResource() {
                            return new ItemContentResource();
                        }

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

                    public class ItemContentResource {

                        @GET
                        public Response get() { ... }

                        @PUT
                        @Path("{version}")
                        public void put(@PathParam("version") int version,
                                        @Context HttpHeaders headers,
                                        byte[] in) {
                            ...
                        }
                    }
                

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. A method can be annotated with the @Path annotation with empty path (@Path("/") or @Path("")) which means that the sub resource locator is matched for the path of the enclosing resource (without sub-resource path).

                    @Path("/item")
                    public class ItemResource {

                        @Path("/")
                        public ItemContentResource getItemContentResource() {
                            return new ItemContentResource();
                        }
                    }
                

In the example above the sub-resource locator method getItemContentResource is matched for example for request path "/item/locator" or even for only "/item".

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). So for example the following sub resource locator is valid:

                    @Path("/item")
                    public class ItemResource {

                        @Path("/")
                        public Object getItemContentResource() {
                            return new AnyResource();
                        }
                    }
                

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. If it is required that the runtime manages the sub-resources as standard resources the Class should be returned as shown in the following example:

                    import javax.inject.Singleton;

                    @Path("/item")
                    public class ItemResource {
                        @Path("content")
                        public Class<ItemContentSingletonResource> getItemContentResource() {
                            return ItemContentSingletonResource.class;
                        }
                    }

                        @Singleton
                        public class ItemContentSingletonResource {
                            // this class is managed in the singleton life cycle
                        }
                    }
                

JAX-RS resources are managed in per-request scope by default which means that new resource is created for each request. In this example the javax.inject.Singleton annotation says that the resource will be managed as singleton and not in request scope. The sub-resource locator method returns a class which means that the runtime will managed the resource instance and its life-cycle. If the method would return instance instead, the Singleton annotation would have no effect and the returned instance would be used.

The sub resource locator can also return a programmatic resource model. See resource builder section for information of how the programmatic resource model is constructed. The following example shows very simple resource returned from the sub-resource locator method.

                    import org.glassfish.jersey.server.model.Resource;

                    @Path("/item")
                    public class ItemResource {

                        @Path("content")
                        public Resource getItemContentResource() {
                            return Resource.from(ItemContentSingletonResource.class);
                        }
                    }
                

The code above has exactly the same effect as previous example. Resource is a resource simple resource constructed from ItemContentSingletonResource. More complex programmatic resource can be returned as long they are valid resources.

By default the life-cycle of root resource classes is per-request which, 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.

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:

                    @Path("id: \d+")
                    public class InjectedResource {
                        // Injection onto field
                        @DefaultValue("q") @QueryParam("p")
                        private String p;

                        // Injection onto constructor parameter
                        public InjectedResource(@PathParam("id") int id) { ... }

                        // Injection onto resource method parameter
                        @GET
                        public String get(@Context UriInfo ui) { ... }

                        // Injection onto sub-resource resource method parameter
                        @Path("sub-id")
                        @GET
                        public String get(@PathParam("sub-id") String id) { ... }

                        // Injection onto sub-resource locator method parameter
                        @Path("sub-id")
                        public SubResource getSubResource(@PathParam("sub-id") String id) { ... }

                        // Injection using bean setter method
                        @HeaderParam("X-header")
                        public void setHeader(String header) { ... }
                    }
                

There are some restrictions when injecting on to resource classes with a life-cycle of singleton scope. In such cases the class fields or constructor parameters cannot be injected with request specific parameters. So, for example the following is not allowed.

                    @Path("resource")
                    @Singleton
                    public static class MySingletonResource {

                        @QueryParam("query")
                        String param; // WRONG: initialization of application will fail as you cannot
                                      // inject request specific parameters into a singleton resource.

                        @GET
                        public String get() {
                            return "query param: " + param;
                        }
                    }
                

The example above will cause validation failure during application initialization as singleton resources cannot inject request specific parameters. The same example would fail if the query parameter would be injected into constructor parameter of such a singleton. In other words, if you wish one resource instance to server more requests (in the same time) it cannot be bound to a specific request parameter.

The exception exists for specific request objects which can injected even into constructor or class fields. For these objects the runtime will inject proxies which are able to simultaneously server more request. These request objects are HttpHeaders, Request, UriInfo, SecurityContext. These proxies can be injected using the @Context annotation. The following example shows injection of proxies into the singleton resource class.

                    @Path("resource")
                    @Singleton
                    public static class MySingletonResource {
                        @Context
                        Request request; // this is ok: the proxy of Request will be injected into this singleton

                        public MySingletonResource(@Context SecurityContext securityContext) {
                            // this is ok too: the proxy of SecurityContext will be injected
                        }

                        @GET
                        public String get() {
                            return "query param: " + param;
                        }
                    }
                

To summarize the injection can be done into the following constructs:

The following example shows all possible java constructs into which the values can be injected.

                    @Path("resource")
                    public static class SummaryOfInjectionsResource {
                        @QueryParam("query")
                        String param; // injection into a class field


                        @GET
                        public String get(@QueryParam("query") String methodQueryParam) {
                            // injection into a resource method parameter
                            return "query param: " + param;
                        }

                        @Path("sub-resource-locator")
                        public Class<SubResource> subResourceLocator(@QueryParam("query") String subResourceQueryParam) {
                            // injection into a sub resource locator parameter
                            return SubResource.class;
                        }

                        public SummaryOfInjectionsResource(@QueryParam("query") String constructorQueryParam) {
                            // injection into a constructor parameter
                        }


                        @Context
                        public void setRequest(Request request) {
                            // injection into a setter method
                            System.out.println(request != null);
                        }
                    }

                    public static class SubResource {
                        @GET
                        public String get() {
                            return "sub resource";
                        }
                    }
                

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.

Resources can be constructed from classes or instances but also can be constructed from a programmatic resource model. Every resource created from from resource classes can also be constructed using the programmatic resource builder api. See resource builder section for more information.

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 asbyte[], 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:

@GET
                    @Path("/images/{image}")
                    @Produces("image/*")
                    public Response getImage(@PathParam("image") String image) {
                    File f = new File(image);

                    if (!f.exists()) {
                    throw new WebApplicationException(404);
                    }

                    String mt = new MimetypesFileTypeMap().getContentType(f);
                    return Response.ok(f, mt).build();
                    }
                

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, the most acceptable MIME type is used when multiple output MIME types allowed:

@GET
                @Produces({"application/xml", "application/json"})
                public String doGetAsXmlOrJson() {
                ...
                }
            

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:

@POST
                    @Consumes("application/xml")
                    public Response post(String content) {
                    URI createdUri = ...
                    create(content);
                    return Response.created(createdUri).build();
                    }
                

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

@POST
                    @Consumes("application/xml")
                    public Response post(String content) {
                    URI createdUri = ...
                    String createdContent = create(content);
                    return Response.created(createdUri).entity(createdContent).build();
                    }
                

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

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:

@Path("items/{itemid}/")
                    public Item getItem(@PathParam("itemid") String itemid) {
                    Item i = getItems().get(itemid);
                    if (i == null)
                    throw new NotFoundException("Item, " + itemid + ", is not found");

                    return i;
                    }
                

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:

public class NotFoundException extends WebApplicationException {

                    /**
                    * Create a HTTP 404 (Not Found) exception.
                    */
                    public NotFoundException() {
                    super(Responses.notFound().build());
                    }

                    /**
                    * Create a HTTP 404 (Not Found) exception.
                    * @param message the String that is the entity of the 404 response.
                    */
                    public NotFoundException(String message) {
                    super(Response.status(Responses.NOT_FOUND).
                    entity(message).type("text/plain").build());
                    }

                    }
                

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:

@Provider
                    public class EntityNotFoundMapper implements
                    ExceptionMapper<javax.persistence.EntityNotFoundException> {
                    public Response toResponse(javax.persistence.EntityNotFoundException ex) {
                    return Response.status(404).
                    entity(ex.getMessage()).
                    type("text/plain").
                    build();
                    }
                    }
                

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:

public SparklinesResource(
                    @QueryParam("d") IntegerList data,
                    @DefaultValue("0,100") @QueryParam("limits") Interval limits,
                    @Context Request request,
                    @Context UriInfo ui) {
                    if (data == null)
                    throw new WebApplicationException(400);

                    this.data = data;

                    this.limits = limits;

                    if (!limits.contains(data))
                    throw new WebApplicationException(400);

                    this.tag = computeEntityTag(ui.getRequestUri());
                    if (request.getMethod().equals("GET")) {
                    Response.ResponseBuilder rb = request.evaluatePreconditions(tag);
                    if (rb != null)
                    throw new WebApplicationException(rb.build());
                    }
                    }
                

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.

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:

@Path("/users/")
                    public class UsersResource {

                    @Context UriInfo uriInfo;

                    ...

                    @GET
                    @Produces("application/json")
                    public JSONArray getUsersAsJsonArray() {
                    JSONArray uriArray = new JSONArray();
                    for (UserEntity userEntity : getUsers()) {
                    UriBuilder ub = uriInfo.getAbsolutePathBuilder();
                    URI userUri = ub.
                    path(userEntity.getUserid()).
                    build();
                    uriArray.put(userUri.toASCIIString());
                    }
                    return uriArray;
                    }
                    }
                

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":

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

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:

Form f = new Form();
                    f.add("x", "foo");
                    f.add("y", "bar");

                    Client c = Client.create();
                    WebResource r = c.resource("http://localhost:8080/form");

                    JAXBBean bean = r.
                    type(MediaType.APPLICATION_FORM_URLENCODED_TYPE)
                    .accept(MediaType.APPLICATION_JSON_TYPE)
                    .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 isPOSTed 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 = 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 anotherWebResource. 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 theWebResource. 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 andfilter2, 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 byfilter3, filter2 and filter1 in that order. After the response has been received the response is filtered byfilter1, 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, aClientResponse. The filter modifies the response (if required) by creating a new ClientResponse or modifying the state of the returnedClientResponse. 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 baseWebResource.

A standard approach of developing JAX-RS application is to implement resource classes annotated with @Path with resource methods annotated with HTTP method annotations like @GET or @POST and implement needed functionality. This approach is described in the chapter JAX-RS Application, Resources and Sub-Resources. Besides this standard JAX-RS approach, Jersey offers an API for constructing resources programmatically.

Imagine a situation where a deployed JAX-RS application consists of many resource classes. These resources implement standard HTTP methods like @GET, @POST, @DELETE. In some situations it would be useful to add an @OPTIONS method which would return some kind of meta data about the deployed resource. Ideally, you would want to expose the functionality as an additional feature and you want to decide at the deploy time whether you want to add your custom OPTIONS method. However, when custom OPTIONS method are not enabled you would like to be OPTIONS requests handled in the standard way by JAX-RS runtime. To achieve this you would need to modify the code to add or remove custom OPTIONS methods before deployment. Another way would be to use programmatic API to build resource according to your needs.

Another use case of programmatic resource builder API is when you build any generic RESTful interface which depends on lot of configuration parameters or for example database structure. Your resource classes would need to have different methods, different structure for every new application deploy. You could use more solutions including approaches where your resource classes would be built using Java byte code manipulation. However, this is exactly the case when you can solve the problem cleanly with the programmatic resource builder API. Let's have a closer look at how the API can be utilized.

Jersey Programmatic API was designed to fully support JAX-RS resource model. In other words, every resource that can be designed using standard JAX-RS approach via annotated resource classes can be also modelled using Jersey programmatic API. Let's try to build simple hello world resource using standard approach first and then using the Jersey programmatic resource builder API.

The following example shows standard JAX-RS "Hello world!" resource class.

                    @Path("helloworld")
                    public class HelloWorldResource {

                        @GET
                        @Produces("text/plain")
                        public String getHello() {
                            return "Hello World!";
                        }
                    }
                

This is just a simple resource class with one GET method returning "Hello World!" string that will be serialized as text/plain media type.

Now we will design this simple resource using programmatic API.

                    package org.glassfish.jersey.examples.helloworld;

                    import javax.ws.rs.container.ContainerRequestContext;
                    import javax.ws.rs.core.Application;
                    import javax.ws.rs.core.Response;
                    import org.glassfish.jersey.process.Inflector;
                    import org.glassfish.jersey.server.ResourceConfig;
                    import org.glassfish.jersey.server.model.Resource;
                    import org.glassfish.jersey.server.model.ResourceMethod;


                    public static class MyResourceConfig extends ResourceConfig {

                        public MyResourceConfig() {
                            final Resource.Builder resourceBuilder = Resource.builder();
                            resourceBuilder.path("helloworld");

                            final ResourceMethod.Builder methodBuilder = resourceBuilder.addMethod("GET");
                            final ResourceMethod.Builder methodBuilder = resourceBuilder.addMethod("GET");
                            methodBuilder.produces(MediaType.TEXT_PLAIN_TYPE)
                                    .handledBy(new Inflector<ContainerRequestContext, String>() {

                                @Override
                                public String apply(ContainerRequestContext containerRequestContext) {
                                    return "Hello World!";
                                }
                            });

                            final Resource resource = resourceBuilder.build();
                            registerResources(resource);
                        }
                    }
                

First, focus on the content of the MyResourceConfig constructor in the example. The Jersey programmatic resource model is constructed from Resources that contain ResourceMethods. In the example, a single resource would be constructed from a Resource containing one GET resource method that returns "Hello World!". The main entry point for building programmatic resources in Jersey is the Resource.Builder class. Resource.Builder contains just a few methods like the path method used in the example, which sets the name of the path. Another useful method is a addMethod(String path) which adds a new method to the resource builder and returns a resource method builder for the new method. Resource method builder contains methods which set consumed and produced media type, define name bindings, timeout for asynchronous executions, etc. It is always necessary to define a resource method handler (i.e. he code of the resource method that will return "Hello World!"). There are more options how a resource method can be handled. In the example the implementation of Inflector is used. The Jersey Inflector interface defines a simple contract for transformation of a request into a response. An inflector can either return a Response or directly an entity object, the way it is shown in the example. Another option is to setup a Java method handler using handledBy(Class<?> handlerClass, Method method) and pass it the chosen java.lang.reflect.Method instance together with the enclosing class.

A resource method model construction can be explicitly completed by invoking build() on the resource method builder. It is however not necessary to do so as the new resource method model will be built automatically once the parent resource is built. Once a resource model is built, it is registered into the resource config at the last line of the MyResourceConfig constructor in the example.

                        ...
                        <servlet>
                            <servlet-name>org.glassfish.jersey.examples.helloworld.MyApplication</servlet-name>
                            <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
                            <init-param>
                                <param-name>javax.ws.rs.Application</param-name>
                                <param-value>org.glassfish.jersey.examples.helloworld.MyResourceConfig</param-value>
                            </init-param>
                            <load-on-startup>1</load-on-startup>
                        </servlet>
                        <servlet-mapping>
                            <servlet-name>org.glassfish.jersey.examples.helloworld.MyApplication</servlet-name>
                            <url-pattern>/*</url-pattern>
                        </servlet-mapping>
                        ...
                    

                    final Resource.Builder resourceBuilder = Resource.builder(HelloWorldResource.class);
                    resourceBuilder.addMethod("OPTIONS")
                        .handledBy(new Inflector<ContainerRequestContext, Response>() {
                            @Override
                            public Response apply(ContainerRequestContext containerRequestContext) {
                                return Response.ok("This is a response to an OPTIONS method.").build();
                            }
                        });
                    final Resource resource = resourceBuilder.build();
                

In the example above the Resource is built from a HelloWorldResource resource class. The resource model built this way contains a GET method producing 'text/plain' responses with "Hello World!" entity. This is quite important as it allows you to whatever Resource objects based on introspecting existing JAX-RS resources and use builder API to enhance such these standard resources. In the example we used already implemented HelloWorldResource resource class and enhanced it by OPTIONS method. The OPTIONS method is handled by an Inflector which returns Response.

The following sample shows how to define sub-resource methods (methods that contains sub-path).

                    final Resource.Builder resourceBuilder = Resource.builder("helloworld");

                    final Resource.Builder childResource = resourceBuilder.addChildResource("subresource");
                    childResource.addMethod("GET").handledBy(new GetInflector());

                    final Resource resource = resourceBuilder.build();
                

Sub-resource methods are defined using so called child resource models. Child resource models (or child resources) are programmatic resources build in the same way as any other programmatic resource but they are registered as a child resource of a parent resource. The child resource in the example is build directly from the parent builder using method addChildResource(String path). However, there is also an option to build a child resource model separately as a standard resource and then add it as a child resource to a selected parent resource. This means that child resource objects can be reused to define child resources in different parent resources (you just build a single child resource and then register it in multiple parent resources). Each child resource groups methods with the same sub-resource path. Note that a child resource cannot have any child resources as there is nothing like sub-sub-resource method concept in JAX-RS. For example if a sub resource method contains more path segments in its path (e.g. "/root/sub/resource/method" where "root" is a path of the resource and "sub/resource/method" is the sub resource method path) then parent resource will have path "root" and child resource will have path "sub/resource/method" (so, there will not be any separate nested sub-resources for "sub", "resource" and "method").

See the javadocs of the resource builder API for more information.

Jersey gives you an option to register so called model processor providers. These providers are able to modify or enhance the application resource model during application deployment. This is an advanced feature and will not be needed in most use cases. However, imagine you would like to add OPTIONS resource method to each deployed resource as it is described at the top of this chapter. You would want to do it for every programmatic resource that is registered as well as for all standard JAX-RS resources.

To do that, you first need to register a model processor provider in your application, which implements org.glassfish.jersey.server.model.ModelProcessor extension contract. An example of a model processor implementation is shown here:

                    import javax.ws.rs.GET;
                    import javax.ws.rs.Path;
                    import javax.ws.rs.Produces;
                    import javax.ws.rs.container.ContainerRequestContext;
                    import javax.ws.rs.core.Application;
                    import javax.ws.rs.core.Configuration;
                    import javax.ws.rs.core.MediaType;
                    import javax.ws.rs.core.Response;
                    import javax.ws.rs.ext.Provider;

                    import org.glassfish.jersey.process.Inflector;
                    import org.glassfish.jersey.server.model.ModelProcessor;
                    import org.glassfish.jersey.server.model.Resource;
                    import org.glassfish.jersey.server.model.ResourceMethod;
                    import org.glassfish.jersey.server.model.ResourceModel;

                    @Provider
                    public static class MyOptionsModelProcessor implements ModelProcessor {

                        @Override
                        public ResourceModel processResourceModel(ResourceModel resourceModel, Configuration configuration) {
                            // we get the resource model and we want to enhance each resource by OPTIONS method
                            ResourceModel.Builder newResourceModelBuilder = new ResourceModel.Builder(false);
                            for (final Resource resource : resourceModel.getResources()) {
                                // for each resource in the resource model we create a new builder which is based on the old resource
                                final Resource.Builder resourceBuilder = Resource.builder(resource);

                                // we add a new OPTIONS method to each resource
                                // note that we should check whether the method does not yet exist to avoid failures
                                resourceBuilder.addMethod("OPTIONS")
                                    .handledBy(new Inflector<ContainerRequestContext, String>() {
                                        @Override
                                        public String apply(ContainerRequestContext containerRequestContext) {
                                            return "On this path the resource with " + resource.getResourceMethods().size()
                                                + " methods is deployed.";
                                        }
                                        }).produces(MediaType.TEXT_PLAIN);

                                // we add to the model new resource which is a combination of the old resource enhanced
                                // by the OPTIONS method
                                newResourceModelBuilder.addResource(resourceBuilder.build());
                            }

                            final ResourceModel newResourceModel = newResourceModelBuilder.build();
                            // and we return new model
                            return newResourceModel;
                        };

                        @Override
                        public ResourceModel processSubResource(ResourceModel subResourceModel, Configuration configuration) {
                            // we just return the original subResourceModel which means we do not want to do any modification
                            return subResourceModel;
                        }
                    }
                

The MyOptionsModelProcessor from the example is a relatively simple model processor which iterates over all registered resources and for all of them builds a new resource that is equal to the old resource except it is enhanced with a new OPTIONS method.

Note that you only need to register such a ModelProcessor as your custom extension provider in the same way as you would register any standard JAX-RS extension provider. During an application deployment, Jersey will look for any registered model processor and execute them. As you can seem, model processors are very powerful as they can do whatever manipulation with the resource model they like. A model processor can even, for example, completely ignore the old resource model and return a new custom resource model with a single "Hello world!" resource, which would result in only the "Hello world!" resource being deployed in your application. Of course, it would not not make much sense to implement such model processor, but the scenario demonstrates how powerful the model processor concept is. A better, real-life use case scenario would, for example, be to always add some custom new resource to each application that might return additional metadata about the deployed application. Or, you might want to filter out particular resources or resource methods, which is another situation where a model processor could be used successfully.

Also mote that processSubResource(ResourceModel subResourceModel, Configuration configuration) method is executed for each sub resource returned from the sub resource locator. The example is simplified and does not do any manipulation but probably in such a case you would want to enhance all sub resources with a new OPTIONS method handlers too.

It is important to remember that any model processor must always return valid resource model. As you might have already noticed, in the example above this important rule is not followed. If any of the resources in the original resource model would already have an OPTIONS method handler defined, adding another handler would cause the application fail during the deployment in the resource model validation phase. In order to pertain the consistency of the final model, a model processor implementation would have to be more robust than what is shown in the example.

Jersey source code is available in a Git repository you can browse at http://java.net/projects/jersey/sources/code/show.

In case you are not familiar with Git, we recommend reading on of the many "Getting Started with Git" articles you can find on the web. For example this DZone RefCard.

Before you can clone Jersey repository you have to sign up for a java.net account. Once you are registered, you have to add an SSH key to your java.net profile - see this article on how to do that: http://java.net/projects/help/pages/ProfileSettings#SSH_Keys_Tab

To clone the Jersey repository you can execute the following command on the command-line (provided you have a command-line Git client installed on your machine):

git clone ssh://<your_java_net_id>@java.net/jersey~code

Milestones and releases of Jersey are tagged. You can list the tags by executing the standard Git command in the repository directory:

git tag -l

Jersey source code requires Java SE 6 or greater. The build is based on Maven. Maven 3 or greater is recommended. Also it is recommended you use the following Maven options when building the workspace (can be set in MAVENT_OPTS environment variable):

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

It is recommended to build all of Jersey after you cloned the source code repository. To do that execute the following commands in the directory where jersey source repository was cloned (typically the directory named "jersey~code"):

mvn -Dmaven.test.skip=true clean install

This command will build Jersey, but skip the test execution. If you don't want to skip the tests, execute the following instead:

mvn clean install

Building the whole Jersey project including tests could take significant amount of time.

Jersey contains many tests. Unit tests are in the individual Jersey modules, integration and end-to-end tests are in jersey~code/tests directory. You can run tests related to a particular area using the following command:

mvn -Dtest=<pattern> test

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

NetBeans IDE has excellent maven support. The Jersey maven modules can be loaded, built and tested in NetBeans without any additional NetBeans-specific project files.

Jersey 1.x contains number of proprietary server APIs. This section covers migration of application code relying on those APIs.

ResourceConfig resourceConfig = new DefaultResourceConfig();
                    resourceConfig.getSingletons().add(
                    new SingletonTypeInjectableProvider<Context, SingletonType>(
                    SingletonType.class, new SingletonType()) {});
                

ResourceConfig resourceConfig = new DefaultResourceConfig();
                    resourceConfig.getSingletons().add(
                    new PerRequestTypeInjectableProvider<Context, PerRequestType>() {
                    @Override
                    public Injectable<PerRequestType> getInjectable(ComponentContext ic, Context context) {
                    //...
                    }
                    });
                

public static class MyBinder extends AbstractBinder {

                    @Override
                    protected void configure() {
                    // request scope binding
                    bind(MyInjectablePerRequest.class).to(MyInjectablePerRequest.class).in(RequestScope.class);
                    // singleton binding
                    bind(MyInjectableSingleton.class).in(Singleton.class);
                    // singleton instance binding
                    bind(new MyInjectableSingleton()).to(MyInjectableSingleton.class);
                    }

                    }

                    // register module to ResourceConfig (can be done also in constructor)
                    ResourceConfig rc = new ResourceConfig();
                    rc.addClasses(/* ... */);
                    rc.addBinders(new MyBinder());
                

public static class MyApplication extends Application {

                    @Inject
                    public MyApplication(ServiceLocator serviceLocator) {
                    System.out.println("Registering injectables...");

                    DynamicConfiguration dc = Injections.getConfiguration(serviceLocator);

                    // request scope binding
                    Injections.addBinding(
                    Injections.newBinder(MyInjectablePerRequest.class).to(MyInjectablePerRequest.class).in(RequestScoped.class),
                    dc);

                    // singleton binding
                    Injections.addBinding(
                    Injections.newBinder(MyInjectableSingleton.class).to(MyInjectableSingleton.class).in(Singleton.class),
                    dc);

                    // singleton instance binding
                    Injections.addBinding(
                    Injections.newBinder(new MyInjectableSingleton()).to(MyInjectableSingleton.class),
                    dc);

                    // request scope binding with specified custom annotation
                    Injections.addBinding(
                    Injections.newBinder(MyInjectablePerRequest.class).to(MyInjectablePerRequest.class)
                    .qualifiedBy(new MyAnnotationImpl())
                    .in(RequestScoped.class),
                    dc);

                    // commits changes
                    dc.commit();
                    }

                    @Override
                    public Set<Class<?>> getClasses() {
                    return ...
                    }
                    }
                

public class Reloader implements ContainerNotifier {
                        List<ContainerListener> ls;

                        public Reloader() {
                        ls = new ArrayList<ContainerListener>();
                        }

                        public void addListener(ContainerListener l) {
                        ls.add(l);
                        }

                        public void reload() {
                        for (ContainerListener l : ls) {
                        l.onReload();
                        }
                        }
                        }
                    

Reloader reloader = new Reloader();
                        resourceConfig.getProperties().put(ResourceConfig.PROPERTY_CONTAINER_NOTIFIER, reloader);
                    

public class Reloader implements ContainerLifecycleListener {

                        Container container;

                        public void reload(ResourceConfig newConfig) {
                        container.reload(newConfig);
                        }

                        public void reload() {
                        container.reload();
                        }

                        @Override
                        public void onStartup(Container container) {
                        this.container = container;
                        }

                        @Override
                        public void onReload(Container container) {
                        // ignore or do whatever you want after reload has been done
                        }

                        @Override
                        public void onShutdown(Container container) {
                        // ignore or do something after the container has been shutdown
                        }
                        }
                    

Reloader reloader = new Reloader();
                        resourceConfig.addSingletons(reloader);
                    

JAX-RS 2.0 provides functionality that is equivalent to the Jersey 1.x proprietary client API. Here is a rough mapping between the Jersey 1.x and JAX-RS 2.0 Client API classes:

The following sub-sections show code examples.

Client client = Client.create();
                    WebResource webResource = client.resource(restURL).path("myresource/{param}");
                    String result = webResource.pathParam("param", "value").get(String.class);
                

Client client = ClientFactory.newClient();
                    WebTarget target = client.target(restURL).path("myresource/{param}");
                    String result = target.pathParam("param", "value").get(String.class);
                

Client client = Client.create();
                    WebResource webResource = client.resource(restURL);
                    webResource.addFilter(new HTTPBasicAuthFilter(username, password));
                

Client client = ClientFactory.newClient();
                    WebTarget target = client.target(restURL);
                    target.configuration().register(new HttpBasicAuthFilter(username, password));
                

Client client = Client.create();
                    WebResource webResource = client.resource(restURL).accept("text/plain");
                    ClientResponse response = webResource.get(ClientResponse.class);
                

Client client = ClientFactory.newClient();
                    WebTarget target = client.target(restURL);
                    Response response = target.request("text/plain").get(Response.class);
                

Client client = Client.create();
                    WebResource webResource = client.resource(restURL);
                    ClientResponse response = webResource.post(ClientResponse.class, "payload");
                

Client client = ClientFactory.newClient();
                    WebTarget target = client.target(restURL);
                    Response response = target.request().post(Entity.text("payload"), Response.class);
                

HTTPSProperties prop = new HTTPSProperties(hostnameVerifier, sslContext);
                    DefaultClientConfig dcc = new DefaultClientConfig();
                    dcc.getProperties().put(HTTPSProperties.PROPERTY_HTTPS_PROPERTIES, prop);
                    Client client = Client.create(dcc);
                

Client client = ClientFactory.newClient();
                    client.configuration().setProperty(ClientProperties.SSL_CONTEXT, sslContext);
                    client.configuration().setProperty(ClientProperties.HOSTNAME_VERIFIER, hostnameVerifier);