This chapter describes how to develop Java EE web service clients that conform to the Representational State Transfer (REST) architectural style using Jersey 2.x Java API for RESTful Web Services (JAX-RS) 2.0 reference implementation (RI).
Note:
Support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs are deprecated in this release of WebLogic Server but are maintained for backward compatibility. For more information, see "Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)."It is recommended that you update your RESTful client applications to use the Jersey 2.x (JAX-RS 2.0 RI) client APIs as described in this chapter at your earliest convenience.
This chapter includes the following sections:
The following table summarizes a subset of the tasks that are required to develop RESTful web service clients using Jersey 2.x (JAX-RS 2.0 RI).
Table 3-1 Summary of Tasks to Develop RESTful Web Service Clients
| Task | More Information |
|---|---|
|
Create and configure an instance of the |
"Creating and configuring a Client instance" in Jersey 2.21 User Guide |
|
Target the Web resource. |
"Targeting a web resource" in Jersey 2.21 User Guide |
|
Identify resources on WebTarget. |
"Identifying resource on WebTarget" in Jersey 2.21 User Guide |
|
Invoke an HTTP request. |
"Invoking a HTTP request" in Jersey 2.21 User Guide |
For information about developing RESTful web service clients using Oracle JDeveloper, see "Creating RESTful Web Services and Clients" in Developing Applications with Oracle JDeveloper.
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 and a WebTarget defined.
The resource path is defined to access the Web resource.
The Invocation.Builder is used to send a get request to the resource.
The response is returned as a String value.
Example 3-1 Simple RESTful Web Service Client Using Jersey 2.x (JAX-RS 2.0 RI)
package samples.helloworld.client;
...
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
public class helloWorldClient{
public static void main(String[] args) {
Client client = ClientBuilder.newClient();
WebTarget target = client.target("http://localhost:7101/restservice");
WebTarget resourceWebTarget;
resourceWebTarget = target.path("resources/helloworld");
Invocation.Builder invocationBuilder;
invocationBuilder = resourceWebTarget.request(
MediaType.TEXT_PLAIN_TYPE);
Response response = invocationBuilder.get();
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));
...
}
...
}
For complete details, see "Client API" in Jersey 2.21 User Guide.
When invoking a RESTful web service from an environment that does not have Oracle Fusion Middleware or WebLogic Server installed locally, without the entire set of Oracle Fusion Middleware or WebLogic Server classes in the CLASSPATH, you can use the standalone client JAR file when invoking the web service.
The standalone RESTful web service client JAR supports basic JAX-RS client-side functionality and OWSM security policies.
To use the standalone RESTful web service client JAR file with your client application, perform the following steps:
Create a Java SE client using your favorite IDE, such as Oracle JDeveloper. For more information, see "Developing and Securing Web Services and Clients" in Developing Applications with Oracle JDeveloper.
Copy the file ORACLE_HOME/oracle_common/modules/clients/com.oracle.jersey.fmw.client.jar from the computer hosting Oracle Fusion Middleware to the client computer, where ORACLE_HOME is the directory you specified as Oracle Home when you installed Oracle Fusion Middleware.
For example, you might copy the file into the directory that contains other classes used by your client application.
Add the JAR file to your CLASSPATH.
Note:
Ensure that your CLASSPATH includes the JAR file that contains the Ant classes (ant.jar) as a subset are used by the standalone client JAR files. This JAR file is typically located in the lib directory of the Ant distribution.Configure your environment for Oracle Web Services Manager (OWSM) policies. This step is optional, required only if you are attaching OWSM security policies to the RESTful web services client.
The configuration steps required vary based on the type of policy being attached. Examples are provided below. For additional configuration requirements, see "Configuring Java SE Applications to Use OPSS" in Securing Applications with Oracle Platform Security Services.
Example: Basic Authentication
For example, to support basic authentication using the oracle/wss_http_token_client_policy security policy, perform the following steps:
Copy the jps-config-jse.xml and audit-store.xml files from the domain_home/config/fmwconfig directory, where domain_home is the name and location of the domain, to a location that is accessible to the RESTful client.
Create a wallet (cwallet.sso) in the same location that you copied the files in step 2 that defines a map called oracle.wsm.security and the credential key name that the client application will use (for example, weblogic-csf-key).
The location of the file cwallet.sso is specified in the configuration file jps-config-jse.xml with the element <serviceInstance>.For more information, see "Using a Wallet-based Credential Store" in Securing Applications with Oracle Platform Security Services.
On the Java command line, pass the following property defining the JPS configuration file copied in step 1:
-Doracle.security.jps.config=<pathToConfigFile>
For more information, see "Scenario 3: Securing a Java SE Application" in Securing Applications with Oracle Platform Security Services.
Example: SSL
For example, to support SSL policies, perform the following steps:
Copy the jps-config-jse.xml and audit-store.xml files from the domain_home/config/fmwconfig directory, where domain_home is the name and location of the domain, to a location that is accessible to the RESTful client.
On the Java command line, pass the following properties defining the JPS configuration file copied in step 1:
Define the JPS configuration file copied in step 1:
-Doracle.security.jps.config=<pathToConfigFile>
For more information, see "Scenario 3: Securing a Java SE Application" in Securing Applications with Oracle Platform Security Services.
Define the trust store containing the trusted certificates:
-Djavax.net.ssl.trustStore=<trustStore>
For more information, see "Setting Up the WebLogic Server in Case of a Java SE Application" in "Setting Up a One-Way SSL Connection to the LDAP" in Securing Applications with Oracle Platform Security Services.
Define the trust store password:
-Djavax.net.ssl.trustStorePassword=<password>