Oracle® Enterprise Pack for Eclipse User's Guide
Release 12.1.3.3
E57399-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

9 REST Web Services Support

This chapter describes how to create and run web services in OEPE which conform to the Representational State Transfer (REST) architectural style using Java API for RESTful Web Services (JAX-RS).

This document contains the following sections:

9.1 Getting Started with REST Web Services

OEPE provides tools to create Representational State Transfer (REST or RESTful) projects, configure Java projects for REST and build REST web services for your projects. REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as 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.

There are a couple steps to enabling REST web services in your OEPE applications:

  1. Create a web project:

  2. Creating a REST Web Service

For complete details about developing REST web services and clients using JAX-RS, see the following Oracle documentation:

9.2 Creating Projects Configured for REST

To use REST in OEPE, first create a project that is configured to support REST (JAX-RS) services. You can do this in a couple steps using the web project wizards in the OEPE interface.

There are two types of projects that you can configure to use REST:

9.2.1 How to Create a Dynamic Web Project that is Configured for REST

When you create a dynamic web project that is configured for REST, the system adds a web.xml file and a weblogic.xml file that contain the REST servlet and servlet mapping detail that your project uses at runtime, as shown in Example 9-1 and Example 9-2.

Example 9-1 web.xml configured for REST

<display-name>REST Project</display-name>
 <servlet>
<description>JAX-RS Tools Generated - Do not modify</description>
<servlet-name>JAX-RS Servlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<load-on-startup>1</load-on-startup
 </servlet>
  <servlet-mapping>
<servlet-name>JAX-RS Servlet</servlet-name>
<url-pattern>/jaxrs/*</url-pattern>
 </servlet-mapping>
</web-app

Example 9-2 weblogic.xml configured for REST

<wls:weblogic-version>12.1.3</wls:weblogic-version
  <wls:context-root>REST_Project</wls:context-root>

To create a dynamic web project configured for REST

  1. Create a WebLogic runtime. Both Weblogic 11g and 12c versions are supported, as well as Glassfish. These steps are for Weblogic 12c. For Weblogic 11g, the wizard interface is slightly different, and adds a weblogic.xml file with a jax library reference <wls:library-name> jax-rs</wls:library-name>.

  2. In the OEPE application, choose File > New > Web > Dynamic Web Project.

  3. Click Next. The New Dynamic Web Project dialog appears, as shown in Figure 9-1. Add the project detail, and choose the target runtime. The target runtime is shown in the Configuration field.

  4. Next to the Configuration field, click Modify to choose what capabilities to enable for your project. The Project Facets dialog appears, as shown in Figure 9-2.

  5. Select JAX-RS (REST Web Services). Click OK.

  6. Click Next. The JAX-RX Capabilities dialog appears with the default servlet and container details. If you accept the defaults click Finish.


    Note:

    When you change the class or project class path in the run configuration wizard, be sure to manually stop the JAXRS application and restart it to reflect your changes. Unless it is stopped and started again, it will not reflect the changes.

    Figure 9-1 New Dynamic Web Project

    create dynamic web

    Figure 9-2 REST Project Facets

    add rest facet

9.2.2 How to Configure a Java Project for REST

To use REST with your Java web project you need to add the JAX-RS library bundle. To do this, convert your Java project to a JAX-RS faceted project.


Note:

JAX-RS tooling in a Java Project does not currently work with a Glassfish Runtime Specific Library Provider. Currently, Glassfish requires a Dynamic Web Project for deployment and to access the JAX-RS Implementation library provider.

To convert a Java project for REST

  1. Select your Java project. Right-click and choose Configure > Convert to Faceted Form.

  2. In the Facet Page select JAX-RS, and choose the appropriate runtime version, as shown in Figure 9-3.

  3. Notice the "Require Further Configuration" link highlighted in the lower part of the dialog. Click Require Further Configuration to continue to the JAX-RS Facet Install page, as shown in Figure 9-4.

  4. In the JAXRS Facet Install page, select User Library.

  5. Select the download button, or select from the previously configured user libraries available for your JAX-RS Runtime, as displayed in the libraries window. The Jersey Download is now available.

  6. Click OK.

Figure 9-3 Convert a Java Project for REST - Project Facets

convert java project

Figure 9-4 Convert a Java Project for REST - JAX-RS Capabilities

convert a java project

9.3 Creating a REST Web Service

Once you have configured your project for REST, you are ready to create your REST web service.

You can create a new REST web service class or generate a REST web service from an existing Java class using the Create RESTful Service wizard. The wizard creates the deployment files for you. After you create your web service, the final step is to deploy it.

When you create a RESTful web service, the JAX-RS Jersey library is automatically added to your REST project.

You can create are two types of REST web services in OEPE:

9.3.1 How to Create a Patterned REST Web Service

There are three options to choose from for your patterned REST web services:

  • Single Source, - Creates a root-level JAX-RS resource class with GET and PUT methods.

  • Resource/sub-resources - Creates a pair of JAX-RS resource classes. The 'item' class represents individual resources in a collection, the other class is for the container that houses the collection. If the item resource URI is determined by the client, the item class is created using the PUT method in the item class, instead of the POST method.

  • Entities Access - Creates JAX-RS compliant web services from JPA entity classes.

To create a Single Source REST web service using the wizard:

  1. In the OEPE application choose New > Other > Web Services > REST Web Service. The Web Service Pattern dialog appears, as shown in Figure 9-5.

  2. The dialog has three REST pattern types from which to choose. Choose the Single Source pattern type and click Next, if you want to configure the REST methods, or click Finish to use the defaults.

  3. If you chose Next, the Web Service Structure dialog appears with the REST Java class and the methods, as shown in Figure 9-7. You can accept the root path default or change it. Under Consumes/produces, choose the format to use to when your REST methods are consumed or produced for the root resource class. For more information see, Section 9.5, "Customizing Media Types for the Request and Response Messages".

  4. Click Next. The Rest Application Class dialog appears. Choose to accept the default, or specify the Package and Class name added to the REST configuration, which is used at runtime to locate all the web services in the project.

Figure 9-5 REST Create Patterned Web Service - Single Root Resource

single root resource

Figure 9-6 REST Create Patterned Web Service - Configure Methods

rest configure methods

To create a Resource/Sub-Resources REST web service:

  1. In the OEPE application choose New > Other > Web Services > REST Web Service. The Web Service Pattern dialog appears, as shown in Figure 9-7.

  2. The dialog has three REST pattern types from which to choose. Choose the Resource/sub-resources pattern type and click Next, to configure the REST methods, or Finish to use the defaults.

  3. If you chose Next, the Web Service Structure dialog appears with the REST Java class and the methods, as shown in Figure 9-7. You can accept the root path default or change it. Under Consumes/produces, choose the format in which you want your REST methods to be consumed or produced for the root resource class. For more information see, Section 9.5, "Customizing Media Types for the Request and Response Messages".

Figure 9-7 REST Create Patterned Web Service - Resource/sub-resources

create patterned web service

To create a Entities Access REST web service

  1. In the OEPE application choose New > Other > REST Web Service. The Web Service Pattern dialog appears.

  2. The dialog has three REST pattern types from which to choose. Choose the Entities Access pattern type and click Next, if you want to configure the REST methods, or Finish to use the defaults.

  3. If you chose Next, the Web Service Structure dialog appears with the REST Java class and the methods, as shown in Figure 9-7. You can accept the root path default or change it. Under Consumes/produces, choose the format in which you want your REST methods to be consumed or produced for the root resource class For more information see, Section 9.5, "Customizing Media Types for the Request and Response Messages".

9.3.2 How to Create a POJO REST Web Service

Once your project is configured for REST (see Section 9.2, "Creating Projects Configured for REST"), you can use annotations on your POJOs to define your REST web service URIs. You can either do this directly on the file, or using the Rest AnnotationProperties window. The @Path annotation defines the relative URI path for the resource, and can be defined as a constant or variable value (referred to as "URI path template"). You can add the @Path annotation at the class or method level.

To create REST web services in the Java source editor:

To define the URI as a constant value, pass a constant value to the @Path annotation. Preceding and ending slashes (/) are optional, as shown in Example 9-3.

Example 9-3 Using Annotations to Define the Resource Class URI as a Constant

package samples.helloworld;
import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {. . .}

In Example 9-4 shows the relative URI for the resource class defined using a variable, enclosed in braces.

Example 9-4 Using Annotations to Define the Resource Class URI as a Variable

package samples.helloworld;
import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/users/{username}")
public class helloWorld {. . .}
}

To create REST web services using the Annotation view

  1. Create a POJO.

  2. Open the Annotations view.

  3. Put Cursor on the type declaration, this will orient the available annotations to this location.

  4. Add the @Path Annotation, specify the value of your path, which is the URI for your resource class. This enable this class as a REST resource, as shown in Figure 9-8.

  5. Select applicable methods and annotate with the appropriate @Path, @Get, @Put, @Post, @Delete.

Figure 9-8 Add REST to POJO - Annotations View

add rest to pojo

9.4 Mapping Incoming Requests to Java Methods

JAX-RS uses Java annotations to map an incoming HTTP request to a Java method. The process for mapping HTTP Requests/Responses will is a function of the MediaTypes designated by the consumes/produces.

For more information on annotations and mapping, see Mapping Incoming HTTP Requests to Java Methods, in Developing and Securing RESTful Web Services for Oracle WebLogic Server.

9.4.1 How to Map an HTTP Request to Java Methods in the REST Generation Wizard

A request method designator annotations are runtime annotations, defined by JAX-RS, and which correspond to the similarly named HTTP methods. Within a resource class file, HTTP methods are mapped to Java programming language methods using the request method designator annotations. The behavior of a resource is determined by which of the HTTP methods the resource is responding to. Jersey defines a set of request method designators for the common HTTP methods: @GET, @POST, @PUT, @DELETE, @HEAD.

To map an HTTP Request to a Java method in the REST wizard

These steps assume that you have a JPA faceted project with generated entities. You will also need to have the JAX-RS facet enabled. (See Chapter 9, "Creating Projects Configured for REST".)

  1. Select File > New > Other > Web Services > Rest Web Services.

  2. Select Entities. The HTTP Type is designated given the following rules:

    • PUT- method to create or update a storage container.

    • GET - Requests data from a specified resource.

    • POST-Submits data to be processed to a specified resource.

    • DELETE-Deletes the specified resource.

    • HEAD-Same as GET but returns only HTTP headers and no document body.

  3. Open your POJO in the source editor.

  4. Open the REST Annotations View.

  5. Place your cursor on the Class Type and Specify the @Path Annotation, making this a JAX-RS.

  6. Place your cursor on the given method and add the appropriate JAX-RS request method designator annotation as defined by the HTTP type rules.

9.4.2 How to Map HTTP Requests to Java Methods in the Java Class

The javax.ws.rs.GET annotation transmits a representation of the resource identified by the URI to the client. The format or the representation returned in the response entity body cant be HTML, plain text, JPEG, or another form. Example 9-5 shows how to map an HTTP GET Request to a Java method in a class called BookmarksResource.

Example 9-5 Mapping the HTTP GET Request to a Java Method

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarksResource {
...
  @Path("{bmid: .+}")
  public BookmarkResource getBookmark(@PathParam("bmid") String bmid) {
 return new BookmarkResource(uriInfo, em,
userResource.getUserEntity(), bmid);
 }
 @GET
   @Produces("application/json")
  public JSONArray getBookmarksAsJsonArray() {
 JSONArray uriArray = new JSONArray();
for (BookmarkEntity bookmarkEntity : getBookmarks()) {
UriBuilder ub = uriInfo.getAbsolutePathBuilder();
 URI bookmarkUri = ub .
 path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
build();
  uriArray.put(bookmarkUri.toASCIIString());
}
return uriArray;
}
...
}

9.4.3 How to Map HTTP Requests to Java Methods in the Annotations View

Use the Annotations view to add your request and response requests to your POJOs.

To create REST web services using the Annotation view

  1. Create a POJO.

  2. Open the Annotations view.

  3. Put cursor on the type declaration, this will orient the available annotations to this location.

  4. For the request customization, add the @Consumes annotation and specify the value. This sets the value of the media type for that annotation. Note that when @Consumes is applied at the method level, it overrides any @Consumes annotations applied at the class level.

    For the response customization, select the @Produces annotation in the properties view. Select the appropriate media type for your response. Note: If it is applied at the method level, it overrides any @Produces annotations applied at the class level.

9.5 Customizing Media Types for the Request and Response Messages

Add the javax.ws.rs.Consumes or javax.ws.rs.Produces annotation at the class or method level of the resource to customize the media type of the request and response messages, respectively. More than one media type can be declared in each case.

With OEPE, you can customize message types for request and response using one of the following options:

9.5.1 How to Customize Media Types in the Java Source Editor

Customize media types for your REST web service by adding the @Produces or @Consumes annotation at the class or method level of the resource. Then you can input the media types values for your produces and consumes attributes, as shown in Example 9-6.

Example 9-6 Customizing the Media Types for the Response using @Produces Annotation

package samples.produces;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;

@Path("/myResource")
@Produces("text/plain")
public class GetDogTreats {
@GET
public String doGetAsPlainText() { ... }
@GET
@Produces("text/html")
public String doGetAsHtml() { ... }
}

9.5.2 How to Customize Media Types in the Annotations View for a Java Class

Use the Annotations view to add your media type annotations and properties to your Java classes.


Note:

Explicit use of the javax.ws.rs.core.MediaType String constants is not directly supported through the annotations view.

To create REST web services using the Annotations view

  1. Create a POJO.

  2. Open the Annotation view.

  3. Put cursor on the type declaration, this will orient the available annotations to this location.

  4. Add the @Consumer or the @Produces annotation, and specify the value of your annotation.

  5. Specify the resource value of your annotation. Choose from the available values for that annotation. For example @Produces("text/plain"), as shown in Figure 9-9.

    Figure 9-9 Adding Media Type REST Annotations in the Annotations View

    Annotations View Media

9.6 Validation and Quick Fix

REST services are validated based on the REST annotations present at the class, method, and method parameters level. The validation is done in the REST annotation processor.

To see the validation messages on a REST service, turn on annotation processing at the project level, through the project properties dialog. By default, annotation processing on a project is not enabled.

There is a quick fix bulb icon on the validation output window which you can select to resolve the following:

  • Issues with the values in the PathParam annotation.

  • Issues related to converting a non-public resource method to a public method.

To show annotation validations:

  1. Go to File > Properties.

  2. Select Java Compiler > Annotation Processing.

  3. Select Enable project specific settings, and Enable annotation processing.

Figure 9-10 Properties - Annotations

rest annotations

9.7 Content Assist

For annotations that require values, the Produces and Consumers annotations, for example, you can use Content Assist to show you the available options and choose your value. To use the Content Assist, from the annotations view click the Add symbol. Then select the <empty> field. This enables the value field below under Details. Click the page icon. This brings up a list of available values for that annotations shown in Figure 9-11

Figure 9-11 Content Assist Annotations Values

content assist

9.8 Run-AS JAX-RS Support

There are two types of server scenarios to run your REST projects.

  • Run on Server - deploys the REST application to the Project Targeted Runtime J2EE Server.

  • Run on a JAX-RS Resource Application - deploys to a lightweight built-in HTTP Server that designed to quickly deploy a simple JAX-RS resource.


Note:

When you change the class or project class path in the run configuration wizard, you need to manually stop the JAXRS application and start to persist changes. Unless it is stopped and started again, it will not reflect the changes.

9.8.1 How to Deploy to a Targeted Runtime J2EE Server

To use the run-as feature, your project needs to have an implementation class annotated with @Path that is packaged with a servlet specified in the web.xml deployment descriptor.

To Run-As > Run On Server to deploy to a targeted J2EE runtime:

Navigate to the implementation class, right-click and choose Run-as > Run On Server. This publishes the application to the server. Once successfully deployed, the Browser is launched with a url specified to target the application.wadl that corresponds to this packaged resource.

The targeted browser can be controlled through the Eclipse Workbench by selecting Window > Preferences > General > Web Browser.


Note:

Advanced packaging through the application subclass is not supported, as well as the. @Path REST resources specified on super types.

9.8.2 How to Deploy to a Basic HTTP Lightweight Server

Use the Run-As > JAX-RS Resource feature to run a basic HTTP Server.


Note:

The REST web service is a lightweight HTTP Server, used for running simple REST compliant POJOs. It is not a fully compliant J2EE server. For complex JAXB, JPA, EJB implementations please defer to the project target J2EE runtime container, per the steps in "How to Deploy to a Targeted Runtime J2EE Server"

To Run-AS > JAX-RS Resource Application

On your JAX-RS annotated simple POJO, right-click and select Run-As > JAX-RS Resource Application. This will launch the Jersey HTTP Server, and by default will direct the browser launch to the application.wadl. By default it uses port 8080, if this port is already in use, you can define another port by doing the following.

  1. Right-click your POJO again, and choose Run As > Run Configurations.

  2. Select the JAX-RS Application with the corresponding class name, as shown in Figure 9-12. Under the Query URL, add your port configuration, as shown in Figure 9-13.

  3. In the JAX-RS Application Run Configuration dialog, create a new configuration by selecting the project and JAX-RS annotated resource. Use the browse and search options to find your available resources.

  4. Change the default Query Url options to customize the browser target url launch behavior. Use the additional tabs to customize the Java runtime behavior, including the VM arguments, environment variables, JRE, classpath, and common.

Figure 9-12 Run Configuration - Resources

As described in surrounding text

Figure 9-13 Run Configuration - Query URL

As described in surrounding text

9.9 Generate a Java REST Client from a WADL

The Web Application Description Language (WADL) is an XML-based file format that describes your REST web services application. By default, a basic WADL is generated at runtime and can be accessed from your REST web service by adding a GET to the /application.wadl resource at the base URI of your REST application. For example: GET http://<path_to_REST_app>/application.wadl.

You can also use the options method to return the WADL for particular resource, as shown in Example 9-7.

Example 9-7 WADL Describing a REST Web Service

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
   <doc xmlns:jersey="http://jersey.dev.java.net/" 
jersey:generatedBy="Jersey: 0.10-ea-SNAPSHOT 08/27/2008 08:24 PM"/>
  <resources base="http://localhost:9998/">
  <resource path="/helloworld">
<method name="GET" id="sayHello">
 <response>
 <representation mediaType="text/plain"/>
 </response>
 </method>
 </resource>
   </resources>
</application>