# Class TapSchemaInterrogator

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

public class TapSchemaInterrogator extends 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 final TapSchemaInterrogator.MetaQuerier<ColumnMeta>`
`COLUMN_QUERIER`
Acquires ColumnMeta objects from TAP_SCHEMA.columns.
`static final TapSchemaInterrogator.MetaQuerier<ForeignMeta>`
`FKEY_QUERIER`
Acquires ForeignMeta objects from TAP_SCHEMA.keys.
`static final TapSchemaInterrogator.MetaQuerier<ForeignMeta.Link>`
`LINK_QUERIER`
Acquires ForeignMeta.Link objects from TAP_SCHEMA.key_columns.
`static final TapSchemaInterrogator.MetaQuerier<SchemaMeta>`
`SCHEMA_QUERIER`
Acquires SchemaMeta objects from TAP_SCHEMA.schemas.
`static final TapSchemaInterrogator.MetaQuerier<TableMeta>`
`TABLE_QUERIER`
Acquires TableMeta objects from TAP_SCHEMA.tables.

## Constructor Summary

Constructors
Constructor
Description
`TapSchemaInterrogator(TapService service, int maxrec, uk.ac.starlink.util.ContentCoding coding)`
Constructs an interrogator with explicit configuration.

## Method Summary

Modifier and Type
Method
Description
`protected TapQuery`
`createTapQuery(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.
`TapService`
`getTapService()`
Returns the TAP service used by this interrogator.
`static void`
`main(String[] args)`
Prints out metadata content of a given TAP service.
`void`
`populateForeignKey(ForeignMeta fmeta, Map<String, List<ForeignMeta.Link>> lMap)`
Fills in link information for a ForeignMeta object.
`void`
`populateSchema(SchemaMeta smeta, Map<String, List<TableMeta>> tMap)`
Fills in table information for a SchemaMeta object.
`void`
`populateTable(TableMeta tmeta, Map<String, List<ForeignMeta>> fMap, Map<String, 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> List<T>`
`readList(TapSchemaInterrogator.MetaQuerier<T> mq, String moreAdql)`
Reads a list of metadata items using a given MetaQuerier object.
`<T> Map<String,List<T>>`
`readMap(TapSchemaInterrogator.MetaQuerier<T> mq, 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 Object

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

## Field Details

### 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 Details

### TapSchemaInterrogator

public TapSchemaInterrogator(TapService service, int maxrec, uk.ac.starlink.util.ContentCoding coding)
Constructs an interrogator with explicit configuration.

Parameters:
  `service` - TAP service description
  `maxrec` - maximum number of records to retrieve per query
  `coding` - configures HTTP compression

## Method Details

### getTapService

public TapService getTapService()
Returns the TAP service used by this interrogator.

Returns:
  TAP service description

### queryMetadata

public SchemaMeta[] queryMetadata() throws 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:
  `IOException`

### readSchemas

public SchemaMeta[] readSchemas(boolean populateSchemas, boolean populateTables, boolean addOrphanTables) throws 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:
  `IOException`

### readMap

public <T> Map<String,List<T>> readMap(TapSchemaInterrogator.MetaQuerier<T> mq, String moreAdql) throws 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:
  `IOException`

### readList

public <T> List<T> readList(TapSchemaInterrogator.MetaQuerier<T> mq, String moreAdql) throws 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:
  `IOException`

### populateForeignKey

public void populateForeignKey(ForeignMeta fmeta, Map<String, 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, Map<String, List<ForeignMeta>> fMap, Map<String, 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, Map<String, 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(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 IOException
Performs an ADQL TAP query to this interrogator's service. May be overridden.

Parameters:
  `tq` - tap query
Returns:
  output table
Throws:
  `IOException`

### main

public static void main(String[] args) throws IOException
Prints out metadata content of a given TAP service.

Parameters:
  `args` - first element is TAP service URL
Throws:
  `IOException`