Changelog for JSR 000311 - JAX-RS 1.1

This page details the accepted and deferred changes to JSR 311, documenting the changes that will go into the 1.1 revision, per Section 4.2 of the JCP 2.6 document.

This is a respin of the original 1.1 maintenance release, changes from the originally-approved 1.1 maintenance release are highlighted using red strike-through for deleted text and green for new or replacement text.

Proposed Changes

ID Category Description
C001 EE6 Rewrite section 2.3.2 Servlet as follows:

A JAX-RS application is packaged as a Web application in a .war file. The Application subclass (see section 2.1), resource classes, and providers are packaged in WEB-INF/classes, required libraries are packaged in WEB-INF/lib. Included libraries MAY also contain resource classes and providers as desired. See the Servlet specification for full details on packaging of web applications.

When using a Servlet 3 container, the Application subclass is optional. By default, all root resource classes and providers packaged in the web application MUST be included in the published JAX-RS application. An Application subclass MAY be included in a .war file to override the default behavior. If both getClasses and getSingletons return an empty list then the default set of classes MUST be used. It is RECOMMENDED that implementations support the Servlet 3 framework pluggability mechanism to enable portability between containers and to avail themselves of container-supplied class scanning facilities.

When using a non-JAX-RS aware servlet container, the servlet-class or filter-class element of the web.xml descriptor SHOULD name the JAX-RS implementation-supplied Servlet or Filter class respectively. The application-supplied subclass of Application is identified using an init-param with a param-name of javax.ws.rs.Application.

A JAX-RS application is packaged as a Web application in a .war file. The application classes are packaged in WEB-INF/classes or WEB-INF/lib and required libraries are packaged in WEB-INF/lib. See the Servlet specification for full details on packaging of web applications.

It is RECOMMENDED that implementations support the Servlet 3 framework pluggability mechanism to enable portability between containers and to avail themselves of container-supplied class scanning facilities. When using the pluggability mechanism the following conditions MUST be met:

  • If no Application subclass is present the added servlet MUST be named "javax.ws.rs.core.Application" and all root resource classes and providers packaged in the web application MUST be included in the published JAX-RS application. The application MUST be packaged with a web.xml that specifies a servlet mapping for the added servlet.
  • If an Application subclass is present and there is already a servlet defined that has a servlet initialization parameter named "javax.ws.rs.Application" whose value is the fully qualified name of the Application subclass then no new servlet should be added by the JAX-RS implementation's ContainerInitializer since the application is already being handled by an existing servlet.
  • If an application subclass is present that is not being handled by an existing servlet then the servlet added by the ContainerInitializer MUST be named with the fully qualified name of the Application subclass.  If the Application subclass is annotated with @ApplicationPath and no servlet-mapping exists for the added servlet then a new servlet mapping is added with the value of the @ApplicationPath  annotation with "/*" appended otherwise the existing mapping is used. If the Application subclass is not annotated with @ApplicationPath then the application MUST be packaged with a web.xml that specifies a servlet mapping for the added servlet. It is an error for more than one Application to be deployed at the same effective servlet mapping

In either of the latter two cases, if both Application#getClasses and Application#getSingletons return an empty list then all root resource classes and providers packaged in the web application MUST be included in the published JAX-RS application. If either getClasses or getSingletons return a non-empty list then only those classes or singletons returned MUST be included in the published JAX-RS application.

If not using the Servlet 3 framework pluggability mechanism (e.g. in a pre-Servet 3.0 container), the servlet-class or filter-class element of the web.xml descriptor SHOULD name the JAX-RS implementation-supplied Servlet or Filter class respectively. The application-supplied subclass of Application SHOULD be identied using an init-param with a param-name of javax.ws.rs.Application.

C002 EE6 Make section 6.2 Java EE Container normative and rewrite as follows:

This section describes the additional features available to an application hosted in a Java EE 6 container that supports JAX-RS.

An implementation MUST support applications packaged as described in section 2.3.2 Servlet. An implementation MUST support use of session beans as root resource classes and stateless session and singleton beans as providers in a Web application. JAX-RS annotations MAY be applied to a bean's local interface or directly to a no-interface bean.

Note: The new java:module JNDI context enables easy lookup of a bean instance given a bean local interface or class name.

In a container that also includes support for JSR-299, an implementation MUST support use of JSR-299 beans as root resource classes, providers and as an Application subclass in a Web application. Provider and Application classes MUST use application scope. JAX-RS annotations MAY be directly applied to JSR-299 beans and the JAX-RS implementation MUST use JSR-299 APIs to obtain bean instances.

This section describes the additional requirements that apply to a JAX-RS implementation when combined in a product that supports these other Java specifications:

  • In a product that also supports the Servlet specification, implementations MUST support JAX-RS applications that are packaged as a web application. Implementations MUST behave as if built using the Servlet 3 pluggability mechanism, see section 2.3.2.
  • In a product that also supports Managed Beans, implementations MUST support use of Managed Beans as root resource classes, providers and Application subclasses. In a product that also supports JSR 299, implementations MUST similarly support use of JSR299-style managed beans. Providers and Application subclasses MUST be singletons or use application scope.
  • In a product that also supports EJB, an implementation MUST support use of stateless and singleton session beans as root resource classes, providers and Application subclasses in a Web application. JAX-RS annotations MAY be applied to a bean’s local interface or directly to a no-interface bean. If an ExceptionMapper for a EJBException or subclass is not included with an application then Exceptions thrown by an EJB resource class or provider method MUST be treated as EJB application exceptions: the embedded cause of the EJBException MUST be unwrapped and processed as described in section 3.3.4.

The following additional requirements apply when using Managed Beans, JSR299-style Managed Beans or EJBs as resource classes, providers or Application subclasses:

  • Field and property injection of JAX-RS resources MUST be performed prior to the container invoking any @PostConstruct annotated method.
  • Support for constructor injection of JAX-RS resources is OPTIONAL. Portable applications MUST instead use fields or bean properties in conjunction with a @PostConstruct annotated method. Implementations SHOULD warn users about use of non-portable constructor injection.
  • Implementations MUST NOT require use of @Inject or @Resource to trigger injection of JAX-RS annotated fields or properties. Implementations MAY support such usage but SHOULD warn users about non-portability.
C003 Enhancement See Issue 55. Clarify handling of empty message bodies for standard message body readers. All bar JAXB will result in an empty (not null) object being passed to the resource method. Using the JAXB entity provider will result in a 400 client error. Add description of how to override default behavior using a custom provider.
C004 Enhancement Add a secondary key to the sort order used when looking for compatible MessageBodyWriters such that writers whose declared generic type is closer in terms of inheritance are sorted earlier than those whose declared generic type is further.
C005 Enhancement Specify that implementations should treat request messages without a specified Content-Type as application/octet-stream. The media type passed to a message body reader will never be null.
C006 Enhancement Require support for static fromString method in addition to existing valueOf method for types used as parameters in resource methods. For backwards compatibility, where both methods exist, valueOf will take precedence except for Enums where the precedence is reversed since every enum defines an implicit valueOf method that cannot be overridden.
C007 Enhancement See Issue 66. The current precondition-related methods of Request cannot support "If-None-Match: *" which is typically used to prevent a request from being acted upon if a resource already exists at the request URI. Add a new method to Request as follows:
    /**
     * Evaluate request preconditions for a resource that does not currently
     * exist. The primary use of this method is to support the {@link <a
     * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">
     * If-None-Match: *</a>} precondition.
     * 
     * @return null if the preconditions are met or a ResponseBuilder set with
     * the appropriate status if the preconditions are not met.
     * @throws java.lang.IllegalStateException if called outside the scope of
     * a request
     */
    ResponseBuilder evaluatePreconditions();
C008 Enhancement See Issue 68. As suggested in the issue, add a new base interface to the Response.Status enum and switch methods of Response and ResponseBuilder that accept a Status to take an instance of the new interface instead. This will allow developers to create new status code enums that work with the API without having to resort to int values.
C009 Enhancement Add an @OPTIONS annotation to complete the set of pre-defined method designators.
C010 Enhancement Add an @ApplicationPath annotation to allow specification of a resource-wide base URI equivalent to that in web.xml servlet-mapping element.
C011 Enhancement Add a default implementation of Application#getClasses which returns an empty set to make it easier to include an Application subclass just for the purpose of setting the path prefix.
C012 Enhancement Add the ability to inject an Application subclass instance into resource classes and providers.
C013 Enhancement Add support for injection into Application subclasses.
E001 Errata See Issue 51. Clarify that annotation inheritance applies to annotations on method parameters, not just annotations on methods.
E002 Errata See Issue 52. Fix typo in Javadoc for Response.notAcceptable(): "vaue"->"value".
E003 Errata See Issue 53. Fix Javadoc in MessageBodyReader and MessageBodyWriter to refer to Method.getGenericParameterTypes and Method.getParameterAnnotations, currently the documentation currently refers to those as being methods of Class.
E004 Errata See Issue 56. Fix typo in Javadoc for Providers.getMessageBodyReader: "written"->"read".
E005 Errata See Issue 57. Add example to Javadoc for MessageBodyReader.readFrom to illustrate difference between type and genericType. Be explicit about where null is allowed.
E006 Errata See Issue 58. Re-order Javadoc for the parameters of Providers.getMessageBodyReader and Providers.getMessageBodyWriter so that it matches parameter order.
E007 Errata See Issue 59. Fix security context description in specification to refer to principal rather than principle.
E008 Errata Fix type in CacheControl Javadoc: "empty list of cache extensions"->"empty map of cache extensions".
E009 Errata Clarify that a valueOf method in type used as a resource method parameter must return the same type.
E010 Errata Clarify that a 400 status code should be returned if an exception is raised during @FormParam-annotated parameter construction (appropriate status codes already specified for @PathParam, @QueryParam, @MatrixParam, @HeaderParam and @CookieParam).
E011 Errata Servlet filters may trigger consumption of a request body by accessing request parameters. Clarify that 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. Include a note to the effect that because the servlet APIs do not differentiate between parameters in the URI and body of a request that URI-based query parameters may be included in the entity parameter.
E012 Errata See Issue 64. Unify the javadoc for the value of @Consumes and @Produces as follows:
    /**
     * A list of media types. Each entry may specify a single type or consist
     * of a comma separated list of types. E.g. {"image/jpeg,image/gif",
     * "image/png"}. Use of the comma-separated form allows definition of a
     * common string constant for use on multiple targets.
     */
    String[] value() default "*/*";
E013 Errata Fix typo in MessageBodyReader Javadoc: "Class.getParameterAnnotations"->"Method.getParameterAnnotations".
E014 Errata See Issue 71. Fix typo in Response Javadoc: "303 See Other"->"301 Moved Permanently".

Accepted Changes

None.

Deferred Changes

None.