org.astrogrid.acr.ivoa
Interface Cone

All Superinterfaces:

Dal

public interface Cone
extends Dal

AR Service: Query for Catalogs from Cone-Search Services (DAL).

Note:

This class provides functions to construct a DAL query. To execute that query, see the examples and methods in the Dal class.

Constructing a Query

The first stage in querying a cone-service is to select the service to query, find the position to query at, and then call the Cone.constructQuery(URI, double, double, double) function:

Contructing a Cone Query (Python)

# connect to the AR
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')        
cone = ar.ivoa.cone #take a reference to the AR Cone component

#the Cone service to query (selected using voexplorer)
service = "ivo://irsa.ipac/2MASS-PSC"
#resolve an object name to a position
pos = ar.cds.sesame.resolve('m54')
#build a query
query = cone.constructQuery(service,pos['ra'],pos['dec'],0.001)
print "QueryURL",query

This script produces a query URL (shown below), which can the be passed to the methods in the Dal class.

QueryURL http://irsa.ipac.caltech.edu/cgi-bin/Oasis/CatSearch/nph-catsearch?CAT=fp_psc&RA=283.7636667&DEC=-30.4785&SR=0.0010

Adding the VERB parameter

The optional VERB parameter determines how many columns are to be returned by the service. From the Cone specification:

The query MAY contain the optional parameter, VERB, whose value is an integer - either 1, 2, or 3 - which determines how many columns are to be returned in the resulting table. Support for this parameter by a Cone Search service implementation is optional. If the service supports the parameter, then when the value is 1, the response should include the bare minimum of columns that the provider considers useful in describing the returned objects. When the value is 3, the service should return all of the columns that are available for describing the objects. A value of 2 is intended for requesting a medium number of columns between the minimum and maximum (inclusive) that are considered by the provider to most typically useful to the user. When the VERB parameter is not provided, the server should respond as if VERB=2. If the VERB parameter is not supported by the service, the service should ignore the parameter and should always return the same columns for every request.

A query that includes the VERB parameter can be constructed as follows:

Constructing a Query with the VERB parameter (Python)

#build a query, as before.
query = cone.constructQuery(service,pos['ra'],pos['dec'],0.001)
#add a 'verb' parameter
query = cone.addOption(query,"VERB",3)

Notes:

This service extends the Dal interface, which provides functions to execute queries. The functions listed within this interface are just for constructing that query.

See Also:

IVOA Cone Search Standard Document, Dal

Service Name

ivoa.cone

Method Summary

URL	constructQuery(URI service, double ra, double dec, double sr) Construct a Cone-Search Query.

Methods inherited from interface org.astrogrid.acr.ivoa.Dal

addOption, execute, executeAndSave, executeVotable, getRegistryQuery, getRegistryXQuery, saveDatasets, saveDatasetsSubset

Method Detail

constructQuery

URL constructQuery(URI service,
                   double ra,
                   double dec,
                   double sr)
                   throws InvalidArgumentException,
                          NotFoundException

Construct a Cone-Search Query. The cone search standard allows queries on Right Ascension, Declination and Search Radius, all given in decimal degrees.

Parameters:

service - Resource Identifier or URL of the Service to query. Prefer providing a Resource Identifier, as this insulates against changes in service endpoint.

Resource Identifier

The resource ID of the Cone Search service to query, as returned by Resource.getId(). Example: ivo://irsa.ipac/2MASS-XSC
The Registry will be queried to resolve the resource ID into a Resource object, from which the ConeCapability will be found, from which in turn the first AccessURL will be used.

URL of the Service

The endpoint URL. Can be any http:// URL.

ra - right ascension e.g 6.950

dec - declination e.g. -1.6

sr - search radius e.g. 0.1

See Also:

Sesame - resolves object names to RA,Dec positions, getRegistryXQuery() - a query to list all Cone Search Services.

Returns:

A query URL. The query can then be performed by either

• programmatically performing a HTTP GET on the query URL
• passing the query URL to one of the Dal execute methods - such as Dal.executeAndSave(URL, URI)

Throws:

InvalidArgumentException - if service is not a http:// or ivo:// reference

NotFoundException - if the service does not exist (i.e. cannot be resolved in reg)