NAME

LS::Authority - Authority service (client stub) for resources identified by LSIDs

SYNOPSIS

use LS::ID;
use LS::Locator;

$lsid = LS::ID->new('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');

$locator = LS::Locator->new;
$authority = $locator->resolveAuthority($lsid);

$auth_host = $authority->host();
$auth_port = $authority->port();
$auth_path = $authority->path();

$resource = $authority->getResource($lsid);
$data = $resource->getData();

DESCRIPTION

An object of the LS::Authority class represents a web service responsible for resolving LSIDs for a particular organization. An authority service is located for a particular LSID by passing the LSID to the resolveAuthority method of an LS::Locator object. More information on LSIDs and authorities can be found at http://www.omg.org/cgi-bin/doc?dtc/04-05-01

CONSTRUCTORS

The following methods are used to construct a new LS::Authority object:

new ( $id )

This class method creates a new LS::Authority object and returns it. The $id parameter may be an LSID in the form of a string or an LS::ID object, in which case the authority governing the LSID is resolved using a default LS::Locator, and the resulting authority is returned. $id may also be a string of the form lsidauth:authority_id, in which case the authority named by the authority ID is resolved using a default LS::Locator, and returned.

Examples:

$authority = LS::Authority->new('lsidauth:ncbi.nlm.nih.gov.lsid.biopathways.org') || warn("Error creating authority: ", &LS::Authority->errorString(), "\n");

$authority = LS::Authority->new('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807') || warn("Error creating authority: ", &LS::Authority->errorString(), "\n");

new_by_hostname ( $host, $port, $path )

This class method creates a new LS::Authority object and returns it. The parameters are the hostname of the server on which the authority service is located, the port number on the host, and the path to the service.

Most users will never need to call this constructor, as the usual way to obtain an LS::Authority object is to call the new constructor using an LSID or an authority ID, or to resolve the authority for an LSID using the resolveAuthority method on an LS::Locator object.

Examples:

$authority = LS::Authority->new('lsid.biopathways.org', '9090', 'authority');

METHODS

host ( )

Returns the hostname of the authority service.

port ( )

Returns the port number of the authority service.

path ( )

Returns the path of the authority service.

getAvailableServices( $lsid )

Queries the authority service for the available operations for the given LSID. The LSID may either be a string or an object of class LS::ID. The return value is a string, which is a WSDL document describing the operations, or undef if an error occurs. Error messages can be checked by calling the errorString method.

Note that this method returns raw WSDL. You probably want to call getResource instead, unless you really intend to parse the WSDL yourself.

Examples:

 $lsid = LS::ID->new('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');
 $wsdl = $authority->getAvailableServices($lsid);

 if ($wsdl) {
	print "WSDL for $lsid:\n";
	print $wsdl;
 }
 else {
 	print "Error getting operations for $lsid: ", $authority->errorString(), "\n";
 }

getResource ( $lsid )

Queries the authority service for the resource identified by the given LSID. The LSID may either be a string or an object of class LS::ID. The return value is an object of class LS::Resource, or undef if an error occurs. Error messages can be checked by calling the errorString method.

Examples:

 $lsid = LS::ID->new('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');
 $resource = $authority->get_resource($lsid);

 if ($resource) {
	print "The resource $lsid is valid\n";
 }
 else {
 	print "Error getting resource $lsid: ", $authority->errorString(), "\n";
 }

errorString ( )

This can be called either as a static method, a class method, or an instance method. As a static or class method, it returns a description of the last error that ocurred during a failed object creation. As an instance method, it returns a description of the error that occurred in the last call to an instance method on the object.

Examples:

 $authority = LS::Authority->new('lsidauth:ncbi.nlm.nih.gov.lsid.biopathways.org') || warn("Error creating authority: ", &LS::Authority::errorString(), "\n");
 
 $authority = LS::Authority->new('lsidauth:ncbi.nlm.nih.gov.lsid.biopathways.org') || warn("Error creating authority: ", &LS::Authority->errorString(), "\n");
 
 $services = $authority->getAvailableServices('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');
 
 unless ($services) {
	warn("Error getting authority WSDL: " . $authority->errorString() . "\n");
 }

COPYRIGHT

Copyright (c) 2002,2003 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.opensource.org/licenses/cpl.php