Chapter 4. Application Deployment and Runtime Environments

The mechanism of feature auto-discovery in Jersey that described above is enabled by default. It can be disabled by using special (common/server/client) properties:

For each of these properties there is a client/server counter-part that is only honored by the Jersey client or server runtime respectively (see ClientProperties/ServerProperties). When set, each of these client/server specific auto-discovery related properties overrides the value of the related common property.

Java based HTTP servers represent a minimalistic and flexible way of deploying Jersey application. The HTTP servers are usually embedded in the application and configured and started programmatically. In general, Jersey container for a specific HTTP server provides a custom factory method that returns a correctly initialized HTTP server instance.

 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
ResourceConfig config = new ResourceConfig(MyResource.class);
HttpServer server = JdkHttpServerFactory.createHttpServer(baseUri, config);

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-jdk-http</artifactId>
    <version>2.13</version>
</dependency>

URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
    ResourceConfig config = new ResourceConfig(MyResource.class);
    HttpServer server = GrizzlyHttpServerFactory.createHttpServer(uri, config);

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-grizzly2-http</artifactId>
    <version>2.13</version>
</dependency>

URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
    ResourceConfig config = new ResourceConfig(MyResource.class);
    SimpleContainer server = SimpleContainerFactory.create(baseUri, config);

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-simple-http</artifactId>
    <version>2.13</version>
</dependency>

URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
ResourceConfig config = new ResourceConfig(MyResource.class);
Server server = JettyHttpContainerFactory.createServer(baseUri, config);

<dependency>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-server</artifactId>
    <version>2.13</version>
</dependency>

Jersey integrates with any Servlet containers supporting at least Servlet 2.5 specification. Running on a Servlet container that supports Servlet API 3.0 or later gives you the advantage of wider feature set (especially asynchronous request processing support) and easier and more flexible deployment options. In this section we will focus on the basic deployment models available in any Servlet 2.5 or higher container.

In Servlet 2.5 environment, you have to explicitly declare the Jersey container Servlet in your Web application's web.xml deployment descriptor file.

<web-app>
    <servlet>
        <servlet-name>MyApplication</servlet-name>
        <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <init-param>
            ...
        </init-param>
    </servlet>
    ...
    <servlet-mapping>
        <servlet-name>MyApplication</servlet-name>
        <url-pattern>/myApp/*</url-pattern>
    </servlet-mapping>
    ...
</web-app>

Alternatively, you can register Jersey container as a filter:

<web-app>
    <filter>
        <filter-name>MyApplication</filter-name>
        <filter-class>org.glassfish.jersey.servlet.ServletContainer</filter-class>
        <init-param>
            ...
        </init-param>
    </filter>
    ...
    <filter-mapping>
        <filter-name>MyApplication</filter-name>
        <url-pattern>/myApp/*</url-pattern>
    </filter-mapping>
    ...
</web-app>

The content of the <init-param> element will vary depending on the way you decide to configure Jersey resources.

<init-param>
    <param-name>javax.ws.rs.Application</param-name>
    <param-value>org.foo.MyApplication</param-value>
</init-param>

<init-param>
    <param-name>jersey.config.server.provider.packages</param-name>
    <param-value>
        org.foo.myresources,org.bar.otherresources
    </param-value>
</init-param>
<init-param>
    <param-name>jersey.config.server.provider.scanning.recursive</param-name>
    <param-value>false</param-value>
</init-param>

<init-param>
    <param-name>jersey.config.server.provider.classnames</param-name>
    <param-value>
        org.foo.myresources.MyDogResource,
        org.bar.otherresources.MyCatResource
    </param-value>
</init-param>

Jersey uses its own ServletContainer implementation of Servlet and Servlet Filter API to intebrate with Servlet containers. As any JAX-RS runtime, Jersey provides support for Servlet containers that support Servlet specification version 2.5 and higher. To support JAX-RS 2.0 asynchronous resources on top of a Servlet container, support for Servlet specification version 3.0 or higher is required.

When deploying to a Servlet container, Jersey application is typically packaged as a .war file. As with any other Servlet application, JAX-RS application classes are packaged in WEB-INF/classes or WEB-INF/lib and required application libraries are located in WEB-INF/lib. For more details, please refer to the Servlet Specification (JSR 315).

Jersey provides two Servlet modules. The first module is the Jersey core Servlet module that provides the core Servlet integration support and is required in any Servlet 2.5 or higher container:

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet-core</artifactId>
</dependency>

To support additional Servlet 3.x deployment modes and asynchronous JAX-RS resource programming model, an additional Jersey module is required:

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet</artifactId>
</dependency>

The jersey-container-servlet module depends on jersey-container-servlet-core module, therefore when it is used, it is not necessary to explicitly declare the jersey-container-servlet-core dependency.

Note that in simple cases, you don't need to provide the deployment descriptor (web.xml) and can use the @ApplicationPath annotation, as described in Section 4.7.2.3.1, “JAX-RS application without an Application subclass” section.

Jersey supports the use of Java EE Managed beans as root resource classes, providers as well as Application subclasses.

In the code below, you can find an example of a bean, that uses a managed-bean interceptor defined as a JAX-RS bean. The bean is used to intercept calls to the resource method getIt():

@ManagedBean
@Path("/managedbean")
public class ManagedBeanResource {

    public static class MyInterceptor {
        @AroundInvoke
        public String around(InvocationContext ctx) throws Exception {
            System.out.println("around() called");
            return (String) ctx.proceed();
        }
    }

    @GET
    @Produces("text/plain")
    @Interceptors(MyInterceptor.class)
    public String getIt() {
        return "Hi managed bean!";
    }
}

CDI beans can be used as Jersey root resource classes, providers as well as Application subclasses. Providers and Application subclasses have to be singleton or application scoped.

The next example shows a usage of a CDI bean as a JAX-RS root resource class. We assume, that CDI has been enabled. The code snipped uses the type-safe dependency injection provided in CDI by using another bean (MyOtherCdiBean):

@Path("/cdibean")
public class CdiBeanResource {
    @Inject MyOtherCdiBean bean;  // CDI injected bean

    @GET
    @Produces("text/plain")
    public String getIt() {
        return bean.getIt();
    }
}

Stateless and Singleton Session beans can be used as Jersey root resource classes, providers and/or Application subclasses. You can choose from annotating the methods in the EJB's local interface or directly the method in an interface-less EJB POJO. JAX-RS specifications requires its implementors to discover EJBs by inspecting annotations on classes (or local interfaces), but not in the deployment descriptors (ejb-jar.xml). As such, to keep your JAX-RS application portable, do not override EJB annotations or provide any additional meta-data in the deployment descriptor file.

Following example consists of a stateless EJB and a local interface used in Jersey:

@Local
public interface LocalEjb {
    @GET
    @Produces("text/plain")
   public String getIt();
}

@Stateless
@Path("/stateless")
public class StatelessEjbResource implements LocalEjb {
    @Override
    public String getIt() {
        return "Hi Stateless!";
    }
}

Since GlassFish utilizes Apache Felix, an OSGi runtime comes out of the box with GlassFish. However, for security reasons, the OSGi shell has been turned off. You can however explicitly enable it either by starting GlassFish the asadmin console and creating a Java system property glassfish.osgi.start.level.final and setting its value to 3:

~/glassfish/bin$ ./asadmin
Use "exit" to exit and "help" for online help.
asadmin>

asadmin>  list-jvm-options
...
-Dglassfish.osgi.start.level.final=2
...

asadmin>  create-jvm-options --target server -Dglassfish.osgi.start.level.final=3

The second option is to change the value in the osgi.properties configuration file:

# Final start level of OSGi framework. This is used by GlassFish launcher code
# to set the start level of the OSGi framework once server is up and running so that
# optional services can start. The initial start level of framework is controlled using
# the standard framework property called org.osgi.framework.startlevel.beginning
glassfish.osgi.start.level.final=3

You can then execute the Felix shell commands by typing osgi <felix_command> in the asadmin console. For example:

asadmin> osgi lb
... list of bundles ...

or launching the shell using osgi-shell command in the admin console (the domain must be started, otherwise the osgi shell won't launch):

asadmin> osgi-shell
Use "exit" to exit and "help" for online help.
gogo$

and execute the osgi commands directly (without the "osgi" prefix):

gogo$ lb
... list of bundles ...

As mentioned above, WAB is just an OSGi-fied WAR archive. Besides the usual OSGi headers it must in addition contain a special header, Web-ContextPath, specifying the web application context path. Our WAB has (beside some other) the following headers present in the manifest:

Web-ContextPath: helloworld
Webapp-Context: helloworld
Bundle-ClassPath: WEB-INF/classese

Here, the second header is ignored by GlassFish, but may be required by other containers not fully compliant with the OSGi Enterprise Specification mentioned above. The third manifest header worth mentioning is the Bundle-ClassPath specifying where to find the application Java classes within the bundle archive. More about manifest headers in OSGi can be found in the OSGi Wiki.

For more detailed information on the example please see the WAB Example source code. This example does not package into a single war file. Instead a war and a set of additional jars is produced during the build. See the next example to see how to deploy OSGi based Jersey application to GlassFish.

You can directly install and activate the Jersey application bundle. In case of our example, you can either install the example bundle stored locally (and alternatively build from Jersey sources):

1) Build (optional)

examples$ cd osgi-http-service/bundle
bundle$ mvn clean package

You can also get the binary readily compiled from Java.net Maven Repository.

2) Install into OSGi runtime:

gogo$ install file:///path/to/file/bundle.jar
Bundle ID: 303

or install it directly from the maven repository:

gogo$ install http://maven.java.net/content/repositories/releases/org/glassfish/jersey/examples/osgi-http-service/bundle/<version>/bundle-<version>.jar
Bundle ID: 303

Make sure to replace <version> with an appropriate version number. Which one is appropriate depends on the specific GlassFish 4.x version you are using. The version of the bundle cannot be higher than the version of Jersey integrated in your GlassFish 4.x server. Jersey bundles declare dependencies on other bundles at the OSGi level and those dependencies are version-sensitive. If you use example bundle from let's say version 2.5, but Glassfish has Jersey 2.3.1, dependencies will not be satisfied and bundle will not start. If this happens, the error will look something like this:

gogo$ lb
...
303 | Installed  |    1| jersey-examples-osgi-http-service-bundle (2.5.0.SNAPSHOT)
gogo$ start 303

org.osgi.framework.BundleException: Unresolved constraint in bundle
org.glassfish.jersey.examples.osgi-http-service.bundle [303]: Unable to resolve 308.0: missing requirement
[303.0] osgi.wiring.package; (&(osgi.wiring.package=org.glassfish.jersey.servlet)
(version>=2.5.0)(!(version>=3.0.0)))

gogo$

In the opposite scenario (example bundle version 2.3.1 and Glassfish Jersey version higher), everything should work fine.

Also, if you build GlassFish from the main trunk sources and use the example from most recent Jersey release, you will most likely be able to run the examples from the latest Jersey release, as Jersey team typically integrates all newly released versions of Jersey immediately into GlassFish.

As a final step, start the bundle:

gogo$ start 303

Again, the Bundle ID (in our case 303) has to be replaced by the correct one returned from the install command.

The example app should now be up and running. You can access it on http://localhost:8080/osgi/jersey-http-service/status . Please see HTTP Service example source code for more details on the example.

As Oracle Public Cloud is based on WebLogic server, the same applies as in the paragraph about WebLogic deployment (see Section 4.8.4.2, “Oracle WebLogic Server”). More on developing applications for Oracle Java Cloud Service can be found in this guide.