香港 cine times在哪里:JSR-311 规范 JAX-RS: Java? API for RESTful Web Services

3.3.4 Exceptions

A resource method, sub-resource method or sub-resource locator may throw any checked or unchecked exception. An implementation MUST catch all exceptions and process them as follows:

1. Instances of WebApplicationException MUST be mapped to a response as follows. If the response property of the exception does not contain an entity and an exception mapping provider (see section 4.4) is available for WebApplicationException an implementation MUST use the provider to create a new Response instance, otherwise the response property is used directly. The resultingResponse instance is then processed according to section 3.3.3.
2. If an exception mapping provider (see section 4.4) is available for the exception or one of its superclasses, an implementation MUST use the provider whose generic type is the nearest superclass of the exception to create aResponse instance that is then processed according to section 3.3.3. If the exception mapping provider throws an exception while creating a Response then return a server error (status code 500) response to the client.
3.  Unchecked exceptions and errors MUST be re-thrown and allowed to propagate to the underlying container.
4.  Checked exceptions and throwables that cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container. Servlet-based implementations MUST use ServletException as the wrapper. JAX-WS Provider-based implementations MUST use WebServiceException as the wrapper.

Note: Items 3 and 4 allow existing container facilities (e.g. a Servlet filter or error pages) to be used to handle the error if desired.

3.3.5 HEAD and OPTIONS

HEAD and OPTIONS requests receive additional automated support. On receipt of a HEAD request an implementation MUST either:

1. Call a method annotated with a request method designator for HEAD or, if none present,
2.  Call a method annotated with a request method designator for GET and discard any returned entity.

Note that option 2 may result in reduced performance where entity creation is significant.

On receipt of an OPTIONS request an implementation MUST either:

1. Call a method annotated with a request method designator for OPTIONS or, if none present,
2. Generate an automatic response using the metadata provided by the JAX-RS annotations on the matching class and its methods.

3.4 URI Templates

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 deployment context.

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

1 @Path("widgets/{id}")  
2 public class Widget {  
3   ...  
4 }

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

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:

1 @Path("widget list/{id}")  
2 @Path("widget%20list/{id}")

Template parameters can optionally specify the regular 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.:

1 @Path("widgets/{path:.+}")  
2 public class Widget {  
3   ...  
4 }

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 pathwidgets/small/a the value of path would be small/a.

3.4.1 Sub Resources

Methods of a resource class that are annotated with @Path are either sub-resource methods or sub-resource locators. Sub-resource methods handle a HTTP request directly whilst sub-resource locators return an object that will handle a HTTP request. The presence or absence of a request method designator (e.g. @GET) differentiates between the two:

Present

Such methods, known as sub-resource methods, are treated like a normal resource method (see section 3.3) except the method is only invoked for request URIs that match a URI template created by concatenating the URI template of the resource class with the URI template of the method² .

Absent

Such methods, known as sub-resource locators, are used to dynamically resolve the object that will handle the request. Any returned object is treated as a resource class instance and used to either handle the request or to further resolve the object that will handle the request, see 3.7 for further details. An implementation MUST dynamically determine the class of object returned rather than relying on the static sub-resource locator return type since the returned instance may be a subclass of the declared type with potentially different annotations, see section 3.6 for rules on annotation inheritance. Sub-resource locators may have all the same parameters as a normal resource method (see section 3.3) except that they MUST NOT have an entity parameter.

The following example illustrates the difference:

1 @Path("widgets")  
2 public class WidgetsResource {  
3   @GET  
4   @Path("offers")  
5   public WidgetList getDiscounted() {...}  
6  
7   @Path("{id}")  
8   public WidgetResource findWidget(@PathParam("id") String id) {  
9     return new WidgetResource(id);  
10   }  
11 }  
12  
13 public class WidgetResource {  
14   public WidgetResource(String id) {...}  
15  
16   @GET  
17   public Widget getDetails() {...}  
18 }

In the above a GET request for the widgets/offers resource is handled directly by the getDiscounted sub-resource method of the resource class WidgetsResource whereas a GET request for widgets/xxx is handled by the getDetails method of the WidgetResource resource class.

Note: A set of sub-resource methods annotated with the same URI template value are functionally equivalent to a similarly annotated sub-resource locator that returns an instance of a resource class with the same set of resource methods.

3.5 Declaring Media Type Capabilities

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 section4.2.3). 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:

1 @Path("widgets")  
2 @Produces("application/widgets+xml")  
3 public class WidgetsResource {  
4  
5   @GET  
6   public Widgets getAsXML() {...}  
7  
8   @GET  
9   @Produces("text/html")  
10   public String getAsHtml() {...}  
11  
12   @POST  
13   @Consumes("application/widgets+xml")  
14   public void addWidget(Widget widget) {...}  
15 }  
16  
17 @Provider  
18 @Produces("application/widgets+xml")  
19 public class WidgetsProvider implements MessageBodyWriter {...}  
20  
21 @Provider  
22 @Consumes("application/widgets+xml")  
23 public class WidgetProvider implements MessageBodyReader {...}

In the above:

• The getAsXML resource method will be called for GET requests that specify a response media type of application/widgets+xml. It returns a Widgets instance that will be mapped to that format using the WidgetsProvider class (see section 4.2 for more information onMessageBodyWriter).
• The getAsHtml resource method will be called for GET requests that specify a response media type of text/html. It returns a Stringcontaining text/html that will be written using the default implementation of MessageBodyWriter.
• The addWidget resource method will be called for POST requests that contain an entity of the media type application/widgets+xml. The value of the widget parameter will be mapped from the request entity using the WidgetProvider class (see section 4.2 for more information on MessageBodyReader).

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.

3.6 Annotation Inheritance

JAX-RS annotations MAY be used on the methods of a super-class or an implemented interface. Such annotations are inherited by a corresponding sub-class or implementation class method provided that method does not have any of its own JAX-RS annotations. Annotations on a super-class take precedence over those on an implemented interface. If a subclass or implementation method has any JAX-RS annotations then all of the annotations on the super class or interface method are ignored. E.g.:

1 public interface ReadOnlyAtomFeed {  
2   @GET @Produces("application/atom+xml")  
3   Feed getFeed();  
4 }  
5  
6 @Path("feed")  
7 public class ActivityLog implements ReadOnlyAtomFeed {  
8   public Feed getFeed() {...}  
9 }

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

1 @Path("feed")  
2 public class ActivityLog implements ReadOnlyAtomFeed {  
3   @Produces("application/atom+xml")  
4   public Feed getFeed() {...}  
5 }

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.

3.7 Matching Requests to Resource Methods

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.

3.7.1 Request Preprocessing

Prior to matching, request URIs are normalized³ by following the rules for case, path segment, and percent encoding normalization described in section 6.2.2 of RFC 3986[5]. The normalized request URI MUST be reflected in the URIs obtained from an injectedUriInfo.

3.7.2 Request Matching

A request is matched to the corresponding resource method or sub-resource method by comparing the normalized request URI (see section 3.7.1), the media type of any request entity, and the requested response entity format to the metadata annotations on the resource classes and their methods. If no matching resource method or sub-resource method can be found then an appropriate error response is returned. Matching of requests to resource methods proceeds in three stages as follows:

1. Identify the root resource class:
   1. Set U = request URI path,C = {root resource classes},E = {}
   2. For each class in C add a regular (computed using the function R(A) described in section 3.7.3) to E as follows:
      • Add R(T_class) where T_class is the URI path template specified for the class.
   3. Filter E by matching each member against U as follows:
      • Remove members that do not match U.
      • Remove members for which the final regular capturing group (henceforth simply referred to as a capturing group) value is neither empty nor ‘/’ and the class associated with R(T_class) had no sub-resource methods or locators.
   4. If E is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate aWebApplicationException with a not found response (HTTP 404 status) and no entity. The exception MUST be processed as described in section 3.3.4.
   5. Sort E using the number of literal characters⁴ in each member as the primary key (descending order), the number of capturing groups as a secondary key (descending order) and the number of capturing groups with non-default regular s (i.e. not ‘([/]+?)’) as the tertiary key (descending order).
   6. Set R_match to be the first member of E, set U to be the value of the final capturing group of R_match when matched againstU, and instantiate an object O of the associated class.
2.  Obtain the object that will handle the request and a set of candidate methods:
   1.  If U is null or ‘/’, setand go to step 3
   2. Set C = class of O,E = {}
   3. For class C add regular s to E for each sub-resource method and locator as follows:
      1.  For each sub-resource method, add R(T_method) where T_method is the URI path template of the sub-resource method.
      2. For each sub-resource locator, add R(T_locator) where T_locator is the URI path template of the sub-resource locator.
   4. Filter E by matching each member against U as follows:
      • Remove members that do not match U.
      • Remove members derived from T_method (those added in step 2(c)i) for which the final capturing group value is neither empty nor ‘/’.
   5. If E is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate aWebApplicationException with a not found response (HTTP 404 status) and no entity. The exception MUST be processed as described in section 3.3.4.
   6. Sort E using the number of literal characters in each member as the primary key (descending order), the number of capturing groups as a secondary key (descending order), the number of capturing groups with non-default regular s (i.e. not ‘([/]+?)’) as the tertiary key (descending order), and the source of each member as quaternary key sorting those derived from T_method ahead of those derived from T_locator.
   7. Set R_match to be the first member of E
   8. If R_match was derived from T_method, then setand go to step 3.
   9. Set U to be the value of the final capturing group of R(T_match) when matched against U, invoke the sub-resource locator method of O and set O to the value returned from that method.
   10. Go to step 2a.
3.  Identify the method that will handle the request:
   1.  Filter M by removing members that do not meet the following criteria:
      • The request method is supported. If no methods support the request method an implementation MUST generate aWebApplicationException with a method not allowed response (HTTP 405 status) and no entity. The exception MUST be processed as described in section 3.3.4. Note the additional support for HEAD and OPTIONS described in section 3.3.5.
      • The media type of the request entity body (if any) is a supported input data format (see section 3.5). If no methods support the media type of the request entity body an implementation MUST generate a WebApplicationException with an unsupported media type response (HTTP 415 status) and no entity. The exception MUST be processed as described in section 3.3.4.
      • At least one of the acceptable response entity body media types is a supported output data format (see section3.5). If no methods support one of the acceptable response entity body media types an implementation MUST generate a WebApplicationException with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section 3.3.4.
   2. Sort M in descending order as follows:
      • The primary key is the media type of input data. Methods whose @Consumes value is the best match for the media type of the request are sorted first.
      • The secondary key is the @Produces value. Methods whose value of @Produces best matches the value of the request accept header are sorted first.

      Determining the best matching media types follows the general rule: n/m > n/* > */*, i.e. a method that explicitly consumes the request media type or produces one of the requested media types is sorted before a method that consumes or produces */*. Quality parameter values in the accept header are also considered such that methods that produce media types with a higher acceptable q-value are sorted ahead of those with a lower acceptable q-value (i.e. n/m;q=1.0 >n/m;q=0.7) - see section 14.1 of [4] for more details.

   3.  The request is dispatched to the first Java method in the set⁵ .

3.7.3 Converting URI Templates to Regular s

The function R(A) converts a URI path template annotation A into a regular as follows:

1. URI encode the template, ignoring URI template variable specifications.
2. Escape any regular characters in the URI template, again ignoring URI template variable specifications.
3. Replace each URI template variable with a capturing group containing the specified regular or ‘([/]+?)’ if no regular is specified.
4. If the resulting string ends with ‘/’ then remove the final character.
5. Append ‘(/.*)?’ to the result.

Note that the above renders the name of template variables irrelevant for template matching purposes. However, implementations will need to retain template variable names in order to facilitate the extraction of template variable values via @PathParam orUriInfo.getPathParameters.

3.8 Determining the MediaType of Responses

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_selected, at run time:

1. If the method returns an instance of Response whose metadata includes the response media type (M_specified) then set M_selected =M_specified, finish.
2. Gather the set of producible media types P :
   • If the method is annotated with @Produces, set P = {V (method)} where V (t) represents the values of @Produces on the specified target t.
   • Else if the class is annotated with @Produces, set P = {V (class)}.
   • Else set P = {V (writers)} where ‘writers’ is the set of MessageBodyWriter that support the class of the returned entity object.
3. If P = {}, set P = {‘*/*’}
4. Obtain the acceptable media types A. If A = {}, set A = {‘*/*’}
5. Set M = {}. For each member of A,a:
   • For each member of P,p:
     • If a is compatible with p, add S(a,p) to M, where the function S returns the most specific media type of the pair with the q-value of a.
6. If M = {} then generate a WebApplicationException with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section 3.3.4. Finish.
7. Sort M in descending order, with a primary key of specificity (n/m > n/* > */*) and secondary key of q-value.
8. For each member of M,m:
   • If m is a concrete type, set M_selected = m, finish.
9. If M contains ‘*/*’ or ‘application/*’, set M_selected = ‘application/octet-stream’, finish.
10. Generate a WebApplicationException with a not acceptable response (HTTP 406 status) and no entity. The exception MUST be processed as described in section 3.3.4. Finish.

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.

Chapter 4
Providers

The JAX-RS runtime is extended using application-supplied provider classes. A provider is annotated with @Provider and implements one or more interfaces defined by JAX-RS.

4.1 Lifecycle and Environment

By default a single instance of each provider class is instantiated for each JAX-RS application. First the constructor (see section 4.1.1) is called, then any requested dependencies are injected (see chapter 5), then the appropriate provider methods may be called multiple times (simultaneously), and finally the object is made available for garbage collection. Section 5.2.5describes 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.

4.1.1 Constructors

Provider classes are instantiated by the JAX-RS runtime and MUST have a public constructor for which the JAX-RS runtime can provide all parameter values. Note that a zero argument constructor is permissible under this rule.

A public constructor MAY include parameters annotated with @Context- chapter 5 defines the parameter types permitted for this annotation. Since providers may be created outside the scope of a particular request, only deployment-specific properties may be available from injected interfaces at construction time - request-specific properties are available when a provider method is called. If more than one public constructor can be used then an implementation MUST use the one with the most parameters. Choosing amongst constructors with the same number of parameters is implementation specific, implementations SHOULD generate a warning about such ambiguity.

4.2 Entity Providers

Entity providers supply mapping services between representations and their associated Java types. Entity providers come in two flavors: MessageBodyReader and MessageBodyWriter described below. In the absence of a suitable entity provider, JAX-RS implementations are REQUIRED to use to the JavaBeans Activation Framework[11] to try to obtain a suitable data handler to perform the mapping instead.

4.2.1 Message Body Reader

The MessageBodyReader interface defines the contract between the JAX-RS runtime and components that provide mapping services from representations to a corresponding Java type. A class wishing to provide such a service implements the MessageBodyReader interface and is annotated with @Provider.

The following describes the logical¹ steps taken by a JAX-RS implementation when mapping a request entity body to a Java method parameter:

1. Identify the Java type of the parameter whose value will be mapped from the entity body. Section 3.7 describes how the Java method is chosen.
2. Select the set of MessageBodyReader classes that support the media type of the request, see section 4.2.3.
3.  Iterate through the selected MessageBodyReader classes and, utilizing the isReadable method of each, choose aMessageBodyReader provider that supports the desired Java type.
4. If step 3 locates a suitable MessageBodyReader then use its readFrom method to map the entity body to the desired Java type.
5. Else if a suitable data handler can be found using the JavaBeans Activation Framework[11] then use it to map the entity body to the desired Java type.
6. Else generate a WebApplicationException that contains an unsupported media type response (HTTP 415 status) and no entity. The exception MUST be processed as described in section 3.3.4.

A MessageBodyReader.readFrom method MAY throw WebApplicationException. If thrown, the resource method is not invoked and the exception is treated as if it originated from a resource method, see section 3.3.4.

4.2.2 Message Body Writer

The MessageBodyWriter interface defines the contract between the JAX-RS runtime and components that provide mapping services from a Java type to a representation. A class wishing to provide such a service implements the MessageBodyWriter interface and is annotated with @Provider.

The following describes the logical steps taken by a JAX-RS implementation when mapping a return value to a response entity body:

1. Obtain the object that will be mapped to the response entity body. For a return type of Response or subclasses the object is the value of the entity property, for other return types it is the returned object.
2. Determine the media type of the response, see section 3.8.
3. Select the set of MessageBodyWriter providers that support (see section 4.2.3) the object and media type of the response entity body.
4. Sort the selected MessageBodyWriter providers as described in section 4.2.3.
5.  Iterate through the sorted MessageBodyWriter providers and, utilizing the isWriteable method of each, choose an MessageBodyWriter that supports the object that will be mapped to the entity body.
6. If step 5 locates a suitable MessageBodyWriter then use its writeTo method to map the object to the entity body.
7. Else if a suitable data handler can be found using the JavaBeans Activation Framework[11] then use it to map the object to the entity body.
8. Else generate a WebApplicationException with an internal server error response (HTTP 500 status) and no entity. The exception MUST be processed as described in section 3.3.4.

A MessageBodyWriter.write method MAY throw WebApplicationException. If thrown before the response is committed, the exception is treated as if it originated from a resource method, see section 3.3.4. To avoid an infinite loop, implementations SHOULD NOT attempt to map exceptions thrown during serialization of an response previously mapped from an exception and SHOULD instead simply return a server error (status code 500) response.

4.2.3 Declaring Media Type Capabilities

Message body readers and writers MAY restrict the media types they support using the @Consumes and @Produces annotations respectively. The absence of these annotations is equivalent to their inclusion with media type (“*/*”), i.e. absence implies that any media type is supported. An implementation MUST NOT use an entity provider for a media type that is not supported by that provider.

When choosing an entity provider an implementation sorts the available providers according to the media types they declare support for. Sorting of media types follows the general rule: x/y < x/* < */*, i.e. a provider that explicitly lists a media types is sorted before a provider that lists */*.

4.2.4 Standard Entity Providers

An implementation MUST include pre-packaged MessageBodyReader and MessageBodyWriter implementations for the following Java and media type combinations:

byte[]

All media types (?/?).

java.lang.String

All media types (?/?).

java.io.InputStream

All media types (?/?).

java.io.Reader

All media types (?/?).

java.io.File

All media types (?/?).

javax.activation.DataSource

All media types (?/?).

javax.xml.transform.Source

XML types (text/xml, application/xml and application/?+xml).

javax.xml.bind.JAXBElement and application-supplied JAXB classes

XML media types (text/xml, application/xml and application/?+xml).

MultivaluedMap

Form content (application/x-www-form-urlencoded).

StreamingOutput

All media types (?/?), MessageBodyWriter only.

The implementation-supplied entity provider(s) for javax.xml.bind.JAXBElement and application-supplied JAXB classes MUST use JAXBContextinstances provided by application-supplied context resolvers, see section 4.3. If an application does not supply a JAXBContext for a particular type, the implementation-supplied entity provider MUST use its own default context instead.

When writing responses, implementations SHOULD respect application-supplied character set metadata and SHOULD use UTF-8 if a character set is not specified by the application or if the application specifies a character set that is unsupported.

An implementation MUST support application-provided entity providers and MUST use those in preference to its own pre-packaged providers when either could handle the same request.

4.2.5 Transfer Encoding

Transfer encoding for inbound data is handled by a component of the container or the JAX-RS runtime. MessageBodyReader providers always operate on the decoded HTTP entity body rather than directly on the HTTP message body.

A JAX-RS runtime or container MAY transfer encode outbound data or this MAY be done by application code.

4.2.6 Content Encoding

Content encoding is the responsibility of the application. Application-supplied entity providers MAY perform such encoding and manipulate the HTTP headers accordingly.

4.3 Context Providers

Context providers supply context to resource classes and other providers. A context provider class implements the ContextResolverinterface and is annotated with @Provider. E.g. an application wishing to provide a customized JAXBContext to the default JAXB entity providers would supply a class implementing ContextResolver.

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.

4.3.1 Declaring Media Type Capabilities

Context provider implementations MAY restrict the media types they support using the @Produces annotation. The absence of this annotation is equivalent to its inclusion with media type (“*/*”), i.e. absence implies that any media type is supported.

When choosing a context provider an implementation sorts the available providers according to the media types they declare support for. Sorting of media types follows the general rule: x/y < x/* < */*, i.e. a provider that explicitly lists a media type is sorted before a provider that lists */*.

4.4 Exception Mapping Providers

When a resource class or provider method throws an exception, the JAX-RS runtime will attempt to map the exception to a suitable HTTP response - see section 3.3.4. An application can supply exception mapping providers to customize this mapping.

Exception mapping providers map a checked or runtime exception to an instance of Response. An exception mapping provider implements the ExceptionMapper interface and is annotated with @Provider. When a resource 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 the method throwing the exception had instead returned the Response, see section 3.3.3.

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.

Chapter 5
Context

JAX-RS provides facilities for obtaining and processing information about the application deployment context and the context of individual requests. Such information is available to both root resource classes (see chapter 3) and providers (see chapter 4). This chapter describes these facilities.

5.1 Concurrency

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 section 5.2, 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.

5.2 Context Types

This section describes the types of context available to resource classes and providers.

5.2.1 URIs and URI Templates

An instance of UriInfo can be injected into a class field or method parameter using the @Context annotation. UriInfo provides both static and dynamic, per-request information, about the components of a request URI. E.g. the following would return the names of any query parameters in a request:

1 @GET  
2 @Produces{"text/plain"}  
3 public String listQueryParamNames(@Context UriInfo info) {  
4   StringBuilder buf = new StringBuilder();  
5   for (String param: info.getQueryParameters().keySet()) {  
6     buf.append(param);  
7     buf.append("\n");  
8   }  
9   return buf.toString();  
10 }

Note that the methods of UriInfo provide access to request URI information following the pre-processing described in section 3.7.1.

5.2.2 Headers

An instance of HttpHeaders can be injected into a class field or method parameter using the @Context annotation. HttpHeaders provides access to request header information either in map form or via strongly typed convenience methods. E.g. the following would return the names of all the headers in a request:

1 @GET  
2 @Produces{"text/plain"}  
3 public String listHeaderNames(@Context HttpHeaders headers) {  
4   StringBuilder buf = new StringBuilder();  
5   for (String header: headers.getRequestHeaders().keySet()) {  
6     buf.append(header);  
7     buf.append("\n");  
8   }  
9   return buf.toString();  
10 }

Note that the methods of HttpHeaders provide access to request information following the pre-processing described in section 3.7.1.

Response headers may be provided using the Response class, see 3.3.3 for more details.

5.2.3 Content Negotiation and Preconditions

JAX-RS simplifies support for content negotiation and preconditions using the Request interface. An instance of Request can be injected into a class field or method parameter using the @Context annotation. The methods of Request allow a caller to determine the best matching representation variant and to evaluate whether the current state of the resource matches any preconditions in the request. Precondition support methods return a ResponseBuilder that can be returned to the client to inform it that the request preconditions were not met. E.g. the following checks if the current entity tag matches any preconditions in the request before updating the resource:

1 @PUT  
2 public Response updateFoo(@Context Request request, Foo foo) {  
3     EntityTag tag = getCurrentTag();  
4     ResponseBuilder responseBuilder = request.evaluatePreconditions(tag);  
5     if (responseBuilder != null)  
6       return responseBuilder.build();  
7     else  
8       return doUpdate(foo);  
9 }

The application could also set the content location, expiry date and cache control information into the returned ResponseBuilderbefore building the response.

5.2.4 Security Context

The SecurityContext interface provides access to information about the security context of the current request. An instance ofSecurityContext can be injected into a class field or method parameter using the @Context annotation. The methods ofSecurityContext provide access to the current user principle, information about roles assumed by the requester, whether the request arrived over a secure channel and the authentication scheme used.

5.2.5 Providers

The Providers interface allows for lookup of provider instances based on a set of search criteria. An instance of Providers can be injected into a class field or method parameter using the @Context annotation.

This interface is expected to be primarily of interest to provider authors wishing to use other providers functionality.

Chapter 6
Environment

The container-managed resources available to a JAX-RS root resource class or provider depend on the environment in which it is deployed. Section 5.2 describes the types of context available regardless of container. The following sections describe the additional container-managed resources available to a JAX-RS root resource class or provider deployed in a variety of environments.

6.1 Servlet Container

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.

6.2 Java EE Container (Non-normative)

This section describes the additional features anticipated to be available to a JAX-RS application hosted in a Java EE 6 container. It is planned that JAX-RS will be finalized prior to Java EE 6 so the contents of this section are preliminary and subject to change. Nothing in this section should be considered a conformance requirement.

JAX-RS root resource classes and providers are supplied with the same resource injection capabilities as are provided for a Servlet instance running in a Java EE Web container. In particular the following annotations may be used according to their individual semantics: @Resource, @Resources, @EJB, @EJBs, @WebServiceRef, @WebServiceRefs, @PersistenceContext, @PersistenceContexts, @PersistenceUnit and@PersistenceUnits.

JAX-RS root resource classes and providers may also make use of the following JSR 250 lifecycle management and security annotations: @PostConstruct, @PreDestroy, @RunAs, @RolesAllowed, @PermitAll, @DenyAll and @DeclareRoles.

6.3 Other

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 section 5.2.

Chapter 7
Runtime Delegate

RuntimeDelegate is an abstract factory class that provides various methods for the creation of objects that implement JAX-RS APIs. These methods are designed for use by other JAX-RS API classes and are not intended to be called directly by applications.RuntimeDelegate allows the standard JAX-RS API classes to use different JAX-RS implementations without any code changes.

An implementation of JAX-RS MUST provide a concrete subclass of RuntimeDelegate. Using the supplied RuntimeDelegate this can be provided to JAX-RS in one of two ways:

1. An instance of RuntimeDelegate can be instantiated and injected using its static method setInstance. In this case the implementation is responsible for creating the instance; this option is intended for use with implementations based on IoC frameworks.
2. The class to be used can be configured, see section 7.1. In this case JAX-RS is responsible for instantiating an instance of the class and the configured class MUST have a public constructor which takes no arguments.

Note that an implementation MAY supply an alternate implementation of the RuntimeDelegate API class (provided it passes the TCK signature test and behaves according to the specification) that supports alternate means of locating a concrete subclass.

A JAX-RS implementation may rely on a particular implementation of RuntimeDelegate being used – applications SHOULD NOT override the supplied RuntimeDelegate instance with an application-supplied alternative and doing so may cause unexpected problems.

7.1 Configuration

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.

1. If a resource with the name of META-INF/services/javax.ws.rs.ext.RuntimeDelegate exists, then its first line, if present, is used as the UTF-8 encoded name of the implementation class.
2. If the ${java.home}/lib/jaxrs.properties file exists and it is readable by the java.util.Properties.load(InputStream) method and it contains an entry whose key is javax.ws.rs.ext.RuntimeDelegate, then the value of that entry is used as the name of the implementation class.
3. If a system property with the name javax.ws.rs.ext.RuntimeDelegate is defined, then its value is used as the name of the implementation class.
4. Finally, a default implementation class name is used.

Appendix A
Summary of Annotations

Target

Description

Type or method

Specifies a list of media types that can be consumed.

Type or method

Specifies a list of media types that can be produced.

Method

Specifies that the annotated method handles HTTP GET requests.

Method

Specifies that the annotated method handles HTTP POST requests.

Method

Specifies that the annotated method handles HTTP PUT requests.

Method

Specifies that the annotated method handles HTTP DELETE requests.

Method

Specifies that the annotated method handles HTTP HEAD requests. Note that HEAD may be automatically handled, see section 3.3.5.

Type or method

Specifies a relative path for a resource. When used on a class this annotation identifies that class as a root resource. When used on a method this annotation identifies a sub-resource method or locator.

Parameter, field or method

Specifies that the value of a method parameter, class field, or bean property is to be extracted from the request URI path. The value of the annotation identifies the name of a URI template parameter.

Parameter, field or method

Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI query parameter. The value of the annotation identifies the name of a query parameter.

Parameter, field or method

Specifies that the value of a method parameter is to be extracted from a form parameter in a request entity body. The value of the annotation identifies the name of a form parameter. Note that whilst the annotation target allows use on fields and methods, the specification only requires support for use on resource method parameters.

Parameter, field or method

Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI matrix parameter. The value of the annotation identifies the name of a matrix parameter.

Parameter, field or method

Specifies that the value of a method parameter, class field, or bean property is to be extracted from a HTTP cookie. The value of the annotation identifies the name of a the cookie.

Parameter, field or method

Specifies that the value of a method parameter, class field, or bean property is to be extracted from a HTTP header. The value of the annotation identifies the name of a HTTP header.

Type, constructor, method, field or parameter

Disables automatic URI decoding for path, query, form and matrix parameters.

Parameter, field or method

Specifies a default value for a field, property or method parameter annotated with @QueryParam,@MatrixParam, @CookieParam, @FormParam or @HeaderParam. The specified value will be used if the corresponding query or matrix parameter is not present in the request URI, if the corresponding form parameter is not in the request entity body, or if the corresponding HTTP header is not included in the request.

Field, method or parameter

Identifies an injection target for one of the types listed in section 5.2 or the applicable section of chapter 6.

Annotation

Specifies the HTTP method for a request method designator annotation.

Type

Specifies that the annotated class implements a JAX-RS extension interface.

Appendix B
HTTP Header Support

The following table lists HTTP headers that are directly supported, either automatically by a JAX-RS implementation runtime or by an application using the JAX-RS API. Any request header may be obtained using HttpHeaders, see section 5.2.2; response headers not listed here may set using the ResponseBuilder.header method.

Description

Used by runtime when selecting a resource method, compared to value of @Produces annotation, see section 3.5.

Processed by runtime if application uses Request.selectVariant method, see section 5.2.3.

Processed by runtime if application uses Request.selectVariant method, see section 5.2.3.

Processed by runtime if application uses Request.selectVariant method, see section 5.2.3.

Included in automatically generated 405 error responses (see section 3.7.2) and automatically generated responses to OPTIONS requests (see section 3.3.5).

Depends on container, information available via SecurityContext, see section 5.2.4.

See CacheControl class and ResponseBuilder.cacheControl method.

Response header set by application using Response.ok or ResponseBuilder.variant.

Response header set by application using Response.ok, ResponseBuilder.language, or ResponseBuilder.variant.

Processed automatically for requests, set automatically in responses if value is provided by theMessageBodyWriter used to serialize the response entity.

Request header used by runtime when selecting a resource method, compared to value of @Consumes annotation, see section 3.5. Response header either set by application using Response.ok, ResponseBuilder.type, or ResponseBuilder.variant, or set automatically by runtime (see section 3.8).

See Cookie class and HttpHeaders.getCookies method.

Included in responses automatically as per HTTP/1.1.

See EntityTag class, Response.notModified method and ResponseBuilder.tag method.

Depends on underlying container.

Set by application using the ResponseBuilder.expires method.

Processed by runtime if application uses corresponding Request.evaluatePreconditions method, see section 5.2.3.

Processed by runtime if application uses corresponding Request.evaluatePreconditions method, see section 5.2.3.

Processed by runtime if application uses corresponding Request.evaluatePreconditions method, see section 5.2.3.

Processed by runtime if application uses corresponding Request.evaluatePreconditions method, see section 5.2.3.

Set by application using the ResponseBuilder.lastModified method.

Set by application using the applicable Response method or directly using the ResponseBuilder.location method.

See NewCookie class and ResponseBuilder.cookie method.

See section 4.2.5.

Set by application using Response.notAcceptable method or ResponseBuilder.variants method.

Depends on container.

Appendix C
Change Log

C.1 Changes Since Proposed Final Draft

• Section 3.7.2: Additional sort criteria so that templates with explicit regexs are sorted ahead of those with the default.
• Sections 3.7.2, 3.8, 4.2.3 and 4.3.1: Q-values not used in @Consumes or @Produces.
• Section 4.2.2: Fixed algorithm to refer to section 3.8 instead of restating it. Fixed status code returned when the media type has been determined but an appropriate message body writer cannot be located.
• Chapter 7: Clarify that an implementation can supply an alternate RuntimeDelegate API class.

C.2 Changes Since Public Review Draft

• Chapter 2: Renamed ApplicationConfig class to Application.
• Chapter 3: UriBuilder reworked to always encode components.
• Sections 3.1.2 and 4.1.1: Added requirement to warn when choice of constructor is ambiguous.
• Section 3.2: FormParam no longer required to be supported on fields or properties.
• Section 3.3.3: Added text describing how to determine raw and generic types from method return type and returned instance.
• Section 3.4: Template parameters can specify the regular that forms their capturing group.
• Section 3.7.1: Make pre-processed URIs available rather than original request URI. Added URI normalization.
• Section 3.7.1: Removed URI-based content negotiation.
• Section 3.7.2: Reorganized the request matching algorithm to remove redundancy and improve readability, no functional change.
• Section 3.7.3: Changes to regular s to eliminate edge cases.
• Section 4.2: Added requirement to use JavaBean Activation Framework when no entity provider can be found.
• Section 4.2.4: Require standard JAXB entity providers to use application-supplied JAXB contexts in preference to their own.
• Section 4.3: Added support for specifying media type capabilities of context providers.
• Section 5.2: Removed ContextResolver from list of injectable resources.
• Section 5.2.5: Changed name to Providers, removed entity provider-specific text to reflect more generic capabilities.
• Chapter B: New appendix describing where particular HTTP headers are supported.

Bibliography

[1]    R. Fielding. Architectural Styles and the Design of Network-based Software Architectures. Ph.d dissertation, University of California, Irvine, 2000. See http://roy.gbiv.com/pubs/dissertation/top.htm.

[2]    REST Wiki. Web site. See http://rest.blueoxen.net/cgi-bin/wiki.pl.

[3]    Representational State Transfer. Web site, Wikipedia. See http://en.wikipedia.org/wiki/Representational_State_Transfer.

[4]    R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners-Lee. RFC 2616: Hypertext Transfer Protocol – HTTP/1.1. RFC, IETF, January 1997. See http://www.ietf.org/rfc/rfc2616.txt.

[5]    T. Berners-Lee, R. Fielding, and L. Masinter. RFC 3986: Uniform Resource Identifier (URI): Generic Syntax. RFC, IETF, January 2005. See http://www.ietf.org/rfc/rfc3986.txt.

[6]    L. Dusseault. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV). RFC, IETF, June 2007. See http://www.ietf.org/rfc/rfc4918.txt.

[7]    J.C. Gregorio and B. de hOra. The Atom Publishing Protocol. Internet Draft, IETF, March 2007. See http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html.

[8]    G. Murray. Java Servlet Specification Version 2.5. JSR, JCP, October 2006. See http://java.sun.com/products/servlet.

[9]    R. Chinnici, M. Hadley, and R. Mordani. Java API for XML Web Services. JSR, JCP, August 2005. See http://jcp.org/en/jsr/detail?id=224.

[10]    S. Bradner. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels. RFC, IETF, March 1997. See http://www.ietf.org/rfc/rfc2119.txt.

[11]    Bill Shannon. JavaBeans Activation Framework. JSR, JCP, May 2006. See http://jcp.org/en/jsr/detail?id=925.