Jakarta RESTful Web Services

This is the final release of version 2.1. The issue tracking system for this release can be found at:

https://github.com/jax-rs/api/issues

The corresponding Javadocs can be found online at:

https://jax-rs.github.io/apidocs/2.1

The reference implementation can be obtained from:

https://jersey.github.io

The expert group seeks feedback from the community on any aspect of this specification, please send comments to:

jaxrs-spec@javaee.groups.io

The following are the goals of the API:

The following are non-goals:

The keywords `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', `RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in RFC 2119[10].

Java code and sample data fragments are formatted as shown in figure [1.1]:

URIs of the general form `http://example.org/…​' and `http://example.com/…​' represent application or context-dependent URIs.

All parts of this specification are normative, with the exception of examples, notes and sections explicitly marked as `Non-Normative'. Non-normative notes are formatted as shown below.

Note: This is a note.

This specification is being developed as part of JSR 370 under the Java Community Process. It is the result of the collaborative work of the members of the JSR 370 Expert Group. The following are the present expert group members:

 — Sergey Beryozkin (Talend SA)

 — Adam Bien (Individual Member)

 — Sebastian Dashner (Individual Member)

 — Markus Karg (Individual Member)

 — Casey Lee (Vision Service Plan)

 — Marcos Luna (Individual Member)

 — Andy McCright (IBM)

 — Julian Reschke (Individual Member)

 — Alessio Soldano (Red Hat)

The following are former group members of the JSR 339 Expert Group:

 — Jan Algermussen (Individual Member)

 — Florent Beniot (OW2)

 — Sergey Beryozkin (Talend SA)

 — Adam Bien (Individual Member)

 — Bill Burke (Red Hat)

 — Clinton L. Combs (Individual Member)

 — Jian Wu Dai (IBM)

 — Bill De Hora (Individual Member)

 — Markus Karg (Individual Member)

 — Sastry Malladi (eBay, Inc)

 — Julian Reschke (Individual Member)

 — Guilherme de Azevedo Silveira (Individual Member)

 — Synodinos, Dionysios G. (Individual Member)

JAX-RS 1.X has been developed as part of JSR 311 under the Java Community Process. The following were group members of the JSR 311 Expert Group:

 — Heiko Braun (Red Hat Middleware LLC)

 — Larry Cable (BEA Systems)

 — Roy Fielding (Day Software, Inc.)

 — Harpreet Geekee (Nortel)

 — Nickolas Grabovas (Individual Member)

 — Mark Hansen (Individual Member)

 — John Harby (Individual Member)

 — Hao He (Individual Member)

 — Ryan Heaton (Individual Member)

 — David Hensley (Individual Member)

 — Stephan Koops (Individual Member)

 — Changshin Lee (NCsoft Corporation)

 — Francois Leygues (Alcatel-Lucent)

 — Jerome Louvel (Individual Member)

 — Hamid Ben Malek (Fujitsu Limited)

 — Ryan J. McDonough (Individual Member)

 — Felix Meschberger (Day Software, Inc.)

 — David Orchard (BEA Systems)

 — Dhanji R. Prasanna (Individual Member)

 — Julian Reschke (Individual Member)

 — Jan Schulz-Hofen (Individual Member)

 — Joel Smith (IBM)

 — Stefan Tilkov (innoQ Deutschland GmbH)

During the course of this JSR we received great contributions and suggestions from many individuals. Special thanks to Marek Potociar and Michal Gajdos. Also Gunnar Morling, Ondrej Mihalyi, Arjan Tijms, Guillermo Gonzales de Aguero, Christian Kaltepoth and many, many others. Last but not least to the JSR 370 Expert Group for all their contributions.

During the course of JSR 339 we received many excellent suggestions. Special thanks to Martin Matula, Gerard Davison, Jakub Podlesak and Pavel Bucek from Oracle as well as Pete Muir and Emmanuel Bernard from Red Hat. Also to Gunnar Morling and Ron Sigal (Red Hat) for their suggestions on how to improve resource validation, and to Mattias Arthursson for his insights on hypermedia.

During the course of JSR 311 we received many excellent suggestions on the JSR and Jersey (RI) mailing lists, thanks in particular to James Manger (Telstra) and Reto Bachmann-Gmür (Trialox) for their contributions. The following individuals (all Sun Microsystems at the time) have also made invaluable technical contributions: Roberto Chinnici, Dianne Jiao (TCK), Ron Monzillo, Rajiv Mordani, Eduardo Pelegri-Llopart, Jakub Podlesak (RI) and Bill Shannon.

The GenericEntity class was inspired by the Google Guice TypeLiteral class. Our thanks to Bob Lee and Google for donating this class to JAX-RS.

The resources and providers that make up a JAX-RS application are configured via an application-supplied subclass of Application. An implementation MAY provide alternate mechanisms for locating resource classes and providers (e.g. runtime class scanning) but use of Application is the only portable means of configuration.

Specific application requirements are detailed throughout this specification and the JAX-RS Javadocs. Implementations MAY perform verification steps that go beyond what it is stated in this document.

A JAX-RS implementation MAY report an error condition if it detects that two or more resources could result in an ambiguity during the execution of the algorithm described Request Matching. For example, if two resource methods in the same resource class have identical (or even intersecting) values in all the annotations that are relevant to the algorithm described in that section. The exact set of verification steps as well as the error reporting mechanism is implementation dependent.

Applications are published in different ways depending on whether the application is run in a Java SE environment or within a container. This section describes the alternate means of publication.

A resource class is a Java class that uses JAX-RS annotations to implement a corresponding Web resource. Resource classes are POJOs that have at least one method annotated with @Path or a request method designator.

When a resource class is instantiated, the values of fields and bean properties annotated with one the following annotations are set according to the semantics of the annotation:

Because injection occurs at object creation time, use of these annotations (with the exception of @Context) on resource class fields and bean properties is only supported for the default per-request resource class lifecycle. An implementation SHOULD warn if resource classes with other lifecycles use these annotations on resource class fields or bean properties.

A JAX-RS implementation is only required to set the annotated field and bean property values of instances created by its runtime. Objects returned by sub-resource locators (see Sub Resources) are expected to be initialized by their creator.

Valid parameter types for each of the above annotations are listed in the corresponding Javadoc, however in general (excluding @Context) the following types are supported:

The DefaultValue annotation may be used to supply a default value for some of the above, see the Javadoc for DefaultValue for usage details and rules for generating a value in the absence of this annotation and the requested data. The Encoded annotation may be used to disable automatic URI decoding for @MatrixParam, @QueryParam, and @PathParam annotated fields and properties.

A WebApplicationException thrown during construction of field or property values using any of the 5 steps listed above is processed directly as described in Exceptions. Other exceptions thrown during construction of field or property values using any of the 5 steps listed above are treated as client errors: if the field or property is annotated with @MatrixParam, @QueryParam or @PathParam then an implementation MUST generate an instance of NotFoundException (404 status) that wraps the thrown exception and no entity; if the field or property is annotated with @HeaderParam or @CookieParam then an implementation MUST generate an instance of BadRequestException (400 status) that wraps the thrown exception and no entity. Exceptions MUST be processed as described in Exceptions.

Resource methods are methods of a resource class annotated with a request method designator. They are used to handle requests and MUST conform to certain restrictions described in this section.

A request method designator is a runtime annotation that is annotated with the @HttpMethod annotation. JAX-RS defines a set of request method designators for the common HTTP methods: @GET, @POST, @PUT, @DELETE, @PATCH, @HEAD and @OPTIONS. Users may define their own custom request method designators including alternate designators for the common HTTP methods.

A root resource class is anchored in URI space using the @Path annotation. The value of the annotation is a relative URI path template whose base URI is provided by the combination of the deployment context and the application path (see the @ApplicationPath annotation).

A URI path template is a string with zero or more embedded parameters that, when values are substituted for all the parameters, is a valid URI[5] path. The Javadoc for the @Path annotation describes their syntax. E.g.:

In the above example the Widget resource class is identified by the relative URI path widgets/xxx where xxx is the value of the id parameter.

Note: Because \{and } are not part of either the reserved or unreserved productions of URI[5] they will not appear in a valid URI.

The value of the annotation is automatically encoded, e.g. the following two lines are equivalent:

Template parameters can optionally specify the regular expression used to match their values. The default value matches any text and terminates at the end of a path segment but other values can be used to alter this behavior, e.g.:

In the above example the Widget resource class will be matched for any request whose path starts with widgets and contains at least one more path segment; the value of the path parameter will be the request path following widgets. E.g. given the request path widgets/small/a the value of path would be small/a.

The value of a URI path parameter is available for injection via @PathParam on a field, property or method parameter. Note that if a URI template is used on a method, a path parameter injected in a field or property may not be available (set to null). The following example illustrates this scenario:

Application classes can declare the supported request and response media types using the @Consumes and @Produces annotations respectively. These annotations MAY be applied to a resource method, a resource class, or to an entity provider (see Declaring Media Type Capabilities). Use of these annotations on a resource method overrides any on the resource class or on an entity provider for a method argument or return type. In the absence of either of these annotations, support for any media type (/*) is assumed.

The following example illustrates the use of these annotations:

In the above:

An implementation MUST NOT invoke a method whose effective value of @Produces does not match the request Accept header. An implementation MUST NOT invoke a method whose effective value of @Consumes does not match the request Content-Type header.

When accepting multiple media types, clients may indicate preferences by using a relative quality factor known as the q parameter. The value of the q parameter, or q-value, is used to sort the set of accepted types. For example, a client may indicate preference for application/widgets+xml with a relative quality factor of 1 and for application/xml with a relative quality factor of 0.8. Q-values range from 0 (undesirable) to 1 (highly desirable), with 1 used as default when omitted. A GET request matched to the WidgetsResource class with an accept header of text/html; q=1, application/widgets+xml; q=0.8 will result in a call to method getAsHtml instead of getAsXML based on the value of q.

A server can also indicate media type preference using the qs parameter; server preference is only examined when multiple media types are accepted by a client with the same q-value. Consider the following example:

Suppose a client issues a GET request with an accept header of application/*; q=0.5, text/html. Based on this request, the server determines that both application/xml and application/json are equally preferred by the client with a q-value of 0.5. By specifying a server relative quality factor as part of the @Produces annotation, it is possible to control which response media type to select:

With the updated value for @Produces in this example, and in response to a GET request with an accept header that includes application/*; q=0.5, JAX-RS implementations are REQUIRED to select the media type application/xml given its higher qs-value. Note that qs-values, just like q-values, are relative and as such are only comparable to other qs-values within the same @Produces annotation instance. For more information see Determining the MediaType of Responses.

JAX-RS annotations may be used on the methods and method parameters of a super-class or an implemented interface. Such annotations are inherited by a corresponding sub-class or implementation class method provided that the method and its parameters do not have any JAX-RS annotations of their own. Annotations on a super-class take precedence over those on an implemented interface. The precedence over conflicting annotations defined in multiple implemented interfaces is implementation specific. Note that inheritance of class or interface annotations is not supported.

If a subclass or implementation method has any JAX-RS annotations then all of the annotations on the superclass or interface method are ignored. E.g.:

In the above, ActivityLog.getFeed inherits the @GET and @Produces annotations from the interface. Conversely:

In the above, the @GET annotation on ReadOnlyAtomFeed.getFeed is not inherited by Activity-Log.getFeed and it would require its own request method designator since it redefines the @Produces annotation.

For consistency with other Jakarta EE specifications, it is recommended to always repeat annotations instead of relying on annotation inheritance.

This section describes how a request is matched to a resource class and method. Implementations are not required to use the algorithm as written but MUST produce results equivalent to those produced by the algorithm.

In many cases it is not possible to statically determine the media type of a response. The following algorithm is used to determine the response media type, \(M_{\mbox{selected}}\), at run time:

Note that the above renders a response with a default media type of application/octet-stream when a concrete type cannot be determined. It is RECOMMENDED that MessageBodyWriter implementations specify at least one concrete type via @Produces.

By default a single instance of each provider class is instantiated for each JAX-RS application. First the constructor (see Constructors) is called, then any requested dependencies are injected (see Chapter Context), then the appropriate provider methods may be called multiple times (simultaneously), and finally the object is made available for garbage collection. Providers describes how a provider obtains access to other providers via dependency injection.

An implementation MAY offer other provider lifecycles, mechanisms for specifying these are outside the scope of this specification. E.g. an implementation based on an inversion-of-control framework may support all of the lifecycle options provided by that framework.

Entity providers supply mapping services between representations and their associated Java types. Entity providers come in two flavors: MessageBodyReader and MessageBodyWriter described below.

Context providers supply context to resource classes and other providers. A context provider class implements the ContextResolver<T> interface and may be annotated with @Provider for automatic discovery. E.g., an application wishing to provide a customized JAXBContext to the default JAXB entity providers would supply a class implementing ContextResolver<JAXBContext>.

Context providers MAY return null from the getContext method if they do not wish to provide their context for a particular Java type. E.g. a JAXB context provider may wish to only provide the context for certain JAXB classes. Context providers MAY also manage multiple contexts of the same type keyed to different Java types.

Exception mapping providers map a checked or runtime exception to an instance of Response. An exception mapping provider implements the ExceptionMapper<T> interface and may be annotated with @Provider for automatic discovery.

When a resource class or provider method throws an exception for which there is an exception mapping provider, the matching provider is used to obtain a Response instance. The resulting Response is processed as if a web resource method had returned the Response, see Return Type. In particular, a mapped Response MUST be processed using the ContainerResponse filter chain defined in Chapter Filters and Interceptors.

When choosing an exception mapping provider to map an exception, an implementation MUST use the provider whose generic type is the nearest superclass of the exception. If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Priorities.

To avoid a potentially infinite loop, a single exception mapper must be used during the processing of a request and its corresponding response. JAX-RS implementations MUST NOT attempt to map exceptions thrown while processing a response previously mapped from an exception. Instead, this exception MUST be processed as described in steps 3 and 4 in Exceptions.

Note that exception mapping providers are not supported as part of the Client API.

Exception handling differs depending on whether a provider is part of the client runtime or server runtime. This is covered in the next two sections.

An instance of Client is required to access a Web resource using the Client API. The default instance of Client can be obtained by calling newClient on ClientBuilder. Client instances can be configured using methods inherited from Configurable as follows:

See Chapter Providers for more information on providers. Properties are simply name-value pairs where the value is an arbitrary object. Features are also providers and must implement the Feature interface; they are useful for grouping sets of properties and providers (including other features) that are logically related and must be enabled as a unit.

A Web resource can be accessed using a fluent API in which method invocations are chained to build and ultimately submit an HTTP request. The following example gets a text/plain representation of the resource identified by http://example.org/hello:

Conceptually, the steps required to submit a request are the following: (i) obtain an instance of Client (ii) create a WebTarget (iii) create a request from the WebTarget and (iv) submit a request or get a prepared Invocation for later submission. See Section [invocations] for more information on using Invocation.

Method chaining is not limited to the example shown above. A request can be further specified by setting headers, cookies, query parameters, etc. For example:

See the Javadoc for the classes in the javax.ws.rs.client package for more information.

The benefits of using a WebTarget become apparent when building complex URIs, for example by extending base URIs with additional path segments or templates. The following example highlights these cases:

Note the use of the URI template parameter {whom}. The example above gets a representation for the resource identified by http://example.org/hello/world.

WebTarget instances are immutable with respect to their URI (or URI template): methods for specifying additional path segments and parameters return a new instance of WebTarget. However, WebTarget instances are mutable with respect to their configuration. Thus, configuring a WebTarget does not create new instances.

In this example, two instances of WebTarget are created. The instance hello inherits the configuration from base and it is further configured by registering MyProvider.class. Note that changes to hello’s configuration do not affect base, i.e. inheritance performs a deep copy of the configuration. See Section [configurable_types] for additional information on configurable types.

The response to a request is not limited to be of type Response. The following example upgrades the status of customer number 123 to "gold status" by first obtaining an entity of type Customer and then posting that entity to a different URI:

Note the use of the variant xml() in the call to post. The class javax.ws.rs.client.Entity defines variants for the most popular media types used in JAX-RS applications.

In the example above, just like in the Server API, JAX-RS implementations are REQUIRED to use entity providers to map a representation of type application/xml to an instance of Customer and vice versa. See Standard Entity Providers for a list of entity providers that MUST be supported by all JAX-RS implementations.

An invocation is a request that has been prepared and is ready for execution. Invocations provide a generic interface that enables a separation of concerns between the creator and the submitter. In particular, the submitter does not need to know how the invocation was prepared, but only how it should be executed: namely, synchronously or asynchronously.

Let us consider the following example ^[11]:

Collections.transform(invs, new F<Invocation, Response>() @Override public Response apply(Invocation inv) return inv.invoke(); );

In this example, two invocations are prepared and stored in a collection by the creator. The submitter then traverses the collection applying a transformation that maps an Invocation to a Response. The mapping calls Invocation.invoke to execute the invocation synchronously; asynchronous execution is also supported by calling Invocation.submit. Refer to Chapter Asynchronous Processing for more information on asynchronous invocations.

The following Client API types are configurable: Client, ClientBuilder, and WebTarget. Configuration methods are inherited from the Configurable interface implemented by all these classes. This interface supports configuration of:

The configuration defined on an instance of any of the aforementioned types is inherited by other instances created from it. For example, an instance of WebTarget created from a Client will inherit the Client’s configuration. However, any additional changes to the instance of WebTarget will not impact the Client’s configuration and vice versa. Therefore, once a configuration is inherited it is also detached (deep copied) from its parent configuration and changes to the parent and child configurations are not be visible to each other.

Client API introduces asynchronous programming in the Client API. Asynchronous programming in JAX-RS enables clients to unblock certain threads by pushing work to background threads which can be monitored and possibly waited on (joined) at a later time. This can be accomplished in JAX-RS by either providing an instance of InvocationCallback or operating on the result of type Future<T> returned by an asynchronous invoker —or some combination of both styles.

Using InvocationCallback enables a more reactive programming style in which user-provided code activates (or reacts) only when a certain event has occurred. Using callbacks works well for simple cases, but the source code becomes harder to understand when multiple events are in play. For example, when asynchronous invocations need to be composed, combined or in any way operated upon. These type of scenarios may result in callbacks that are nested inside other callbacks making the code far less readable —often referred to as the pyramid of doom because of the inherent nesting of calls.

To address the requirement of greater readability and to enable programmers to better reason about asynchronous computations, Java 8 introduces the a new interface called CompletionStage that includes a large number of methods dedicated to managing asynchronous computations.

JAX-RS 2.1 defines a new type of invoker called RxInvoker, as well a default implementation of this type called CompletionStageRxInvoker that is based on the Java 8 type CompletionStage. There is a new rx method which is used in a similar manner to async as described in Client API. Let us consider the following example:

This example first creates an asynchronous computation of type CompletionStage<String>, and then simply waits for it to complete and displays its result (technically, a second computation of type CompletionStage<Void> is created on the last line simply to consume the result of the first computation).

The value of CompletionStage becomes apparent when multiple asynchronous computations are necessary to accomplish a task. The following example obtains, in parallel, a price and a forecast for a destination and makes a reservation only if the desired conditions are met.

Note that the Consumer passed in the call to method thenCombine requires the values of each stage to be available and, therefore, can only be executed after the two parallel stages are completed.

As we shall see in the next section, support for CompletionStage is the default for all JAX-RS implementations, but other reactive APIs may also be supported as extensions.

Executor services can be used to submit asynchronous tasks for execution. JAX-RS applications can specify executor services while building a Client instance. Two methods are provided in ClientBuilder for this purpose, namely, executorService and scheduledExecutorService.

In an environment that supports Jakarta Concurrency [13], such as full Jakarta EE platform products, implementations MUST use ManagedExecutorService and ManagedScheduledExecutorService, respectively. The reader is referred to the Javadoc of ClientBuilder for more information about executor services.

Entity interceptors wrap around a method invocation at a specific extension point. Filters execute code at an extension point but without wrapping a method invocation. There are four extension points for filters: ClientRequest, ClientResponse, ContainerRequest and ContainerResponse. There are two extension points for entity interceptors: ReadFrom and WriteTo. For each of these extension points, there is a corresponding interface:

A client filter is a class that implements ClientRequestFilter or ClientResponseFilter or both. A container filter is a class that implements ContainerRequestFilter or ContainerResponseFilter, or both. An entity interceptor is a class that implements ReaderInterceptor or WriterInterceptor, or both. Filters and entity interceptors are providers and, as such, may be annotated with @Provider for automatic discovery.

In the Client API, a ClientRequestFilter is executed as part of the invocation pipeline, before the HTTP request is delivered to the network; a ClientResponseFilter is executed upon receiving a server response, before control is returned to the application. In the Server API, a ContainerRequestFilter is executed upon receiving a request from a client; a ContainerResponseFilter is executed as part of the response pipeline, before the HTTP response is delivered to the network.

A globally-bound (see Global Binding) ContainerRequestFilter is a container filter executed after resource matching unless it is annotated with @PreMatching. The use of this annotation on this type of filters defines a new extension point for applications to use, namely . Certain ContainerRequestContext methods may not be available at this extension point.

An entity interceptor implementing ReaderInterceptor wraps around calls to MessageBodyReader’s method readFrom. An entity interceptor implementing WriterInterceptor wraps around calls to MessageBodyWriter’s method writeTo. JAX-RS implementations are REQUIRED to call registered interceptors when mapping representations to Java types and vice versa. See Entity Providers for more information on entity providers.

Please refer to Appendix Processing Pipeline for some diagrams on the client and server processing pipelines that show the interaction between filters and entity interceptors.

Filters are grouped into filter chains. There is a separate filter chain for each extension point introduced in the previous section, namely: ClientRequest, ClientResponse, ContainerRequest, ContainerResponse and PreMatchContainerRequest. Filters in a chain are sorted based on their priorities (see Priorities) and are executed in order.

The following example shows an implementation of a container logging filter: each method simply logs the message and returns.

ContainerRequestContext is a mutable class that provides request-specific information for the filter, such as the request URI, message headers, message entity or request-scoped properties. The exposed setters allow (certain) modification of the request before it is processed by the resource method. Similarly, there is a corresponding ContainerResponseContext that provides response-specific information.

Request filters implementing ClientRequestFilter or ContainerRequestFilter can stop the execution of their corresponding chains by calling abortWith(Response) in their corresponding context object. If this method is invoked, JAX-RS implementations are REQUIRED to abort execution of the chain and treat the response object as if produced by calling the resource method (Server API) or executing the HTTP invocation (Client API). For example, upon a cache hit, a client caching filter may call abortWith(Response) to abort execution and optimize network access.

As stated above, a ContainerRequestFilter that is annotated with @PreMatching is executed upon receiving a client request but before a resource method is matched. Thus, this type of filter has the ability to modify the input to the matching algorithm (see Request Matching) and, consequently, alter its outcome. The following example uses a ContainerRequestFilter annotated with @PreMatching to tunnel requests via POST by using the X-HTTP-Method-Override header to overwrite the HTTP method prior to resource matching.

An entity interceptor implements interface ReaderInterceptor or WriterInterceptor, or both. There is an interceptor chain for each kind of entity interceptor. Entity interceptors in a chain are sorted based on their priorities (see Priorities) and are executed in order.

As part of the JAX-RS processing pipeline (see Appendix Processing Pipeline), entity interceptors wrap calls to the methods readFrom in classes implementing MessageBodyReader and writeTo in classes implementing MessageBodyWriter. An interceptor SHOULD explicitly call the context method proceed to continue the execution of the chain. Because of their wrapping nature, failure to call this method will prevent execution of the wrapped method in the corresponding message body reader or message body writer.

The following example shows an implementation of a GZIP entity interceptor that provides deflate and inflate capabilities ^[12].

The context types, ReaderInterceptorContext and WriterInterceptorContext, provide read and write access to the parameters of the corresponding wrapped methods. In the example shown above, the input and output streams are wrapped and updated in the context object before proceeding. JAX-RS implementations MUST use the last parameter values set in the context object when calling the wrapped methods MessageBodyReader.readFrom and MessageBodyWriter.writeTo.

It is worth noting that a readFrom or a writeTo that is called directly from application code, e.g. via the injection of a Providers instance, will not trigger the execution of any entity interceptors since it is not part of the normal JAX-RS processing pipeline.

By default, just like all the other providers, a single instance of each filter or entity interceptor is instantiated for each JAX-RS application. First the constructor is called, then any requested dependencies are injected, then the appropriate methods are called (simultaneously) as needed. Implementations MAY offer alternative lifecycle options beyond the default one. See Lifecycle and Environment for additional information.

Binding is the process by which a filter or interceptor is associated with a resource class or method (Server API) or an invocation (Client API). The forms of binding presented in the next sections are only supported as part of the Server API. See Binding in Client API for binding in the Client API.

The order in which filters and interceptors are executed as part of their corresponding chains is controlled by the @Priority annotation defined in [15]. Priorities are represented by integer numbers. Execution chains for extension points , , ,  and  are sorted in ascending order; the lower the number the higher the priority. Execution chains for extension points  and  are sorted in descending order; the higher the number the higher the priority. These rules ensure that response filters are executed in reversed order of request filters.

The Priorities class in JAX-RS defines a set of built-in priorities for security, header decorators, decoders and encoders. The default binding priority is javax.ws.rs.Priorities.USER. For example, the priority of an authentication filter can be set as follows:

Note that even though, as explained in Binding in Client API, annotations are not used for binding in the Client API, they are still used to define priorities. Therefore, if a priority other than the default is required, the @Priority annotation must be used for a filter or interceptor registered with the Client API.

The order in which filters and interceptors that belong to the same priority class are executed is implementation dependent.

The Server API provides support for extracting request values and mapping them into Java fields, properties and parameters using annotations such as @HeaderParam, @QueryParam, etc. It also supports mapping of request entity bodies into Java objects via non-annotated parameters (i.e., parameters without any JAX-RS annotations). See Chapter Resources for additional information.

In earlier versions of JAX-RS, any additional validation of these values needed to be performed programmatically. This version of JAX-RS introduces support for declarative validation based on the Bean Validation specification [16].

The Bean Validation specification [16] supports the use of constraint annotations as a way of declaratively validating beans, method parameters and method returned values. For example, consider the following resource class augmented with constraint annotations:

The annotations @NotNull and @Email impose additional constraints on the form parameters firstName, lastName and email. The @NotNull constraint is built-in to the Bean Validation API; the @Email constraint is assumed to be user defined in the example above. These constraint annotations are not restricted to method parameters, they can be used in any location in which the JAX-RS binding annotations are allowed with the exception of constructors and property setters. Rather than using method parameters, the MyResourceClass shown above could have been written as follows:

Note that in this version, firstName and lastName are fields initialized via injection and email is a resource class property. Constraint annotations on properties are specified in their corresponding getters.

Constraint annotations are also allowed on resource classes. In addition to annotating fields and properties, an annotation can be defined for the entire class. Let us assume that @NonEmptyNames validates that one of the two name fields in MyResourceClass is provided. Using such an annotation, the example above can be extended as follows:

Constraint annotations on resource classes are useful for defining cross-field and cross-property constraints.

Annotation constraints and validators are defined in accordance with the Bean Validation specification [16]. The @Email annotation shown above is defined using the Bean Validation @Constraint meta-annotation:

The @Constraint annotation must include a reference to the validator class that will be used to validate decorated values. The EmailValidator class must implement ConstraintValidator<Email, T> where T is the type of values being validated. For example,

Thus, EmailValidator applies to values annotated with @Email that are of type String. Validators for different types can be defined for the same constraint annotation.

Constraint annotations must also define a groups element to indicate which processing groups they are associated with. If no groups are specified (as in the example above) the Default group is assumed. For simplicity, JAX-RS implementations are NOT REQUIRED to support processing groups other than Default. In what follows, we assume that constraint validation is carried out in the Default processing group.

Request entity bodies can be mapped to resource method parameters. There are two ways in which these entities can be validated. If the request entity is mapped to a Java bean whose class is decorated with Bean Validation annotations, then validation can be enabled using @Valid:

In this case, the validator associated with @StandardUser (as well as those for non-class level constraints like @NotNull) will be called to verify the request entity mapped to user. Alternatively, a new annotation can be defined and used directly on the resource method parameter.

In the example above, @PremiumUser rather than @StandardUser will be used to validate the request entity. These two ways in which validation of entities can be triggered can also be combined by including @Valid in the list of constraints. The presence of @Valid will trigger validation of all the constraint annotations decorating a Java bean class. This validation will take place in the Default processing group unless the @ConvertGroup annotation is present. See [16] for more information on @ConvertGroup.

Response entity bodies returned from resource methods can be validated in a similar manner by annotating the resource method itself. To exemplify, assuming both @StandardUser and @PremiumUser are required to be checked before returning a user, the getUser method can be annotated as shown next:

Note that @PremiumUser is explicitly listed and @StandardUser is triggered by the presence of the @Valid annotation —see definition of User class earlier in this section.

According to [16], validation is enabled by default only for the so called constrained methods. Getter methods as defined by the Java Beans specification are not constrained methods, so they will not be validated by default. The special annotation @ValidateOnExecution defined in [16] can be used to selectively enable and disable validation. For example, you can enable validation on method getEmail shown above as follows:

The default value for the type attribute of @ValidateOnExecution is IMPLICIT which, in the example above, results in method getEmail being validated. See [16] for more information on other uses of this annotation.

Note that if validation for getter methods is enabled and a resource method’s signature obeys the rules for getters, the resource method may be (unintentionally) invoked during validation. Conversely, if validation for getter methods is disabled and the matching resource method’s signature obeys the rules for getters, the JAX-RS runtime will still validate the method (i.e., the validation preference will be ignored) before invocation.

The rules for inheritance of constraint annotation are defined in [16]. It is worth noting that these rules are incompatible with those defined in Annotation Inheritance. Generally speaking, constraint annotations in [16] are cumulative (can be strengthen) across a given type hierarchy while JAX-RS annotations are inherited or, overridden and ignored.

The goal of this specification is to enable validation of JAX-RS resources by leveraging existing Bean Validation implementations. Therefore, JAX-RS implementations MUST follow the constraint annotation rules defined in [16].

Constraint annotations are allowed in the same locations as the following annotations: @MatrixParam, @QueryParam, @PathParam, @CookieParam, @HeaderParam and @Context, except in class constructors and property setters. Specifically, they are allowed in resource method parameters, fields and property getters as well as resource classes, entity parameters and resource methods (return values).

The default resource class instance lifecycle is per-request in JAX-RS. Implementations MAY support other lifecycles; the same caveats related to the use of other JAX-RS annotations in resource classes apply to constraint annotations. For example, a constraint validation annotating a constructor parameter in a resource class whose lifecycle is singleton will only be executed once.

JAX-RS implementations SHOULD use the following process to validate resource class instances after they have been instantiated:

The exception model in [16] defines a base class javax.validation.ValidationException and a few subclasses to report errors that are specific to constraint definitions, constraint declarations, group definitions and constraint violations. JAX-RS implementations MUST provide a default exception mapper (see Exception Mapping Providers) for javax.validation.ValidationException according to the following rules:

In all cases, JAX-RS implementations SHOULD include a response entity describing the source of the error; however, the exact content and format of this entity is beyond the scope of this specification. As described in Exception Mapping Providers, applications can provide their own exception mappers and, consequently, customize the default mapper described above.

Asynchronous processing is a technique that enables a better and more efficient use of processing threads. On the client side, a thread that issues a request may also be responsible for updating a UI component; if that thread is blocked waiting for a response, the user’s perceived performance of the application will suffer. Similarly, on the server side, a thread that is processing a request should avoid blocking while waiting for an external event to complete so that other requests arriving to the server during that period of time can be attended^[14].

As stated in Enterprise Java Beans (EJBs), JAX-RS implementations in products that support EJB must also support the use of stateless and singleton session beans as root resource classes. When an EJB method is annotated with @Asynchronous, the EJB container automatically allocates the necessary resources for its execution. Thus, in this scenario, the use of an Executor is unnecessary to generate an asynchronous response.

Consider the following example:

There is no explicit thread management needed in this case since that is under the control of the EJB container. Just like the other examples in this chapter, the response is produced by calling resume on the injected AsyncResponse. Hence, the return type of longRunningOp is simply void.

The fluent API supports asynchronous invocations as part of the invocation building process. By default, invocations are synchronous but can be set to run asynchronously by calling the async method and (optionally) registering an instance of InvocationCallback as shown next:

Note that in this example, the call to get after calling async returns immediately without blocking the caller’s thread. The response type is specified as a type parameter to InvocationCallback. The method completed is called when the invocation completes successfully and a response is available; the method failed is called with an instance of Throwable when the invocation fails.

All asynchronous invocations return an instance of Future<T> here the type parameter T matches the type specified in InvocationCallback. This instance can be used to monitor or cancel the asynchronous invocation:

Even though it is recommended to pass an instance of InvocationCallback when executing an asynchronous call, it is not mandated. When omitted, the Future<T> returned by the invocation can be used to gain access to the response by calling the method Future.get, which will return an instance of T if the invocation was successful or null if the invocation failed.

Server-sent events (SSE) is a specification originally introduced as part of HTML5 by the W3C, but is currently maintained by the WHATWG [17]. It provides a way to establish a one-way channel from a server to a client. The connection is long running: it is re-used for multiple events sent from the server, yet it is still based on the HTTP protocol. Clients request the opening of an SSE connection by using the special media type text/event-stream in the Accept header.

Events are structured and contain several fields, namely, event, data, id, retry and comment. SSE is a messaging protocol where the event field corresponds to a topic, and where the id field can be used to validate event order and guarantee continuity. If a connection is interrupted for any reason, the id can be sent in a request header for a server to re-play past events —although this is an optional behavior that may not be supported by all implementations. Event payloads are conveyed in the data field and must be in text format; retry is used to control re-connects and finally comment is a general purpose field that can also be used to keep connections alive.

The JAX-RS client API for SSE was inspired by the corresponding JavaScript API in HTML5, but with changes that originate from the use of a different language. The entry point to the client API is the type SseEventSource, which provides a fluent builder similarly to other classes in the JAX-RS API. An SseEventSource is constructed from a WebTarget that is already configured with a resource location; SseEventSource does not duplicate any functionality in WebTarget and only adds the necessary logic for SSE.

The following example shows how to open an SSE connection and read some messages for a little while:

As seen in this example, an SseEventSource implements AutoCloseable. Before opening the source, the client registers an event consumer that simply prints each event. Additional handlers for other life-cycle events such as onComplete and onError are also supported, but for simplicity only onEvent is shown in the example above.

The JAX-RS SSE server API is used to accept connections and send events to one or more clients. A resource method that injects an SseEventSink and produces the media type text/event-stream is an SSE resource method.

The following example accepts SSE connections and uses an executor thread to send 3 events before closing the connection:

SSE resource methods follow a similar pattern to those for asynchronous processing (see Introduction) in that the object representing the incoming connection, in this case SseEventSink, is injected into the resource method.

The example above also injects the Sse type which provides factory methods for events and broadcasters. See Broadcasting for more information about broadcasting. Note that, just like SseEventSource, the interface SseEventSink is also auto-closeable, hence the use of the try-with-resources statement above.

Method send on SseEventSink returns a CompletionStage<?> as a way to provide a handle to the action of asynchronously sending a message to a client.

Applications may need to send events to multiple clients simultaneously. This action is called broadcasting in JAX-RS. Multiple SseEventSink’s can be registered on a single SseBroadcaster.

A broadcaster can only be created by calling method newBroadcaster on the injected Sse instance. The life-cycle and scope of an SseBroadcaster is fully controlled by applications and not the JAX-RS runtime. The following example shows the use of broadcasters, note the @Singleton annotation on the resource class:

The register method on a broadcaster is used to add a new SseEventSink; the broadcast method is used to send an SSE event to all registered consumers.

Connections from SSE clients are represented by injectable instances of SseEventSink. There are some similarities between SSE and asynchronous processing (see Chapter Asynchronous Processing). Asynchronous responses can be resumed at most once while an SseEventSink can be used multiple times to stream individual events.

For compatibility purposes, implementations MUST initiate processing of an SSE response when either the first message is sent or when the resource method returns, whichever happens first. The initial SSE response, which may only include the HTTP headers, is processed using the standard JAX-RS pipeline as described in Appendix Processing Pipeline. Each subsequent SSE event may include a different payload and thus require the use of a specific message body writer. Note that since this use case differs slightly from the normal JAX-RS pipeline, implementations SHOULD NOT call entity interceptors on each individual event.^[15]

The SseEventSource class uses the existing JAX-RS mechanism based on RuntimeDelegate to find an implementation using the service name javax.ws.rs.sse.SseEventSource.Builder. The majority of types in the javax.ws.rs.sse are thread safe; the reader is referred to the Javadoc for more information on thread safety.

Context is specific to a particular request but instances of certain JAX-RS components (providers and resource classes with a lifecycle other than per-request) may need to support multiple concurrent requests. When injecting an instance of one of the types listed in Context Types, the instance supplied MUST be capable of selecting the correct context for a particular request. Use of a thread-local proxy is a common way to achieve this.

This section describes the types of context available to providers (client and server) as well as resource classes and Application subclasses (server only). Except for Configuration and Providers, which are injectable in both client and server-side providers, all the other types are server-side only.

The @Context annotation can be used to indicate a dependency on a Servlet-defined resource. A Servlet-based implementation MUST support injection of the following Servlet-defined types: ServletConfig, ServletContext, HttpServletRequest and HttpServletResponse.

An injected HttpServletRequest allows a resource method to stream the contents of a request entity. If the resource method has a parameter whose value is derived from the request entity then the stream will have already been consumed and an attempt to access it MAY result in an exception.

An injected HttpServletResponse allows a resource method to commit the HTTP response prior to returning. An implementation MUST check the committed status and only process the return value if the response is not yet committed.

Servlet filters may trigger consumption of a request body by accessing request parameters. In a servlet container the @FormParam annotation and the standard entity provider for application/x-www-form-urlencoded MUST obtain their values from the servlet request parameters if the request body has already been consumed. Servlet APIs do not differentiate between parameters in the URI and body of a request so URI-based query parameters may be included in the entity parameter.

This section describes the additional requirements that apply to a JAX-RS implementation when combined in a product that supports the following specifications.

Other container technologies MAY specify their own set of injectable resources but MUST, at a minimum, support access to the types of context listed in Context Types.

If not supplied by injection, the supplied RuntimeDelegate API class obtains the concrete implementation class using the following algorithm. The steps listed below are performed in sequence and, at each step, at most one candidate implementation class name will be produced. The implementation will then attempt to load the class with the given class name using the current context class loader or, missing one, the java.lang.Class.forName(String) method. As soon as a step results in an implementation class being successfully loaded, the algorithm terminates.