org.astrogrid.acr.ivoa
Interface Registry


public interface Registry

AR Service: Query the system-configured Registry. AstroRuntime uses an IVOA-compliant registry to retrieve details of available resources - servers, applications, catalogues, etc.

This component provides a range of different methods to search the registry. The most convenient is to use the Registry.search(String) method, which accepts a simple query in the form used by VOExplorer's smart-lists.

The endpoint of this registry service can be inspected by calling Registry.getSystemRegistryEndpoint(). In cases where this service is unavailable, registry queries will automatically fall-back to the backup registry service, whose endpoint is defined by Registry.getFallbackSystemRegistryEndpoint(). The query functions in this interface are the equivalent to their counterparts in the ExternalRegistry interface, but operate against the System and Fallback registries.

Note:

These endpoints can be altered by using the UI preferences pane, or the web interface, or via commandline properties, or programmatically using the Configuration service.

See Also:
IVOA Identifiers, IVOA VOResource Definition, IVOA Registry Interface Standard, XQuery Language Tutorial, External Registry - fuller interface to an arbitrary registry
Service Name
ivoa.registry

Method Summary
 URI getFallbackSystemRegistryEndpoint()
          Access the endpoint of the fallback system registry
 RegistryService getIdentity()
          Access the resource that describing the system registry itself.
 Resource getResource(URI id)
          Retrieve a named resource from the registry.
 URI getSystemRegistryEndpoint()
          Access the endpoint of the system registry
 Resource[] keywordSearch(String keywords, boolean orValues)
          Perform a keyword search.
 Resource[] search(String srql)
          Perform a search using the query language used by VOExplorer SmartLists (SRQL)

Search for IR Redshift resources (Python)

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
#call this function
rs = ar.ivoa.registry.search("ucd = redshift AND waveband = infrared")
#see what we've got  
print len(rs)
#list first 10 identifiers
for r in rs[:10]:
   print r['id']
The output is
 String toXQuery(String srql)
          Translate a SRQL query (as used by VOExplorer SmartLists) into an equivalent XQuery
 Resource[] xquerySearch(String xquery)
          Search the registry using an XQuery.
 Document xquerySearchXML(String xquery)
          Search the registry using an XQuery, returning results as XML.
 

Method Detail

search

Resource[] search(String srql)
                  throws ServiceException,
                         InvalidArgumentException
Perform a search using the query language used by VOExplorer SmartLists (SRQL)

Search for IR Redshift resources (Python)

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
#call this function
rs = ar.ivoa.registry.search("ucd = redshift AND waveband = infrared")
#see what we've got  
print len(rs)
#list first 10 identifiers
for r in rs[:10]:
   print r['id']
The output is
 109
 ivo://CDS.VizieR/J/ApJ/655/51
 ivo://CDS.VizieR/J/ApJ/653/1004
 ivo://CDS.VizieR/J/ApJ/649/63
 ivo://CDS.VizieR/J/ApJ/634/128
 ivo://CDS.VizieR/J/AJ/117/102
 ivo://CDS.VizieR/J/AN/329/418
 ivo://CDS.VizieR/J/ApJS/166/470
 ivo://CDS.VizieR/VII/173
 ivo://CDS.VizieR/VII/157
 ivo://CDS.VizieR/J/other/PBeiO/18.7
 

Equivalent To:
xquerySearch(toXQuery(srql))
Parameters:
srql - query to perform
See Also:
SRQL Language Description
Returns:
list of matching resources
Throws:
ServiceException - if registry cannot be queried.
InvalidArgumentException - if query passed in cannot be parsed as SRQL

keywordSearch

Resource[] keywordSearch(String keywords,
                         boolean orValues)
                         throws ServiceException
Perform a keyword search.

Python Example

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
#call this function
rs = ar.ivoa.registry.keywordSearch("abell",False)
#see what we've got  
print len(rs)
#list first 10 identifiers
for r in rs[:10]
   print r['id']:
The output is
 150
 ivo://CDS.VizieR/J/A+A/486/755
 ivo://uk.ac.le.star.tmpledas/ledas/ledas/abell
 ivo://nasa.heasarc/wblgalaxy
 ivo://nasa.heasarc/wbl
 ivo://nasa.heasarc/twosigma
 ivo://nasa.heasarc/rassebcs
 ivo://nasa.heasarc/noras
 ivo://nasa.heasarc/eingalclus
 ivo://nasa.heasarc/abell
 ivo://CDS.VizieR/VII/96 
 

Parameters:
keywords - space separated list of keywords to search for
orValues - - true to 'OR' together matches. false to 'AND' together matches
Returns:
list of matching resources.
Throws:
ServiceException - if an error occurs talking to the service

toXQuery

String toXQuery(String srql)
                throws InvalidArgumentException
Translate a SRQL query (as used by VOExplorer SmartLists) into an equivalent XQuery

Parameters:
srql - the query to translate
See Also:
SRQL Language Description
Returns:
the equivalent XQuery
Throws:
InvalidArgumentException - if the query cannot be parsed as SRQL.

getResource

Resource getResource(URI id)
                     throws NotFoundException,
                            ServiceException
Retrieve a named resource from the registry.

Parameters:
id - identifier of the registry resource to retrieve. e.g.ivo://uk.ac.cam.ast/IPHAS/images/SIAP
Returns:
a datastructure representing the registry entry - will be a Resource or one of it's subclasses depending on the registry entry type.
Throws:
NotFoundException
ServiceException
XMLRPC
will return a struct. See Resource for details of keys

xquerySearch

Resource[] xquerySearch(String xquery)
                        throws ServiceException
Search the registry using an XQuery.

Warning:

This method returns an array of matching Resource objects - so the XQuery used must produce whole VOResource elements

Python Example

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
 #call this function
xquery ="//vor:Resource[@xsi:type &= '*DataCollection']" 
rs = ar.ivoa.registry.xquerySearch(xquery)
The above XQuery could be written in a longer equivalent form, which is convenient when there are many filter clauses:
for $r in //vor:Resource 
  where $r/@xsi:type  &=  '*DataCollection' 
  return $r     

Notes:
The XML view in VOExplorer is useful for constructing new XQueries. Enable it by Preferences > System > Show Advanced Features
Parameters:
xquery - An XQuery that should return a document, or nodeset, containing whole <Resource> elements. Results are not required to be single-rooted, and resource elements may be embedded within other elements - although the parser will fail in extreme cases.
See Also:
XQuery Language Tutorial, Dal.getRegistryXQuery() - produces XQueries to list all DAL services.
Returns:
an array containing any registry records present in the query result.
Throws:
ServiceException
XMLRPC
will return an array of struct. See Resource for details of keys

xquerySearchXML

Document xquerySearchXML(String xquery)
                         throws ServiceException
Search the registry using an XQuery, returning results as XML.

This method can accept an arbitrary XQuery, unlike Registry.xquerySearch(String), which requires that the XQuery return a list of VOResource elements.

Python Example

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
 #call this function
xquery ="""
    <ssap-wavebands> 
         {
         (:find all spectral services :)
          let $ssap := //vor:Resource[capability/@standardID="ivo://ivoa.net/std/SSA"]          
          (: find the distinct set of wavebands these services cover  (no duplicates) :)
          for $waveband in distinct-values($ssap/coverage/waveband)
          order by $waveband
          (: print each waveband in turn :)
          return <band name="{data($waveband)}">
                 {
                 (: list IDs of all services that cover this band :)
                   for $r in $ssap[coverage/waveband=$waveband]
                   return $r/identifier
                 }
                 </band> 
         }
      </ssap-wavebands>
         """   
xml = ar.ivoa.registry.xquerySearchXML(regEndpoint,xquery)
This will return the following result
<ssap-wavebands>
   <band name="EUV">
       <identifier>ivo://iap.fr/FUSE/SSA</identifier>
       <identifier>ivo://www.g-vo.org/ssa.service.tmap</identifier>
   </band>
   <band name="Infrared">
       <identifier>ivo://archive.eso.org/ESO-SAF-SSAP</identifier>
       <identifier>ivo://basebe.obspm.fr/bess0.1</identifier>
       ...
   </band>
   <band name="Millimeter">
       <identifier>ivo://svo.laeff/models/dalessio</identifier>
       <identifier>ivo://voparis.obspm.gepi/BeStars/BeSS/SSAP</identifier>
   </band>
   <band name="Optical">
       <identifier>ivo://archive.eso.org/ESO-SAF-SSAP</identifier>
       <identifier>ivo://basebe.obspm.fr/bess0.1</identifier>
       ...
   </band>
   <band name="Radio">
       <identifier>ivo://obspm.fr/SSA_HIG</identifier>
       <identifier>ivo://voparis.obspm.gepi/BeStars/BeSS/SSAP</identifier>
   </band>
   <band name="UV">
       <identifier>ivo://archive.eso.org/ESO-SAF-SSAP</identifier>
       <identifier>ivo://basebe.obspm.fr/bess0.1</identifier>
       ...
   </band>
   <band name="X-ray">
       <identifier>ivo://svo.iaa/models/SSP/Xray</identifier>
       <identifier>ivo://www.g-vo.org/ssa.service.tmap</identifier>
   </band>
</ssap-wavebands>
    

Notes:
The XML view in VOExplorer is useful for constructing new XQueries. Enable it by Preferences > System > Show Advanced Features
Parameters:
xquery - the query to perform. Must return a well-formed xml document - i.e. starting with a single root element.
See Also:
XQuery Language Tutorial, Example of registry resource XML
Returns:
the result of executing this xquery over the specified registry - a document of arbitrary structure.
Throws:
ServiceException - if there's a problem connecting to the registry
XMLRPC
will return the string representation of the xml document.

getIdentity

RegistryService getIdentity()
                            throws ServiceException
Access the resource that describing the system registry itself.

This returned resource describes what search capabilities are provided by the registry

See Also:
SearchCapability, ExternalRegistry.getIdentity(java.net.URI)
Throws:
ServiceException

getSystemRegistryEndpoint

URI getSystemRegistryEndpoint()
                              throws ServiceException
Access the endpoint of the system registry

Throws:
ServiceException

getFallbackSystemRegistryEndpoint

URI getFallbackSystemRegistryEndpoint()
                                      throws ServiceException
Access the endpoint of the fallback system registry

Throws:
ServiceException


Copyright © 2002-2010 AstroGrid. All Rights Reserved.