DataVerifier PERL package for the NASA ADEC ITWG. QUICKSTART 1) Install the package as outlined below. Please note that you need SOAP::Lite as a pre-requisite, which I suggest you install using PERL's CPAN utility. You will also need perl 5.6.0 or higher. If you are not doing a system-wide install, please see the INSTALL section below for more instructions. 2) Test a sample query to the ADS test DataVerifier client by running: perl examples/ITWG-DataVerifier-client foo bar 3) Create your own test CGI script that performs data verification for your archive by copying examples/ITWG-DataVerifier-test to the proper cgi-bin directory (I suggest you call it ITWG-DataVerifier). Make sure that the first line has the correct perl path in it. Now you should be able to have it generate a WSDL file for your service by retrieving the URL: http://your.server.edu/cgi-path/ITWG-DataVerifier?WSDL 4) Now test the command-line client against your new CGI server. perl examples/ITWG-DataVerifier-client --proxy \ http://your.server.edu/cgi-path/ITWG-DataVerifier foo bar 5) Modify the test script by writing your own version of verify_id() so that it does something useful 6) You may also want to fill in the entries of the hash $ITWG::DataVerifier::datacenterProfile so that they reflect your site's information. This allows the CGI script to serve your site's XML profile when invoked as: http://your.server.edu/cgi-path/ITWG-DataVerifier-test?Profile You should then go to the above URL with your browser to verify that the XML document comes back as expected. 7) Go register your newly created service with the ADS as described in http://ads.harvard.edu/www/dv/ INSTALLATION To install this module type the following: perl Makefile.PL make make test make install This will install the module under the standard perl distribution (which likely requires root priviledges under your system). If you want to install the module under your own private directory, the first step should be: perl Makefile.PL PREFIX=/my/perl_directory In order to run the example scripts described above, you will then have to tell perl where to find the module by using the -I command line directory: perl -I/my/perl_directory examples/ITWG-DataVerifier-client foo bar DEPENDENCIES SOAP::Lite DOCUMENTATION POD is included in the package and should be available after installation by calling "perldoc ITWG::DataVerifier" A copy of the manpage is included below. -------------------------------------------------------------------------- NAME ITWG::DataVerifier - Perl extension for SOAP Data Verification SYNOPSIS ### sample CGI SOAP server: use ITWG::DataVerifier; my $server = ITWG::DataVerifier::Server::CGI->new->handle; # example of verification routine; you should replace it with your # own version that actually does something with the input identifier; # $res is -1 for illegal syntax, 0 for unrecognized id, 1 for valid id sub verify_id { my $id = shift; my $res = 1; my $url = ($res > 0) ? 'http://foo.org/bar?' . $id : ''; return ($res,$url); } ### sample client setting up connection via WSDL description use ITWG::DataVerifier; my $wsdl = 'http://ads.harvard.edu/ws/ITWG-DataVerifier-test?WSDL'; my $client = ITWG::DataVerifier::Client->new(service => $adswsdl); my @ids = $client->verify('foo', 'bar') or die "could not verify data ids"; my $id = $ids[0]->{input}; # this should be 'foo' my $res = $ids[0]->{result}; # this should be 1 my $url = $ids[0]->{url}; # URL that can be used for linking ### sample client using direct proxy to server (WSDL not available) my $proxy = 'http://ads.harvard.edu/ws/ITWG-DataVerifier-test'; my $client = ITWG::DataVerifier::Client->new(service => $adswsdl); my @ids = $client->verify('foo', 'bar') or die "could not verify data ids: $@"; # same as above... DESCRIPTION ITWG::DataVerifier is a simple PERL module that provides simple framework for building SOAP clients and servers that implement the verification of dataset identifiers as defined by NASA's ADEC. The module contains two main packages, ITWG::DataVerifier::Client and ITWG::DataVerifier::Server, which implement the functionality needed to serialize and exchange the relevant data. It also includes ITWG::DataVerifier::Server::CGI that can be used to deploy a CGI script that implements the server-side verification. If you are a data provider, this is probably what you want to use. In order to get started, please see the scripts and additional files in the subdirectory examples. ITWG::DataVerifier::Client The client package provides an object with a verify() method that can be used for dataset verification. "new(service => WSDL_URL, [OPTIONS])" "new(proxy => CGI_URL, [OPTIONS])" Creates a new ITWG::DataVerifier::Client object. You must supply either a WSDL file URL as part of the input arguments in the call to new() or a server proxy URL so that the object can be properly initialized. Typically the WSDL description of a service can be obtained by retrieving the URL of the CGI service and appending `?WSDL' to it (this at least works for CGI scripts that make use of the ITWG::DataVerifier::Server::CGI package, see below). Additional options can be given as a set of (key => value) elements. Currently the available options are: debug => VAL turn debugging on. If VAL is > 0 a dump of the SOAP request and response is displayed. If VAL > 1 a dump of the deserialized data structures is also displayed. encoding => STRING force a particular encoding. If STRING is set to 'literal' the client will create a SOAP payload which has no type attributes describing the serialized data structure. This sometimes causes interoperability problems with SOAP toolkits that rely on SOAP encoding to deserialize the structure. protocolversion => VAL force the protocol version to be VAL. The default version for this implementation is 0.3. The prior version (0.2) used a different serialization for the data structure exchanged between client and server, which unfortunately makes it incompatible with the current version, although clients and servers using protocol version 0.3 will do their best to interact properly with clients and servers using version 0.2. You should only change this if you know what you're doing. "verify(IDENTIFIER [...])" This is the method that actually sends a SOAP request to a data verification service. The arguments to this function call should be simply the data identifier strings that need to be verified. The function returns an array of hash references, one for each input identifier. The elements of each hash are the following: input - the input string for the identifier result - an integer value specifying whether the identifier is known (1), unknown (0), or has invalid syntax (-1) url - a URL that can be used to create a link for a page describing the dataset in question. ITWG::DataVerifier::Server The server package provides an object with a handle() method that can be used for dataset verification. "new([location => SERVICEURL])" "new([wsdl => WSDLSTRING])" Creates a new object for data verification services. If the option `wsdl' is specified, the buffer in WSDLSTRING is taken to be the WSDL description of the server, and will be returned when the method wsdl() below is called. If the option `location' is specified, the WSDL description is built automatically from the template included in this package. If neither option is specified, the Server object will not be able to server a WSDL file. "verify($hashref)" Drives the verification of data identifiers. This method properly decodes the request (which is encoded in the $hashref variable) and then for each identifier calls a function called `verify_id' in the main package as follows: ($result,$url) = verify_id($identifier); The `verify_id' function must be declared by the application developer in the main program. It should accept a single string as input (the identifier itself), and should return a two-element array consisting of an integer indicating the success of failure of the verification, and in case of success a URL corresponding to a location where data relevant to the identifier is available. See examples/ITWG-DataVerifier-test for an example. ITWG::DataVerifier::Server::CGI The class derived from ITWG::DataVerifier::Server for CGI use. If you need to provide data verification services for your archive, this is probably what you need to use. This class simplifies its usage by automatically creating a WSDL file for you based on the template provided in the package, and serving it when requested. It does this by overloading the new() method so that the location of the service is automatically detected from the CGI enviroment, and then the WSDL file is built based on it. Of course you can still override these settings by specifying either the `location' or `wsdl' options as documented above. "handle()" This call actually decodes and forwards the input request to the verify() function described above. All the work involved in dealing with the SOAP encoding, decoding and verification is encapsulated in this function. SEE ALSO SOAP::Lite AUTHOR Alberto Accomazzi, COPYRIGHT AND LICENSE Copyright 2003 by Alberto Accomazzi This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.