Once finished, the wizard will create the project into its current PowerBuilder library. The project looks like Figure 1. Right-click the project in the system tree and select Deploy. The project will generate the proxy automatically. If there are complex types in the WSDL file, the project will generate PB structures for them too. Now the proxy is ready for PowerScript.

 

Step 2: Use the Proxy to Call Web Services
Invoking Web services through SOAP requires serialization and deserialization of data type, building SOAP messages, and parsing SOAP messages. In PowerBuilder 9, PBSoapClient90.pbd and PBSoapClient90. dll are developed for this task. These two files are installed in the Shared/PowerBuilder directory when PowerBuilder 9 is installed. The PBSoapClient90.pbd must be added into the applications and PBSoap- Client90.dll must be deployed with your application executables. PowerBuilder 9 (GA release) will add PBSoapClient90.pbd into the system tree automatically when you create an application.

If you're using a beta version, you may need to do this manually. To do so, right-click the application in the system tree and select Properties, then type in the full path and name in the Library List or browse the file from the hard disk.

There are two classes in PBSoapClient90. pbd, namely SoapConnection and SoapException. The SoapConnection class is used to instantiate the proxy object, populate the SOAP options, and connect to the SOAP server. It has three public methods that we can use immediately.

"SoapLog=~"Logpath~", userID=~"username~", Password=~"password~"

The SoapException class is used to process exception. It inherits from the PowerBuilder Runtime error class. All exceptions and errors during the execution of Web services will be converted to Soap Exception and thrown to calling script. PowerScript can use try-catch black to capture this exception.

The script in Listing 1 shows you how to invoke Web services in PowerScript. It creates an instance of SoapConnection and sets the options for the connection first. In the example, we only set the SOAP log file to capture the exchanged messages between PowerBuilder client and SOAP server. Then it creates an instance for the proxy. Next, it invokes the method ("get Rate") of the Web service and prints out the result. If anything goes wrong, the script will capture the exception and print out an error message.

Result
Now we can run our application; we can see a message box with the correct return value (see Figure 2).

 

It's really simple to build PowerBuilder applications to consume Web services. The sample Web service used here is developed in Java. And we can make use of it in our PowerScript. Besides that, PowerBuilder can also consume Web services that are developed in any other language and run on any Web servers. such as .NET server, Apache, WebLogic, WebSphere, and EAServer. Visit www.xmethods.com for more information or to create your own Web services in PowerBuilder 9.

Consuming Web services in a JSP Application
PowerBuilder 9 enables developers to build and use JavaServer Pages (JSPs) in their PowerBuilder Web applications. A JSP application in PowerBuilder 9 may consume Web services as well. Create a JSP target with the source and build folder and deployment configuration first. The JSP may be deployed to EAServer or Tomcat. In this example, we use EAServer. Then we use the JSP Web Service Proxy Wizard on the Web page of the New dialog box to create a custom tag library with the information necessary for calling a Web service in a JSP. The JSP Web Service Proxy Wizard is similar to the Web Service Proxy Wizard for the PowerBuilder Windows application. It collects information such as the location of a WSDL file, the service, and port. We can specify overrides to the WSDL file for a custom bean name, Java class name, Java package name, TLD name, JAR file name, output variables, and the selection of operations within a service. The wizard creates a TLD file, the Java source code to process the custom tag, and the compiled Java class files of the source.

Once the custom tag is generated, it appears in the system tree. To use custom tags to invoke Web services, do the following:

The TLD file for the currency exchange example used earlier looks like Listing 2. The source code of the JSP page to call the Web service is shown in Listing 3. Now run the JSP page in PowerBuilder or browse to the JSP page just deployed. If all went well, the correct exchange rate will show on the page. If anything goes wrong, consult the log file.

A custom tag for Web services throws a JspTagException for non-recoverable errors if something goes wrong. The JspTag Exception contains information about the root cause of the exception and the point where the error occurred in processing the custom tag. This exception can be caught in a Try-Catch block or mapped to a specific error page in the Deployment Configuration Properties dialog box for the JSP target.

Note: JSP in PowerBuilder 9 now supports only RPC-style Web services.

Deploying Web Services in PowerBuilder 9 to EAServer
PowerBuilder, as a 4GL RAD tool, extends to component and Web service development as well. I'll use EAServer 4.1.3 as both application server and Web server. What follows is a five-step program for developing EAServer components and deploying them to Web services via EAServer. If you already have your PowerBuilder components, you may skip Step 1.

Step 1: Develop EAServer Component in PowerBuilder 9
In PowerBuilder, there are several kinds of wizards - such as application, template application, EAServer component, COM/ MTS component, and automation server - to help developers generate PowerBuilder applications. In our case, we chose the EA- Server component. Before running the wizard to generate the EAServer component, the EAServer must be started and the EAServer profile must be created in PowerBuilder.

We selected the EAServer Component Wizard icon from the Target page of the New dialog box. As you work through the wizard, you'll make the following decisions:

For most wizard pages, we use the default values. Once finished, you'll see a PB target named "hello" within the system tree. Under the target, a project ("p_hello_eascomps") and a component ("n_hello") were already created. Now you may develop any functions in the component. The following function is an example:

function string f_hello (string name)
return string("Hello, Web services from") + string(name)
end function

Step 2: Deploy PowerBuilder Object to EAServer
Once the development of the component is finished, right-click the project ("p_hello_eascomps") and select Deploy to deploy the component to EAServer.

Step 3: Wrap the PowerBuilder Component to a J2EE Component
In Jaguar manager, an EAServer management console, you need to generate a client-side stub and server skeleton for the deployed package/component. To generate the stub/ skeleton, right-click the just deployed package, then select Generate Stub/Skeleton. On the dialog, select "Cobra" as the protocol and generate and compile Java files for stub/skeleton.

Step 4: Create WSDL Documents and Services
Web Services Toolkit (WST) will wrap the components to SOAP components and generate WSDL files. WST generates two WSDL files for each component - one is for the interface of the service and the other is for implementing information of the service.

To generate WSDL files, first right-click the WSDL Documents folder and select New WSDL Document. Figure 3 shows the dialog for Create WSDL Document. Give the definition name ("helloDemo") and target namespace. The target namespace not only works as the "TargetNamespace" attribute in the WSDL file, but also specifies the location where the implementation WSDL try to look for the interface WSDL file. So it's critical for WST to generate a workable Web service. Give a URL where you want to put the interface WSDL file. Secondly, create a new Web service by right-clicking "hello Demo" document and select New Web service. You can browse all EAServer components and select any one to use. For this article, we selected package "p_hello" and component "n_ hello". Finally, add properties to the Web service. You need to specify the address for SOAP listener and which functions in the component to be exposed to Web services.

 

Step 5: Copy the WSDL Files For Use
The two WSDL files generated at the last step reside under <EAServer host folder>\WebServices\work\wsdl\. Copy them to the virtual directory of the Web server. In this tutorial, we copied them to the virtual directory of http://localhost: 8090. Now the Web services are ready for use.

Summary
PowerBuilder 9 abstracts the complexity of the Web services development and provides a wizard-guided development environment. The sample applications in this article demonstrate the ease of Web services development. PowerBuilder 9.0 is an excellent development tool to build Web service clients both in Windows and JSP applications, and produce Web service components.