Brad Loveland & Stuart Schroeder

Subscribe to Brad Loveland & Stuart Schroeder: eMailAlertsEmail Alerts
Get Brad Loveland & Stuart Schroeder: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

Related Topics: Apache Web Server Journal

Apache Web Server: Article

EAServer 5 - Web Services Made Easier

Leverage existing business logic and DataWindows

Now is a terrific time to try Web services using EAServer. EAServer 5 has a completely new Web service interface that makes providing Web services a snap. Some of the greatest enhancements are the new tools Sybase provides to create and test your Web services.

This article is based on my experience developing Web services for the Utah Department of Environmental Quality using prerelease versions of EAServer 5. Over a period of several months, I worked closely with the EAServer product managers and development team to resolve issues uncovered by our team. My experience working with Sybase was amazing. I would report bugs to the development team and they would have them resolved about a week later.

This article is written to help developers and senior system architects determine how to leverage existing business logic and DataWindows to provide Web services using PowerBuilder nonvisual objects (NVOs), XML DataWindows, EAServer 5.0, and Eclipse (new Web service IDE). It also provides a strong argument for using PowerBuilder NVOs to provide XML data via Web services instead of other development tools.

In this article, we'll look at a project overview, PB NVO design creation and tips, XML DataWindow creation and schema mapping, component deployment and modifications on EAServer 5, Eclipse IDE Web service creation and testing, using the new WSDL file, and finally the new Sybase Web Services Management Console.

Project Overview
The goal of the project was to provide state-collected environmental data to the Environmental Protection Agency. Hundreds of elements had to be mapped to approximately 50 predefined government XML Schemas. The specification was defined by a government team that consisted of individuals from multiple state agencies. A third-party consulting agency drove the project under EPA management.

The project presented many technical and business requirement challenges:

  • Create Web services based on a .NET WSDL file.
  • Create user-defined data types. (EAServer 4.0 doesn't do this but EAServer 5 does. We were required to create an array of structures to be passed as an argument to some of the Web services.)
  • Web service methods had to be defined within one WSDL file and, therefore, within one EAServer component.
  • Fifty XML Schemas had to be analyzed and mapped to the Utah DEQ database.
  • Design approaches needed to be technologically agnostic as some states were using .NET, some were using Oracle solutions, and many others, Java.
  • DIME attachments - PowerBuilder 9 doesn't support this feature yet for NVOs.
  • Create mixed-case Web service methods where PowerBuilder creates all lowercase methods (e.g., nodeping needed to be NodePing).
EAServer 5 can accomplish all these tasks and do it using NVOs and XML DataWindows.

PowerBuilder NVO Design, Creation, and Tips
A strong business argument for using PowerBuilder to build the components is that you can focus on getting the job done instead of focusing on technology. Since this is the case, we were able to complete component coding very quickly by using DataStores for all of our DataWindow retrieves.

Under most circumstances, the company providing the Web service has complete control over the Web service specification and the information being provided by those Web services. In this particular project, the Utah Department of Environmental Quality had to code to an EPA specification that contained some challenging requirements.

Since EAServer can only generate a WSDL file for each component, we had to create a component that contained all the Web services. This created development challenges since there were multiple developers working on the project and we couldn't all work on the same component at the same time. We decided to create a front-end component that matched the EPA specification and a series of back-end components to accomplish the business objectives. We found that this avoided many deployment and modification headaches. For example, when a component is deployed to EAServer, an IDL file is generated on the server. Since we needed to modify the IDL for the front-end component, we would have had to modify the IDL file each time the component was deployed. Using the front-end/back-end approach, we could deploy our individual components without affecting the front-end component and modifying the IDL file each time. (This will be discussed in the Component Deployment and Modifications section in more detail.)

Another deployment recommendation we have is to create a component deployment project for each server you will be working on. Make a project for localhost, for test, and for production. This way you don't have to modify the project each time you decide to deploy it. This makes deployment fast and clear. We made extensive use of the XML DataWindows in the components (discussed in the next section). We used PowerBuilder 9.0.1 build 7066 to create our NVOs and deploy them to EAServer. In Figure 1 notice how the new WSDL files are referenced in EAServer 5.

XML DataWindow Creation and Schema Mapping
PowerBuilder provides a default XML Schema for each DataWindow. You can display the template for an open DataWindow by choosing "Export/Import Template > XML" from the View menu.

The template's top-level attribute names the data represented by the schema followed by an attribute that indicates the beginning and end of each row of data. Below the row attribute is an attribute for each column along with the name of the column to which that attribute maps. The name assigned to the attribute (which you can alter) is the one that will appear in the XML. The template definitions for a DataWindow (you can have more than one per DataWindow) are stored within the DataWindow. (It would be nice if we had more control over where the templates were stored and how they were used.)

Note that the default template always includes an attribute that marks the beginning and end of each row of data (in Figure 2 it's called d_facility_site_data_type_row). If your Web services will be used by applications other than ones written in PB, you'll probably want to exclude that attribute from your XML Schemas. Unfortunately, that prevents you from using 99% of the default schema since when you delete the row attribute, PowerBuilder deletes all child attributes of the attribute being deleted (e.g., PB deletes the database mappings for all of the DataWindow's columns).

Also, in Figure 2 notice the horizontal line running beneath the d_facility_site_data_type attribute. The line indicates what PowerBuilder refers to as the beginning of the "detail" section of the template. When XML is generated, everything below that line will be repeated once per row of data. Without that line, you'll get only one row of data when you generate XML, so be sure to carefully set its position in your template.

We were given a collection of XML Schemas to implement - some of the Web services required a simple schema that mapped to a single table, others required nested schemas that mapped to many tables. The latter case is where PowerBuilder really shines. PowerBuilder uses DataWindow nesting to provide XML Schema nesting. This allows you to generate complex XML without having to manipulate XML manually using the PBDOM (PowerBuilder Document Object Model).

In the more complex XML Schema FacilitySiteDetails, the FacilitySite and LocationAddress attributes are themselves schemas. I implemented this in the DataWindow for FacilitySiteDetails by nesting in it the DataWindows for FacilitySite and LocationAddress (I used up to three levels of nesting for this project). As usual, I passed the appropriate retrieval argument(s) to each nested DataWindow. To complete the XML nesting, in the XML Schema for FacilitySiteDetails I linked in the schema for FacilitySite by using the "Add Child/DataWindow Control Reference" options from the context-sensitive menu and selected dw_facility_site_data_type (the nested DataWindow for FacilitySiteDataType) from the pop-up list. Ditto for the LocationAddress schema but I used the dw_location_address_data_type DataWindow instead.

When our component performs a retrieve on the FacilitySiteDetails DataWindow, the data for the nested DataWindows is also retrieved. When the component asks for the XML from the DataWindow (ds_object.Object.DataWindow.Data.XML), PowerBuilder uses the nested data along with the nested XML templates to generate the final XML.

Bottom line: you get to use the familiar DataWindow and familiar techniques to generate complex XML quickly and easily. I used XMLSPY to validate all of the XML generated by EAServer.

More Stories By Brad Loveland & Stuart Schroeder

Brad Loveland is an instructor for Venturi Technology Partners' (VTPs) EAServer and PowerBuilder courses. He has been working with PowerBuilder for over 10 years as a consultant.

Stuart Schroeder is an instructor for Venturi Technology Partners' (VTPs) EAServer and PowerBuilder courses. He has been working with PowerBuilder for over 10 years as a consultant.
[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.