Skip Headers
Oracle® Fusion Middleware Developing RESTful Web Services for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24983-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Packaging and Deploying RESTful Web Services

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:

About RESTful Web Service Packaging and Deployment

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 3-1 summarizes the specific packaging options available for RESTful Web service applications.

Table 3-1 Packaging Options for RESTful Web Service Applications

Packaging Option Description

Application subclass

Define a class that extends javax.ws.rs.core.Application to define the components of a RESTful Web service application deployment and provide additional metadata. You can add a javax.ws.rs.ApplicationPath annotation to the subclass to configure the servlet context path. For more information, see Packaging With an Application Subclass.

Servlet

Update the web.xml deployment descriptor to configure the servlet and mappings. The method used depends on whether your Web application is using Servlet 3.0 or earlier. For more information, see Packaging With a Servlet.

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, resources. For more information, see Packaging as a Default Resource.


Packaging With an Application Subclass

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://download.oracle.com/javaee/6/api/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://download.oracle.com/javaee/6/api/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 3-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 3-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;
    }
}

Packaging With a Servlet

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.

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.

How to Package the RESTful Web Service Application with Servlet 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.

For more information about any of the elements, see "servlet" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Packaging the RESTful Web Service Application Using web.xml With Application Subclass

If a class that extends javax.ws.rs.core.Application is packaged with web.xml, then define the elements as described in Table 3-2. For an example, see Example 3-1.

Table 3-2 Packaging the RESTful Web Service Application Using web.xml With Application Subclass

Element Then define elements . . .

<servlet-name>

Set this element to the fully qualified name of the class that extends javax.ws.rs.core.Application. You can specify multiple servlet entries to define multiple Application subclass names.

<servlet-class>

Not required.

<init-param>

Set this element to define the class that extends the javax.ws.rs.core.Application:

<init-param>
   <param-name>
      javax.ws.rs.Application
   </param-name>
   <param-value>
      ApplicationSubclassName
   </param-value>
</init-param>

<servlet-mapping

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:

  • @ApplicationPath annotation value defined in the javax.ws.rs.core.Application subclass. For example:

    package test;
    @ApplicationPath("res")
    public class MyJaxRsApplication extends java.ws.rs.core.Application
    ...
    

    For more information, see Packaging With an Application Subclass.

  • The value resources. This is the default base URI pattern for RESTful Web service applications. For more information, see Packaging as a Default Resource.

If both the <servlet-mapping> and @ApplicationPath are specified, the <servlet-mapping> takes precedence.

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 3-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>

Packaging the RESTful Web Service Application Using web.xml Without Application Subclass

If a class that extends javax.ws.rs.core.Application is not packaged with web.xml, then define the elements as described in Table 3-3.

Note:

In this scenario, you cannot support multiple RESTful Web service applications.

Table 3-3 Packaging the RESTful Web Service Application Using web.xml Without Application Subclass

Element Description

<servlet-name>

Set this element to the desired servlet name.

<servlet-class>

Set this element to one of the following classes to delegate all Web requests to the Jersey servlet:

  • weblogic.jaxrs.server.portable.servlet.ServletContainer

  • com.sun.jersey.spi.container.servlet.ServletContainer

<init-param>

Set this element to define the class that extends the javax.ws.rs.Application:

<init-param>
   <param-name>
      javax.ws.rs.Application
   </param-name>
   <param-value>
      ApplicationSubclassName
   </param-value>
</init-param>

<servlet-mapping

Set as the base URI pattern that gets mapped to the servlet. If not specified, this value defaults to resources. For more information, see Packaging as a Default Resource.

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 3-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>

How to Package the RESTful Web Service Application with Pre-3.0 Servlets

Table 3-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 3-4 Packaging the RESTful Web Service Application with Pre-3.0 Servlets

Element Description

<servlet-name>

Set this element to the desired servlet name.

<servlet-class>

Set this element to one of the following classes to delegate all Web requests to the Jersey servlet:

  • weblogic.jaxrs.server.portable.servlet.ServletContainer

  • com.sun.jersey.spi.container.servlet.ServletContainer

<init-param>

Set this element to define the class that extends the javax.ws.rs.core.Application:

<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> 

<servlet-mapping

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:

  • @ApplicationPath annotation value defined in the javax.ws.rs.core.Application subclass. For example:

    package test;
    @ApplicationPath("res")
    public class MyJaxRsApplication extends java.ws.rs.core.Application
    ...
    

    For more information, see Packaging With an Application Subclass.

  • The value resources. This is the default base URI pattern for RESTful Web service applications. For more information, see Packaging as a Default Resource.

If both the <servlet-mapping> and @ApplicationPath are specified, the <servlet-mapping> takes precedence.

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 3-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>

Packaging as a Default Resource

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:

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