Web Service Developer Case Study
A successful, fast-moving software company with multiple product lines on different development cycles needed a way to keep the whole organization up to date on all the features of the latest product versions.
The product management team at Altova created a product information database for other departments to use as a quick reference catalog – a way for colleagues in Sales, Support, Accounting, and other departments to get fast facts on any Altova product. A Web service on the company intranet proved to be an ideal way to distribute the data across multiple departments in multiple locations.
The Web services implementation was assigned to an application engineer who works with Altova tools at the end-user level.
The application engineer's analysis of the project identified six decisions or tasks that were required. In order of difficulty from the simplest to the most time consuming, these were:
Q: What will the Web service be called?
The name selected for the Web service is altovaCatalog
Q: Where will the Web service be located?
The Web service will run in a directory of the in-house server called /services/altovaCatalog.
Q: How will clients communicate with the Web service?
Web service client applications will send and receive SOAP / RPC-encoded messages. Initially, end users will communicate through a Web browser, although other types of client applications might be added later.
Q: What operations will the Web service perform?
Three operations were selected: get a list of product categories, view a list of products in any category, and view detailed information about any individual product.
Q: What parameters will each operation require as input and what will it return as the result?
Get list of categories – this is a query with no parameter, returning a list of the categories defined in the database.
View list within a category – the input parameter is the category name, and the result is a table of products that match the category.
View details of a product – the input parameter is a product SKU, and the response is the detailed product description stored in the database.
Q: What data types or data structures are required by each of the input and output parameters?
The data types will be based on the structure of the existing data source.
A WSDL file was needed to define the functionality of the Web service. Embedded in the WSDL would be a schema identifying the data structures to be passed by the Web service queries and responses. The application engineer began by using Altova XMLSpy to connect to the database that stored the product information and automatically generate an XML Schema, which he then optimized for the Web service.
Choosing the RPC message style required the schema components to be defined as types rather than as elements, and the parameters that would be passed in the SOAP messages needed to be structured as global components in the schema hierarchy. Making these edits was a simple point-and-click process with XMLSpy.
Schema for the product information stored in the database, optimized for the Web service
When the optimized schema was complete, the developer created a new WSDL file by using the File / New option in XMLSpy, and pasted in the schema. Next, in the XMLSpy WSDL designer, the engineer defined the Services, Bindings, and Operations with their inputs and outputs. He worked in graphical view, focusing on the logic of the Web service, while in the background XMLSpy automatically created a WSDL file over 175 lines long (more than 7,000 bytes) that could be examined at any time by switching to text view.
The XMLSpy right-click menus, helper windows, the drag and drop method for connecting components, and the ability to edit directly in the diagram and properties windows combined to let the developer build the WSDL directly in the visual editor. He could add features in any sequence he chose, without the burden of concentrating on the unwieldy WSDL syntax.
Graphical view of the completed WSDL in XMLSpy
Next, the engineer used the XMLSpy SOAP menu to create a SOAP request from the WSDL file for each of the three operations. He just selected the operations from a dialog box list and XMLSpy did the rest. The SOAP requests were saved as XML files to be used later during testing and for creation of the browser-based Web service client.
All six original questions were now answered, and the completed WSDL formed a blueprint of the Web service. Next, implementation code was needed that could be compiled and deployed on a Web server. The application engineer launched Altova MapForce and selected the option to create a new MapForce Web service project based on the WSDL file.
The engineer used MapForce to visually connect tables and fields in the product database to the input and output parameters for each of the Web service operations (as defined by the WSDL file's embedded XML Schema). The MapForce function library let him easily define Boolean conditions to match a parameter in a Web services request to a field in the database, such as the product category or individual product SKU.
MapForce mapping for the getProductsByCategoryID operation. The database appears at the top left, the input message at the lower left, and the Web service reply at the right.
The built-in MapForce engine let the developer test each of the mappings as he worked. He simply assigned the SOAP request XML file previously saved in XMLSpy as his operation input by right clicking on it and entering the file path in the component settings dialog box. Then, when he clicked the Output tab below the mapping window, MapForce processed the sample request file as if it was a SOAP message, queried the database using the parameter contained in the request file, and displayed the result in XML representing the SOAP response. This procedure greatly accelerated development, since no program source code had to be written, compiled, or deployed to test the inner workings of any Web service operation.
Once all three operations were mapped, the developer selected the MapForce Generate Code menu item to automatically create all the necessary implementation source code. MapForce generates the entire source code project, including build files in either Java or C#, complete with deploy and undeploy scripts for the Web server.
The service was planned to run on an Apache Web server, so the developer chose to generate Java source code, then ran the ANT scripts created by MapForce to compile the code and deploy it.
Once the Web service was running on the server, the developer wanted to test the deployment before creating the HTTP client. The XMLSpy SOAP menu allowed him to send SOAP requests to the Web service and examine the replies. This verified proper functioning of the Web service itself, separate from the client application.
The XMLSpy SOAP menu
For the very last step, the developer chose the ASP scripting language to build the Web pages that form the Web service client interface. Turning again to XMLSpy, he created an XSLT stylesheet to transform the XML replies from the Web service into handsomely-formatted HTML for display in the Web browser.
The completed Web service works this way:
- A user opens a URL that queries the Web service for the list of categories, which are then displayed at the upper left of the browser window.
- Clicking on any category name retrieves a table listing all the products in the database that match the selection.
- Clicking on any product in the table sends a request for product details by SKU, which are then displayed in place of the table.
Browser view of products in the Software category
A key benefit of the Web service implementation became apparent when a product manager added a new category to the database to highlight new features in the latest product releases. Because the new category added new information to the database, but did not change the underlying data structure, and because the Web service was designed to request the list of categories each time it ran, no rework or enhancement to the Web service was required and the new information was immediately available throughout the company.
Browser view of a product detail page. Note the new category at the top left.
To deploy the altovaCatalog Web service, the product manager simply sent an email announcement to the interested departments. The email contained a link to the initial product category list, and, with that, the catalog data was made instantly available.
For more information on how Altova's solution can help you build your own Web services, check out these additional resources: