Later we'll look at a WSDL document generated for our service. There's quite a bit to look at, considering we have only a few service methods and no custom data type. As we will see, WSDL documents tend to be lengthy and hard to understand, even for very simple services. That's why you're better off letting a tool like Axis generate the WSDL for you.

Axis with PowerBuilder 9
A PowerBuilder application can now act as a client and consume a Web service that's accessed through the Internet without using any third-party product (as we did in the previous article). Using SOAP and WSDL, a collection of functions published remotely as a single entity can now become part of our PowerBuilder application. A Web service accepts and responds to requests sent by applications or other Web services.

Invoking Web services through SOAP requires the serialization and deserialization of data types and the building and parsing of XML-based SOAP messages. Using the new files, PBSoapClient90.pbd and PBSoapClient90.dll, the Web services client proxy performs these tasks for us, thereby eliminating the need to have extensive knowledge of the SOAP specification and schema, the XML Schema specification, or the WSDL specification and schema.

Custom Deployment with Axis - Introducing WSDD
JWS files are quick ways to get your classes out there as Web services, but they're not always the best choice. For one thing, you need the source code - there might be times when you want to expose a preexisting class on your system without source. Also, the amount of configuration you can do as to how the service gets accessed is pretty limited - you can't specify custom-type mappings or control which handlers get invoked when people are using your service. (Note: The Axis team and the Java SOAP community at large are thinking of ways to embed this sort of metadata into your source files if desired.)

To use the flexibility available to you in Axis, you should become familiar with the Axis Web Services Deployment Descriptor (WSDD) format. A deployment descriptor contains a number of things you want to "deploy" into Axis - i.e., make available to the Axis engine. The most common thing to deploy is a Web service, so let's start by looking at a deployment descriptor for our basic service (see Listing 1).

Pretty simple, really. The outermost element tells the engine that this is a WSDD deployment and defines the "java" namespace. Then the service element defines the service for us. In this case, our provider is "java:RPC", which is built into Axis and indicates a Java RPC service. The actual class that handles this is org.apache.axis.providers.java.RPCProvider.

We need to tell the RPCProvider that it should instantiate and call the correct class (e.g., AxisCalculator), and we do so by including <parameter> tags, and giving the service one parameter to configure the class name, and another to tell the engine that any public method on that class may be called via SOAP (that's what the "*" means; we could also have restricted the SOAP-accessible methods by using a space or comma-separated list of available method names).

Using the AdminClient
Once we have this file, we need to send it to an Axis server in order to actually deploy the described service. (Don't forget to copy the Web service .class file from my last article into Copy %Jaguar%\Repository\ WebApplication\Axis\WEB-INF\classes\AxisCalculator.class. You can also download the files from the PBDJ Web site, www.sys-con.com/pbdj/sourcec.cfm.) We do this with the AdminClient or the "org.apache.axis.client.AdminClient" class. An invocation of the AdminClient looks like:

java org.apache.axis.client.AdminClient deploy.wsdd

Note: Look at my setpath.bat file (see Listing 2), which sets the classpath.

If you want to see that the deployment really worked, use the AdminClient to get a listing of all the deployed components in the server:

java org.apache.axis.client.AdminClient list

When you make a service available using Axis, there's typically a unique URL associated with it. For JWS files, that URL is simply the path to the file. For non-JWS services, this is usually the URL: http://localhost:8080/axis/services/<service-name> (in our case <service-name> is PBCalculator).

If you access the service URL in a browser, you'll see a message indicating that the endpoint is an Axis service and that you should access it using SOAP. However, if you tack on "?wsdl" to the end of the URL, Axis will automatically generate a service description for the deployed service, and return it as XML in your browser (try it!).

The resulting description may be saved or used as input to proxy generation, described next. You can give the WSDL-generation URL to your online partners and they can use it to access your service with PowerBuilder or with toolkits like .NET, SOAP::Lite, or any other software that supports using WSDL.

The PowerBuilder 9 Client
To enable PowerBuilder 9 to call our Web service, follow the next three steps:

1. Create a proxy to the Web service by using a WSDL file.
2. Use the proxy to call the Web service.
3. Test the request and response using tcpmon.

We'll choose option one. We create a new Web service proxy and select the Web Services Proxy Wizard icon from the Projects page in the New dialog box. The Web Services Proxy Wizard helps us create the proxy so we can use the Web service in PowerScript. In the wizard we specify:

• Which WSDL file we want to access
• Which service within the WSDL file we want to select
• Which port or ports we want to use
• A prefix that's appended to a port name and becomes the proxy name
• Which PowerBuilder library we want the proxy deployed to

Proxy Project
Execute the proxy and you'll get some errors in this beta release. Change your p_pbcalculator.srx file so it looks like Listing 3 and import it into your library.

Now comes step two. We want to invoke the Web service through our proxy object. To do this we need the PBSoapClient90.dll and PBSoapClient90.pbd files, which are installed in the Shared/PowerBuilder directory when you install PowerBuilder 9. When you create a Web service client application, you don't need to copy PBSoapClient90.dll to another location, but you do need to deploy it with the client executable in a directory in the application's search path. To add PBSoapClient90.pbd to the application's search path, right-click the client target in the system tree and select properties from the pop-up menu. In the current beta release, type in the full path and name of the PBSoapClient90.pbd file.

The SoapConnection class is used to connect to the SOAP server that hosts the Web service you want to access. It has these public methods that we'll use immediately:

CreateInstance(proxyObj,proxyName),
CreateInstance(proxyObj, proxyName, endpoint),
SetOptions(optionsString)

The script in Listing 4 shows a connection to a Web service on a SOAP server. It sets the connection properties using our tcpmon-URL (described later). If you don't set a URL, the one stored in the proxy will be used. Then the script creates an instance of the SoapConnection object and enables logging, so we set SoapLog (other connection options [for HTTPS] would be "UserID", "Password", or "Timeout"). Next we invoke our proxy object for the PBCalculator Web service, then print out the return value or an error message, if something was wrong.

Using the Axis TCP Monitor (tcpmon)
Now to step three. We want to know what goes through the wire - what PowerBuilder 9 will send to Axis and what will come back. To do this we use another tool that comes with Axis: tcpmon. It's a great way to see what's going on with the SOAP messages.

The included "tcpmon" utility can be found in the org.apache.axis.utils package. To run it from the command line, type:

javaw org.apache.axis.utils.tcpmon 8090 localhost 8080

This means we select a local port that tcpmon will monitor for incoming connections (8090), a target host (localhost) where it will forward such connections, and the port number on the target machine that should be "tunneled" to (8080). Now each time a SOAP connection is made to the local port, you'll see the request appear in the "Request" panel and the response from the server in the "Response" panel. Tcpmon keeps a log of all request/response pairs, and allows you to view any particular pair by selecting an entry in the top panel. You may also remove selected entries or all of them, or save to a file for later viewing.

Now we start our application; we can see the request to EAServer and Axis and the response back to our PowerBuilder client. We should see a messagebox with the correct value (4+3=7).

Figure 2 shows the output from tcpmon.

Conclusion
PowerBuilder 9 is now the perfect tool to act as a Web service client. EAServer with Axis and PowerBuilder 9 is the right combination for using the newest technologies in your company. So go and download PowerBuilder 9 beta 3 from www.sybase.com/betapb90program.