Package uk.ac.starlink.vo

## Class DalQuery

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

-     public class DalQuery
      extends java.lang.Object

  Represents a particular query to a DAL-like service. DAL refers to the the Data Access Layer family of protocols defined by the IVOA.
  Since:
    2 Feb 2009
  Author:
    Mark Taylor (Starlink)

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DalQuery​(java.lang.String baseURL, java.lang.String serviceType, double raPos, double decPos, double size, uk.ac.starlink.util.ContentCoding coding)` | Constructs a DAL query based on a service URL.
    `DalQuery​(RegResource resource, RegCapabilityInterface capability, java.lang.String serviceType, double raPos, double decPos, double size)` | Constructs a DAL query based on a resource from a registry.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addArgument​(java.lang.String name, java.lang.String value)` | Adds an argument to the query.
    `java.lang.String` | `doubleToString​(double value)` | Encodes a floating point value as a string for use in a DAL query.
    `uk.ac.starlink.table.StarTable` | `execute​(uk.ac.starlink.table.StarTableFactory tfact)` | Executes this query synchronously, returning a StarTable which represents the results.
    `static uk.ac.starlink.table.StarTable` | `executeQuery​(java.net.URL qurl, uk.ac.starlink.table.StarTableFactory tfact, uk.ac.starlink.util.ContentCoding coding)` | Submits a synchronous query to a URL and retrieves the result as a StarTable following standard DAL conventions.
    `java.lang.String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DalQuery

          public DalQuery​(RegResource resource,
                          RegCapabilityInterface capability,
                          java.lang.String serviceType,
                          double raPos,
                          double decPos,
                          double size)

      Constructs a DAL query based on a resource from a registry.
      Parameters:
        `resource` - resource describing the DAL service
        `capability` - DAL capability from resource
        `serviceType` - short name for service type; informative, used for error messages etc
        `raPos` - right ascension of ROI center in degrees
        `decPos` - declination of ROI center in degrees
        `size` - ROI size in degrees

    - #### DalQuery

          public DalQuery​(java.lang.String baseURL,
                          java.lang.String serviceType,
                          double raPos,
                          double decPos,
                          double size,
                          uk.ac.starlink.util.ContentCoding coding)

      Constructs a DAL query based on a service URL.
      Parameters:
        `baseURL` - URL forming basis of CGI query for the DAL service
        `serviceType` - short name for service type; informative, used for error messages etc
        `raPos` - right ascension of ROI center in degrees
        `decPos` - declination of ROI center in degrees
        `size` - size in degrees
        `coding` - controls HTTP-level byte-stream compression

  - ### Method Detail

    - #### addArgument

          public void addArgument​(java.lang.String name,
                                  java.lang.String value)

      Adds an argument to the query. No validation is performed to check it is one of the ones that the DAL service knows about.
      Parameters:
        `name` - service argument name
        `value` - argument value

    - #### execute

          public uk.ac.starlink.table.StarTable execute​(uk.ac.starlink.table.StarTableFactory tfact)
                                                 throws java.io.IOException

      Executes this query synchronously, returning a StarTable which represents the results. If the query resulted in a QUERY_STATUS of ERROR, or if the returned VOTable document is not comprehensible according to the DAL rules, an IOException will be thrown.
      Parameters:
        `tfact` - factory which may be used to influence how the table is built
      Throws:
        `java.io.IOException` - in absence of good data

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### doubleToString

          public java.lang.String doubleToString​(double value)

      Encodes a floating point value as a string for use in a DAL query. There ought to be a definition within the DAL protocols of how to do this. At time of writing there is not, so the current implementation defers to the ad-hoc implementation in `CgiQuery.formatDouble(double)`, which avoids exponential notation except for very large/small values.
      Parameters:
        `value` - numeric value
      Returns:
        string equivalent

    - #### executeQuery

          public static uk.ac.starlink.table.StarTable executeQuery​(java.net.URL qurl,
                                                                    uk.ac.starlink.table.StarTableFactory tfact,
                                                                    uk.ac.starlink.util.ContentCoding coding)
                                                             throws java.io.IOException

      Submits a synchronous query to a URL and retrieves the result as a StarTable following standard DAL conventions.
      Parameters:
        `qurl` - query URL
        `tfact` - table factory
        `coding` - encoding to use for communications
      Returns:
        table included in DAL result resource
      Throws:
        `java.io.IOException`