NAME

LS::Resource - A resource identified by an LSID

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

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

or

 use LS::Resource;

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

DESCRIPTION

An object of the LS::Resource class represents a resource identified by an LSID. A resource can be either an abstract class, or a concrete instance of that class. More information on LSIDs and the resources they identify can be found at http://www.omg.org/cgi-bin/doc?dtc/04-05-01.

CONSTRUCTORS

The following method is used to construct a new LS::Resource object:

new ( $lsid, [ $authority, [$wsdl] ] )

This class method creates a new LS::Resource object and returns it. The $lsid parameter is the LSID which identifies this resource, and can either be a string or an object of class LS::ID. The optional $authority parameter is an object of class LS::Authority, and represents the authority service which "knows" about this resource. If $authority is omitted, the authority will be determined by resolving $lsid using a default LS::Locator object. The optional $wsdl parameter is a string containing a description of the interface to the resource. If $wsdl is omitted, the description will be obtained by calling the getAvailableServices method of the authority service. If an error occurs during object creation, undef is returned, and an error message can be retrieved using the errorString class method.

Most users will only call this constructor using the first parameter.

Examples:

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

 if (!$resource) {
        print "Error creating resource: ", &LS::Resource::errorString(), "\n";
 }

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

 if (!$another_resource) {
        print "Error creating another resource: ", LS::Resource->errorString(), "\n";
 }

METHODS

PARAMETER DETAILS

For the methods: getMetadata, getData, getMetadataLocation, getMetadataLocations, getDataLocation, and getDataLocations, you may specify the following options as hash arguments:

location

The location LS::Authority::WSDL::Simple::Location object describing this location. This is the parameter that is the most specifc and receives the highest priority in the search.

protocol

May be one of the following constants: $LS::Authority::WSDL::Constants::Protocols::HTTP, $LS::Authority::WSDL::Constants::Protocols::SOAP

The FTP protocol is discouraged: $LS::Authority::WSDL::Constants::Protocols::FTP

method

For the $LS::Authority::WSDL::Constants::Protocols::HTTP protocol you can optionally specify either POST or GET directing the HTTP client how it should retrieve the data.

authority ( )

Returns the authority service that has knowledge about this resource, as an object of class LS::Authority.

lsid ( )

Returns the LSID that identifies this resource, as an object of class LS::ID.

getMetadata ( %options )

Retrieves the RDF metadata describing the resource. The return value is an LS::Service::Response object containing the metadata, or undef if an error occurs. Error messages can be checked by calling the errorString method.

In addition to the standard method parameters, you may optionally specify an results format string as seen in the following example:

        $resource->getMetadata(format=> 'application/xml+rdf');

This will instruct the authority for the LSID resource to only return metadata that is of the MIME type 'application/rdf+xml'.

See the section entitled "PARAMETER DETAILS" for mor information about how to pass parameters to this method.

getMetadataLocations ( [ $serviceName ] )

Retrieves the locations of the getMetadata operation of the resource for the specified $serviceName. If the $serviceName is left unspecified the default or first service defined in the WSDL will be used.

The return value is a reference to an array of objects of class LS::Authority::WSDL::Simple::Location, or undef if the method is not available. The location objects have three members, as shown in the example.

 $locations = $resource->getMetadataLocations();

 if ($locations) {
        foreach $loc (@$locations) {
                $protocol = $loc->protocol();  # a string, either 
                $url = $loc->url(); # a string

                if ($protocol eq $LS::Authority::WSDL::Constants::Protocols::HTTP) {
                        $method = $loc->method(); # if protocol is HTTP, this is the HTTP method, eg 'GET'
                }
        }
 }

For more granular control over which location to return see getMetadataLocation

getMetadataLocation ( %options )

See the section entitled "PARAMETER DETAILS" for mor information about how to pass parameters to this method.

getData ( %options )

If you need more control over the download, you can use the getDataLocation and getDataLocations methods to find the URLs where the data are located, and then pass that location to this method.

See the section entitled "PARAMETER DETAILS" for mor information about how to pass parameters to this method.

Examples:

 $data = $resource->getData();

 if (defined $data) {
        open FILE, '>data');
        print FILE $data;
        close FILE;
 }
 else {
        print "Error getting data: ", $resource->errorString(), "\n";   
 }

getDataLocations( %options )

Retrieves the locations of the getData operation for the resource. The return value is a reference to an array of objects of class LS::Authority::WSDL::Simple::Location, or undef if the method is not available. The location objects have three members, as shown in the example.

Examples:

 $locations = $resource->getDataLocations();

 if ($locations) {
        foreach $loc (@$locations) {
                $protocol = $loc->protocol();  # a string, either $LS::Authority::WSDL::Constants::Protocols::HTTP, $LS::Authority::WSDL::Constants::FTP, or $LS::Authority::WSDL::Constants::SOAP
                $url = $loc->url(); # a string

                if ($protocol eq $LS::Authority::WSDL::Constants::Protocols::HTTP) {
                        $method = $loc->method(); # if protocol is HTTP, this is the HTTP method, eg 'GET'
                }
        }
 }

See the section entitled "PARAMETER DETAILS" for mor information about how to pass parameters to this method.

getDataLocation ( %options )

Returns the locations at which the resource's data can be found, which is accessible using the given protocol. If the protocol is HTTP, an optional HTTP method can be supplied. undef is returned if no matching location is found. The return value is an object of class LS::Authority::WSDL::Simple::Location, as shown above.

Examples:

 $ftp_location = $resource->getDataLocation(protocol=> $LS::Authority::WSDL::Constants::Protocols::FTP);

 $http_get_location = $resource->getDataLocation(protocol=> $LS::Authority::WSDL::Constants::Protocols::HTTP, 
                                                 method=> 'GET');

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 last error that occurred in another instance method on the object.

Examples:

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

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

 $data = $resource->getData();

 if (defined $data) {
        # Do something
 }
 else {
        print "Error getting data: ", $resource->errorString(), "\n";
 }

data_locations ( )

Deprecated. Use getDataLocations instead.

data_location ( $protocol, [ $method ] )

Deprecated. Use getDataLocation instead.

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