uk.ac.starlink.votable

## Class VOStarTable

- java.lang.Object
- - uk.ac.starlink.table.AbstractStarTable
  - - uk.ac.starlink.votable.VOStarTable

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable

      public class VOStarTable
      extends AbstractStarTable

  A `StarTable` implementation based on a VOTable.

  Some of the FIELD attributes defined by the VOTable format correspond to standard information in the corresponding ColumnInfo object, and some do not. Those that do are accessed using the relevant ColumnInfo getter/setter methods directly, for instance

           String ucd = table.getColumnInfo(0).getUCD();

  The ones that don't are stored in the ColumnInfo's auxiliary metadata keyed using the various `*_INFO` public static variables defined in this class. These are accessed using the `ColumnInfo.getAuxDatum(uk.ac.starlink.table.ValueInfo)` method, for instance:

           String id = (String) table.getColumnInfo(0)
                                     .getAuxDatumValue(VOStarTable.ID_INFO);

  In the same way, if you set an auxiliary metadata item under one of these keys, like this:

           DescribedValue idVal = new DescribedValue(VOStarTable.ID_INFO, "COL0");
           table.getColumnInfo(0).setAuxDatum(idVal);

  then if the result is written to a VOTable the relevant attribute will be attached to the corresponding FIELD element.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ValueInfo` | `COOSYS_EPOCH_INFO` ValueInfo for COOSYS `epoch` attribute.
    `static ValueInfo` | `COOSYS_EQUINOX_INFO` ValueInfo for COOSYS `equinox` attribute.
    `static ValueInfo` | `COOSYS_REFPOSITION_INFO` ValueInfo for COOSYS `refposition` attribute.
    `static ValueInfo` | `COOSYS_SYSTEM_INFO` ValueInfo for COOSYS `system` attribute.
    `static ValueInfo` | `DATATYPE_INFO` ValueInfo for VOTable `datatype` attribute.
    `static ValueInfo` | `ID_INFO` ValueInfo for VOTable `ID` attribute.
    `static ValueInfo` | `PRECISION_INFO` ValueInfo for VOTable `precision` attribute.
    `static ValueInfo` | `REF_INFO` ValueInfo for VOTable `ref` attribute.
    `static ValueInfo` | `TIMESYS_REFPOSITION_INFO` ValueInfo for TIMESYS `refposition` attribute.
    `static ValueInfo` | `TIMESYS_TIMEORIGIN_INFO` ValueInfo for TIMESYS `timeorigin` attribute.
    `static ValueInfo` | `TIMESYS_TIMESCALE_INFO` ValueInfo for TIMESYS `timescale` attribute.
    `static ValueInfo` | `TYPE_INFO` ValueInfo for VOTable `type` attribute.
    `static ValueInfo` | `UCD_INFO` ValueInfo for VOTable `ucd` attribute.
    `static ValueInfo` | `UTYPE_INFO` ValueInfo for VOTable `utype` attribute.
    `static ValueInfo` | `WIDTH_INFO` ValueInfo for VOTable `width` attribute.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VOStarTable(TableElement tableEl)` Construct a VOStarTable from a TABLE element.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` The `AbstractStarTable` implementation of this method does nothing.
    `static VOStarTable` | `createDecoratedTable(StarTable dataTable, TableElement metadataEl)` Returns a table in which the data comes from an input StarTable, but the metadata is supplied by a TableElement.
    `java.lang.Object` | `getCell(long lrow, int icol)` The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
    `java.util.List<ValueInfo>` | `getColumnAuxDataInfos()` Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name.
    `int` | `getColumnCount()` Returns the number of columns in this table.
    `ColumnInfo` | `getColumnInfo(int icol)` Returns the object describing the data in a given column.
    `java.util.List<DescribedValue>` | `getParameters()` Returns a list of table parameters, that is metadata items which pertain to the entire table.
    `static int` | `getRefColumnIndex(java.lang.String colRef, StarTable table)` Identifies the column that was labelled with a given ID attribute.
    `java.lang.Object[]` | `getRow(long lrow)` The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `AbstractStarTable.getCell(long, int)`.
    `RowAccess` | `getRowAccess()` Returns an object which can provide random access to this table's data, if random access is implemented.
    `long` | `getRowCount()` Returns the number of rows in this table, if known.
    `RowSequence` | `getRowSequence()` Returns an object which can iterate over all the rows in the table sequentially.
    `TableElement` | `getTableElement()` Returns the TABLE element on which this VOStarTable is built.
    `static ValueInfo` | `getValueInfo(FieldElement field)` Returns a ValueInfo object suitable for holding the values in a VOTable Field (or Param) object.
    `boolean` | `isRandom()` The `AbstractStarTable` implementation of this method returns `false`.

    - ### Methods inherited from class uk.ac.starlink.table.AbstractStarTable

      `checkedLongToInt, getName, getRowSplittable, getURL, setName, setParameters, setURL`

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

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

    - ### Methods inherited from interface uk.ac.starlink.table.StarTable

      `getParameterByName, setParameter`

- - ### Field Detail

    - #### ID_INFO

          public static final ValueInfo ID_INFO

      ValueInfo for VOTable `ID` attribute.

    - #### UCD_INFO

          public static final ValueInfo UCD_INFO

      ValueInfo for VOTable `ucd` attribute.

    - #### UTYPE_INFO

          public static final ValueInfo UTYPE_INFO

      ValueInfo for VOTable `utype` attribute.

    - #### WIDTH_INFO

          public static final ValueInfo WIDTH_INFO

      ValueInfo for VOTable `width` attribute.

    - #### PRECISION_INFO

          public static final ValueInfo PRECISION_INFO

      ValueInfo for VOTable `precision` attribute.

    - #### REF_INFO

          public static final ValueInfo REF_INFO

      ValueInfo for VOTable `ref` attribute.

    - #### TYPE_INFO

          public static final ValueInfo TYPE_INFO

      ValueInfo for VOTable `type` attribute.

    - #### DATATYPE_INFO

          public static final ValueInfo DATATYPE_INFO

      ValueInfo for VOTable `datatype` attribute.

    - #### COOSYS_SYSTEM_INFO

          public static final ValueInfo COOSYS_SYSTEM_INFO

      ValueInfo for COOSYS `system` attribute.

    - #### COOSYS_EPOCH_INFO

          public static final ValueInfo COOSYS_EPOCH_INFO

      ValueInfo for COOSYS `epoch` attribute.

    - #### COOSYS_REFPOSITION_INFO

          public static final ValueInfo COOSYS_REFPOSITION_INFO

      ValueInfo for COOSYS `refposition` attribute.

    - #### COOSYS_EQUINOX_INFO

          public static final ValueInfo COOSYS_EQUINOX_INFO

      ValueInfo for COOSYS `equinox` attribute.

    - #### TIMESYS_TIMEORIGIN_INFO

          public static final ValueInfo TIMESYS_TIMEORIGIN_INFO

      ValueInfo for TIMESYS `timeorigin` attribute.

    - #### TIMESYS_TIMESCALE_INFO

          public static final ValueInfo TIMESYS_TIMESCALE_INFO

      ValueInfo for TIMESYS `timescale` attribute.

    - #### TIMESYS_REFPOSITION_INFO

          public static final ValueInfo TIMESYS_REFPOSITION_INFO

      ValueInfo for TIMESYS `refposition` attribute.

  - ### Constructor Detail

    - #### VOStarTable

          public VOStarTable(TableElement tableEl)
                      throws java.io.IOException

      Construct a VOStarTable from a TABLE element. The data itself is inferred or constructed from the state and content of the element.
      Parameters:
        `tableEl` - Table VOElement
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### getColumnCount

          public int getColumnCount()

      Description copied from interface: `StarTable`
      Returns the number of columns in this table.
      Specified by:
        `getColumnCount` in interface `StarTable`
      Specified by:
        `getColumnCount` in class `AbstractStarTable`
      Returns:
        the number of columns

    - #### getRowCount

          public long getRowCount()

      Description copied from interface: `StarTable`
      Returns the number of rows in this table, if known. If the number of rows cannot be (easily) determined, a value of -1 will be returned.
      Specified by:
        `getRowCount` in interface `StarTable`
      Specified by:
        `getRowCount` in class `AbstractStarTable`
      Returns:
        the number of rows, or -1

    - #### isRandom

          public boolean isRandom()

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method returns `false`.
      Specified by:
        `isRandom` in interface `StarTable`
      Overrides:
        `isRandom` in class `AbstractStarTable`
      Returns:
        `true` if table random access methods are available

    - #### getColumnInfo

          public ColumnInfo getColumnInfo(int icol)

      Description copied from interface: `StarTable`
      Returns the object describing the data in a given column.
      Specified by:
        `getColumnInfo` in interface `StarTable`
      Specified by:
        `getColumnInfo` in class `AbstractStarTable`
      Parameters:
        `icol` - the column for which header information is required
      Returns:
        a ValueInfo object for column `icol`

    - #### getParameters

          public java.util.List<DescribedValue> getParameters()

      Description copied from interface: `StarTable`
      Returns a list of table parameters, that is metadata items which pertain to the entire table.
      Specified by:
        `getParameters` in interface `StarTable`
      Overrides:
        `getParameters` in class `AbstractStarTable`
      Returns:
        a `List` of `DescribedValue` objects constituting table-wide metadata not covered elsewhere in this interface

    - #### getColumnAuxDataInfos

          public java.util.List<ValueInfo> getColumnAuxDataInfos()

      Description copied from class: `AbstractStarTable`
      Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name. Subclasses should override this if they can do better, for instance providing an order for the keys.
      Specified by:
        `getColumnAuxDataInfos` in interface `StarTable`
      Overrides:
        `getColumnAuxDataInfos` in class `AbstractStarTable`
      Returns:
        a list of all the auxiliary metadata `ValueInfo` items which in fact crop up in column metadata
      See Also:
        `DefaultValueInfo.getAuxData()`

    - #### getRowSequence

          public RowSequence getRowSequence()
                                     throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can iterate over all the rows in the table sequentially. Each such returned object is safe for use within a single thread, but not in general from multiple threads concurrently.
      Specified by:
        `getRowSequence` in interface `StarTable`
      Specified by:
        `getRowSequence` in class `AbstractStarTable`
      Returns:
        new RowSequence
      Throws:
        `java.io.IOException` - if there is an error providing access

    - #### getRowAccess

          public RowAccess getRowAccess()
                                 throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can provide random access to this table's data, if random access is implemented. Each such returned object is safe for use within a single thread, but not in general from multiple threads concurrently.
      Specified by:
        `getRowAccess` in interface `StarTable`
      Overrides:
        `getRowAccess` in class `AbstractStarTable`
      Returns:
        new RowAccess
      Throws:
        `java.io.IOException` - if there is an error setting up access

    - #### getRow

          public java.lang.Object[] getRow(long lrow)
                                    throws java.io.IOException

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `AbstractStarTable.getCell(long, int)`.
      Specified by:
        `getRow` in interface `StarTable`
      Overrides:
        `getRow` in class `AbstractStarTable`
      Parameters:
        `lrow` - the index of the row to retrieve
      Returns:
        an array of the objects in each cell in row `irow`
      Throws:
        `java.io.IOException` - if there is an error reading the data

    - #### getCell

          public java.lang.Object getCell(long lrow,
                                          int icol)
                                   throws java.io.IOException

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
      Specified by:
        `getCell` in interface `StarTable`
      Overrides:
        `getCell` in class `AbstractStarTable`
      Parameters:
        `lrow` - the index of the cell's row
        `icol` - the index of the cell's column
      Returns:
        the contents of this cell
      Throws:
        `java.io.IOException` - if there is an error reading the data

    - #### close

          public void close()
                     throws java.io.IOException

      Description copied from class: `AbstractStarTable`
      The `AbstractStarTable` implementation of this method does nothing.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `StarTable`
      Overrides:
        `close` in class `AbstractStarTable`
      Throws:
        `java.io.IOException`

    - #### getTableElement

          public TableElement getTableElement()

      Returns the TABLE element on which this VOStarTable is built.
      Returns:
        TABLE element

    - #### getValueInfo

          public static ValueInfo getValueInfo(FieldElement field)

      Returns a ValueInfo object suitable for holding the values in a VOTable Field (or Param) object. The datatype, array shape and other metadata in the returned object are taken from the relevant bits of the supplied field.
      Parameters:
        `field` - the FieldElement object for which the ValueInfo is to be constructed
      Returns:
        a ValueInfo suitable for `field`

    - #### getRefColumnIndex

          public static int getRefColumnIndex(java.lang.String colRef,
                                              StarTable table)

      Identifies the column that was labelled with a given ID attribute.
      Parameters:
        `colRef` - ID string
        `table` - table to interrogate; this will presumably be based on a VOStarTable, but it may be some kind of wrapped form of one
      Returns:
        index of the column in `table` whose FIELD element had an ID attribute of `colRef`, or -1 if none exists

    - #### createDecoratedTable

          public static VOStarTable createDecoratedTable(StarTable dataTable,
                                                         TableElement metadataEl)
                                                  throws java.io.IOException

      Returns a table in which the data comes from an input StarTable, but the metadata is supplied by a TableElement. It is the responsibility of the calling code to ensure that the supplied metadata is consistent with the supplied data.
      Parameters:
        `dataTable` - StarTable supplying data
        `metadataEl` - TABLE element supplying metadata
      Returns:
        table, not guaranteed to be consistent
      Throws:
        `java.io.IOException`