This chapter describes how to package and deploy Java EE web services that conform to the Representational State Transfer (REST) architectural style using the Jersey 2.x Java API for RESTful Web Services (JAX-RS) 2.0 reference implementation (RI).
Build your RESTful web service and client applications using the compilation tools, such as Apache Ant, Maven, or your favorite IDE, such as Oracle JDeveloper. For more information, see "Overview of WebLogic Server Application Development" in Developing Applications for Oracle WebLogic Server. For more information about JDeveloper, see "Building Java Projects" in Developing Applications with Oracle JDeveloper.
All RESTful web service applications must be packaged as part of a Web application. If your web service is implemented as an EJB, it must be packaged and deployed within a WAR.
Table 4-1 summarizes the specific packaging options available for RESTful web service applications.
Table 4-1 Packaging Options for RESTful Web Service Applications
| Packaging Option | Description |
|---|---|
|
Application subclass |
Define a class that extends For more information, see Packaging With an Application Subclass. |
|
Servlet |
Update the |
|
Default resource |
If you do not configure the servlet context path in your configuration using either of the options specified above, the WebLogic Server provides a default RESTful web service application servlet context path, |
In this packaging scenario, you create a class that extends javax.ws.rs.core.Application to define the components of a RESTful web service application deployment and provides additional metadata. For more information, see javax.ws.rs.core.Application in the Java EE 7 Specification APIs.
Within the Application subclass, override the getClasses() and getSingletons() methods, as required, to return the list of RESTful web service resources. A resource is bound to the Application subclass that returns it.
Note that an error is returned if both methods return the same resource.
Use the javax.ws.rs.ApplicationPath annotation to define the base URI pattern that gets mapped to the servlet. For more information about how this information is used in the base URI of the resource, see What Happens at Runtime: How the Base URI is Constructed. For more information, see the @ApplicationPath annotation in the Java EE 7 Specification APIs.
For simple deployments, no web.xml deployment descriptor is required. For more complex deployments, for example to secure the web service or specify initialization parameters, you can package a web.xml deployment descriptor with your application, as described in Packaging With a Servlet.
Example 4-1 provides an example of a class that extends javax.ws.rs.core.Application and uses the @ApplicationPath annotation to define the base URI of the resource.
Example 4-1 Example of a Class that Extends javax.ws.rs.core.Application
import javax.ws.rs.core.Application;
javax.ws.rs.ApplicationPath;
...
@ApplicationPath("resources")
public class MyApplication extends Application {
public Set<Class<?>> getClasses() {
Set<Class<?>> s = new HashSet<Class<?>>();
s.add(HelloWorldResource.class);
return s;
}
}
Alternatively, use the following API to scan for root resource and provider classes for a specified classpath or a set of package names:
org.glassfish.jersey.server.ResourceConfig, as described in "JAX-RS Application Model" in Jersey 2.21 User Guide
The following sections describe how to package the RESTful web service application with a servlet using the web.xml deployment descriptor, based on whether your Web application is using Servlet 3.0 or earlier.
How to Package the RESTful Web Service Application with Servlet 3.0
How to Package the RESTful Web Service Application with Pre-3.0 Servlets
The web.xml file is located in the WEB-INF directory in the root directory of your application archive. For more information about the web.xml deployment descriptor, see "web.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
To package the RESTful Web Service application with Servlet 3.0, update the web.xml deployment descriptor to define the elements defined in the following sections. The elements vary depending on whether you include in the package a class that extends javax.ws.rs.core.Application.
Packaging the RESTful Web Service Application Using web.xml With Application Subclass
Packaging the RESTful Web Service Application Using web.xml Without Application Subclass
For more information about any of the elements, see "servlet" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
If a class that extends javax.ws.rs.core.Application is packaged with web.xml, then define the elements as described in Table 4-2. For an example, see Example 4-2.
Table 4-2 Packaging the RESTful Web Service Application Using web.xml With Application Subclass
| Element | Description |
|---|---|
|
|
Set this element to the fully qualified name of the class that extends |
|
|
Not required. |
|
|
Not required. |
|
|
Set as the base URI pattern that gets mapped to the servlet. If not specified, one of the following values are used, in order of precedence:
If both the For more information about how this information is used in the base URI of the resource, see What Happens at Runtime: How the Base URI is Constructed. |
The following provides an example of how to update the web.xml file if a class that extends javax.ws.rs.core.Application is packaged with web.xml.
Example 4-2 Updating web.xml for Servlet 3.0 If Application Subclass is in Package
<web-app>
<servlet>
<servlet-name>org.foo.rest.MyApplication</servlet-name>
</servlet>
...
<servlet-mapping>
<servlet-name>org.foo.rest.MyApplication</servlet-name>
<url-pattern>/resources</url-pattern>
</servlet-mapping>
...
</web-app>
If a class that extends javax.ws.rs.core.Application is not packaged with web.xml, then define the elements as described in Table 4-3.
Note:
In this scenario, you cannot support multiple RESTful web service applications.Table 4-3 Packaging the RESTful Web Service Application Using web.xml Without Application Subclass
| Element | Description |
|---|---|
|
|
Set this element to the desired servlet name. |
|
|
Set this element to |
|
|
Not required. |
|
|
Set as the base URI pattern that gets mapped to the servlet. If not specified, this value defaults to For more information about how this information is used in the base URI of the resource, see What Happens at Runtime: How the Base URI is Constructed. |
The following provides an example of how to update the web.xml file if an class that extends javax.ws.rs.core.Application is not packaged with web.xml.
Example 4-3 Updating web.xml for Servlet 3.0 If Application Subclass is Not in Package
<web-app>
<servlet>
<servlet-name>Jersey Web Application</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Jersey Web Application</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Table 4-4 describes the elements to update in the web.xml deployment descriptor to package the RESTful web service application with a pre-3.0 servlet.
Table 4-4 Packaging the RESTful Web Service Application with Pre-3.0 Servlets
| Element | Description |
|---|---|
|
|
Set this element to the desired servlet name. |
|
|
Set this element to |
|
|
Set this element to define the class that extends the
<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>
Alternatively, you can specify the packages to be scanned for resources and providers, as follows:
<init-param>
<param-name>
jersey.config.server.provider.packages
</param-name>
<param-value>
project1
</param-value>
</init-param>
<init-param>
<param-name>
jersey.config.server.provider.scanning.recursive
</param-name>
<param-value>
false
</param-value>
</init-param>
|
|
|
Set as the base URI pattern that gets mapped to the servlet. If not specified, one of the following values are used, in order of precedence:
If both the For more information about how this information is used in the base URI of the resource, see What Happens at Runtime: How the Base URI is Constructed. |
The following provides an example of how to update the web.xml file if an class that extends javax.ws.rs.core.Application is not packaged with web.xml.
Example 4-4 Updating web.xml for Pre-3.0 Servlets
<web-app>
<servlet>
<servlet-name>Jersey Web Application</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
<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>
...
</servlet>
...
</web-app>
By default, WebLogic Server defines a default RESTful web service application context path, resources. The default RESTful web service application context path is used if the following are true:
You did not update the web.xml deployment descriptor to include a Servlet mapping, as described in Packaging With a Servlet.
The @ApplicationPath annotation is not defined in the javax.ws.rs.core.Application subclass, as described in Packaging With an Application Subclass.
Note:
If a servlet is already registered at the default context path, then a warning is issued.For example, if the relative URI of the root resource class for the RESTful web service application is defined as @Path('/helloworld') and the default RESTful web service application context path is used, then the RESTful web service application resource will be available at:
http://<host>:<port>/<contextPath>/resources/helloworld
For information about deploying a Web application, see "Understanding WebLogic Server Deployment" in Deploying Applications to Oracle WebLogic Server.