PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

Third Generation Web Service Implementation

Third Generation Web Service Implementation

The Web Services Description Language (WSDL) makes it possible for automated code-generation tools, like PowerBuilder 9 with its Web services wizard, to simplify building clients for existing Web services.

In my previous article "Axis" (PBDJ, Vol. 9, issue 8) we discussed the basic steps involved in implementing a Web service using Axis, EAServer, and PowerBuilder 8. Now we'll explore the technologies that make it easier to use Web services that have already been deployed.

What Is WSDL?
WSDL is an XML-based language used to define Web services and describe how to access them. Fortunately, we don't need to learn all the details because there are tools or implementations like Axis that generate WSDL for us. This article provides you with just enough information on WSDL to understand what's going on and be able to tweak tool-generated WSDL files and maybe troubleshoot WSDL-related problems.

Interoperability between applications in different programming languages and on various operating system platforms is frequently hindered because one system's "integer" may not be exactly the same as another's. Because each operating system and programming language has different definitions of not only what particular base (or primitive) data types are called, but also how they are expressed when sent over the wire, those operating systems and programming languages cannot communicate with each other. To allow seamless cross-platform interoperability, there must be a mechanism by which the service consumer and the service provider agree to a common set of types and the textual representation of the data stored in them. The Web services description provides the framework through which the common data types may be defined.

In WSDL, the primary method of defining these shared data types is the W3C's XML Schema specification. However, WSDL is capable of using any mechanism to define data types, and may actually leverage the type definition mechanisms of existing programming languages or data interchange standards. No matter which type of definition mechanism is used, both the service consumer and the service provider must agree to it or the service description is useless. That's why the authors of the WSDL specification chose to use XML Schemas - they're platform-neutral.

A WSDL document is a collection of one or more service definitions. The document contains a root XML element named definitions that contains the service definitions. The definitions element can also contain an optional targetNamespace attribute that specifies the URI associated with the service definitions. WSDL uses namespaces and namespace IDs in the same way we've been using them in SOAP envelopes, so it's common to find a number of namespaces declared at the definitions level of the document.

WSDL defines services as collections of network endpoints. These endpoints, in WSDL terminology, are known as ports. WSDL separates the service ports and their associated messages from the network protocol that the service is bound to (binding). The combination of a binding and a network address results in a port, and a service is a collection of those ports.

The WSDL specification defines the main document sections as follows:

  • Types: A container for data type definitions using some type system (such as XSD)
  • Message: An abstract typed definition of the data being communicated
  • Operation: An abstract description of an action supported by the service
  • portType: An abstract set of operations supported by one or more endpoints
  • Binding: A concrete protocol and data format specification for a particular port type
  • Port: A single endpoint defined as a combination of a binding and a network address
  • Service: A collection of related endpoints

    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.
    To accomplish step one we need a WSDL file; Axis supports WSDL three ways:
    1.   When we deploy a service in Axis, users may then access its URL with a standard Web browser. By appending "?WSDL" to the end of the URL, they'll obtain an automatically generated WSDL document that describes your service.
    2.   Axis has a tool, "WSDL2Java", that will build Java proxies and skeletons for services with WSDL descriptions.
    3.   It has another tool, "Java2WSDL", that will build WSDL from Java classes.

    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
    Fill in the values so your project looks like Figure 1.

    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, endpoint),

    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.

    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.

  • More Stories By Berndt Hamboeck

    Berndt Hamboeck is a senior consultant for BHITCON (www.bhitcon.net). He's a CSI, SCAPC8, EASAC, SCJP2, and started his Sybase development using PB5. You can reach him under [email protected]

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.