In the web services world, REpresentational State Transfer (REST) is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs. The HTTP methods such as GET and POST are the verbs that the developer can use to describe the necessary create, read, update, and delete (CRUD) actions to be performed. Conforming to the REST constraints is referred to as being ‘RESTful’.

This tutorial illustrates how to implement the REST architecture using Oracle JDeveloper 11g 11.1.2. It shows how to create a REST service from simple Java classes and then shows you how to consume and interact with a REST service from an ADF Web application through the use of the URL Service Data Controls.

show more or lessRead more...
Purpose Duration Application
This tutorial describes how to implement the REST architecture with JDeveloper. You see how to make a set of POJO classes REST compliant using the JAX-RS- library. Then, running the REST service in WebLogic server, you create ADF URL data controls for the Get, and Delete methods. Then, in a jsf page you use these data controls to experiment with your REST methods in your page..

To see the complete applications you will create, click the Download button to download the zip file of the finished applications, and unzip it to c:\temp folder.
45 minutes Download My First Application Solution.zip
Step 1: Launch the Starter Application
In this step, you upload an application containing components for the web service architecture.
  1. To download the Rest.zip file right click the following link and choose Save Link As... from context to download the file on a local directory of your choice.

  2. Unzip the Rest.zip file on a local directory of your choice (i.e. temp)

  3. Start JDeveloper by selecting Start > Programs > Oracle Fusion Middleware 11.1.2.0.0 > JDeveloper Studio 11.1.2.0.0

    Programs menu

    If a dialog box opens asking if you would like to import preferences from a previous JDeveloper installation, click NO.

  4. In the Select Role dialog, choose Studio Developer and click OK.

    Role selection
  5. Shaping, which is based on the role of the user, allows the JDeveloper environment to tailor itself. It does this by removing unneeded items from the menus, preferences, new gallery, and even individual fields on dialogs. Show more or lessRead more...

    Close the Tip of the Day window.

    Once loaded, the JDeveloper IDE appears. Show more or lessRead more...
  6. Click the Open Application link (or from the tool menu, choose File | Open).

    The Open Application link
  7. Locate the workspace Rest.jws where you've unzipped the Rest.zip file. i.e.: c:\temp\Rest.

    The Open Application dialog.
  8. Expand RestServiceProject to discover the existing components.

    The project contains a Java class called Emp that defines the data structure that we are working with, and another class called Service that provides various methods on the Emp object such as adding and deleting instances of the object.

    The Open Application dialog.

  9. REST-style architectures consist of clients and servers. Show more or lessRead more...
  10. To add the Jersey library, right-click RestServiceProject and select Project Properties from context .

    The Open Application dialog.
    To make your project REST compliant, you need to add the Jersey library. Show more or lessRead more...
  11. In the Project Properties dialog, select the Libraries and Classpath node and click the Add/JAR/Directory.

    The Open Application dialog.
  12. Expand the Rest | RestServiceProject | public_html | Jersey | directory nodes where you installed the Rest application and select the lib folder.

    The Open Application dialog.

    Click Select.

  13. Back to the Project Properties dialog, the new library has been added, click OK. Then save all your work.

    The Open Application dialog.
    JAX-RS: Java API for RESTful Web Services is a Java programming language API that provides support in creating web services according to the Representational State Transfer (REST) architectural style.Show more or lessRead more...
Step 2: Integrate REST Annotations to Resource and Service Classes
In this step, you refine the resource and service classes with REST annotations.

To turn your POJO and WebService into REST supporting services you'll use annotations. You are going to map specific methods in your code to specific REST operations by adding the appropriate annotation. We'll also see how annotations are used to map parameters on the request URL to be used in the service.

To make your classes REST compliant, perform the following steps:

  1. Double click the Emp.java node to open the POJO class in the java code editor and explore its code.
    The Emp class is a standard data transfer object with all the getters and setters for an employee object. Later you'll add a tooString method to provide an XML string to represent this object at runtime.

    The Open Application dialog.


    The REST architectural style describes the following six constraints applied to the architecture, while leaving the implementation of the individual components free to design.Show more or lessRead more...


  2. Right above the class definition add the @XmlRootElement annotation statement which defines the root element for a XML tree.

    The Open Application dialog.
  3. As requested, press the Alt + Enter keys combination to populate the required import statement.

    The Open Application dialog.
  4. At the bottom of the class, add the following method that returns a displayable string for an employee. Then save all your work.

    public String toString(){
    String empXml = "<name>"+getName()+"</name>"+"\n"+
    "<id>"+getId()+"</id>"+"\n"+
    "<experience>"+getExp()+"</experience>"+"\n"+
    "<salary>"+getSalary()+"</salary>";
    return empXml;
    }

    The Open Application dialog.
  5. Double click Service.java to open the web service class and explore its code.
    The Service class is a class with the CRUD methods using annotation. In the next few steps, you'll add annotations to bind consumer methods to HTTP methods.

    Also included in the class is a collection that is defined as a static java collection (static ArrayList<Emp>).
    It adhears to the Singleton design pattern. It indicates there is a single class of this type and there will only ever be one instance of this array in memory. This allows the class to employ stateful behavior.

    Start page
  6. Prior to the Class definition, enter the following annotation: @Path("/restlab"). The complete path to a web service resource is now based on the base URL and the @Path annotation from your class.

    Start page
  7. Click the light bulb in the margin and select the Configure Project for JAX-RS Web Services option.

    Start page
  8. While configuring the project with this option, the web.xml and the weblogic.xml files have been created
    Close the weblogic.xml tab and looking at the Service.java entry in the Application Navigator, notice that the icon next to the name has changed. The class is now recognized as a web service class type.
    Save all your work.

    Start page
  9. In the Service.java class, above the //Read comment, add the @GET annotation syntax which Indicates that the following method will answer to a HTTP GET request.

    Start page

    Press the Alt + Enter key combination to add the proposed import statement.

  10. Just after the @GET annotation, add @Produces("application/xml"). @Produces defines which MIME type is delivered by a method annotated with @GET.

    Start page

    Press the Alt + Enter key combination to add the proposed import statement.

  11. Change the signature of the addEmp method from:
    public void addEmp(int id, int exp, String name, int sal){
    to:
    public void addEmp(@QueryParam("id") int id, @QueryParam("exp")int exp, @QueryParam("name") String name, @QueryParam("sal")int sal) {

    Start page

    The @QueryParam is a parameter that is used in the URL and map to the id variable name.
    Press the Alt + Enter key combination to add the proposed import statement. Save all your work.

  12. Just above the //DELETE comment, add @DELETE annotation.

    Start page

    Press the Alt + Enter key combination to add the proposed import statement.

  13. Change the signature for the deleteEmp method adding the @QueryParam annotation:
    public void deleteEmp(@QueryParam("id") int id) {

    Start page
  14. After the Helper Methods comment, add the following annotation and methods to populate employee records.

    @PUT
    @Path("defaultEmp")
    public Response addEmp(){
    loe.add(new Emp("Adderley",1,5,1000));
    loe.add(new Emp("Coltrane",2,6,2000));
    loe.add(new Emp("Davis",3,7,3000));
    return Response.ok().build();
    }

    Start page

    Press the Alt + Enter key combination to add the proposed import statements.

    Start page
  15. Verify that you have the following import statements and then save all your work.

    import java.util.*;
    import javax.ws.rs.DELETE;
    import javax.ws.rs.GET;
    import javax.ws.rs.PUT;
    import javax.ws.rs.Path;
    import javax.ws.rs.Produces;
    import javax.ws.rs.QueryParam;
    import javax.ws.rs.core.Response;

    Start page
  16. Double click the emp.xsd node to open the xml file and explore it. The XSD file (XML Schema Document) is a schema definition file, one of several XML schema languages. The XSD can be used to express a set of rules to which an XML document must conform in order to be considered 'valid' according to that schema.

    Notice the three attributes defined in the emp class (id, name & salary).

    Start page
  17. Click the Source tab to display the xml code. This representation of the file shows you the detailed definition of the schema, including the elements and element types.

    Start page
  18. Double click the emp.xsl node to open the xml file and explore its code. The XSL file (Extensible Stylesheet Language) is used to transform and render XML documents. XSL is a language for expressing style sheets. A XSL style sheet is like a CSS file, a file that describes how to display an XML document of a given type.

    Start page
  19. Click the Save All SaveAll icon on JDev main toolbar. icon on the JDeveloper menu bar to save your work.

  20. Right click RestServiceProject and select Rebuild from context.

    Start page
  21. Make sure the compilation is successful.

    Start page
Step 3: Test the Web Service
In this step, you check that the web service is responding as expected using Put Get and Delete methods. To test the web service perform the following steps:
  1. Right-click the Service.java node in the Application Navigator and select Test Web Service from context.

    Application Navigator with cursor on New Application menu option
  2. Wait for the web service to be deployed. Then the HTTP Analyzer gets uploaded.

    New Gallery with Custom Application selected
  3. Notice that the Method is already set and the GET Method is specified by default. Click the method list of values to discover all the available methods.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  4. Switch back to the Service.java class. Notice that the Get method matches the getEmps method in the Service.java class.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  5. Back in the HTTP Analyzer, click the Send Request button to retrieve the existing employees.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    No employees are returned yet, since no employees have been populated. Notice the 200 OK return status indicating that the method was successfully performed.

  6. Click the Service.java tab and locate the PUT annotation where the emps are populated. Notice that the path for the addEmp method is called defaultEmp.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  7. In the Log window, click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  8. Back to the HTTP Analyzer, add /defaultEmp at the end of the URL and select the PUT method.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    Click the Send Request button.

  9. Once again the 200 OK status indicates that the request was performed successfully, meaning that the Emps were created.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  10. In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  11. Click the Send Request button to perform the default GET method and fetch the employees previously created.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    Now, you can see that all employees defined in the PUT annotation are retrieved and displayed.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

  12. In the Log window re click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  13. To test the Delete method, at the end of the URL type: ?id=1 to indicate which specific emp to delete and choose the DELETE method from the list.
    Click the Send Request button.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    The 204 No Content status is now returned.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

  14. Back In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab
    link to re launch a new request. Notice the first emp name Adderley is displayed.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  15. Click the Send Request button with the default GET method to fetch the employees. Notice that emp #1 has been removed.

    Page 2 of the wizard with MyProject in the Name field and JavaServerFaces selected in the Avaliable technologies pane
  16. In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  17. At the end of the URL type: ?id=2 to indicate which specific emp to delete and choose the DELETE method from the list. Click the Send Request button.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  18. Back In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab
    link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  19. Click the Send Request button with the default GET method to fetch the employees. Notice that emp #2 is gone.

    Page 2 of the wizard with MyProject in the Name field and JavaServerFaces selected in the Avaliable technologies pane
  20. In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  21. At the end of the URL type: ?id=3 to indicate which specific emp to delete and choose the DELETE method from the list. Click the Send Request button.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  22. Back In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request. Click the Send Request button with the default GET method. No more emps are returned.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  23. Back in the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request. Append /defaultEmp at the end of the URL, select the PUT method and click the Send Request button. This is to repopulate the web service with employees again.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  24. Back In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request. Click the Send Request button with the default GET method. Emps have been repopulated.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    Now that the emps are populated again, you see how you can use these data in a page.

  25. Right-click any tab and select Close All from context to dismiss all opened editors.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  26. Now that the Back-end side is tested and validated, you implement the web service in a Front-end side where web service REST methods can be used as data controls and implemented in a page.

Step 4: Create a New Application
In this step, you will consume and interact with REST services from ADF based applications. You will create an ADF data control that interact with the REST service, and then we'll see how to create a Web user interface using ADF Faces that works with that REST based data control..

To create the application perform the following steps:
  1. From the down arrow, select New Application to open the New Gallery.

    Application Navigator with cursor on New Application menu option
  2. In the New Gallery, choose the Fusion Web Application (ADF) and click OK.

    New Gallery with Custom Application selectedRest
  3. In the Name your application page of the Create Fusion Web Application wizard, modify the default application name to REST_DC.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

    Click Finish.

  4. The new ADF Fusion application creates two projects. The Model project and the ViewController project.

    Page 2 of the wizard with MyProject in the Name field and JavaServerFaces selected in the Avaliable technologies pane
  5. The application is the highest level in the control structure. It is a view of all the objects you need while you are working. An application keeps track of all your projects while you are developing your Java programs.Show more or lessRead more...
  6. In the Application Navigator, projects are displayed as the second level in the hierarchy under the application. The Application Navigator should look like this:

    App Navigator with MyProject displayed.

Step 5: Create the Model Components

This step explains how to expose URL services using the ADF Model layer. A URL service can be simply a URL against which a query is posted, so that the URL can be exposed as an ADF form. For example, you can have a URL service that allows you to access employee data for your company.
With RESTFul web services, there is a natural mapping between the HTTP methods and most CRUD-like business operations that many services expose.Show more or lessRead more...
  1. Right-click the Model node in the Application Navigator and select New... from the context menu.

    App Navigator with the context menu for the project displayed and the New menu option selected
  2. The New Gallery displays. Click the All Features tab, select the Business Tier | Data Controls node as the category and choose URL Service Data Control as the Item. Then click OK.

    New Gallery with Java Class selected.
  3. The URL service data control enables you to access and consume the data stream from a specified URL. Show more or lessRead more...
  4. In the Create URL Service Data Control dialog, change the name to URL_Get, and have the Connection field set to Create New Connection.

    Create Java Class dialog with

    Click Next.

  5. REST services are web services that can be accessed using a simple HTTP URL, rather than a more complex SOAP protocol.Show more or lessRead more...
  6. In the Connection step, enter the following values:

    Name RESTConn
    URL Endpoint http://localhost:7101/
    Source Rest_lab-RestServiceProject-context-root/jersey/restlab
    Source editor displayed with skeleton class definition. Students add

    Click Next.In the Parameters step, click Next again.

  7. In the Data Format step, select XML from the drop-down list. In the new fields, enter the following values:
    XSD URL: http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/emp.xsd
    XSL URL: http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/emp.xsl

    Source editor displayed with skeleton class definition. Students add

    Click Next.

  8. In the Finish step, click the Test URL Connection button. It should return a URL successful status if the web service is up and running.

    Source editor displayed with skeleton class definition. Students add

    Click Finish.

  9. The Application Navigator now should look like the following:

    Source editor completes method declaration by adding final curly bracket. But one red marker still remains.

    Notice that the Get method created in the Data Controls accordion.

  10. The DataControls.dcx opens in the editor showing the URL_Get data control in the Data Control Registry.
    Save all your work.

    Source editor completes method declaration by adding final curly bracket. But one red marker still remains.
  11. Right-click the Model node again to create a the delete service. In the New Gallery, select the Business Tier | Data Controls node as the category and choose URL Service Data Control as the Item. Then click OK.

    Source editor with Gog Class code. Shows new return statement added:
  12. In the Data Source step of the Create URL Service Data Control, type URL_Delete as the name.
    Select RESTConn as the Connection from the drop-down list.
    Select DELETE as the Http Method.
    In the Source, enter Rest_lab-RestServiceProject-context-root/jersey/restlab?id=##id##.

    New Gallery with Java Class selected.

    Click Next.

  13. In the Parameters step, for the id parameter enter the default value 0.

    New Gallery with Java Class selected.

    Click Next.

  14. In the Data Format step, select XML as the Data Format.

    New Gallery with Java Class selected.

    Click Next.

  15. In the Finish step click the Test URL Connection button.

    New Gallery with Java Class selected.

    You should get a URL successful return status. Click Finish.
    Save your work.

  16. Open the Data Controls accordion to visualize the created data controls.
    Press the refresh icon to see the two new data controls.

    New Gallery with Java Class selected.

    In the Data Controls panel, each data control object components can create a a different type of component.Show more or lessRead more...

  17. You can also review the details of the data controls in the editor. Expand the data control nodes to examine each component created.

    New Gallery with Java Class selected.
  18. Click the Save All SaveAll icon on JDev main toolbar. icon on the JDeveloper menu bar to save your work.

Step 6: Create a JSF Page

The model project is now defined and contains the data control pointing to the web service. Now you can start building a page that implements the data controls. To do so, perform the following actions:

  1. Collapse the Model project and expand the ViewController one.

    Source editor - list of templates displayed.
  2. Right-click the ViewController node and select New from context.

    Source editor - list of templates displayed.
  3. In the New Gallery, select the Web Tier | JSF/Facelets node and select the Page item.

    Source editor - list of templates displayed.

    You can create UI pages that allow you to display and collect information using data controls created for your business services.Show more or lessRead more...

    Click OK.

  4. In the Create JSF Page dialog, type Emp as the File Name , select Facelets as the Document Type and choosing the Page Template, select the Oracle Three Column Layout.

    Source editor - list of templates displayed.

    Click OK.

  5. Wait for the page to display in the Design editor.

    Source editor - list of templates displayed.
  6. You now have a page with three facets (start - center - end). Scroll to the right and right-click in the end pane and select Delete from context since you will only use two panels.

    Source editor - list of templates displayed.
  7. In the Data Controls accordion, select the URL_Get | loadData | Return | emps | emp entry and drop it onto the center facet. From the context menu, select Table --> ADF Read-only Table

    Source editor - list of templates displayed.

    Unlike forms, tables allow you to display more than one data object from a collection at a time. Show more or lessRead more...
  8. In the Edit Table Columns, click OK to accept defaults.

    Source editor - list of templates displayed.
  9. In the Data Controls pane, select the loadData method and drop it above the af:table - t1 in the Structure pane.

    Source editor - list of templates displayed.
  10. From the context menu select ADF Button.

    Source editor - list of templates displayed.
  11. In the Structure pane, select the af:table - t1 node and move it up just above the button you just created.

    Source editor - list of templates displayed.
  12. Select the loadData button and in the Property Inspector, type Query Emps in the text field.

    Source editor - list of templates displayed.
  13. Collapse the URL_Get node and expand the URL_Delete one.

    Source editor - list of templates displayed.
  14. Select the loadData (String) entry and drop it onto the start facet.

    Source editor - list of templates displayed.
  15. Select ADF Parameter Form from context.

    Source editor - list of templates displayed.

    Instead of dropping each of the individual attributes of a collection to create a form, you can a complete form that displays or collects data for all the attributes on an object. Show more or lessRead more...
  16. In the Edit Form Fields type Emp Id in the Display Label for the id component.

    Source editor - list of templates displayed.

    Click OK.

  17. Select the loadData2 button and in the Property Inspector, enter Delete Emp as the Text.

    Source editor - list of templates displayed.
  18. Your page should look like the following:

    Source editor - list of templates displayed.
  19. Click the Save All SaveAll icon on JDev main toolbar. icon on the JDeveloper menu bar to save your work.

Step 7: Run your Page and Test

In this step, you run the page and experiment the REST methods implemented as ADF data controls. In order to test the page, the WebLogic Server must be started and the employee collection must be loaded. If your environment is not setup in this way, complete the first three steps. Otherwise you may skip them and start on number 4.
  1. Right-click the Service.java node in the Application Navigator and select Test Web Service from context.

    Application Navigator with cursor on New Application menu option
  2. In the Log window re-click the http://127.0.0.1:7101/Rest_lab-RestServiceProject-context-root/jersey/restlab link to re launch a new request.

    Create Custom App wizard first page -with MyFirstApplication in the Name field

  3. In the HTTP Analyser, a ppend /defaultEmp at the end of the URL, select the PUT method and click the Send Request button. This is to repopulate the web service with employees again.

    Create Custom App wizard first page -with MyFirstApplication in the Name field
  4. In the Application Navigator, right-click the Emp.jsf node and select Run from context.

    Source editor - list of templates displayed.
  5. Wait for the page to display in your browser.

    Source editor - list of templates displayed.

    Notice that the Emps are queried automatically displaying the existing records.

  6. In the Delete Emp section, enter a value for an existing emp id to delete. (i.e. 2).

  7. Source editor - list of templates displayed.

    Click the Delete Emp button.

  8. From the center pane, click the Query Emps button.

    Source editor - list of templates displayed.

    Notice that one of the emp has been removed from the list.

  9. In the right side pane, enter a new id value (3) and click the Delete Emp button.

  10. Source editor - list of templates displayed.
  11. Back in the center pane, click the Query Emps button. The deleted employee is now gone.

    App Navigator, context menu for Dog.java, with Make menu option selected.
  12. You can try to remove the last employee, if you wish.

You've successfully performed this REST tutorial.

Summary

In this tutorial you learned how to find your way around the JDeveloper IDE. You learned how to:

To learn more about REST and JDeveloper, refer to:

Bookmark Print Expand all | Hide all
Back to top

Did you find this page helpful?



Copyright © 2011, Oracle and/or its affiliates. All rights reserved.