6 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 (the 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 how to call a Web service from within an Oracle Application Express application.

Topics in this section include:

About Creating Web Service References
Creating a New Application
Specifying an Application Proxy Server Address
Searching a UDDI Registry for a Business Name
Searching a UDDI Registry for a Service Name

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/

About Creating Web Service References

To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. Each Web service reference is based on a Web Services Description Language (WSDL) document that describes the target Web service. When you create a Web service reference, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message.

When you create a Web service reference you need to decide how to locate the WSDL. You can locate a WSDL two ways:

By searching a Universal Description, Discovery, and Integration (UDDI) registry for either a service name or business name.

A UDDI registry is a directory where businesses register their Web services.
By entering the URL to the WSDL document.

In this tutorial, you create Web service references by searching a UDDI registry.

Creating a New Application

First, create a new application.

To create an application:

On the Database Home Page, click the Application Builder icon.
When the Application Builder home page appears, click Create.
For Method, select Create Application and click Next.
For Name:
1. For Name, enter Web Services.
2. For Create Application, select From Scratch.
3. Accept the remaining defaults and click Next.
Add a blank page:
1. Under Select Page Type, select Blank as shown in Figure 6-1.
  
  Figure 6-1 Add Page
  
  Description of "Figure 6-1 Add Page"
2. In Page Name, enter Web Services and click Add Page.
  
  The new page appears in the list at the top of the page.
3. Click Next.
For Tabs, accept the default, One Level of Tabs, and click Next.
For Shared Components, accept the default and click Next.
For Attributes, accept the default for Authentication Scheme, Language, and User Language Preference Derived From and click Next.
For User Interface, select Theme 2 and click Next.
Review your selections and click Create.

The Application Builder 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 for an application:

On the Application Builder home page, click Edit Attributes.
Click Edit Standard Attributes.
Under Name, enter the proxy server in Proxy Server.
Click Apply Changes.

Searching a UDDI Registry for a Business Name

In this exercise you create a form which displays stock quotes based on a stock symbol you provide. You will create a Web service reference by searching the UDDI registry for a business name:

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 Web service reference by searching for a business name:

On Application Builder home page, click Shared Components.
Under Logic, select Web Service References.

The Web Service References page appears.
Click Create.
When prompted whether to search a UDDI registry to find a WSDL, select Yes and click Next.
For UDDI Location, select IBM UDDI and click Next.
On Search:
1. For Search Type, select Business Name.
2. In Name, enter:
```
%xMethods%
```
3. Click Search.
  
  Matching Services appear.
4. Under Matching Services, select xMethods Delayed Stock Quotes.
5. Click Next.
A summary page appears describing the selected Web service.
Review your selection and click Next to continue.

The URL to the WSDL document displays in the WSDL Location field.
Click Finish.

Create a Form to Display a Stock Quote

Next, you create a form to display a stock quote based on the stock symbol you provide.

To create a form after creating a Web Service Reference:

On the Create Web Service Reference page, click Create Form on Web Service.
On Web Service Reference and Operation:
1. For Web Service Reference, select XMethods Delayed Stock Quotes.
2. For Operation, select getQuote.
3. Click Next.
For Page and Region Attributes:
1. For Page and Page Name, accept the defaults.
2. In Region Title, enter Get Stock Quote.
3. For Region Template, accept the default.
4. Click Next.
For Input Items, accept the defaults and click Next.
For Output Items:
1. For Item Label, enter Stock Price.
2. Accept the other defaults.
3. Click Finish.
Click Run Page to view the form.
On the Log in page, enter the User Name and Password for your database user account and click Login.

A form resembling Figure 6-2 appears.

Figure 6-2 Get Stock Quote Form

Description of "Figure 6-2 Get Stock Quote Form"
Test the form. In Symbol, enter a stock symbol (such as ORCL) and click Submit.

The associated stock price displays in the Stock Price field.
Click Edit Application on the Developer toolbar to return to the Application Builder home page.

Searching a UDDI Registry for a Service Name

Next, you create a form that displays market futures. 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.

Note:

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

Navigate to the Application Builder home page.
Click Shared Components.

The Shared Components page appears.
Under Logic, select Web Service References.

The Web Service References page appears.
Click Create.
When prompted whether to search a UDDI registry to find a WSDL, select Yes and click Next.
For UDDI Location, select XMethods UDDI and click Next.
For Search:
1. For Search Type, select Service Name.
2. In Name, enter xignite and click Search.
  
  This is a search engine for market news.
3. Under Matching Services, select XigniteFutures.
4. Click Next.
A summary page appears describing the selected Web service.
Review your selection and click Next to continue.

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

The Web service reference, XigniteFutures, 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 create a form and report after creating a Web Service Reference:

On the Create Web Service Reference page, select Create Form and Report on Web Service.
For Choose Service and Operation:
1. For Web Service Reference, select XigniteFutures.
2. For Operation, select ListFuturesByExchange.
3. Click Next.
For Page and Region Attributes:
1. Change Form Region Title to List Futures By Exchange.
2. Accept the other defaults and click Next.
For Input Items:
1. For P2_USERNAME, P2_PASSWORD, P2_TRACER, select No in the Create column.
2. For P2_EXCHANGE, accept the default Yes in the Create column.
3. Click Next.
For Web Service Results:
1. For Temporary Result Set Name (Collection), accept the default.
2. Result Tree to Report On, select Future (tns:Future).
3. Click Next.
For Result Parameters to Display, select all the parameters and click Finish.
Click Run Page to view the form.
If a Log in page appears, enter the User Name and Password for your database user account and click Login.

A form and report resembling Figure 6-3 appears. Notice that the List Futures by Exchange Form on the top of the page contains a data entry field and a submit button, but the Results Report does not contain any data.

Figure 6-3 List Futures by Exchange Form and Report without Data

Description of "Figure 6-3 List Futures by Exchange Form and Report without Data"
Test the form. In Exchange, enter NYMEX and click Submit.

The report at the bottom of the page should resemble Figure 6-4. The report lists the symbol, name, month, and year of futures from the New York Mercantile Exchange (NYMEX).

Figure 6-4 List Futures by Exchange Form and Report with Data

Description of "Figure 6-4 List Futures by Exchange Form and Report with Data"