Net::Z3950::UDDI - Perl extension for querying UDDI services using Z39.50
use Net::Z3950::UDDI; $handle = new Net::Z3950::UDDI($configFile); $handle->launch_server("myAppName", @yazOptions);
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
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).
$handle = new Net::Z3950::UDDI($configFile);
Creates and returns a new Z39.50-to-UDDI gateway object, configured by the file named as
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
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::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::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.
Apart from the modules included in the
Net::Z3950::UDDI distribution, the following software is also required.
Net::Z3950::SimpleServermodule provides a Perl API to the YAZ GFS (Generic Frontend Server) which provides server-side Z39.50, SRU and SRW protocol capabilities.
Exception::Classmodule implements the exceptions used by
Net::Z3950::ZOOMmodule provides the
ZOOM::Exceptionclass 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.
YAMLmodule 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
HTML::Entitiesprovides 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.
LWPmodule (Lib-WWW-Perl) is used to send and receive HTTP requests and responses for the
XML::LibXMLis 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::LibXMLfrom version 1.61 onwards, but will need to be downloaded and installed separately if your LibXML is older than that.
SOAP::Litemodule, 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::Liteas 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).
Mike Taylor <email@example.com>
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 (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.