How to deploy a JAX-RS application?

Question

The JAX-RS 1.1 specification says on page 6:

If no Application subclass is present the added servlet MUST be named:

javax.ws.rs.core.Application

What is the added servlet? Could it be an arbitrary 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

Again, what is "a servlet" here?

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.

Does "the servlet added by the ContainerInitializer" mean that the servlets is added automatically? How would a configuration look like?

At the moment I use neither an Application class nor a web.xml and it works (with GlassFish 3.1). Does this deployment mechanism require a full class path scan, which could be slow with big libraries?

How to deploy on a Servlet container?

There is a confusing number of configuration options around in the web. See this example with context params in the web.xml (doesn't work for me!). What is the preferred way to deploy a JAX-RS application?

Answer 1

There are a number of options for deploying into a Java EE 6 container (more specifically a Servlet 3.0 implementation):

The simplest is:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd" version="3.0">
    <servlet>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
</web-app>

Then all the @Path and @Provider classes found in your web application will be available in the "default" JAX-RS application with a servlet URL pattern of "/rest/*".

If you have one or more classes that extends javax.ws.rs.core.Application, you can specify like so:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd" version="3.0">
    <servlet>
        <servlet-name>com.example.jaxrs.MyApplication</servlet-name>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>com.example.jaxrs.MyApplication</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
</web-app>

You may want to do the above in case you wish to only return specific sets of @Path/@Provider classes on a URL (so you could have a second MyApplication2 with a different URL pattern above).

You can also skip the whole web.xml altogether and just annotate your MyApplication class wih @ApplicationPath which will serve as the URL pattern. I would recommend keeping the web.xml in any case because you will probably have to add other information about the web application there anyway.

If you're wondering where the servlet-class comes from, it is automatically added in by the environment. You can get an idea by looking at the Servlet 3.0 ServletContext.