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

Related Topics: PowerBuilder

PowerBuilder: Article

Pocket PowerBuilder, SOAP, and PocketSOAP

Pocket PowerBuilder, SOAP, and PocketSOAP

What should you do if you have diverse components in your enterprise and need to access them from your Pocket PowerBuilder application? I won't spend too much time on SOAP and Web services, as there's lots of reading you can do on those subjects, especially if you have insomnia. All I'll do now is set the scene around the technologies of SOAP and Web services and then show what we can do. SOAP
Simple Object Access Protocol (SOAP) is widely viewed as the backbone of a new generation of cross-platform, cross-language, distributed applications - Web services. As its name suggests, it's a lightweight, XML-based protocol for the exchange of information in a distributed environment. The SOAP protocol consists of three parts: an envelope that defines a framework for describing what's in the message and how to process it, a set of encoding rules for data types, and a convention for remote procedure calls and responses. Web Services
A Web service's public interfaces and bindings are defined and described using XML and identified by a URI. The definition and description are defined using Web Services Definition Language (WSDL) and can be discovered by other software systems via Universal Description, Discovery, and Integration (UDDI), an XML-based registry for businesses worldwide to list themselves on the Internet. Once a service is discovered, interaction takes place using XML-based messages conveyed by Internet protocols (SOAP) in a manner consistent with its definition. PocketSOAP
PocketSOAP is an open source SOAP client Component Object Model (COM) component, originally targeted for the Pocket PC, that's now developed for Pocket PC and Windows 95, 98, ME, NT4.0, and 2000. PocketSOAP is distributed under the Mozilla Public License (MPL), and includes SOAP Section 5 encoding support; support for document/literal style SOAP services (such as ASP.NET); attachments support via both DIME and SOAP with attachments; support for SOAP; HTTP 1.1 support including persistent connections, SSL, proxies, authentication, proxy authentication, redirects, cookies, and compression. PocketSOAP can make remote procedure calls to SOAP servers implemented with 4s4c, ROPE, Apache SOAP, SOAP::Lite, DM's SOAP/Perl, and the XMethods SOAP Server. The package includes an HTTP client for making HTTP-based SOAP requests, but other transports can be added. More features and information can be viewed at www.pocketsoap.com. Pocket PowerBuilder and PocketSOAP
Pocket PowerBuilder and PocketSOAP interact through an interface/external DLL wrapper, which provides simple access to the PocketSOAP package via its COM interface. Pocket PowerBuilder doesn't have a COM object, aka OleObject, at the moment; this wrapper will still exist and work when the OleObject does appear in the next version of Pocket PowerBuilder, but the recommended way to use PocketSOAP will be via the OleObject. Eventually code will have to be changed, as we'll be programming directly to the PocketSOAP interface rather than the wrapper. Until then, let's enjoy using the wrapper and find out what we need to do. The model for the API is, first the service object is created, which returns the access handle, then you can set the various attributes in whatever order you desire. Internally, the attributes are stored for later use, then you make the SOAP call. This uses the previously set attributes. Finally, destroy the service object, which cuts away all the previously created COM objects. All this is built on top of the PocketSOAP system. To run with PocketSOAP, retrieve the installs from www.pocketsoap.com and install them on both the desktop and Pocket PC devices. These installs contain the API documentation, which will be useful in the future when we'll code directly to the PocketSOAP COM object via the OleObject. The PocketSOAP wrapper can be found on the CodeXchange Web site, http://pocketpb.codexchange.sybase.com, with other examples. EAServer
Let's look at an example of using PocketSOAP within Pocket PowerBuilder to call a Web service on EAServer 4.x. This Web service is in fact an EJB that retrieves old stock prices from an ASA database via a connection cache (see Listing 1). This EJB was developed and deployed to EAServer 4.x via JBuilder and the EAServer plug-in for JBuilder. It uses the sample database from the myPortfolio J2EE demonstrator that's part of the EAServer Cookbook on the EAServer CD. It was then exposed as a Web service by defining it through the Web Services Toolkit within EAServer, which is accessible through Jaguar Manager. This allows us to expose any component in EAServer as a Web service in a simple point-and-click manner. We'll briefly look at the process of using the Web Services Toolkit to expose a component as a Web service. First we create a new WSDL document, defining its definition name and target namespace. Second, we define a new Web service within that WSDL document, browsing to components that EAServer 4.2 deems "SOAPable". By "SOAPable", EAServer means components that take and return data types defined by the SOAP standard or by user-defined data types that have already been defined within the Web Services Toolkit in EAServer. Third, adding Web services properties of address and operation (method within the component) and then finally the Web Services Toolkit will generate all the WSDL needed and our component is then accessible as a Web service. If you need more information on the Web Services Toolkit in EAServer 4.x, check out the white papers on www.sybase.com. Calling an EAServer 4.x Web Service The code in Listing 2 is needed to access an EAServer 4.x Web service though PocketSOAP. The Web service is the myPortfolio component that returns a list of current shares and share prices, as shown in Figure 1. The three important things we need to set are the endpoint, namespace, and method. The endpoint indicates a specific location for accessing a service using a specific protocol and data format. The namespace indicates the specific Web service and, obviously, the method is the method that we want to call within that Web service. In the example we use the method PocketSoap_SimpleCall, which executes a synchronous call to the endpoint URL with a single argument. This argument is a name/value pair and is optional. For a more complex call, there's another method called PocketSoap_Call, which takes arguments as name/value pairs but is represented as a single DataWindow-friendly string.

Name1 ~t value1 ~t data-type1 ~r~n
Name2 ~t value2 ~t data-type2 ~r~n
Name3 ~t value1 ~t data-type1 ~r~n
PocketSOAP will take care of generating the SOAP message and parsing the response. The SOAP call and the response from the server can be viewed by using the SOAP Util tool from Apache (www.apache.org). This is started by using the command line:

java org.apache.soap.util.net.TcpTunnelGui 10000 ithain-home 8080 This allows the tool to intercept all requests that are made to localhost:10000, display them, then reroute them to ithain-home:8080. Likewise, the tool intercepts the response from ithain-home:8080, displays it, and reroutes it back to the caller. For EAServer 4.x we need to set the SoapAction attribute, because in EAServer 4.x we're using the SoapAction attribute within our proprietary implementation of Web services, though this is compatible with other implementations such as Apache. That being said, other implementations also require SoapAction. EAServer 5.0
No need to lose sleep with regard to the current usage of SOAPAction in EAServer 4.x since within the next version of EAServer, EAServer 5.0, the implementation of Web services will be AXIS so we won't need to set the SoapAction at all. For your information, within EAServer 5.0 components can be exposed as Web services in a slightly different way. One, by a command-line tool called wstool:

wstool exposeComponent PFShareListAll/PFShareList Two, via an Eclipse-based plug-in. Either way will expose that component as a Web service. The only difference from the code example above will be that the namespace changes to PFShareListAll_PFShareList and the endpoint to http://localhost:10000/ws/services. Calling an XMethods Web Service
Listing 3 is an example of calling a Web service on XMethods (www.xmethods.net). XMethods is a Web site that provides lists of example Web services. I say example, as some of these are very simple and it's questionable whether they should be part of any enterprise system. Some of these Web services are hosted by XMethods and some by their authors, so there is never a guarantee that the Web service will be available 24x7. Figure 2 uses a Web service that is a 20-minute delayed quote implemented via GLUE. On XMethods there are many other Web services implemented using MS .NET, Delphi, SOAPLite, WASP Server for Java, ColdFusion, BEA WebLogic, ApacheSOAP, AXIS, and more. Listing 3 is nearly the same as Listing 2 except for the highlighted lines. This time the SOAP Util tool was started using the command line:

java org.apache.soap.util.net.TcpTunnel
Gui 10000 services.xmethods.net 9090
and the endpoint was set to http://localhost:10000/soap rather than http://services.xmethods.net/soap in the code snippet. You can also see from the request that this implementation does not require a SoapAction to be set. For multiple arguments and a more complex call see the example in Figure 3 and see Listing 4, which provides a Web service that's on XMethods and accesses Babel Fish. Conclusion
Over the last few years we've been telling you to partition your applications, reuse code, and take advantage of your favorite application server (EAServer). PocketSOAP can be used to access components exposed anywhere as Web services and is accessible from Pocket PowerBuilder applications via a Pocket PowerBuilder interface. Now with all these technologies you can reap your reward, ROI indeed!

More Stories By Ian Thain

As one of the Sybase Technical Evangelists, Ian regularly addresses technical audiences all over the world and his sessions are always very well attended. He also writes education classes, whitepapers, demos and articles for various Sybase products and publishes regularly in Journals such as SYS-CON's PBDJ and International Developer Magazine. He is also the Sybase Unwired Platform & PocketBuilder Evangelist and works closely with the team in Dublin, CA and Concord, MA on new features and demonstrations for the products. In his customer-facing Evangelist role, Ian is very involved with the design, production and testing of Enterprise class Unwired Solutions, that have been implemented using Sybase's Unwired tools for Sybase customers around the globe. In addition, Ian is a dedicated technical expert continually working with Sybase's key partners and clients to enhance the capabilities of the Unwired solutions that Sybase can offer to its customers. Ian can also be found on Twitter @ithain

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.