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 UDDI::HalfDecent and Net::Z3950::UDDI use, and uddihd, a simple command-line test-harness to exercise the UDDI::HalfDecent library.
z2uddi
UDDI::HalfDecent
UDDI::Lite
Net::Z3950::UDDI
uddihd
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 $configFile.
$configFile
$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.
$handle
$label
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.
Net::Z3950::UDDI::Config
Net::Z3950::UDDI::Session
Net::Z3950::UDDI::Database
Net::Z3950::UDDI::ResultSet
Config
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.)
Net::Z3950::UDDI::plugins::uddi
Net::Z3950::UDDI::plugins::soap
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.
UDDI::HalfDecent::ResultSet
UDDI::HalfDecent::Record
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.
Net::Z3950::SimpleServer
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.
Exception::Class
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.
Net::Z3950::ZOOM
ZOOM::Exception
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.)
YAML
YAML::Syck
YAML::Tiny
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.
HTML::Entities
encode_entities()
The LWP module (Lib-WWW-Perl) is used to send and receive HTTP requests and responses for the UDDI::HalfDecent library.
LWP
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.
XML::LibXML
XML::LibXML::XPathContext
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).
SOAP::Lite
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 (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.
To install Net::Z3950::UDDI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Z3950::UDDI
CPAN shell
perl -MCPAN -e shell install Net::Z3950::UDDI
For more information on module installation, please visit the detailed CPAN module installation guide.