Package uk.ac.starlink.vo
Class TapQuery
java.lang.Object
uk.ac.starlink.vo.TapQuery
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final uk.ac.starlink.votable.DataFormat
Default VOTable serialization format for uploading VOTables to a TAP service. -
Constructor Summary
ConstructorsConstructorDescriptionConvenience constructor that uses a URL rather than a TapService object.Constructs a query with no uploaded tables.TapQuery
(TapService service, String adql, Map<String, String> extraParams, Map<String, uk.ac.starlink.table.StarTable> uploadMap, long uploadLimit, uk.ac.starlink.votable.VOTableWriter vowriter) Constructs a query with uploaded tables. -
Method Summary
Modifier and TypeMethodDescriptioncreateSyncConnection
(uk.ac.starlink.util.ContentCoding coding) Opens a URL connection for the result of synchronously executing this query.uk.ac.starlink.table.StarTable
executeSync
(uk.ac.starlink.table.StoragePolicy storage, uk.ac.starlink.util.ContentCoding coding) Executes this query synchronously and returns the resulting table.boolean
executeSync
(uk.ac.starlink.table.TableSink sink, uk.ac.starlink.util.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.getAdql()
Returns the text of the ADQL query for this object.static uk.ac.starlink.table.StarTable
getResult
(UwsJob uwsJob, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.StoragePolicy storage) Reads and returns the table that resulted from a successful TAP query, represented by a given UWS job.Returns the map of streamed parameters to be passed to the TAP service.Returns the map of string parameters to be passed to the TAP service.Returns the TAP service object to which this query will be submitted.static InputStream
getVOTableStream
(URLConnection conn, uk.ac.starlink.util.ContentCoding coding) Gets an input stream from a URL connection that should contain a VOTable.static uk.ac.starlink.table.StarTable
readResultVOTable
(URLConnection conn, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.TableSink sink) Streams a VOTable document which may represent a successful result or an error.Submits this query asynchronously and returns the corresponding UWS job.static uk.ac.starlink.table.StarTable
waitForResult
(UwsJob uwsJob, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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.
-
Field Details
-
DFLT_UPLOAD_SER
public static final uk.ac.starlink.votable.DataFormat DFLT_UPLOAD_SERDefault VOTable serialization format for uploading VOTables to a TAP service. The value is currentlyDataFormat.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 Details
-
TapQuery
Constructs a query with no uploaded tables.- Parameters:
service
- TAP service descriptionadql
- text of ADQL queryextraParams
- 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, throws IOExceptionuk.ac.starlink.table.StarTable> uploadMap, long uploadLimit, uk.ac.starlink.votable.VOTableWriter vowriter) 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 descriptionadql
- text of ADQL queryextraParams
- 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 ifuploadMap
null or emptyvowriter
- serializer for producing content of uploaded tables; ignored ifuploadMap
null or empty, if null a default value is used- Throws:
IOException
- if upload tables exceed the upload limit
-
TapQuery
Convenience constructor that uses a URL rather than a TapService object. This just usesTapServices.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 serviceadql
- text of ADQL queryextraParams
- 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 Details
-
getAdql
Returns the text of the ADQL query for this object.- Returns:
- ADQL query text
-
getTapService
Returns the TAP service object to which this query will be submitted.- Returns:
- service locations
-
getStringParams
Returns the map of string parameters to be passed to the TAP service.- Returns:
- name->value map for TAP string parameters
-
getStreamParams
Returns the map of streamed parameters to be passed to the TAP service.- Returns:
- name->value map for TAP stream parameters
-
executeSync
public uk.ac.starlink.table.StarTable executeSync(uk.ac.starlink.table.StoragePolicy storage, uk.ac.starlink.util.ContentCoding coding) throws IOException Executes this query synchronously and returns the resulting table.- Parameters:
storage
- storage policy for caching table datacoding
- configures HTTP compression- Returns:
- result table
- Throws:
IOException
-
executeSync
public boolean executeSync(uk.ac.starlink.table.TableSink sink, uk.ac.starlink.util.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 destinationcoding
- configures HTTP compression- Returns:
- true iff the result was marked as overflowed
- Throws:
IOException
SAXException
-
createSyncConnection
public HttpURLConnection createSyncConnection(uk.ac.starlink.util.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
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 querypollMillis
- polling interval in milliseconds- Returns:
- open URL connection to result stream
- Throws:
IOException
InterruptedException
-
waitForResult
public static uk.ac.starlink.table.StarTable waitForResult(UwsJob uwsJob, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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 querycoding
- configures HTTP compressionstorage
- storage policy for caching table datapollMillis
- polling interval in milliseconds- Returns:
- result table
- Throws:
IOException
InterruptedException
-
getResult
public static uk.ac.starlink.table.StarTable getResult(UwsJob uwsJob, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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 querycoding
- configures HTTP compressionstorage
- storage policy for caching table data- Returns:
- the result of reading the TAP result as a table
- Throws:
IOException
-
scalarQuery
Utility method to obtain a single-cell table as the result of a synchronous TAP query.- Parameters:
service
- TAP service descriptionadql
- query stringclazz
- class of required value- Returns:
- single value, or null if no rows
- Throws:
IOException
- if required result cannot be got
-
readResultVOTable
public static uk.ac.starlink.table.StarTable readResultVOTable(URLConnection conn, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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 resourcecoding
- HTTP content coding policy used to prepare connectionstorage
- storage policy- Returns:
- table result of successful query
- Throws:
IOException
-
streamResultVOTable
public static boolean streamResultVOTable(URLConnection conn, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.table.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 resourcecoding
- HTTP content coding policy used to prepare connectionsink
- 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, uk.ac.starlink.util.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 callcoding
- HTTP content coding policy used to prepare connection- Returns:
- stream containing a response table (error or result)
- Throws:
IOException
-
followRedirects
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
-