NAME

Net::Z3950::UDDI - Perl extension for querying UDDI services using Z39.50

SYNOPSIS

  use Net::Z3950::UDDI;
  $handle = new Net::Z3950::UDDI($configFile);
  $handle->launch_server("myAppName", @yazOptions);

DESCRIPTION

This library provides all the guts of the Z39.50-to-UDDI gateway, z2uddi (which is supplied along with it). In the same package comes an underlying library, UDDI::HalfDecent, which supports a subset of UDDI but supports it really well, reliably, and with good error-reporting -- unlike, to pick the module-name out of the thin air, UDDI::Lite for example. Also included in the package are the swarm of auxiliary modules which UDDI::HalfDecent and Net::Z3950::UDDI use, and uddihd, a simple command-line test-harness to exercise the UDDI::HalfDecent library.

The gateway provides a server that understands not only ANSI/NISO Z39.50 (aka. ISO 23950), but also the related web-service protocols SRU (in both its GET and POST forms) and SRW (SRU over SOAP).

The API of the Net::Z3950::UDDI module itself is trivial: the synopsis above captures it in its entirely, and is essentially the whole of the code of the z2uddi script. I'll document it anyway, but the important stuff is elsewhere (see below).

METHODS

new()

  $handle = new Net::Z3950::UDDI($configFile);

Creates and returns a new Z39.50-to-UDDI gateway object, configured by the file named as $configFile.

launch_server()

  $handle->launch_server($label, @yazOptions);

Launches the gateway $handle, using the $label string in logging output and running in accordance with the specified YAZ options. The implications of this are discussed in the z2uddi documentation.

SEE ALSO

Documentation Roadmap

Apart from the Net::Z3950::UDDI module itself, there are many other components that go to make up the package that provides the Z39.50-to-UDDI gateway. Each is documented separately, but here is a basic overview.

z2uddi is the gateway program, and consists only of a trival invocation of the Net::Z3950::UDDI library. That in turn uses four worker classes: Net::Z3950::UDDI::Config parses the configuration file, Net::Z3950::UDDI::Session represents a front-end session which may reference several databases and result-sets, Net::Z3950::UDDI::Database represents a connection to a back-end database and Net::Z3950::UDDI::ResultSet represents a set of records that result from a search. The Config documentation also describes the configuration file format.

Both the database and result-set classes are virtual: they are not instantiated directly, but only as subclasses specific to particular back-ends such as UDDI and SOAP, using modules such as Net::Z3950::UDDI::plugins::uddi and Net::Z3950::UDDI::plugins::soap. (These backend-specific modules are not individually documented.)

UDDI access is provided by a stand-alone module UDDI::HalfDecent, which may be useful in other applications. This in turn uses two worker classes, UDDI::HalfDecent::ResultSet and UDDI::HalfDecent::Record. Others may follow as its UDDI capabilities are extended and generalised. The program uddihd provides a simple command-line interface to the UDDI library.

Prerequsites

Apart from the modules included in the Net::Z3950::UDDI distribution, the following software is also required.

• The Net::Z3950::SimpleServer module provides a Perl API to the YAZ GFS (Generic Frontend Server) which provides server-side Z39.50, SRU and SRW protocol capabilities.

• Index Data's fine YAZ toolkit provides the underlying GFS itself. http://indexdata.com/yaz/

• The Exception::Class module implements the exceptions used by UDDI::HalfDecent.

• The Net::Z3950::ZOOM module provides the ZOOM::Exception class used within the gateway: Exception::Class-based exceptions are translated into ZOOM exceptions as required. Note that ZOOM is used only for ZOOM::Exception, and not for any of its other facilities: specifically, the gateway does not act as a Z39.50, SRU or SRW client.

• The YAML module provides the parser for the gateway's configuration file. (Its error-messages are not very good: it might be possible to improve matters by using YAML::Syck or YAML::Tiny instead.)

• HTML::Entities provides the much-needed encode_entities() function to quote funny characters such as less-than and greater-than for insertion into XML. It took me ages to find a standard library, available, as Debian package, that provided this simple but indispensible function.

• The LWP module (Lib-WWW-Perl) is used to send and receive HTTP requests and responses for the UDDI::HalfDecent library.

• XML::LibXML is used to parse the XML-formatted UDDI responses. In order to use XPath on the parsed documents, it's necessary to have XML::LibXML::XPathContext: this is included in XML::LibXML from version 1.61 onwards, but will need to be downloaded and installed separately if your LibXML is older than that.

• The SOAP::Lite module, which provides horrible, unreliable, impossible-to-debug SOAP client facilities that may be used to enable invocation of arbitrary SOAP services that, if you're very lucky, might work, or at least produce a comprehensible diagnostic. The <Net::Z3950::UDDI> distribution includes most of the code to run a Z39.50 gateway to arbitrary SOAP services, but since it relies on the notoriously unreliable SOAP::Lite as the back-end, this facility is not as useful or robust as one might wish (and certainly not solid enough to build the UDDI support on, as I had hoped).

AUTHOR

Mike Taylor <mike@miketaylor.org.uk>

I gratefully acknowledge the funding provided by the United States Geological Survey (USGS) to create this software, and the sterling efforts of Eliot Christian to forge the commercial arrangements.

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Mike Taylor.

This library is distributed under the terms of GNU General Public License, version 2. A copy of the license is included in the file "GPL-2" in this distribution.