Net::Z3950::UDDI::Config - Configuration for z2uddi
use Net::Z3950::UDDI::Config; $config = new Net::Z3950::UDDI::Config($uddi, $configFile, $constHash);
This module parses configuration files for the
Net::Z3950::UDDI module that implements the guts of
z2uddi, the Z39.50-to-UDDI gateway.
$config = new Net::Z3950::UDDI::Config($uddi, $configFile, $constHash); use Data::Dumper; print Dumper($config);
Reads the configuration file named by
$configFile and parses it on behalf of the UDDI object
$uddi, returning a Net::Z3950::UDDI::Config object representing its contents. Constants referred to in the configuration file are substituted with their values as specifed in the hash referenced by
The returned object is a pretty-much self-documenting rendition of the configuration file, as you will see if you print it out using
Throws an exception if an error occurs.
$fileName = $config->file() $time = $config->timestamp()
file() returns the name of the file that was parsed to generate the configuration object;
timestamp() returns the time (in seconds since the epoch) that the configuration was compiled.
The configuration information returned from the contructor is a self-describing structure reflecting the contents of the configuration file, which can mostly be traversed by simple hash-accessing. Two of the substructures are special, however: database blocks and parameter blocks. Both of these may have parents, from which they inherit values that they do not define themselves. All database-specific parameter blocks (of type
Net::Z3950::UDDI::Config::Params) inherit values from the top-level parameter block; and each database block (of type
Net::Z3950::UDDI::Config::Database) may nominate a parent to inherit from using the
In order to ensure that this inheritance works, it is necessary always to use the
property() method when accessing properties of these blocks. For example:
$url = $database->property("endpoint"); $handler = $params->property("soap-fault");
z2uddi is configured primarily by a single file (although see the SRU and SRW documentation below). The file is expressed using the metaformat YAML, which is a structured data language conceptually somewhat similar to XML but very much easier for humans to read and write. YAML is described in detail at http://yaml.org/ but very briefly:
#) as their first non-whitespace character, and are ignored.
:. All lines of a substructure are indented to the same level, which must be a deeper level than the label that introduces it.
(There is much more to YAML, but the rest of it is not needed for
As usual, an ounce of example is worth a ton of explanation, so here is a brief bibliography expressed in YAML:
bibliography: TaylorNaish2005: authors: Michael P. Taylor, Darren Naish year: 2005 title: The phylogenetic taxonomy of Diplodocoidea (Dinosauria: Sauropoda) Wilson2002: authors: Jeffrey A. Wilson year: 2002 title: Sauropod dinosaur phylogeny: critique and cladistic analysis
z2uddi configuration file, the YAML has three top-level elements:
zparams contains Z39.50 parameters,
params contains parameters that configure the UDDI and SOAP back-ends, and
databases contains the configurations for individual databases.
zparams may contain three elements, all of them providing information to be returned to Z39.50 client in the Init Response:
params may contain any of the following:
Specifies how the
SOAP::Lite library should respond when it detects a fault. Acceptable values are
die (the default),
Specifies what logging the
SOAP::Lite module should perform. he value is a list of
SOAP::Lite tracing levels, separated by spaces or commas. Recognised levels include but are not limited to:
databases element contains the databases, each named by a key that is the name they will be known as in Z39.50/SRU/SRW.
Each database may contain a human-readable
params block specific to that database, whose values will override those in the global
params; and an
inherit-from, which is the name of another database in the same configuration. This last is useful primarily for setting up debugging versions of databases, which inherit all functional parameters from their parent but add more verbose logging.
Every database must specify a
type, which indicates the name of a back-end plugin to use in fulfulling search requests on this database. At present, the supported values are
soap. The interpretation of other values is dependent on the type:
endpoint is mandatory, and specifies the URL of the UDDI endpoint (duh).
qualifier is options, and if provided is a list of UDDI find-qualifiers to attach to searches, separated by spaces or commas. Any element whose name begins with
option- is interpreted as a UDDI option, and is set into the
UDDI::HalfDecent object before any searching or retrieval is done. Recognised options include
log specifies what types of logging to use, and may contain one or more logging types separated by spaces or commas. See
UDDI::HalfDecent for details.
service correspond to the same-named
SOAP::Lite parameters and specify where the SOAP connection is made to. (Maybe the names
wsdl would be better, but we'll keep it as it is in honour of
indexmap contains one or more Z39.50 attribute-set names, each of which contains the number values of one or more access points (use attributes) from that attribute sets. These access points are mapped onto SOAP method names: searches on the specified access points are translated into the corresponding method calls.
Anywhere in the configuration, implementation constants may be referenced using the syntax
), and will be substituted by their implementation-defined values. A small number of names are supported, including
$(package), the name of the Perl module that implements the gateway, and
$(version), the current version of that module.
An example configuration is provided in the file
etc/config.yaml in the
z2uddi distribution: if in doubt, copy and massage this file.
The configuration file format is based on YAML rather than XML, since YAML's syntax is much cleaner, more concise and more human-readable. If, however, it is considered necessary to configure
z2uddi using XML rather than YAML, then the facilities exist to do so: an XSLT stylesheet is described and provided at http://yaml.org/xml.html by which an XML-based configuration file can be automatically transformed into the YAML version that the gateway uses. If the configuration file is maintained in XML (and transformed using simple
Makefile, perhaps,) then facilities such as XInclude may be used to break the congfiguration across multiple files.
But the YAML version is much nicer.
The configuration of
z2uddi is expressed in terms of incoming ANSI/NISO Z39.50 connections from the client. Support for the related protocols SRU and SRW (which are REST-like and SOAP-based web-services respectively) is provided by the GFS (Generic Front-end Server) of the YAZ toolkit, which in turn is made available to Perl via the
The GFS translates incoming SRU and SRW requests and reformulates them as Z39.50 before passing them through the the specific server implementation, in particular translating SRU's and SRW's query language into Z39.50's Type-1 query. Configuration of the GFS is done using an XML file, often called
yazgfs.xml, which is specified on in the command-line invocation using the
-f option. This file in turn nominates a CQL-to-PQF translation file which provides the mappings of specific CQL indexes, relations, etc. to PQF (Prefix Query Format), from which the Z39.50 Type-1 query is made. The format of the GFS configuration file is described at http://indexdata.com/yaz/doc/server.vhosts.tkl
So to run
z2uddi in such a way that Z39.50, SRU and SRW are all supported, you will need to invoke it as
z2uddi config.yaml -f yazgfs.xml
etc/yazgfs.xml includes the line:
And ensure that the three files
pqf.properties are all in the working directory. (There are examples of all three files in the distribution's
etc directory.) Then the server can be interrogated using SRU URLs such as http://localhost:8019/gbif?version=1.1&operation=searchRetrieve&query=dc.title=geo%25&maximumRecords=1 http://localhost:8019/gbif?version=1.1&operation=searchRetrieve&query=dc.title=/service%20geo%25&maximumRecords=2
Net::Z3950::UDDI is the module that uses this, and the only one that would ever want to, I'm sure.
z2uddi is the gateway program, built on
Net::Z3950::UDDI, that is driven by configuration files in this format.
http://yaml.org/ is the web-site of the YAML data-serialisation language.