uk.ac.starlink.vo
Class TapQuery

java.lang.Object
  extended by 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

Constructor Summary
TapQuery(URL serviceUrl, String adql, Map<String,String> extraParams)
          Constructs a query with no uploaded tables.
TapQuery(URL serviceUrl, String adql, Map<String,String> extraParams, Map<String,StarTable> uploadMap, long uploadLimit, VOTableWriter vowriter)
          Constructs a query with uploaded tables.
 
Method Summary
 HttpURLConnection createSyncConnection()
          Opens a URL connection for the result of synchronously executing this query.
 StarTable executeSync(StoragePolicy storage)
          Executes this query synchronously and returns the resulting table.
 boolean executeSync(TableSink sink)
          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, StoragePolicy storage)
          Reads and returns the table that resulted from a successful TAP query, represented by a given UWS job.
 URL getServiceUrl()
          Returns the TAP service URL to which this query will be submitted.
 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.
static InputStream getVOTableStream(URLConnection conn)
          Gets an input stream from a URL connection that should contain a VOTable.
static StarTable readResultVOTable(URLConnection conn, StoragePolicy storage)
          Reads a VOTable which may represent a successful result or an error.
static SchemaMeta[] readTableMetadata(URL serviceUrl)
          Reads table metadata from a TAP service.
static TapCapability readTapCapability(URL serviceUrl)
          Reads capability information from a TAP service.
static boolean streamResultVOTable(URLConnection conn, 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, 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
 

Constructor Detail

TapQuery

public TapQuery(URL serviceUrl,
                String adql,
                Map<String,String> extraParams)
Constructs a query with no uploaded tables.

Parameters:
serviceUrl - base service URL for TAP service (excluding "/[a]sync")
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(URL serviceUrl,
                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:
serviceUrl - base service URL for TAP service (excluding "/[a]sync")
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
Method Detail

getAdql

public String getAdql()
Returns the text of the ADQL query for this object.

Returns:
ADQL query text

getServiceUrl

public URL getServiceUrl()
Returns the TAP service URL to which this query will be submitted.

Returns:
serviceUrl

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)
                      throws IOException
Executes this query synchronously and returns the resulting table.

Parameters:
storage - storage policy for caching table data
Returns:
result table
Throws:
IOException

executeSync

public boolean executeSync(TableSink sink)
                    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
Returns:
true iff the result was marked as overflowed
Throws:
IOException
SAXException

createSyncConnection

public HttpURLConnection createSyncConnection()
                                       throws IOException
Opens a URL connection for the result of synchronously executing this query.

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,
                                      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
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,
                                  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
storage - storage policy for caching table data
Returns:
the result of reading the TAP result as a table
Throws:
IOException

readTableMetadata

public static SchemaMeta[] readTableMetadata(URL serviceUrl)
                                      throws IOException,
                                             SAXException
Reads table metadata from a TAP service.

Parameters:
serviceUrl - base TAP service URL
Returns:
table metadata
Throws:
IOException
SAXException

readTapCapability

public static TapCapability readTapCapability(URL serviceUrl)
                                       throws IOException,
                                              SAXException
Reads capability information from a TAP service.

Parameters:
serviceUrl - base TAP service URL
Returns:
capability information
Throws:
IOException
SAXException

readResultVOTable

public static StarTable readResultVOTable(URLConnection conn,
                                          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
storage - storage policy
Returns:
table result of successful query
Throws:
IOException

streamResultVOTable

public static boolean streamResultVOTable(URLConnection conn,
                                          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.

Parameters:
conn - connection to table resource
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)
                                    throws IOException
Gets an input stream from a URL connection that should contain a VOTable.

Parameters:
conn - connection to result of TAP service call
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.

Parameters:
conn - initial URL connection
Returns:
target URL connection (if no redirects, the same as hconn)
Throws:
IOException


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.