dev@jsr311.java.net

Servlet integration update

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 25 Jun 2009 11:06:23 -0400

We published the 1.1 MR before the Servlet 3 plugability work was
completed and unfortunately some of the assumptions we made then
didn't match with the final reality. In particular there's currently
no way to portably set the context path of a JAX-RS application or add
additional servlet settings like security constraints so we think we
should respin the 1.1 MR with the following text replacing the current
section 2.3.2.

-- start new text --

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 @PathPrefix
and no servlet-mapping exists for the added servlet then a new servlet
mapping is added with the value of the @PathPrefix annotation with "/
*" appended otherwise the existing mapping is used. If the Application
subclass is not annotated with @PathPrefix 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.

-- end new text --

As part of the JAX-RS 1.1 respin we also propose to add the following
related features:

(i) A new annotation @PathPrefix (or ApplicationPath ?) whose value is
a resource-wide path prefix, see above.
(ii) A default implementation of Application#getClasses which returns
an empty list to make it easier to include an Application subclass
just for the purpose of setting the path prefix.
(iii) The ability to inject an Application subclass instance into
resource classes and providers.
(iv) Dependency injection for Application subclasses.

We'll have an additional proposal for changes to the EE section 6.2 to
take account of the forthcoming managed beans spec and JSRs 299/330
once it becomes clearer what we need there.

I'm currently trying to find out the process to respin an approved-but-
not-final-MR, I'll send an update once I have more information.
Apologies for the disruption.

Marc.