Package uk.ac.starlink.vo

## Class TapSchemaInterrogator

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

-     public class TapSchemaInterrogator
      extends java.lang.Object

  Interrogates the TAP_SCHEMA tables from a TAP service to acquire table metadata information. In the current implementation, synchronous queries are used.
  Since:
    6 Jun 2011
  Author:
    Mark Taylor
  See Also:
    TAP standard

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `TapSchemaInterrogator.MetaQuerier<T>` | Object that can read a certain type of TAP metadata object from a table of a TAP_SCHEMA database table.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static TapSchemaInterrogator.MetaQuerier<ColumnMeta>` | `COLUMN_QUERIER` | Acquires ColumnMeta objects from TAP_SCHEMA.columns.
    `static TapSchemaInterrogator.MetaQuerier<ForeignMeta>` | `FKEY_QUERIER` | Acquires ForeignMeta objects from TAP_SCHEMA.keys.
    `static TapSchemaInterrogator.MetaQuerier<ForeignMeta.Link>` | `LINK_QUERIER` | Acquires ForeignMeta.Link objects from TAP_SCHEMA.key_columns.
    `static TapSchemaInterrogator.MetaQuerier<SchemaMeta>` | `SCHEMA_QUERIER` | Acquires SchemaMeta objects from TAP_SCHEMA.schemas.
    `static TapSchemaInterrogator.MetaQuerier<TableMeta>` | `TABLE_QUERIER` | Acquires TableMeta objects from TAP_SCHEMA.tables.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TapSchemaInterrogator​(EndpointSet endpointSet, int maxrec, uk.ac.starlink.util.ContentCoding coding)` | Constructs an interrogator with explicit configuration.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected TapQuery` | `createTapQuery​(java.lang.String adql)` | Constructs a TAP query for a given ADQL string.
    `protected uk.ac.starlink.table.StarTable` | `executeQuery​(TapQuery tq)` | Performs an ADQL TAP query to this interrogator's service.
    `EndpointSet` | `getEndpointSet​()` | Returns the TAP endpoint locations used by this interrogator.
    `static void` | `main​(java.lang.String[] args)` | Prints out metadata content of a given TAP service.
    `void` | `populateForeignKey​(ForeignMeta fmeta, java.util.Map<java.lang.String,java.util.List<ForeignMeta.Link>> lMap)` | Fills in link information for a ForeignMeta object.
    `void` | `populateSchema​(SchemaMeta smeta, java.util.Map<java.lang.String,java.util.List<TableMeta>> tMap)` | Fills in table information for a SchemaMeta object.
    `void` | `populateTable​(TableMeta tmeta, java.util.Map<java.lang.String,java.util.List<ForeignMeta>> fMap, java.util.Map<java.lang.String,java.util.List<ColumnMeta>> cMap)` | Fills in foreign key and column information for a TableMeta object, Any relevant entries are removed from the supplied maps.
    `SchemaMeta[]` | `queryMetadata​()` | This convenience method returns an array of fully filled in SchemaMeta objects describing the tables available from the service.
    `<T> java.util.List<T>` | `readList​(TapSchemaInterrogator.MetaQuerier<T> mq, java.lang.String moreAdql)` | Reads a list of metadata items using a given MetaQuerier object.
    `<T> java.util.Map<java.lang.String,java.util.List<T>>` | `readMap​(TapSchemaInterrogator.MetaQuerier<T> mq, java.lang.String moreAdql)` | Reads a map of metadata items using a given MetaQuerier object.
    `SchemaMeta[]` | `readSchemas​(boolean populateSchemas, boolean populateTables, boolean addOrphanTables)` | Reads all schemas.

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

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

- - ### Field Detail

    - #### LINK_QUERIER

          public static final TapSchemaInterrogator.MetaQuerier<ForeignMeta.Link> LINK_QUERIER

      Acquires ForeignMeta.Link objects from TAP_SCHEMA.key_columns. When reading a map, it is keyed by key_id.

    - #### FKEY_QUERIER

          public static final TapSchemaInterrogator.MetaQuerier<ForeignMeta> FKEY_QUERIER

      Acquires ForeignMeta objects from TAP_SCHEMA.keys. When reading a map, it is keyed by from_table.

    - #### COLUMN_QUERIER

          public static final TapSchemaInterrogator.MetaQuerier<ColumnMeta> COLUMN_QUERIER

      Acquires ColumnMeta objects from TAP_SCHEMA.columns. When reading a map, it is keyed by table_name.

    - #### TABLE_QUERIER

          public static final TapSchemaInterrogator.MetaQuerier<TableMeta> TABLE_QUERIER

      Acquires TableMeta objects from TAP_SCHEMA.tables. When reading a map, it is keyed by schema_name.

    - #### SCHEMA_QUERIER

          public static final TapSchemaInterrogator.MetaQuerier<SchemaMeta> SCHEMA_QUERIER

      Acquires SchemaMeta objects from TAP_SCHEMA.schemas. It doesn't read maps.

  - ### Constructor Detail

    - #### TapSchemaInterrogator

          public TapSchemaInterrogator​(EndpointSet endpointSet,
                                       int maxrec,
                                       uk.ac.starlink.util.ContentCoding coding)

      Constructs an interrogator with explicit configuration.
      Parameters:
        `endpointSet` - TAP service locations
        `maxrec` - maximum number of records to retrieve per query
        `coding` - configures HTTP compression

  - ### Method Detail

    - #### getEndpointSet

          public EndpointSet getEndpointSet​()

      Returns the TAP endpoint locations used by this interrogator.
      Returns:
        TAP endpoints

    - #### queryMetadata

          public SchemaMeta[] queryMetadata​()
                                     throws java.io.IOException

      This convenience method returns an array of fully filled in SchemaMeta objects describing the tables available from the service.
      Returns:
        fully populated array of known schemas
      Throws:
        `java.io.IOException`

    - #### readSchemas

          public SchemaMeta[] readSchemas​(boolean populateSchemas,
                                          boolean populateTables,
                                          boolean addOrphanTables)
                                   throws java.io.IOException

      Reads all schemas. According to the options, the schemas may or may not have their tables filled in, and those tables may or may not have their columns and foreign key information filled in.
      Parameters:
        `populateSchemas` - if true, schemas will contain non-null table lists
        `populateTables` - if true, tables will contain non-null column/key lists (ignored if populateSchemas is false)
        `addOrphanTables` - if true include tables whose schemas are not explicitly declared
      Returns:
        schema list
      Throws:
        `java.io.IOException`

    - #### readMap

          public <T> java.util.Map<java.lang.String,java.util.List<T>> readMap​(TapSchemaInterrogator.MetaQuerier<T> mq,
                                                                               java.lang.String moreAdql)
                                                                        throws java.io.IOException

      Reads a map of metadata items using a given MetaQuerier object. The key of the map is the name of the parent object of the map value list type. See the documentation of the specific querier object for details.

      The form of the basic SELECT statement generated by this call is "SELECT <columns≫ FROM <table>". If non-null the text of the `moreAdql` parameter is appended (after a space), so it may be used to qualify the query further.

      Parameters:
        `mq` - type-specific querier
        `moreAdql` - additional ADQL text to append after the FROM clause (for example a WHERE clause); may be null
      Returns:
        map from parent metadata item name to list of metadata items
      Throws:
        `java.io.IOException`

    - #### readList

          public <T> java.util.List<T> readList​(TapSchemaInterrogator.MetaQuerier<T> mq,
                                                java.lang.String moreAdql)
                                         throws java.io.IOException

      Reads a list of metadata items using a given MetaQuerier object.

      The form of the basic SELECT statement generated by this call is "SELECT <columns≫ FROM <table>". If non-null the text of the `moreAdql` parameter is appended (after a space), so it may be used to qualify the query further.

      Parameters:
        `mq` - type-specific querier
        `moreAdql` - additional ADQL text to append after the FROM clause (for example a WHERE clause); may be null
      Returns:
        list of metadata items
      Throws:
        `java.io.IOException`

    - #### populateForeignKey

          public void populateForeignKey​(ForeignMeta fmeta,
                                         java.util.Map<java.lang.String,java.util.List<ForeignMeta.Link>> lMap)

      Fills in link information for a ForeignMeta object. Any relevant entries are removed from the supplied map. If the map contains no relevant entries, an empty list is filled in.
      Parameters:
        `fmeta` - unpopulated foreign key item
        `lMap` - map acquired using `LINK_QUERIER`

    - #### populateTable

          public void populateTable​(TableMeta tmeta,
                                    java.util.Map<java.lang.String,java.util.List<ForeignMeta>> fMap,
                                    java.util.Map<java.lang.String,java.util.List<ColumnMeta>> cMap)

      Fills in foreign key and column information for a TableMeta object, Any relevant entries are removed from the supplied maps. Where the maps contain no relevant entries, an empty list is filled in.
      Parameters:
        `tmeta` - unpopulated table metadata item
        `fMap` - map acquired using `FKEY_QUERIER`
        `cMap` - map acquired using `COLUMN_QUERIER`

    - #### populateSchema

          public void populateSchema​(SchemaMeta smeta,
                                     java.util.Map<java.lang.String,java.util.List<TableMeta>> tMap)

      Fills in table information for a SchemaMeta object. Any relevant entries are removed from the supplied map. If the map contains no relevant entries, an empty list is filled in.
      Parameters:
        `smeta` - unpopulated schema metadata item
        `tMap` - map acquired using `TABLE_QUERIER`

    - #### createTapQuery

          protected TapQuery createTapQuery​(java.lang.String adql)

      Constructs a TAP query for a given ADQL string. May be overridden.
      Parameters:
        `adql` - query text
      Returns:
        query to execute

    - #### executeQuery

          protected uk.ac.starlink.table.StarTable executeQuery​(TapQuery tq)
                                                         throws java.io.IOException

      Performs an ADQL TAP query to this interrogator's service. May be overridden.
      Parameters:
        `tq` - tap query
      Returns:
        output table
      Throws:
        `java.io.IOException`

    - #### main

          public static void main​(java.lang.String[] args)
                           throws java.io.IOException

      Prints out metadata content of a given TAP service.
      Parameters:
        `args` - first element is TAP service URL
      Throws:
        `java.io.IOException`

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