Developing RESTful Web Services
You can develop RESTful Web Service by using techniques supported by Oracle Java Cloud Service - SaaS Extension.
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.
Oracle Java Cloud Service - SaaS Extension supports the following methods to enable the development of RESTful web services:
Using the Jersey JAX-RS Reference Implementation
Oracle Java Cloud Service - SaaS Extension ships with a pre-built shared library, Jersey JAX-RS RI Version 1.9, packaged as a web application, that is required to run applications that are based on the Jersey JAX-RS RI.
Summary of the Jersey JAX-RS RI Shared Library
The Jersey JAX-RS RI shared library is pre-deployed for your convenience, so you only need to reference it.
The following table describes the pre-built shared library that supports Jersey JAX-RS RI Version 1.9 web services.
| Functionality | Description |
|---|---|
|
|
Using the Jersey JAX-RS RI Shared Library
The Jersey JAX-RS RI shared library is pre-deployed for your convenience; using it is a two-step process.
To use the Jersey JAX-RS RI:
As required, you can build and deploy a more recent version of the Jersey JAX-RS RI shared libraries. Just package the library with your application archive.
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.
To configure the Web Application to use the Jersey JAX-RS RI, you need to update the following two deployment descriptor files that are associated with your application:
-
web.xml—Update to delegate web requests to the Jersey servlet. See Updating web.xml to Delegate Web Requests to the Jersey Servlet. -
weblogic.xml—Update to reference the shared library that is required by your application. SeeSummary of the Jersey JAX-RS RI Shared Libraryand Updating weblogic.xml to Reference the Shared Libraries.
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.
The following provides an example of how to update the web.xml file:
<web-app>
<servlet>
<display-name>My Jersey Application</display-name>
<servlet-name>MyJerseyApp</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>myPackage.myJerseyApplication</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>MyJerseyApp</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
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 tocom.sun.jersey.spi.container.servlet.ServletContainer. -
<init-param>element defines the class that extends thejavax.ws.rs.Application. -
<servlet-mapping>element defines the base URL pattern that gets mapped to theMyJerseyAppservlet. The portion of the URL after thehttp://<host>:<port>+<webAppName>is compared to the<url-pattern>by Oracle Java Cloud Service - SaaS Extension. If the patterns match, the servlet mapped in this element will be called.
For more information about the web.xml deployment descriptor, see web.xml Deployment Descriptor Elements in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
Updating web.xml to Set Authentication
HTTP Basic Authentication forces the server to request a user name and password from the web client and then verify that the user name and password are valid by comparing them against a database of authorized users. You can set basic authentication in web.xml as shown here:
<login-config> <auth-method>BASIC</auth-method> </login-config>
When you use basic authentication, passwords are not protected, which means that passwords sent between a client and a server on an unprotected session can be viewed and intercepted by third parties. If you want to prevent hijacking of data when BASIC is your chosen authentication method, use a user data constraint. A user data constraint (<user-data-constraint> in the deployment descriptor) forces all URL patterns and HTTP methods specified in the security constraint to be received over a protected connection, such as HTTPS. A user data constraint specifies a transport guarantee (<transport-guarantee> in the deployment descriptor). The choices for transport guarantee include CONFIDENTIAL, INTEGRAL, or NONE. If you specify CONFIDENTIAL or INTEGRAL as a security constraint, that type of security constraint applies to all requests that match the URL patterns in the web resource collection and not just to the login dialog box. If you don't want a user data constraint, you can set it to NONE, as in this example:
<security-constraint>
<display-name>index</display-name>
<web-resource-collection>
<web-resource-name>index</web-resource-name>
<url-pattern>/index.jsp</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
Updating weblogic.xml to Reference the Shared Libraries
Update the weblogic.xml file to reference the shared library that is 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 deployed shared library will be used. In Oracle Java Cloud Service - SaaS Extension, only implementation version 1.9 is deployed as shared library. You can set the <exact-match> element in the following ways:
-
You can skip adding this element all together. In this case, do not add the
<specification-version>as well. The service runtime will pick the latest implementation version, which is 1.9. -
You can add the element and set it to
false. The service runtime will pick the latest version deployed to the Oracle Java Cloud Service - SaaS Extension, regardless of what is specified in the<specification-version>of theweblogic.xmlfile. -
You can add the element and set it to
true. In this case, you have to set the<specification-version>to 1.9, otherwise deployment will fail.
The following example shows how to update the weblogic.xml file to use the Jersey JAX-RS RI Version 1.9.
<library-ref>
<library-name>jax-rs</library-name>
<specification-version>1.1</specification-version>
<implementation-version>1.9</implementation-version>
<exact-match>false</exact-match>
</library-ref>
For more information about the weblogic.xml deployment descriptor, see weblogic.xml Deployment Descriptor Elements in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
Creating JAX-RS Web Services and Clients
After you have configured your web application, you can start creating JAX-RS web services and clients.
The following sections show a simple web service and client.
A Simple RESTful Web Service
The following provides a very simple example of a RESTful web service:
package samples.helloworld;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloworld {
// Specifies that the method processes HTTP GET requests
@GET
@Path("sayHello")
@Produces("text/plain")
public String sayHello() {
return "Hello World!";
}
}
A Simple RESTful Client
The following example provides a simple RESTful client that demonstrates basic authorization, adds a header and query parameters. This sample uses classes that are provided by the Jersey JAX-RS RI specifically; they are not part of the JAX-RS standard.
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
import com.sun.jersey.api.client.filter.LoggingFilter;
.
public static void main(String s[]) throws Exception {
Client client = Client.create();
WebResource resource = client.resource("https://javas2-jcscdc.java.us2.oraclecloudapps.com/secapp/");.
//Adds query parameter
resource = resource.queryParam("param1", "value");
//Handles Basic Authentication
client.addFilter(new HTTPBasicAuthFilter("user", "pwd"));
//Logs request and response
//This is for debugging only; do not use it
//in the production instance.
client.addFilter(new LoggingFilter());
Response response = resource.header("X-custom-header","value").get(Response.class);
System.out.println(response.getStatus());
}
.