Package uk.ac.starlink.vo

## Class TapQuery

- java.lang.Object
- - uk.ac.starlink.vo.TapQuery

-     public class TapQuery
      extends java.lang.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 | Description
    --- | --- | ---
    `static uk.ac.starlink.votable.DataFormat` | `DFLT_UPLOAD_SER` | Default VOTable serialization format for uploading VOTables to a TAP service.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TapQuery​(java.net.URL serviceUrl, java.lang.String adql, java.util.Map<java.lang.String,java.lang.String> extraParams)` | Convenience constructor that uses a URL rather than an EndpointSet.
    `TapQuery​(EndpointSet endpointSet, java.lang.String adql, java.util.Map<java.lang.String,java.lang.String> extraParams)` | Constructs a query with no uploaded tables.
    `TapQuery​(EndpointSet endpointSet, java.lang.String adql, java.util.Map<java.lang.String,java.lang.String> extraParams, java.util.Map<java.lang.String,uk.ac.starlink.table.StarTable> uploadMap, long uploadLimit, uk.ac.starlink.votable.VOTableWriter vowriter)` | Constructs a query with uploaded tables.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.net.HttpURLConnection` | `createSyncConnection​(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 java.net.URLConnection` | `followRedirects​(java.net.URLConnection conn)` | Takes a URLConnection and repeatedly follows 303 redirects until a non-303 status is achieved.
    `java.lang.String` | `getAdql​()` | Returns the text of the ADQL query for this object.
    `EndpointSet` | `getEndpointSet​()` | Returns the endpoints of TAP services to which this query will be submitted.
    `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.
    `java.util.Map<java.lang.String,HttpStreamParam>` | `getStreamParams​()` | Returns the map of streamed parameters to be passed to the TAP service.
    `java.util.Map<java.lang.String,java.lang.String>` | `getStringParams​()` | Returns the map of string parameters to be passed to the TAP service.
    `static java.io.InputStream` | `getVOTableStream​(java.net.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​(java.net.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​(EndpointSet endpointSet, java.lang.String adql, java.lang.Class<T> clazz)` | Utility method to obtain a single-cell table as the result of a synchronous TAP query.
    `static boolean` | `streamResultVOTable​(java.net.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.
    `UwsJob` | `submitAsync​()` | 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 java.net.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 uk.ac.starlink.votable.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​(EndpointSet endpointSet,
                          java.lang.String adql,
                          java.util.Map<java.lang.String,java.lang.String> extraParams)

      Constructs a query with no uploaded tables.
      Parameters:
        `endpointSet` - locations of TAP service endpoints
        `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​(EndpointSet endpointSet,
                          java.lang.String adql,
                          java.util.Map<java.lang.String,java.lang.String> extraParams,
                          java.util.Map<java.lang.String,uk.ac.starlink.table.StarTable> uploadMap,
                          long uploadLimit,
                          uk.ac.starlink.votable.VOTableWriter vowriter)
                   throws java.io.IOException

      Constructs a query with uploaded tables. May throw an IOException if the tables specified for upload exceed the stated upload limit.
      Parameters:
        `endpointSet` - locations of TAP service endpoints
        `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:
        `java.io.IOException` - if upload tables exceed the upload limit

    - #### TapQuery

          public TapQuery​(java.net.URL serviceUrl,
                          java.lang.String adql,
                          java.util.Map<java.lang.String,java.lang.String> extraParams)

      Convenience constructor that uses a URL rather than an EndpointSet. This just uses `Endpoints.createDefaultTapEndpointSet(java.lang.String)` and then invokes one of the other constructors.

      This form is mildly deprecated, it is preferred to create your own EndpointSet 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 EndpointSet-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 java.lang.String getAdql​()

      Returns the text of the ADQL query for this object.
      Returns:
        ADQL query text

    - #### getEndpointSet

          public EndpointSet getEndpointSet​()

      Returns the endpoints of TAP services to which this query will be submitted.
      Returns:
        service locations

    - #### getStringParams

          public java.util.Map<java.lang.String,java.lang.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 java.util.Map<java.lang.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 uk.ac.starlink.table.StarTable executeSync​(uk.ac.starlink.table.StoragePolicy storage,
                                                            uk.ac.starlink.util.ContentCoding coding)
                                                     throws java.io.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:
        `java.io.IOException`

    - #### executeSync

          public boolean executeSync​(uk.ac.starlink.table.TableSink sink,
                                     uk.ac.starlink.util.ContentCoding coding)
                              throws java.io.IOException,
                                     org.xml.sax.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:
        `java.io.IOException`
        `org.xml.sax.SAXException`

    - #### createSyncConnection

          public java.net.HttpURLConnection createSyncConnection​(uk.ac.starlink.util.ContentCoding coding)
                                                          throws java.io.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:
        `java.io.IOException`

    - #### submitAsync

          public UwsJob submitAsync​()
                             throws java.io.IOException

      Submits this query asynchronously and returns the corresponding UWS job. The job is not started.
      Returns:
        new UWS job for this query
      Throws:
        `java.io.IOException`

    - #### waitForResultUrl

          public static java.net.URL waitForResultUrl​(UwsJob uwsJob,
                                                      long pollMillis)
                                               throws java.io.IOException,
                                                      java.lang.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:
        `java.io.IOException`
        `java.lang.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 java.io.IOException,
                                                                     java.lang.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:
        `java.io.IOException`
        `java.lang.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 java.io.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:
        `java.io.IOException`

    - #### scalarQuery

          public static <T> T scalarQuery​(EndpointSet endpointSet,
                                          java.lang.String adql,
                                          java.lang.Class<T> clazz)
                                   throws java.io.IOException

      Utility method to obtain a single-cell table as the result of a synchronous TAP query.
      Parameters:
        `endpointSet` - locations of TAP services
        `adql` - query string
        `clazz` - class of required value
      Returns:
        single value, or null if no rows
      Throws:
        `java.io.IOException` - if required result cannot be got

    - #### readResultVOTable

          public static uk.ac.starlink.table.StarTable readResultVOTable​(java.net.URLConnection conn,
                                                                         uk.ac.starlink.util.ContentCoding coding,
                                                                         uk.ac.starlink.table.StoragePolicy storage)
                                                                  throws java.io.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:
        `java.io.IOException`

    - #### streamResultVOTable

          public static boolean streamResultVOTable​(java.net.URLConnection conn,
                                                    uk.ac.starlink.util.ContentCoding coding,
                                                    uk.ac.starlink.table.TableSink sink)
                                             throws java.io.IOException,
                                                    org.xml.sax.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
        `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:
        `java.io.IOException`
        `org.xml.sax.SAXException`

    - #### getVOTableStream

          public static java.io.InputStream getVOTableStream​(java.net.URLConnection conn,
                                                             uk.ac.starlink.util.ContentCoding coding)
                                                      throws java.io.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:
        `java.io.IOException`

    - #### followRedirects

          public static java.net.URLConnection followRedirects​(java.net.URLConnection conn)
                                                        throws java.io.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:
        `java.io.IOException`

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