Changelog for JSR 000311 - JAX-RS 1.1

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.

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.

    /**
     * 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();

    /**
     * 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 "*/*";