Marc Hadley's Blog

New Jersey Features

I recently merged the experimental "resourcefactory" branch back into the main Jersey trunk. The new code includes the following features and changes:

• A change to the default resource object lifecyle from singleton to per-request
• Support for non-empty resource class constructors
• A new SPI for plugging-in new resource providers

Details on these changes below

Lifecycle Changes

Prior to the merge the Jersey runtime would create a single instance of a resource class and use that for all requests. Resource classes had to be re-entrant and thread safe. Following the merge the default scope for a resource object is per-request, i.e. the Jersey runtime creates a new instance of a resource class for each request. This change brings Jersey back in line with the current JSR 311 specification which requires a default per-request life-cycle. The old behavior can be recovered by annotating a resource class with the Singleton annotation from the com.sun.ws.rest.spi.resource package. If you want to be explicit about a resource classes life-cycle rather than rely on the default you can also use the PerRequest annotation from the same package. More on how these annotations work in the description of the new SPI below.

Non-empty Constructors

Prior to the merge a resource class was required to have a zero argument constructor that the Jersey runtime would use when creating the singleton instance. Following the merge this requirement has been relaxed such that constructors can now have arguments. This in conjunction with the change to a default per-request lifecycle allows a more natural use of constructors to perform instance initialization, e.g.:

@UriTemplate("entries/{id}")
public class Entry {
  
  EntryEntity entity;

  public Entry(@UriParam("id") String id) {
    entity = findEntryEntity(id);
    ...
  }

  @HttpMethod
  @ProduceMime({"application/json", "application/xml"})
  public EntryEntity getEntity() {
    return entity;
  }
}

The arguments allowed in a resource class constructor depends on the resource provider used to create an instance of the resource class (see the description of the new SPI below). For default per-request resource classes you can use any combination of parameters annotated with UriParam, UriParam, QueryParam, MatrixParam, HeaderParam or HttpContext. Singleton resource classes must still have a zero argument constructor.

Resource Provider SPI

The new resource provider SPI allows plugging-in of custom resource class factories and is used internally to support the per-request and singleton life-cycles. If you're not planning to develop a new resource provider you can safely stop reading here unless of course you are curious as to how the above features are implemented.

A resource provider is responsible for creating instances of resource classes for the Jersey runtime to use. A resource provider implements ResourceProvider and must have a zero-argument constructor. The Jersey runtime will create a new instance of a resource provider for each resource class that uses that provider so there is no need for a provider to maintain a list or map of resource classes and instances thereof.

The Jersey runtime identifies the resource provider to use for a particular resource class by examining the annotations on that resource class. It examines each class-level annotation in turn looking for a ResourceFactory meta-annotation and then uses the value of that annotation or the default per-request provider if none is found as the resource provider. This approach allows you to define new annotations that point to a particular resource provider, e.g. Jersey defines the Singleton annotation as follows:

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ResourceFactory(SingletonProvider.class)
public @interface Singleton {}

Note the ResourceFactory meta-annotation which points to SingletonProvider, the Jersey-supplied resource provider for singleton resource classes.

The getInstance method of ResourceProvider supplies a ResourceProviderContext that a resource provider can use to obtain values for the resource class constructor's arguments and perform dependency injection on a newly created resource class instance, PerRequestProvider shows an example of its use. A resource provider is expected to supply values for constructor arguments unknown to Jersey (anything not annotated with UriParam, UriParam, QueryParam, MatrixParam, HeaderParam or HttpContext) and inject additional dependencies as required.

Its hoped that this SPI will support integration of Jersey with a variety of frameworks. Let us know if anything is unclear or needs improvement.

Comments

This work is licensed under a Creative Commons License.