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.

This tutorial illustrates two methods for calling a Web service from within an Oracle Application Express application.

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:

  • You supply the URL to a WSDL document. The wizard then analyzes the WSDL and collects all the necessary information to create a valid SOAP message.

    The wizard provides a step where you can locate a WSDL using the Universal Description, Discovery, and Integration (UDDI) registry. A UDDI registry is a directory where businesses register their Web services. You search for the WSDL by entering either a service or business name.

  • You supply the relevant information on how to interact with the Web reference, including the SOAP request envelope, and create the Web reference manually.

This tutorial describes both methods. First, you create a Web service reference by searching a UDDI registry. After that, you create a second 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, as shown in Figure 7-1.

    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.

Searching a UDDI Registry

In this exercise, you create a Web service reference by searching a UDDI registry for a service name. Then, you create a form and report for displaying movie theaters and locations.

Note:

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

To create a new Web service by searching for a service name:

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

    The Shared Components page appears.

  2. Under Logic, select Web Service References.

    The Web Service References page appears.

  3. Click Create.

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

  5. For UDDI Location, select XMethods UDDI v2 and click Next.

  6. For Search, specify the following:

    1. Search Type - Select Service Name.

    2. Name - Enter ignyte and click Search.

    3. Under Matching Services, select Ignyte's Retrieve Theaters and Movie Showtimes.

    4. Click Next.

    A summary page appears, describing the selected Web service.

  7. Review your selections and click Next.

    The WSDL Location field displays the URL to the WSDL document.

  8. Accept the defaults, and click Finish. Note that since this service does not require authentication, you do not need to enter your user name and password.

The Create Web Service Reference page appears. The Web service reference, 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-2 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-2 Theater Information Form and Report without Data

    Description of Figure 7-2 follows
    Description of "Figure 7-2 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-3. The report lists the names and addresses of movie theaters matching the entered ZIP code and radius.

    Figure 7-3 Theater Information Report Showing Resulting Data

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

Creating a Web 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 Reference Manually

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

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 (such as 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 (such as http://www.ignyte.com/whatsshowing/GetTheatersAndMovies)

  11. Locate the SOAP request envelope:

    1. Go to a Web services tool, such as Mindreef:

      http://www.mindreef.net/tide/scopeit/start.do?referer=xmethods&url=http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl
      
      
    2. Click the Invoke tab and then click GetTheatersAndMovies.

    3. In the Message Envelope section in Mindreef:

      - Enter #ZIP# in the xs:string tns:zipCode field.

      - Enter #RADIUS# in the xs:int tns:radius field.

      Later, you will create two items on a page: ZIP Code and Radius. When this service is called, the values entered for the two items will be sent with the request.

    4. Click Preview/Edit on the Invoke page of Mindreef. This shows the SOAP request envelope with the parameters defined by the values you entered.

      At the time of this release, the following appeared after the HTTP Authentication region on the page:

      <?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>
      
      
  12. In the SOAP Envelope field on the Create/Edit Web Reference page, enter the xml code that appeared after the HTTP Authentication region on the page (such as the code shown in Step 11d).

  13. 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-4.

    Figure 7-4 Create/Edit Web Service Page

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

  14. 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.

  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 Movie Information 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 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 ZIPCODE.

    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 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.

    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 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 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-5.

      Figure 7-5 Movie Information Form with No Data

      Description of Figure 7-5 follows
      Description of "Figure 7-5 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.