This chapter describes how to package and deploy WebLogic Web services that conform to the Representational State Transfer (REST) architectural style using Java API for RESTful Web Services (JAX-RS).
This chapter includes the following topics:
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. For more information about deploying a Web application, see "Understanding WebLogic Server Deployment" in Deploying Applications to Oracle WebLogic Server.
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 |
|
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 about javax.ws.rs.core.Application, see the Javadoc at http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Application.html.
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 defined 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 about the @ApplicationPath annotation, see the Javadoc at: http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/ApplicationPath.html.
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;
}
}
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.
Note:
If you are running a Web application that uses pre-3.0 Servlets, see Packaging With a Servlet. This section applies only to Web applications running Servlets 3.0.
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-1.
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. |
|
|
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>
|
|
|
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>
<display-name>My JAX-RS Servlet</display-name>
<servlet-name>jersey.samples.MyApplication</servlet-name>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>myPackage.myJaxRsApplication</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>MyJaxRsApp</servlet-name>
<url-pattern>/*</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 one of the following classes to delegate all Web requests to the Jersey servlet:
|
|
|
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>
|
|
|
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>RestServlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>RestServlet</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 one of the following classes to delegate all Web requests to the Jersey servlet:
|
|
|
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 declare the packages in your application, as follows:
<init-param>
<param-name>
com.sun.jersey.config.property.packages
</param-name>
<param-value>
project1
</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>
<display-name>My JAX-RS Servlet</display-name>
<servlet-name>javax.ws.rs.core.Application</servlet-name>
<servlet-class>weblogic.jaxrs.server.portable.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
<param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
</init-param>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>project1</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