Overview of RESTful Web Services

REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as Simple Object Access Protocol (SOAP). REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs. A client accesses the resource using the URI, a standardized fixed set of methods, and a representation of the resource is returned. The client is said to transfer state with each new resource representation.

WebLogic Server supports the following methods to enable the development of RESTful Web services:

Register and use the set of pre-built shared libraries, delivered with WebLogic Server, that are required to run Jersey JAX-RS Reference Implementation (RI). The following versions are available as pre-built shared libraries:

The Jersey JAX-RS RI provides an open source, production quality Reference Implementation for building RESTful Web services; it is recommended as a best practice over the standard JAX-WS HTTP protocol method.

Using the Jersey JAX-RS Reference Implementation

WebLogic Server ships with a set of pre-built shared libraries, packaged as Web applications, that are required to run applications that are based on the Jersey JAX-RS RI. The following versions are supported:

Jersey JAX-RS RI Version 1.9

Jersey JAX-RS RI Version 1.1.5.1

The following sections summarize the Jersey JAX-RS RI shared libraries and the steps to use them, and how to register a more recent version of the Jersey JAX-RS RI.

Table 20-2 summarizes the pre-built shared libraries that support Jersey JAX-RS RI Version 1.1.5.1 Web services, organized by the functionality that they support. The table also indicates whether the shared library is required or optional.

Table 20-2 Shared Libraries for Jersey JAX-RS RI 1.1.5.1

Functionality

Description

Required?

Jersey

Shared Library Name: jersey-bundle

JAR Filename: jersey-bundle-1.1.5.1.jar

WAR Filename: jersey-bundle-1.1.5.1.war

Version: 1.1.5.1

License: SUN CDDL+GPL

Required

JAX-RS API

Shared Library Name: jsr311

JAR Filename: jsr311-api-1.1.1.jar

WAR Filename: jsr311-api-1.1.1.war

Version: 1.1.1

License: JSR311 license

Required

JSON processing

Shared Library Name: jackson-core-asl

JAR Filename: jackson-core-asl-1.1.1.jar

WAR Filename: jackson-core-asl-1.1.1.war

Version: 1.1.1

License: Apache 2.0

Optional

JSON processing

Shared Library Name: jackson-jaxrs

JAR Filename: jackson-jaxrs-1.1.1.jar

WAR Filename: jackson-jaxrs-1.1.1.war

Version: 1.1.1

License: Apache 2.0

Optional

JSON processing

Shared Library Name: jackson-mapper-asl

JAR Filename: jackson-mapper-asl-1.1.1.jar

WAR Filename: jackson-mapper-asl-1.1.1.war

Version: 1.1.1

License: Apache 2.0

Optional

JSON streaming

Shared Library Name: jettison

JAR Filename: jettison-1.1.jar

WAR Filename: jettison-1.1.war

Version: 1.1

License: Apache 2.0

Optional

ATOM processing

Shared Library Name: rome

JAR Filename: rome-1.0.jar

WAR Filename: rome-1.0.war

Version: 1.0

License: Apache 2.0

Optional

In addition, the following table lists the dependent JARs that are available on WebLogic Server, and not required to be registered as shared libraries.

Shared Java EE libraries are registered with one or more WebLogic Server instances by deploying them to the target servers and indicating that the deployments are to be shared. Shared Java EE libraries must be targeted to the same WebLogic Server instances you want to deploy applications that reference the libraries.

When a referencing application is deployed, WebLogic Server merges the shared library files with the application. If you try to deploy a referencing application to a server instance that has not registered a required library, deployment of the referencing application fails.

Based on the functionality required by your application and the version of the Jersey JAX-RS RI that you want to use, you can register one or more of the Jersey JAX-RS shared libraries defined in Summary of the Jersey JAX-RS RI Shared Libraries, as follows:

Choose whether you want to use Version 1.9 or 1.1.5.1 of the Jersey JAX-RS RI. Based on the version you choose, refer to Table 20-2 or Table 20-1, respectively, to determine the shared libraries that are required by your application.

Determine the WebLogic Server targets to which you will register the shared libraries. Shared libraries must be registered to the same WebLogic Server instances on which you plan to deploy referencing applications. (You may consider deploying libraries to all servers in a domain, so that you can later deploy referencing applications as needed.)

Register a shared library by deploying the shared library files to the target servers identified in Step 2, and identifying the deployment as a library using the -library option.

The following shows an example of how to deploy the shared libraries that provide support for Jersey JAX-RS RI Version 1.9.

If you wish to use Jersey JAX-RS RI Version 1.1.5.1, the following shows an example of how to deploy the shared libraries that provide support for the basic Jersey JAX-RS RI functionality and JAX-RS API.

Configuring the Web Application to Use the Jersey JAX-RS RI

You need to configure the Web application that contains the RESTful Web services to use the Jersey shared libraries. Specifically, you need to update the following two deployment descriptor files that are associated with your application:

Updating web.xml to Delegate Web Requests to the Jersey Servlet

Update the web.xml file to delegate all Web requests to the Jersey Servlet, com.sun.jersey.spi.container.servlet.ServletContainer. The web.xml file is located in the WEB-INF directory in the root directory of your application archive.

As shown in the previous example, you need to define the following elements:

<servlet-class> element defines the servlet that is the entry point into the Jersey JAX-RS RI. This value should always be set to com.sun.jersey.spi.container.servlet.ServletContainer.

<init-param> element defines the class that extends the javax.ws.rs.Application.

<servlet-mapping> element defines the base URL pattern that gets mapped to the MyJerseyApp servlet. The portion of the URL after the http://<host>:<port> +<webAppName> is compared to the <url-pattern> by WebLogic Server. If the patterns match, the servlet mapped in this element will be called.

Updating weblogic.xml to Reference the Shared Libraries

Update the weblogic.xml file to reference the shared libraries that are required by your application. The weblogic.xml file is located in the WEB-INF directory in the root directory of your application archive.

The <exact-match> directive enables you to control whether the latest version of the shared libraries that are deployed will be used. If set to true, then the version specified in the weblogic.xml will be used, regardless of whether a newer version has been deployed to WebLogic Server. If set to false, then the latest version deployed to WebLogic Server will be used, regardless of what is specified in the weblogic.xml file.

For example, if you set the <exact-match> directive to false and register as a shared library a more recent version of the Jersey software, as described in Registering a More Recent Version of the Jersey JAX-RS RI, then the more recent version of the shared library will be used by your application automatically; you do not have to edit the weblogic.xml file in this case to pick up the latest version.

The following example shows how to update the weblogic.xml file to use the Jersey JAX-RS RI Version 1.9.

The following example shows how to update the weblogic.xml file to use the Jersey JAX-RS RI Version 1.1.5.1. Not all shared library references will be required for every Web application; the jersey-bundle and jsr311 shared libraries are both required to use the Jersey JAX-RS RI. In this example, <exact-match> is set to false specifying that the latest version of the shared library deployed to WebLogic Server should be used.

A Simple RESTful Client

The following provides a simple RESTful client that calls the RESTful Web service defined previously. This sample uses classes that are provided by the Jersey JAX-RS RI specifically; they are not part of the JAX-RS standard.

Registering a More Recent Version of the Jersey JAX-RS RI

If you wish to use a more recent version of the Jersey JAX-RS RI shared libraries than the version that is provided with WebLogic Server, you need to perform the following steps:

Download the required version of the relevant Jersey JAR file from the Jersey Web site at: http://jersey.java.net.

Expand the JAR file downloaded in Step 1 and create a new shared library following the steps described in "Creating Shared Java EE Libraries" in Developing Applications for Oracle WebLogic Server.

Register the shared library by deploying the shared library files to the target servers identified in Step 2, and identifying the deployment as a library using the -library option. You must do the following:

Set the -libSpecVer and -libImplVer arguments to distinguish between the different shared library versions.

The following shows an example of how to deploy the latest versions of the Jersey JAX-RS RI functionality. For more information about the weblogic.Deployer, see "weblogic.Deployer Command-Line Reference" in Deploying Applications to Oracle WebLogic Server.

If you set the <exact-match> directive to false in the weblogic.xml file when configuring your Web application, as described in Configuring the Web Application to Use the Jersey JAX-RS RI, then the shared library with the most recent specification version will be used and you do not have to update your Web application configuration.

If you set the <exact-match> directive to true or if you want to use a version of the Jersey JAX-RS RI that is not the most recent version, then you will have to update the weblogic.xml to reference the desired shared library. For more information, see Configuring the Web Application to Use the Jersey JAX-RS RI.

Redeploy any applications that needs to use the newly registered version of the Jersey JAX-RS shared library.

Programming Web Services Using XML Over HTTP

Note:

As a best practice, it is recommended that you use the Jersey JAX-RS RI shared library solution, described in Using the Jersey JAX-RS Reference Implementation. The Jersey JAX-RS RI provides an open source, production quality RI for building RESTful Web services and supports all of the HTTP methods.

When using the HTTP protocol to access Web service resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods: GET, PUT, DELETE, POST, or HEAD.

Note:

In this JAX-WS implementation, the set of supported HTTP methods is limited to GET and POST. DELETE, PUT, and HEAD are not supported. Any HTTP requests containing these methods will be rejected with a 405 Method Not Allowed error.

If the functionality of PUT and DELETE are required, the desired action can be accomplished by tunneling the actual method to be executed on the POST method. This is a workaround referred to as overloaded POST. (A Web search on "REST overloaded POST" will return a number of ways to accomplish this.

The procedure in this section describes how to program and compile the JWS file required to implement Web services using XML over HTTP. The procedure shows how to create the JWS file from scratch; if you want to update an existing JWS file, you can also use this procedure as a guide.