NAME

Net::Z3950::UDDI::Config - Configuration for z2uddi

SYNOPSIS

 use Net::Z3950::UDDI::Config;
 $config = new Net::Z3950::UDDI::Config($uddi, $configFile, $constHash);

DESCRIPTION

This module parses configuration files for the Net::Z3950::UDDI module that implements the guts of z2uddi, the Z39.50-to-UDDI gateway.

METHODS

new()

 $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 $constHash.

The returned object is a pretty-much self-documenting rendition of the configuration file, as you will see if you print it out using Data::Dumper.

Throws an exception if an error occurs.

file(), timestamp()

 $fileName = $config->file()
 $time = $config->timestamp()

Accessor methods: 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.

Fetching Database and Parameter-Block Properties

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 inherit-from property.

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");

CONFIGURATION FILE FORMAT

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:

• Comment lines have hash (#) as their first non-whitespace character, and are ignored.

• Blank lines are ignored.

• Data lines are of the form key: value

• Substructures are introduced by a line of the form key:. 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 z2uddi configuration.)

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

In the 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: implementation-id, implementation-name and implementation-version.

params may contain any of the following:

soap-fault

Specifies how the SOAP::Lite library should respond when it detects a fault. Acceptable values are die (the default), warn and ignore.

soap-debug

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: method, parameters, fault, trace, debug and all

The 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 description; a 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 uddi and soap. The interpretation of other values is dependent on the type:

uddi

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 http-version, uddi-version, proxy and loglabel. Finally, 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.

soap

proxy, uri and service correspond to the same-named SOAP::Lite parameters and specify where the SOAP connection is made to. (Maybe the names endpoint, namespace and wsdl would be better, but we'll keep it as it is in honour of SOAP::Lite. 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 $(name), 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.

XML

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.

SRU AND SRW

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 Net::Z3950::SimpleServer module.

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

Where etc/yazgfs.xml includes the line:

 <cql2rpn>pqf.properties</cql2rpn>

And ensure that the three files config.yaml, yazgfs.xml and 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

SEE ALSO

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.

AUTHOR, COPYRIGHT AND LICENSE

As for Net::Z3950::UDDI.

cpanm Net::Z3950::UDDI

perl -MCPAN -e shell
install Net::Z3950::UDDI