Skip Headers
Oracle® Application Express Advanced Tutorials
Release 3.2

Part Number E11945-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

7 How to Implement a Web Service

Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the HTTP protocol. The service receives the request, processes it, and returns a response. You can incorporate calls to external Web services in applications developed in Oracle Application Express.

Web services in Oracle Application Express are based on SOAP (Simple Object Access Protocol). SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes.

Web services are called from within an Oracle Application Express application by:

This tutorial illustrates the later method.

Topics in this section include:

Note:

The SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)

For information about Simple Object Access Protocol (SOAP) 1.1 see:

http://www.w3.org/TR/SOAP/

See Also:

"Implementing Web Services" in Oracle Database Application Express User's Guide

About Creating Web Service References

To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. When you create the Web reference, you can follow one of these methods:

This tutorial describes the second method, creating a Web service reference manually.

Creating a New Application

First, create a new application.

To create an application:

  1. On the Workspace home page, click the Application Builder icon.

  2. On the Application Builder home page, click Create.

  3. For Method, select Create Application, and click Next.

  4. For Name:

    1. For Name - Enter Web Services.

    2. Accept the remaining defaults and click Next.

  5. Add a blank page:

    1. Under Select Page Type, accept the default, Blank.

    2. In Page Name, enter Web Services and then click Add Page.

      The new page appears in the list at the top of the page.

    3. Click Next.

  6. For Tabs, accept the default, One Level of Tabs, and click Next.

  7. For Shared Components, accept the default, No, and click Next.

  8. For Attributes, accept the default for Authentication Scheme, Language, and User Language Preference Derived From and click Next.

  9. For User Interface, select Theme 2 and click Next.

  10. Review your selections and click Create.

The Application home page appears.

Specifying an Application Proxy Server Address

If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.

To specify a proxy address:

  1. On the Application home page, click Shared Components.

  2. Under Application, click Definition.

  3. Under Name, enter the proxy server in the Proxy Server field.

  4. Click Apply Changes.

    The Application home page appears.

Creating a Web Service Reference from a WSDL

In this exercise, you create a Web service by supplying the location of a WSDL document to a Web service. You then create a form and report for displaying movie theaters and locations.

Note:

The following exercise is dependent upon the availability of the specified Web service ultimately invoked. If the Web service is unavailable, you may experience difficulties completing this exercise.

To create a new Web reference by supplying the WSDL location:

  1. On the Application home page, click Shared Components.

    The Shared Components page appears.

  2. Under Logic, select Web Service References.

  3. Click Create

  4. When prompted whether to search a UDDI registry to find a WSDL, select No and click Next.

    1. In the WSDL Location field enter:

      http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl

    2. Click Next.

      A summary page appears describing the selected Web service.

  5. Click Create Reference.

    The Create Web Service Reference page appears. The Web service reference for MovieInformation is added to the Web Service References Repository.

Create a Form and Report

Next, you need to create a page that contains a form and report to use with your Web Service Reference.

To create a form and report after creating a Web Service Reference:

  1. On the Create Web Service Reference success page, select Create Form and Report on Web Service.

  2. For Choose Service and Operation:

    1. Web Service Reference - Select MovieInformation.

    2. Operation - Select GetTheatersAndMovies.

    3. Click Next.

  3. For Page and Region Attributes:

    1. Form Region Title - Change to Theater Information.

    2. Accept the other defaults and click Next.

  4. For Input Items:

    1. For P2_ZIPCODE and P2_RADIUS, accept the default, Yes, in the Create column.

    2. For P2_ZIPCODE, change the Item Label default to ZIP Code.

    3. Click Next.

  5. For Web Service Results:

    1. Temporary Result Set Name (Collection) - Accept the default.

    2. Result Tree to Report On - Select Theater (tns:Theater).

    3. Click Next.

  6. For Result Parameters, select all the parameters and click Finish.

  7. Click Run Page.

  8. If prompted to log in, enter the user name and password for your workspace and click Login.

    A form and report resembling Figure 7-1 appear. Notice that the Theater Information Form at the top of the page contains a data entry field and a submit button, but the Results Report does not contain any data.

    Figure 7-1 Theater Information Form and Report without Data

    Description of Figure 7-1 follows
    Description of "Figure 7-1 Theater Information Form and Report without Data"

  9. To test the form, enter 43221 in the ZIP Code field and 5 in the Radius field. Then click Submit.

    The report at the bottom of the page should resemble Figure 7-2. The report lists the names and addresses of movie theaters matching the entered ZIP code and radius.

    Figure 7-2 Theater Information Report Showing Resulting Data

    Description of Figure 7-2 follows
    Description of "Figure 7-2 Theater Information Report Showing Resulting Data"

Creating a Web Service Reference Manually

In this exercise, you create a Web reference by supplying information about the Web service and using the manual facility. Manual Web references are created by visually inspecting the WSDL document as well as using a tool to determine the SOAP envelope for the Web service request.

Topics in this section include:

Create a Web Service Reference Manually

To create a Web reference manually, you will copy code from the WSDL for a service called MovieInformation.

Please note the example settings provided in the following steps are based on the MovieInformation service at the time this document was released.

To create a manual Web reference:

  1. On the Application home page, click Shared Components.

  2. Under Logic, click Web Service References.

  3. Click Create.

  4. For Search UDDI, select No and click Next.

  5. From the Tasks list on the right, click the Create Web Reference Manually link.

    The Create/Edit Web Service page appears.

  6. In the Name field, enter Movie Info.

  7. Locate the endpoint of the MovieInformation service:

    1. Open the WSDL by going to:

      http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl
      
    2. In the WSDL, find the location attribute of the soap:address element, which is a child of the port element. You can search for the following term within the code: soap:address location.

      At the time of this release, it was this attribute:

      http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx
      
  8. In the URL field on the Create/Edit Web Service page, enter the endpoint of the MovieInformation service you located. For example: http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx

  9. Locate the SOAP action for the GetTheatersAndMovies operation:

    1. If necessary, open the WSDL again. See Step 7a.

    2. In the WSDL, find the soapAction attribute of the soap:operation element, which is a child of the operation element that has a name attribute of GetTheatersAndMovies. You can search for the following term within the code: soap:operation soapAction.

      At the time of this release, it was this attribute:

      http://www.ignyte.com/whatsshowing/GetTheatersAndMovies
      
  10. In the Action field on the Create/Edit Web Service page, enter the SOAP action you located. For example: http://www.ignyte.com/whatsshowing/GetTheatersAndMovies

  11. In the SOAP Envelope field on the Create/Edit Web Reference page, enter the xml code representing the SOAP Request message. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:tns="http://www.ignyte.com/whatsshowing"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
       <soap:Body>
          <tns:GetTheatersAndMovies>
             <tns:zipCode>#ZIP#</tns:zipCode>
             <tns:radius>#RADIUS#</tns:radius>
          </tns:GetTheatersAndMovies>
       </soap:Body>
    </soap:Envelope>
    

    You can use a SOAP message generating tool, such as MindReef, to construct a valid SOAP Request for a given Web service.

  12. In the Store Response in Collection field, enter MOVIE_RESULTS. This is where the response from the Web service will be stored.

    The Create/Edit Web Service page should resemble Figure 7-3.

    Figure 7-3 Create/Edit Web Service Page

    Description of Figure 7-3 follows
    Description of "Figure 7-3 Create/Edit Web Service Page"

  13. Click Create.

    The Web Service References page appears, showing Movie Info in the list.

Test the Web Service

To test the Web service:

  1. On the Web Service References page, click the Test icon next to the Movie Info Web reference.

    The Web Services Testing page appears.

    Note View must be set to Details, otherwise the Test icon is not displayed.

  2. In the SOAP Envelope field, replace #ZIP# with 43221 and #RADIUS# with 5.

  3. Click Test.

  4. Review the Result field and note the following about the response:

    • The base node in the return envelope is called:

      GetTheatersAndMoviesResponse
      
    • The namespace for the message is:

      http://www.ignyte.com/whatsshowing
      
    • The XPath to the interesting parts of the response under the result element is:

      /GetTheatersAndMoviesResponse/GetTheatersAndMoviesResult/Theater/Movies/Movie
      
    • The interesting elements in the results are called:

      Name
      Rating
      RunningTime
      ShowTimes
      

Create a Page to Call the Manual Web Service

Next, you want to create a page to call the manual Web Service.

To create a page to call the manual Web service:

  1. Click the Application breadcrumb link.

  2. On the Application home page, click Create Page.

  3. For Page, select Blank Page and click Next.

  4. Accept the default for the Page Number and click Next.

  5. In Name, enter Find Movies and click Next.

  6. For Tabs, accept the default, No, and click Next.

  7. Click Finish.

  8. On the Success page, click Edit Page.

  9. On the Page Definition, locate the Regions section.

  10. Click the Create icon.

  11. For Region, select HTML and click Next.

  12. Select HTML as the HTML region container and click Next.

  13. In the Title field, enter Movie Information and click Next.

  14. Click Create Region.

Create a Submit Button

Next, you want to add a Submit button to the region to initiate a search from the page.

To create a Submit button:

  1. On the Page Definition, click the Create icon in the Buttons section.

  2. For Button Region, accept the default, Movie Information, and click Next.

  3. For Button Position, accept the default, Create a button in a region position, and click Next.

  4. For Button Attributes, enter SUBMIT in the Button Name and click Next.

  5. For Button Template, accept the default, Button, and click Next.

  6. For Display Properties, select Region Template Position #CREATE# from the Position list and click Next.

  7. In the Branch to Page field, select Find Movies from the list. The page number appears in the field.

  8. Click Create Button.

Create Items for ZIP Code and Radius

Next, you want to create two items where users can enter a search term.

To create the ZIP Code item:

  1. On the Find Movies Page Definition, click the Create icon in the Items section.

  2. For Item Type, select Text and click Next.

  3. For Text Control Display Type, accept the default, Text Field, and click Next.

  4. For Display Position and Name, specify the following:

    1. Item Name - Enter ZIP.

      The Movie Info Web Service Reference defines the zip code sent in the SOAP Request as #ZIP#. Therefore, this Item Name must be ZIP in order for it's value to be substituted into the SOAP Request sent to the Web Service.

    2. Region - Accept the default, Movie Information.

    3. Click Next.

  5. In the Label field, replace the existing text with ZIP Code and click Next.

  6. Click Create Item.

To create the Radius item:

  1. On the Find Movies Page Definition, click the Create icon in the Items section.

  2. For Item Type, select Text and click Next.

  3. For Text Control Display Type, accept the default, Text Field, and click Next.

  4. For Display Position and Name, specify the following:

    1. Item Name - Enter RADIUS.

      The Movie Info Web Service Reference defines the radius sent in the SOAP Request as #RADIUS#. Therefore, this Item Name must be RADIUS in order for it's value to be substituted into the SOAP Request sent to the Web Service.

    2. Region - Accept the default, Movie Information.

    3. Click Next.

  5. In the Label field, enter Radius and click Next.

  6. Click Create Item.

Create a Process to Call the Manually Created Web Reference

Next, you want to create a process that calls the manually created Web reference.

To create a process to call the manually created Web reference:

  1. On the Find Movies Page Definition, click the Create icon in the Processes section.

  2. For Process Type, select Web Services and click Next.

  3. In the Name field, enter Call Movie Info and click Next.

  4. From the Web Service Reference list, select Movie Info and click Next.

  5. In the Success Message area, enter Called Movie Info.

  6. In the Failure Message area, enter Error calling Movie Info and click Next.

  7. From the When Button Pressed list, select SUBMIT and click Create Process.

Create a Report on the Web Service Result

Next, you want to add a report that displays the results of the called Web service.

To create a report on the Web service result:

  1. On the Find Movies Page Definition, click the Create icon in the Regions section.

  2. Select Report and click Next.

  3. For Region, select Report on collection containing Web service result and click Next.

  4. In the Title field, enter Search Results and click Next.

  5. For Web Reference Type, select Manually Created and click Next.

  6. For Web Reference Information, specify the following:

    1. Web Service Reference - Select Movie Info from the list.

    2. SOAP Style - Select Document.

    3. Message Format - Select Literal.

      Note that these two attributes can be determined by manually inspecting the WSDL document for the service.

    4. Result Node Path - Enter:

      /GetTheatersAndMoviesResponse/GetTheatersAndMoviesResult/Theater/Movies/Movie
      
    5. Message Namespace - Enter:

      http://www.ignyte.com/whatsshowing
      

      Note that you reviewed both the Result Node Path and Message Namespace when testing the service.

    6. Click Next.

  7. In the first four Parameter Names, enter Name, Rating, RunningTime, and ShowTimes, and click Create SQL Report.

  8. To test the page:

    1. Click Run Page. If prompted to log in, enter your workspace user name and password. The Movie Information form appears, as shown in Figure 7-4.

      Figure 7-4 Movie Information Form with No Data

      Description of Figure 7-4 follows
      Description of "Figure 7-4 Movie Information Form with No Data"

    2. In the ZIP Code and Radius fields, enter information and click Submit.

      The results appear in the Search Results area.