A Compatibility with Earlier Jersey/JAX-RS Releases

This appendix describes Jersey 1.x (JAX-RS 1.1 RI) features that have been deprecated or are no longer supported, but have been maintained for backward compatibility.

This appendix includes the following sections:

Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)
Support for Jersey 1.18 (JAX-RS 1.1 RI) Deployments Packaged with Pre-3.0 Servlets

Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)

Note:

Support for the client packages described in this section, including the com.sun.jersey package, its nested packages, and the weblogic.jaxrs.api.client package, is deprecated in this release of WebLogic Server.

It is recommended that you update your RESTful client applications to use the JAX-RS 2.0 client APIs at your earliest convenience. For more information, see Summary of Tasks to Develop RESTful Web Service Clients.

The Jersey 1.x server-side APIs are no longer supported. You should use the corresponding standard JAX-RS 2.0 or Jersey 2.x server APIs instead.

The following table summarizes a subset of the tasks that are required to develop RESTful web service clients. For more information about advanced tasks, see More Advanced RESTful Web Service Client Tasks.

Table A-1 Summary of Tasks to Develop RESTful Web Service Clients

Task	More Information
Create and configure an instance of the `weblogic.jaxrs.api.client.Client` class.	Creating and Configuring a Client Instance
Create an instance of the Web resource.	Creating a Web Resource Instance
Send requests to the resource. For example, HTTP requests to GET, PUT, POST, and DELETE resource information.	Sending Requests to the Resource
Receive responses from the resource.	Receiving a Response from a Resource

For information about developing RESTful web service clients using Oracle JDeveloper, see "Creating RESTful Web Services and Clients" in Developing Applications with Oracle JDeveloper.

Example of a RESTful Web Service Client

The following provides a simple example of a RESTful web service client that can be used to call the RESTful web service defined in Example 2-1, "Simple RESTful Web Service". In this example:

The Client instance is created to access the client API. For more information, see Creating and Configuring a Client Instance.
The WebResource instance is created to access the Web resource. For more information, see Creating a Web Resource Instance.
A get request is sent to the resource. For more information, see Sending Requests to the Resource.
The response is returned as a String value. For more information about receiving the response, see Receiving a Response from a Resource.

Additional examples are listed in Learn More About RESTful Web Services.

Example A-1 Simple RESTful Web Service Client Using Jersey 1.18 (JAX-RS 1.1 RI)

package samples.helloworld.client;
 
import weblogic.jaxrs.api.client.Client;
import com.sun.jersey.api.client.WebResource;
 
public class helloWorldClient {
    public helloWorldClient() {
        super();
    }
 
    public static void main(String[] args) {
        Client c = Client.create();
        WebResource resource = c.resource("http://localhost:7101/RESTfulService/jersey/helloworld");
        String response = resource.get(String.class);
        System.out.println(response);
    }
}

Creating and Configuring a Client Instance

To access the Jersey JAX-RS RI client API, create an instance of the weblogic.jaxrs.api.client.Client class.

Note:

Alternatively, you can create an instance of the com.sun.jersey.api.client.Client class.

Optionally, you can pass client configuration properties, defined in Table A-2, when creating the client instance by defining a com.sun.jersey.api.client.config.ClientConfig and passing the information to the create method. For more information, see the ClientConfig interface in the jersey-bundle 1.18 API.

Table A-2 RESTful Web Service Client Configuration Properties

Property	Description
`PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION`	Boolean value that specifies whether the client should buffer the response entity, if any, and close resources when a `UniformInterfaceException` is thrown. This property defaults to `true`.
`PROPERTY_CHUNKED_ENCODING_SIZE`	Integer value that specifies the chunked encoding size. A value equal to or less than 0 specifies that the default chunk size should be used. If not set, then chunking will not be used.
`PROPERTY_CONNECT_TIMEOUT`	Integer value that specifies the connect timeout interval in milliseconds. If the property is 0 or not set, then the interval is set to infinity.
`PROPERTY_FOLLOW_REDIRECTS`	Boolean value that specifies whether the URL will redirect automatically to the URI declared in `3xx` responses. This property defaults to `true`.
`PROPERTY_READ_TIMEOUT`	Integer value that specifies the read timeout interval in milliseconds. If the property is 0 or not set, then the interval is set to infinity.

Example A-2 provides an example of how to create a client instance.

Example A-2 Creating a Client Instance

import weblogic.jaxrs.api.client.Client;
...
    public static void main(String[] args) {
        Client c = Client.create();
...

Example A-3 provides an example of how to create a client instance and pass configuration properties to the create method.

Example A-3 Creating and Configuring a Client Instance

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
    public static void main(String[] args) {
        ClientConfig cc = new DefaultClientConfig();
        cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
        Client c = Client.create(cc);
...

Alternatively, you can configure a client instance after the client has been created, by setting properties on the map returned from the getProperties method or calling a specific setter method.

Example A-4 provides an example of how to configure a client after it has been created. In this example:

PROPERTY_FOLLOW_REDIRECTS is configured by setting the property on the map returned from the getProperties method.
PROPERTY_CONNECT_TIMEOUT is configured using the setter method.

Example A-4 Configuring a Client Instance After It Has Been Created

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
    public static void main(String[] args) {
        Client c = Client.create();
        c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
        c.setConnectTimeout(3000);
...

Example A-5 provides an example of how to configure a client instance to use basic authentication.

Example A-5 Configuring a Client Instance to Use Basic Authentication

import javax.ws.rs.core.MediaType;
 
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
...
      Client c = Client.create();
      c.addFilter(new HTTPBasicAuthFilter("weblogic", "weblogic1"));
      WebResource resource = c.resource("http://localhost:7001/management/tenant-monitoring/datasources/JDBC%20Data%20Source-0");
      String response = resource.accept("application/json").get(String.class); //application/xml
      // resource.accept(MediaType.APPLICATION_JSON_TYPE).get(String.class);
      System.out.println(response);
...

Creating a Web Resource Instance

Before you can issue requests to a RESTful web service, you must create an instance of com.sun.jersey.api.client.WebResource or com.sun.jersey.api.client.AsyncWebResource to access the resource specified by the URI. The WebResource or AsyncWebResource instance inherits the configuration defined for the client instance. For more information, see the following in the jersey-bundle 1.18 API:

Note:

Because clients instances are expensive resources, if you are creating multiple Web resources, it is recommended that you re-use a single client instance whenever possible.

Example A-6 provides an example of how to create an instance to a Web resource hosted at http://example.com/helloworld.

Example A-6 Creating a Web Resource Instance

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
    public static void main(String[] args) {\
...
        Client c = Client.create();
        WebResource resource = c.resource("http://example.com/helloWorld");
...

Example A-7 provides an example of how to create an instance to an asynchronous Web resource hosted at http://example.com/helloworld.

Example A-7 Creating an Asynchronous Web Resource Instance

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
    public static void main(String[] args) {\
...
        Client c = Client.create();
        AsyncWebResource asyncResource = c.asyncResource("http://example.com/helloWorld");
...

Sending Requests to the Resource

Use the WebResource or AsyncWebResource instance to build requests to the associated Web resource, as described in the following sections:

How to Build Requests
How to Send HTTP Requests
How to Configure the Accept Header
How to Pass Query Parameters

How to Build Requests

Requests to a Web resource are structured using the builder pattern, as defined by the com.sun.jersey.api.client.RequestBuilder interface. The RequestBuilder interface is implemented by com.sun.jersey.api.client.WebResource, com.sun.jersey.api.client.AsyncWebResource, and other resource classes.

You can build a request using the methods defined in Table A-3, followed by the HTTP request method, as described in How to Send HTTP Requests. Examples of how to build a request are provided in the sections that follow.

For more information, see the RequestBuilder methods in the jersey 1.18 bundle API.

Table A-3 Building a Request

Method	Description
`accept()`	Defines the acceptable media types. See How to Configure the Accept Header.
`acceptLanguage()`	Defines the acceptable languages using the `acceptLanguage` method.
`cookie()`	Adds a cookie to be set.
`entity()`	Configures the request entity. See How to Configure the Request Entity.
`header()`	Adds an HTTP header and value. See How to Configure the Accept Header.
`type()`	Configures the media type. See How to Configure the Request Entity.

How to Send HTTP Requests

Table A-4 list the WebResource and AsyncWebResource methods that can be used to send HTTP requests.

In the case of AsyncWebResource, a java.util.concurrent.Future<V> object is returned, which can be used to access the result of the computation later, without blocking execution. For more information, see the Future<V> interface methods in the Java Platform, Standard Edition 6 API Specification.

Table A-4 WebResource Methods to Send HTTP Requests

Method	Description
`get()`	Invoke the HTTP GET method to get a representation of the resource.
`head()`	Invoke the HTTP HEAD method to get the meta-information of the resource.
`options()`	Invoke the HTTP OPTIONS method to get the HTTP methods that the JAX-RS service supports.
`post()`	Invoke the HTTP POST method to create or update the representation of the specified resource.
`put()`	Invoke the HTTP PUT method to update the representation of the resource.
`delete()`	Invoke the HTTP DELETE method to delete the representation of the resource.

If the response has an entity (or representation), then the Java type of the instance required is declared in the HTTP method.

Example A-8 provides an example of how to send an HTTP GET request. In this example, the response entity is requested to be an instance of String. The response entity will be de-serialized to a String instance.

Example A-8 Sending an HTTP GET Request

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
         WebResource resource = c.resource("http://example.com/helloWorld");
         String response = resource.get(String.class);
...

Example A-9 provides an example of how to send an HTTP PUT request and put the entity foo:bar into the Web resource. In this example, the response entity is requested to be an instance of com.sun.jersey.api.client.ClientResponse.

Example A-9 Sending an HTTP PUT Request

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
         WebResource resource = c.resource("http://example.com/helloWorld");
         ClientResponse response = resource.put(ClientResponse.class, "foo:bar");
...

If you wish to send an HTTP request using a generic type, to avoid type erasure at runtime, you need to create a com.sun.jersey.api.client.GenericType object to preserve the generic type. For more information, see the GenericType class in jersey-bundle 1.18 API.

Example A-10 provides an example of how to send an HTTP request using a generic type using GenericType to preserve the generic type.

Example A-10 Sending an HTTP GET Request Using a Generic Type

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        List<String> list = resource.get(new GenericType<List<String>>() {});
...

How to Pass Query Parameters

You can pass query parameters in the GET request by defining a javax.ws.rs.core.MultivaluedMap and using the queryParams method on the Web resource to pass the map as part of the HTTP request.

For more information, see the MultivaluedMap interface in Java EE 6 API Specification.

Example A-11 provides an example of how to pass parameters in a GET request to a Web resource hosted at http://example.com/helloworld, resulting in the following request URI: http://example.com/base?param1=val1&param2=val2

Example A-11 Passing Query Parameters

import com.sun.jersey.api.client.WebResource;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.MultivaluedMapImpl;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        MultivaluedMap queryParams = new MultivaluedMapImpl();
        queryParams.add("param1", "val1");
        queryParams.add("param2", "val2");
        String response = resource.queryParams(queryParams).get(String.class);
...

How to Configure the Accept Header

Configure the Accept header for the request using the accept method on the Web resource.

Example A-12 provides an example of how to specify text/plain as the acceptable MIME media type in a GET request to a Web resource hosted at http://example.com/helloworld.

Example A-12 Configuring the Accept Header

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.accept("text/plain").get(String.class);
...

How to Add a Custom Header

Add a custom header to the request using the header method on the Web resource.

Example A-13 provides an example of how to add a custom header FOO with the value BAR in a GET request to a Web resource hosted at http://example.com/helloworld.

Example A-13 Adding a Custom Header

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.header("FOO", "BAR").get(String.class);
...

How to Configure the Request Entity

Configure the request entity and type using the entity method on the Web resource. Alternatively, you can configure the request entity type only using the type method on the Web resource.

Example A-14 provides an example of how to configure a request entity and type.

Example A-14 Configuring the Request Entity

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.entity(request, MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

Example A-15 provides an example of how to configure the request entity media type only.

Example A-15 Configuring the Request Entity Media Type Only

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.type(MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

Receiving a Response from a Resource

You define the Java type of the entity (or representation) in the response when you call the HTTP method, as described in How to Send HTTP Requests.

If response metadata is required, declare the Java type com.sun.jersey.api.client.ClientResponse as the response type. The ClientResponse type enables you to access status, headers, and entity information.

The following sections describes the response metadata that you can access using the ClientResponse. For more information, see ClientResponse class in jersey-bundle 1.18 API.

How to Access the Status of Request
How to Get the Response Entity

How to Access the Status of Request

Access the status of a client response using the getStatus method on the ClientResponse object. For a list of valid status codes, see ClientResponse.Status in jersey-bundle 1.18 API.

Example A-16 provides an example of how to access the status code of the response.

Example A-16 Accessing the Status of the Request

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        ClientResponse response = resource.get(ClientResponse.class);
        int status = response.getStatus();
...

How to Get the Response Entity

Get the response entity using the getEntity method on the ClientResponse object.

Example A-17 provides an example of how to get the response entity.

Example A-17 Getting the Response Entity

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        ClientResponse response = resource.get(ClientResponse.class);
        String entity = response.getEntity(String.class);
...

More Advanced RESTful Web Service Client Tasks

For more information about advanced RESTful web service client tasks, including those listed below, see the Jersey 1.18 User Guide.

Adding new representation types
Using filters
Enabling security with HTTP(s) URLConnection

Support for Jersey 1.18 (JAX-RS 1.1 RI) Deployments Packaged with Pre-3.0 Servlets

For backwards compatibility, deployments that reference the servlet classes shown in Table A-5 are supported. This table 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 A-5 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 a class that extends javax.ws.rs.core.Application is not packaged with web.xml.

Example A-18 Updating web.xml for Pre-3.0 Servlets

<web-app>
    <servlet> 
        <servlet-name>Jersey Web 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>org.foo.rest;org.bar.rest</param-value> 
        </init-param>
        ...
    </servlet>
    ...
</web-app>