1. Developing and Securing RESTful Web Services for Oracle WebLogic Server
  2. Building, Packaging, and Deploying RESTful Web Service Applications

4 Building, Packaging, and Deploying RESTful Web Service Applications

Oracle WebLogic Server provides the components and utilities you need to package and deploy Jakarta EE web services that conform to the Representational State Transfer (REST) architectural style using the Jersey 2.x JAX-RS 2.1 reference implementation (RI).

This chapter includes the following sections:

Building RESTful Web Service Applications

You can 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.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.

Parent topic: Building, Packaging, and Deploying RESTful Web Service Applications

Packaging RESTful Web Service Applications

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

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. 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. See Packaging as a Default Resource.

Parent topic: Building, Packaging, and Deploying RESTful Web Service Applications

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. See javax.ws.rs.core.Application in the Jakarta EE 8 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. See the @ApplicationPath annotation in the Jakarta EE 8 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:

Parent topic: Packaging RESTful Web Service Applications

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.

Parent topic: Packaging RESTful Web Service Applications

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

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

Not required.

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

    See Packaging With an Application Subclass.

  • The value resources. This is the default base URI pattern for RESTful web service applications. 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 example demonstrates 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>
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 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

<servlet-name>

Set this element to the desired servlet name.

<servlet-class>

Set this element to org.glassfish.jersey.servlet.ServletContainer to delegate all Web requests to the Jersey servlet.

<init-param>

Not required.

<servlet-mapping>

Set as the base URI pattern that gets mapped to the servlet. If not specified, this value defaults to resources. 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 example demonstrates how to update the web.xml file if a class that extends javax.ws.rs.core.Application is not packaged with web.xml.

Note:

The JAX-RS Specification requires the RESTful Web Service application using the web.xml without the Application subclass for Servlet 3.0 to set the servlet-name to javax.ws.rs.Application as described in the Jersey 2.29 User Guide. The packaging method defined in this section is not supported by the JAX-RS Specification.

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>
How to Package the RESTful Web Service Application with Pre-3.0 Servlets

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

<servlet-name>

Set this element to the desired servlet name.

<servlet-class>

Set this element to org.glassfish.jersey.servlet.ServletContainer to delegate all Web requests to the Jersey servlet.

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

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

    See Packaging With an Application Subclass.

  • The value resources. This is the default base URI pattern for RESTful web service applications. 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 example demonstrates how to update the web.xml file if a 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>

Parent topic: Packaging With a Servlet

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

Parent topic: Packaging RESTful Web Service Applications

Deploying RESTful Web Service Applications

Application deployment refers to the process of making an application or module available for processing client requests in a WebLogic domain. For information about deploying a web application, see Understanding WebLogic Server Deployment in Deploying Applications to Oracle WebLogic Server.

Parent topic: Building, Packaging, and Deploying RESTful Web Service Applications