Unless you have been hiding in a cave for the past couple of years, you are probably well aware of the buzz surrounding service-oriented architecture (SOA). This concept of interaction among loosely coupled collections of components is often implemented through a series of services accessible over HTTP that processes requests and responses (Web services). As a PowerBuilder developer you may be wondering how you can join the SOA party while still leveraging your existing skills. This article will walk you through three techniques available to the PowerBuilder developer (even if you may not be on a currently supported version).

Accessing a Web service is very similar to visiting a Web page containing parameters in the URL or submitting a form on a Web page. An HTTP request gets sent to a URL via an HTTP GET or POST along with a set of arguments in the form of name/value pairs. In PowerBuilder there are three options available for performing this type of operation: the GetURL/PostURL functions, using Microsoft's XmlHttp object via OLE, and using the Web Service Proxy object.

Demonstration Application to Call Amazon.com Web Services
In this article we will create a demonstration application that interacts with the Amazon.com E-Commerce Web Service (http://aws.amazon.com). Our application will use this service to search through one of their product indexes for items matching our search criteria. To use the Amazon.com Web service you will need to sign up for an access key through their site. The code samples will show where your key should be placed with the indicator "[YourAccessKey]".

By looking at the documentation for the Amazon E-commerce Web service, we can see that to perform an item search operation a minimal set of arguments is required. There are many additional arguments that may be used when performing searches, but we will be using the subset listed below. (Browse the Amazon.com Web service documentation to see the full range of search arguments and operations available.)

• Web Service URL: http://webservices.amazon.com/onca/xml
• Service: Name of the service being used; should be AWSECommerceService
• AWSAccessKeyID: [YourAccessKey]
• Operation: Operation to be performed (ItemSearch in our case)
• Keywords: Word or phrase to search for
• SearchIndex: One of Amazon.com's search indexes (Music, Books, etc.)

Responses from this Amazon Web service will be returned as structured XML that can then be parsed and displayed. A demonstration of the various methods available for parsing XML in PowerBuilder will be covered in a later article.

Before we can send requests, we must decide what to search for. I'm a huge music fan, so for this example we will use the "Music" SearchIndex and for our Keywords argument we will search for information on one of my favorite musicians, the great "Butch Walker" (an Atlanta musician formerly with the Marvelous 3).

GetURL/PostURL
The oldest methods for pulling data over HTTP in PowerBuilder (since version 6.5) are the GetURL and PostURL functions. These functions allow you to send an HTTP GET or POST request from within PowerScript and capture the resulting response.

When passing arguments to a URL via an HTTP GET, the URL is generated in the format:

BaseURL?<name1>=<value1>&=<value2>&...

The full URL for an HTTP GET to our Amazon Web services with our selected parameters would be as follows: Click Here!

The resulting response would be XML containing a list of items matching our search (see Figure 1).

Now that we know what our request should look like, we can begin to write code to call the Web service. Both the GetURL and PostURL functions require that you first create a standard class of the type InternetResult to capture and process the Web service response via the InternetData(blob) function. Once we have created this class, we will override the InternetData(blob) function with code to process the response. For demonstration purposes, a simple MessageBox will do for now, but we could write the data out to a file or parse it for display in a DataWindow. The following code snippet should be added to the function InternetData(blob) in the InternetResult object:

MessageBox("Response", & String(data))
Return 1

The code in Listing 1 demonstrates a call to the service with GetURL (see Listing 1). Note that to call the GetURL/PostURL functions, you must use GetContextService to get a service reference to the Internet service.

Executing the snippet should generate a MessageBox filled with our XML response from the Amazon Web service. Performing the same operation with a PostURL is almost identical; we just have to set a couple of extra parameters (content headers and port) (see Listing 2).

While this approach works well for standard HTTP requests, the GetURL/PostURL functions do not allow communication over HTTPS. To achieve secure communication with the Web service, we must move on to one of our other two methods.

Microsoft XmlHttp Object Using OLE
Using PowerBuilder's OLE capabilities, we can take advantage of Microsoft's XmlHttp object to send requests to a Web service. The code to use this object is very similar to what we have seen for GetURL/PostURL. The XmlHttp object can send requests via HTTP GET and POST but adds the benefit of being able to also send requests over HTTPS. Before you may use this object, you must download and install the MSXML package from Microsoft's Web site (this example uses version 4.0 of the package). One nice added bonus included with this package is an XML parser (handy if you don't happen to be on a version of PowerBuilder that can parse XML) (see Listing 3).

Web Service Proxy Object
Last but not least is the Web Service Proxy Object. This object is available to those who are using PowerBuilder version 9 and above. This object examines a Web service's WSDL (Web Service Description Language) file to determine all of the services available that may be requested. We will step through the Web Service Proxy Wizard to create a proxy object for our Amazon Web Service. We can then deploy this object, which will generate a set of objects, methods, and structures we can use to call our Web service and capture the response (because of recent changes in the Amazon WSDL file, PowerBuilder 9.0.3 Build 8565 or above is required to generate a proxy using the wizard). The Web Service Proxy uses SOAP-style requests to interact with our Web service. The other two methods shown used REST-style requests (for more information see the sidebar SOAP vs REST).

To create a Web Service Proxy Object, proceed through the following steps:

1. Click New object and select the Web Service Proxy Wizard from the Project tab (see Figure 2).
2. Click Next and select a WSDL File. Enter the URL to the Amazon WSDL file: http://webservices.amazon.com/AWSECommerceService/ 2005-10-05/AWSECommerceService.wsdl.
3. Click Next and select the available services exposed through the WSDL file.
4. Click Next and select an available port for the Web service.
5. Click Next and, if you like, enter a prefix for the proxy name.
6. Click Next and select a library and name for the proxy object. Click Next and confirm the proxy settings and click Finish (see Figure 3).

Now you should have a proxy object present in your library that can be deployed to create all of the objects needed to access the Amazon Web service. To use the new objects, you will need to create a SoapClient connection (to use the SoapClient object you will need to add either pbsoapclient90.pbd (PowerBuilder 9) or pbsoapclient100.pbd (PowerBuilder 10) to your library list).