uk.ac.starlink.vo

Class TapQuery

java.lang.Object

uk.ac.starlink.vo.TapQuery

public class TapQuery
extends Object

Represents a query to be made to a Table Access Protocol service. This class aggregates the information which needs to be sent to make such a query and provides methods to submit the query synchronously or asynchronously. It also contains some static methods to perform other TAP-related operations.

Since:

8 Apr 2011

Author:

Mark Taylor

See Also:

IVOA TAP Recommendation

Field Summary

Fields

Modifier and Type	Field and Description
static DataFormat	DFLT_UPLOAD_SER Default VOTable serialization format for uploading VOTables to a TAP service.

Constructor Summary

Constructors

Constructor and Description
TapQuery(TapService service, String adql, Map<String,String> extraParams) Constructs a query with no uploaded tables.
TapQuery(TapService service, String adql, Map<String,String> extraParams, Map<String,StarTable> uploadMap, long uploadLimit, VOTableWriter vowriter) Constructs a query with uploaded tables.
TapQuery(URL serviceUrl, String adql, Map<String,String> extraParams) Convenience constructor that uses a URL rather than a TapService object.

Method Summary

Modifier and Type	Method and Description
HttpURLConnection	createSyncConnection(ContentCoding coding) Opens a URL connection for the result of synchronously executing this query.
StarTable	executeSync(StoragePolicy storage, ContentCoding coding) Executes this query synchronously and returns the resulting table.
boolean	executeSync(TableSink sink, ContentCoding coding) Executes this query synchronously and streams the resulting table to a table sink.
static URLConnection	followRedirects(URLConnection conn) Takes a URLConnection and repeatedly follows 303 redirects until a non-303 status is achieved.
String	getAdql() Returns the text of the ADQL query for this object.
static StarTable	getResult(UwsJob uwsJob, ContentCoding coding, StoragePolicy storage) Reads and returns the table that resulted from a successful TAP query, represented by a given UWS job.
Map<String,HttpStreamParam>	getStreamParams() Returns the map of streamed parameters to be passed to the TAP service.
Map<String,String>	getStringParams() Returns the map of string parameters to be passed to the TAP service.
TapService	getTapService() Returns the TAP service object to which this query will be submitted.
static InputStream	getVOTableStream(URLConnection conn, ContentCoding coding) Gets an input stream from a URL connection that should contain a VOTable.
static StarTable	readResultVOTable(URLConnection conn, ContentCoding coding, StoragePolicy storage) Reads a VOTable which may represent a successful result or an error.
static <T> T	scalarQuery(TapService service, String adql, Class<T> clazz) Utility method to obtain a single-cell table as the result of a synchronous TAP query.
static boolean	streamResultVOTable(URLConnection conn, ContentCoding coding, TableSink sink) Streams a VOTable document which may represent a successful result or an error.
UwsJob	submitAsync() Submits this query asynchronously and returns the corresponding UWS job.
static StarTable	waitForResult(UwsJob uwsJob, ContentCoding coding, StoragePolicy storage, long pollMillis) Blocks until the TAP query represented by a given UWS job has completed, then returns a table based on the result.
static URL	waitForResultUrl(UwsJob uwsJob, long pollMillis) Blocks until the TAP query represented by a given UWS job has completed, then returns the URL from which the successful result can be obtained.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DFLT_UPLOAD_SER

public static final DataFormat DFLT_UPLOAD_SER

Default VOTable serialization format for uploading VOTables to a TAP service. The value is currently DataFormat.TABLEDATA. BINARY would be more efficient and ought to be OK, but at time of writing at least CADC, and under some circumstances other services, work properly with TABLEDATA but not BINARY uploaded tables, so for now conform to the lowest common denominator.

Constructor Detail

TapQuery

public TapQuery(TapService service,
                String adql,
                Map<String,String> extraParams)

Constructs a query with no uploaded tables.

Parameters:

service - TAP service description

adql - text of ADQL query

extraParams - key->value map for optional parameters; if any of these match the names of standard parameters (upper case) the standard values will be overwritten, so use with care (may be null)

TapQuery

public TapQuery(TapService service,
                String adql,
                Map<String,String> extraParams,
                Map<String,StarTable> uploadMap,
                long uploadLimit,
                VOTableWriter vowriter)
         throws IOException

Constructs a query with uploaded tables. May throw an IOException if the tables specified for upload exceed the stated upload limit.

Parameters:

service - TAP service description

adql - text of ADQL query

extraParams - key->value map for optional parameters; if any of these match the names of standard parameters (upper case) the standard values will be overwritten, so use with care (may be null)

uploadMap - name->table map of tables to be uploaded to the service for the query (may be null)

uploadLimit - maximum number of bytes that may be uploaded; if negative, no limit is applied, ignored if uploadMap null or empty

vowriter - serializer for producing content of uploaded tables; ignored if uploadMap null or empty, if null a default value is used

Throws:

IOException - if upload tables exceed the upload limit

TapQuery

public TapQuery(URL serviceUrl,
                String adql,
                Map<String,String> extraParams)

Convenience constructor that uses a URL rather than a TapService object. This just uses TapServices.createDefaultTapService(java.net.URL) and then invokes one of the other constructors.

This form is mildly deprecated, it is preferred to create your own TapService as above and submit that to one of the other constructors instead. It's present because other classes rely on it, but there is no intention to add URL-based constructors corresponding to the other TapService-based forms.

Parameters:

serviceUrl - base URL of TAP service

adql - text of ADQL query

extraParams - key->value map for optional parameters; if any of these match the names of standard parameters (upper case) the standard values will be overwritten, so use with care (may be null)

Method Detail

getAdql

public String getAdql()

Returns the text of the ADQL query for this object.

Returns:

ADQL query text

getTapService

public TapService getTapService()

Returns the TAP service object to which this query will be submitted.

Returns:

service locations

getStringParams

public Map<String,String> getStringParams()

Returns the map of string parameters to be passed to the TAP service.

Returns:

name->value map for TAP string parameters

getStreamParams

public Map<String,HttpStreamParam> getStreamParams()

Returns the map of streamed parameters to be passed to the TAP service.

Returns:

name->value map for TAP stream parameters

executeSync

public StarTable executeSync(StoragePolicy storage,
                             ContentCoding coding)
                      throws IOException

Executes this query synchronously and returns the resulting table.

Parameters:

storage - storage policy for caching table data

coding - configures HTTP compression

Returns:

result table

Throws:

IOException

executeSync

public boolean executeSync(TableSink sink,
                           ContentCoding coding)
                    throws IOException,
                           SAXException

Executes this query synchronously and streams the resulting table to a table sink. If the result is a TAP error document, it will be presented as an exception thrown from this method. Overflow status of a successful result is provided by the return value.

Parameters:

sink - table destination

coding - configures HTTP compression

Returns:

true iff the result was marked as overflowed

Throws:

IOException

SAXException

createSyncConnection

public HttpURLConnection createSyncConnection(ContentCoding coding)
                                       throws IOException

Opens a URL connection for the result of synchronously executing this query.

Parameters:

coding - HTTP content-coding policy result should be interpreted with same coding

Returns:

HTTP connection containing query result

Throws:

IOException

submitAsync

public UwsJob submitAsync()
                   throws IOException

Submits this query asynchronously and returns the corresponding UWS job. The job is not started.

Returns:

new UWS job for this query

Throws:

IOException

waitForResultUrl

public static URL waitForResultUrl(UwsJob uwsJob,
                                   long pollMillis)
                            throws IOException,
                                   InterruptedException

Blocks until the TAP query represented by a given UWS job has completed, then returns the URL from which the successful result can be obtained. If the job does not complete successfully, an IOException is thrown instead.

Parameters:

uwsJob - started UWS job representing an async TAP query

pollMillis - polling interval in milliseconds

Returns:

open URL connection to result stream

Throws:

IOException

InterruptedException

waitForResult

public static StarTable waitForResult(UwsJob uwsJob,
                                      ContentCoding coding,
                                      StoragePolicy storage,
                                      long pollMillis)
                               throws IOException,
                                      InterruptedException

Blocks until the TAP query represented by a given UWS job has completed, then returns a table based on the result. In case of job failure, an exception will be thrown instead.

Parameters:

uwsJob - started UWS job representing an async TAP query

coding - configures HTTP compression

storage - storage policy for caching table data

pollMillis - polling interval in milliseconds

Returns:

result table

Throws:

IOException

InterruptedException

getResult

public static StarTable getResult(UwsJob uwsJob,
                                  ContentCoding coding,
                                  StoragePolicy storage)
                           throws IOException

Reads and returns the table that resulted from a successful TAP query, represented by a given UWS job. The query is assumed to have requested output in VOTable format. If the job has not reached COMPLETED phase, an IOException will result.

Parameters:

uwsJob - successfully completed UWS job representing an async TAP query

coding - configures HTTP compression

storage - storage policy for caching table data

Returns:

the result of reading the TAP result as a table

Throws:

IOException

scalarQuery

public static <T> T scalarQuery(TapService service,
                                String adql,
                                Class<T> clazz)
                         throws IOException

Utility method to obtain a single-cell table as the result of a synchronous TAP query.

Parameters:

service - TAP service description

adql - query string

clazz - class of required value

Returns:

single value, or null if no rows

Throws:

IOException - if required result cannot be got

readResultVOTable

public static StarTable readResultVOTable(URLConnection conn,
                                          ContentCoding coding,
                                          StoragePolicy storage)
                                   throws IOException

Reads a VOTable which may represent a successful result or an error. If it represents an error (in accordance with the TAP rules for expressing this), an exception will be thrown.

Parameters:

conn - connection to table resource

coding - HTTP content coding policy used to prepare connection

storage - storage policy

Returns:

table result of successful query

Throws:

IOException

streamResultVOTable

public static boolean streamResultVOTable(URLConnection conn,
                                          ContentCoding coding,
                                          TableSink sink)
                                   throws IOException,
                                          SAXException

Streams a VOTable document which may represent a successful result or an error. If it represents an error (in accordance with the TAP rules for expressing this), an exception will be thrown. Overflow status of a successful result is provided by the return value.

Note: any XML that comes after the TABLE element of the result table is ignored for the purposes of reporting the table metadata. The only thing after the end of the TABLE that affects the result of this method is the overflow flag, which affects the return value. So if you need to pick up items which might be in trailing elements, for instance Service Descriptors in later RESOURCE elements, you will have to use a different method.

Parameters:

conn - connection to table resource

coding - HTTP content coding policy used to prepare connection

sink - destination for table result of succesful query

Returns:

true iff the result was marked as overflowed

Throws:

IOException

SAXException

getVOTableStream

public static InputStream getVOTableStream(URLConnection conn,
                                           ContentCoding coding)
                                    throws IOException

Gets an input stream from a URL connection that should contain a VOTable.

Parameters:

conn - connection to result of TAP service call

coding - HTTP content coding policy used to prepare connection

Returns:

stream containing a response table (error or result)

Throws:

IOException

followRedirects

public static URLConnection followRedirects(URLConnection conn)
                                     throws IOException

Takes a URLConnection and repeatedly follows 303 redirects until a non-303 status is achieved. Infinite loops are defended against. The Accept-Encoding header, if present, is propagated to redirect targets.

Parameters:

conn - initial URL connection

Returns:

target URL connection (if no redirects, the same as hconn)

Throws:

IOException