uk.ac.starlink.table

## Class AbstractStarTable

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

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable
  Direct Known Subclasses:
    AsciiTableStarTable, BintableStarTable, CalcStarTable, CdfStarTable, ColFitsStarTable, EcsvStarTable, FeatherStarTable, GbinStarTable, JDBCStarTable, JoinStarTable, MetadataStarTable, ParquetStarTable, Pds4StarTable, RandomStarTable, SequentialResultSetStarTable, StreamStarTable, VOStarTable

      public abstract class AbstractStarTable
      extends java.lang.Object
      implements StarTable

  Abstract base class providing an implementation of the generic and straightforward parts of the `StarTable` interface. This implementation assumes that random access is not available; subclasses which provide random access should override the `isRandom`, `getCell` and perhaps `getRow` methods.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractStarTable()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `checkedLongToInt(long lval)` Convenience method to get an `int` value from a `long`.
    `void` | `close()` The `AbstractStarTable` implementation of this method does nothing.
    `java.lang.Object` | `getCell(long irow, 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.
    `abstract int` | `getColumnCount()` Returns the number of columns in this table.
    `abstract ColumnInfo` | `getColumnInfo(int icol)` Returns the object describing the data in a given column.
    `java.lang.String` | `getName()` Returns the name of this table, if it has one.
    `java.util.List<DescribedValue>` | `getParameters()` Returns a list of table parameters, that is metadata items which pertain to the entire table.
    `java.lang.Object[]` | `getRow(long irow)` The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `getCell(long, int)`.
    `RowAccess` | `getRowAccess()` Returns an object which can provide random access to this table's data, if random access is implemented.
    `abstract long` | `getRowCount()` Returns the number of rows in this table, if known.
    `abstract RowSequence` | `getRowSequence()` Returns an object which can iterate over all the rows in the table sequentially.
    `RowSplittable` | `getRowSplittable()` Returns a default splittable which relies on table random access if available, or otherwise provides only sequential access (no splits).
    `java.net.URL` | `getURL()` Returns the URL of this table, if it has one.
    `boolean` | `isRandom()` The `AbstractStarTable` implementation of this method returns `false`.
    `void` | `setName(java.lang.String name)` Sets the name for this table.
    `void` | `setParameters(java.util.List<DescribedValue> parameters)` Sets the list of table parameters, that is items which pertain to the entire table.
    `void` | `setURL(java.net.URL url)` Sets the URL for this table.

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

- - ### Constructor Detail

    - #### AbstractStarTable

          public AbstractStarTable()

  - ### Method Detail

    - #### getColumnAuxDataInfos

          public 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. Subclasses should override this if they can do better, for instance providing an order for the keys.
      Specified by:
        `getColumnAuxDataInfos` in interface `StarTable`
      Returns:
        a list of all the auxiliary metadata `ValueInfo` items which in fact crop up in column metadata
      See Also:
        `DefaultValueInfo.getAuxData()`

    - #### 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`
      Returns:
        a `List` of `DescribedValue` objects constituting table-wide metadata not covered elsewhere in this interface

    - #### setParameters

          public void setParameters(java.util.List<DescribedValue> parameters)

      Sets the list of table parameters, that is items which pertain to the entire table. Each element of the provided list `parameters` should be a `DescribedValue` object.
      Parameters:
        `parameters` - a List of `DescribedValue`s pertaining to this table

    - #### getName

          public java.lang.String getName()

      Description copied from interface: `StarTable`
      Returns the name of this table, if it has one. The meaning of the name is not defined, but it will typically be a short string of text indicating the identity of this table.
      Specified by:
        `getName` in interface `StarTable`
      Returns:
        a name for this table, or `null` if no suitable one exists

    - #### setName

          public void setName(java.lang.String name)

      Sets the name for this table.
      Specified by:
        `setName` in interface `StarTable`
      Parameters:
        `name` - the table name - may be `null`

    - #### getURL

          public java.net.URL getURL()

      Description copied from interface: `StarTable`
      Returns the URL of this table, if it has one. A non-null return from this method indicates that this table is in some sense persistent.
      Specified by:
        `getURL` in interface `StarTable`
      Returns:
        the URL of this table, or `null` if none is known

    - #### setURL

          public void setURL(java.net.URL url)

      Sets the URL for this table.
      Specified by:
        `setURL` in interface `StarTable`
      Parameters:
        `url` - the URL where this table lives - may be `null`

    - #### checkedLongToInt

          public static int checkedLongToInt(long lval)

      Convenience method to get an `int` value from a `long`. Invokes `Tables.checkedLongToInt(long)`.

    - #### isRandom

          public boolean isRandom()

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

    - #### 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`
      Returns:
        new RowAccess
      Throws:
        `java.io.IOException` - if there is an error setting up access

    - #### getRowSplittable

          public RowSplittable getRowSplittable()
                                         throws java.io.IOException

      Returns a default splittable which relies on table random access if available, or otherwise provides only sequential access (no splits).

      It is often possible to provide a better implementation than this.

      Specified by:
        `getRowSplittable` in interface `StarTable`
      Returns:
        `Tables.getDefaultRowSplittable(this)`
      Throws:
        `java.io.IOException`
      See Also:
        `RowRunner`

    - #### getCell

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

      The `AbstractStarTable` implementation of this method throws an `UnsupportedOperationException`, since unless otherwise provided there is no random access.
      Specified by:
        `getCell` in interface `StarTable`
      Parameters:
        `irow` - 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

    - #### getRow

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

      The `AbstractStarTable` implementation of this method constructs a row by repeated invocation of `getCell(long, int)`.
      Specified by:
        `getRow` in interface `StarTable`
      Parameters:
        `irow` - 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

    - #### close

          public void close()
                     throws java.io.IOException

      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`
      Throws:
        `java.io.IOException`

    - #### getColumnInfo

          public abstract 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`
      Parameters:
        `icol` - the column for which header information is required
      Returns:
        a ValueInfo object for column `icol`

    - #### getColumnCount

          public abstract int getColumnCount()

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

    - #### getRowCount

          public abstract 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`
      Returns:
        the number of rows, or -1

    - #### getRowSequence

          public abstract 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`
      Returns:
        new RowSequence
      Throws:
        `java.io.IOException` - if there is an error providing access