This Web-service example will provide the ability to search a database of libraries and retrieve the results. The service is based on the database of libraries available in lib-web-cats (www.librarytechnology.org/libwebcats); this database includes information on more than twenty-five thousand libraries worldwide.

The Web service discussed in this chapter is designed to operate with two types of messages, the first to pass the service request to the server, and the second to pass the response back to the client. This is considered a synchronous service.

First, a plan for how the messages should be constructed needs to be established. The basic input for the Web service will invoke a method named LibrarySearch within the designated namespace LibraryInformation Server, and the input will pass the text to be searched as a string. I'll also include an optional parameter, which specifies the fields to search. The service request might be conceptualized in the simple XML fragment shown in figure 5.

The application will take the basic structure shown in figure 5 and transform it into a SOAP message, including all the headers needed; provide references to each of the schemas and namespaces involved; and specify the data types that apply. The resulting SOAP message would look something like the script shown in figure 6.

Compared to the service request, the service response will be more complex. Instead of passing a single value and qualifier, the response will carry much more information. After the service provider carries out the LibrarySearch method, a user may want to receive some information about each of the items returned in the search; the response will also tell the user the number of items returned.

Such a response requires the user to define a complex data structure. One component of the results will consist of an object that tells him or her about each library found by the query. The structure will be called item and will include several descriptive elements. The item structure can be conceptualized as the script shown in figure 7.

The user, however, will receive many of these, so he or she will need to build an array of <item>. This array is deemed ResultElements, and it will hold as many instances of <ResultElement> as the user needs. The result set will also tell the user the number of items to be returned. This value will be passed in a data structure called TotalResultsCount. So, the request response will consist of a complex data structure called <return>, which includes <ResultElements> and <TotalResultsCount> where ResultElements is an array of multiple <ResultElement>. As the application wraps the results in SOAP, it will look something like the script shown in appendix 13.

I have described the design of the service, so now I'll describe how to construct a WSDL file, which will render the data structures involved and the methods and messages available. This WSDL file will include each of the concepts covered in chapter one.

Because the WSDL file is an XML document (see appendix 14), it begins with the appropriate declaration. The root element of the document will be <definitions> as are all WSDL files. The <types> section specifies the data structures involved in the service, and you can see the structure outline for the complex object (described above). The WSDL includes a section that defines the <messages>, which include one for the service request called <LibrarySearch> and one for the service response called <LibrarySearchResponse> . The <PortType> section references the previously defined messages. The <bindings> and <service> provide the specifications for how this service can be invoked. Note that this listing is meant to illustrate the structure of WSDL and should not be considered the specification of a publicly available service.q

Now that the user has determined what he or she wants the service to do, the user can write some programs to implement it. I'll continue in the mode of using Perl with SOAP::Lite.

The most complex part of the programming project will be to create a Perl module that implements the service. This program will need to access the underlying database and be able to deliver results to the SOAP environment. The Perl module illustrated in appendix 15 performs these tasks.

This module uses the Open Database Connectivity (ODBC) model to communicate with the underlying database. The ODBC layer is provided by the Win32::ODBC Perl module and the ODBC driver of the underlying database. Using ODBC makes the program database independent, and it can be used with any database with an ODBC driver available.

The Perl module contains the sub-routine Library- Search, which serves as the primary method for the user-created Web service. The module receives as its input parameters the messages passed by the service request. The <query> parameter is passed into the sub-routine, into the local variable $request, which is then inserted into an SQL statement. The SQL statement is stored as a string in the global variable $SqlStatement, and it's executed by the ODBC engine by the sub-routine executeSQL. ODBC returns the results of the query in the object $db. The user can then use the ODBC method FetchRow to retrieve each of the table rows returned by the query. An associative array named data holds the values for each field. As each row is processed, the values in the data array are pushed into the SOAP data structures. The rows are counted as it goes along, so it can also return the number of results in the TotalResultsCount component of the structured response.

The user must ensure that all data passed in the service response is valid XML. The MakeValidXML sub-routine performs this function. In the simple example, it only fixes the known problem of unescaped ampersands. In a production service, the user would need to perform a rigorous check of the data to ensure the service does not fail due to problems with the data (such as using characters outside the defined encoding or character set).

Once the module has been developed that performs the work defined in the service, the user can activate it through a program that sets up the server to monitor SOAP requests. There are many ways to activate a SOAP service; in the SOAP::Lite environment, for example, a user can establish a service with the few simple lines of code (appendix 16), and the service operates through TCP sockets.

With the service operational, the user can use the following command-line client (appendix 17) to access it, which continues to rely on Perl and SOAP::Lite.

Although it is clearly more complex to develop a Web service than to access an existing one, it can be accomplished without too much effort (as illustrated in this chapter). This Web service performs a relatively simple task—that of searching a database and delivering a result. Most of the complexity comes into play in the setting up the data types and message structures needed for the SOAP environment, and many programming environments automate much of this part of the development process.