NAME

LS::Locator - Resolve authorities for 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

Objects of the LS::Locator class will resolve the authority of a given LSID using DNS SRV records. Results are cached for speed.

If a file called authorities is present in the working directory, the locator's cache is preloaded with the contents of the file. The authorities file contains a newline separated list of id/location pairs. Each pair is delimited with whitespace. Lines starting with # are treated as comments. An example authorities file would look like this:

 # This file enables local resolution of LSID authorities.
 # id      server:port/servicepath

 authority.testing.org   myauthority.org:80/cgi-bin/authority.pl

More information on LSIDs and their resolution can be found at http://www.omg.org/cgi-bin/apps/doc?dtc/04-05-01

CONSTRUCTORS

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

new ( [%options] )

This class method creates a new LS::Locator object and returns it. Key/value pair arguments may be provided to initialize locator options. The available options names are local and nocache. The options can also be set or modified later by method calls described below.

Examples:

 $locator = LS::Locator->new(localMappingFile => 'c:\lsid\authorities.txt');

This creates a new locator object whose cache will be preloaded with the contents of the file c:\lsid\authorities.txt.

METHODS

loadLocalMappingFile ( )

Loads the entries specified by localMappingFile in to the locator's cache. Calling this method will overwrite any existing entries in the cache that also appear in the file.

localMappingFile ( [$filename] )

Sets or retrieves the name of the local authorities file being used by the locator. By default, the authorities file is the file called authorities in the working directory. To turn off local authority resolution, call clearCache, then call this method with an argument of undef.

The file is NOT immediately read into the locator's cache, you must call loadLocalMappingFile which will overwrite any existing entries in the cache that also appear in the file.

Examples:

 $locator = LS::Locator->new();
 
 # Load the cache with the contents of f<c:\lsid\myauthorities.txt>
 
 $locator->localMappingFile('c:\lsid\myauthorities.txt');
 $locator->loadLocalMappingFile();
 
 $authority = $locator->resolveAuthority('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');
 
 # Now turn off local resolution

 $locator->clearCache();
 $locator->localMappingFile(undef);

clearCache ( )

Clears the locator's cache of authorities. After the cache is cleared, it is re-initialized with the contents of the local authorities file, if present.

cacheAuthorities ( $bool )

If this method is called with a true value, the results of future Authority resolutions will be cached. This does not affect the current contents of the cache, nor does it affect the reading of a local authorities file into the cache. It only prevents future DNS respnses from being added. If the method is called with a defined false value, e.g. 0, caching of Authority responses will stop. If the method is called with an undefined argument, the current setting is returned.

resolveAuthority ( $id )

Resolves the authority for the given ID. The ID may either be an LSID as a string or an object of class LS::ID, or an authority ID as a string of the form lsidauth:authority_id. The return value is an object of class LS::Authority, or undef if the LSID could not be resolved. In this case, errorString can be checked for a description of the error.

Examples:

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

 $authority = $locator->resolveAuthority('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');

 $authority = $locator->resolveAuthority('lsidauth:ncbi.nlm.nih.gov.lsid.biopathways.org');

errorString ( )

Returns a description of the last error that occurred in the locator.

Examples:

 $authority = $locator->resolveAuthority('urn:lsid:ncbi.nlm.nih.gov.lsid.biopathways.org:pubmed:12441807');

 if (!$authority) {
        warn('Unable to resolve authority: ', $locator->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