uk.ac.starlink.table

## Class WrapperStarTable

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

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable
  Direct Known Subclasses:
    ColumnPermutedStarTable, ColumnStoreStarTable, ConcatStarTable, EmptyStarTable, ExplodedStarTable, MetaCopyStarTable, ProgressBarStarTable, ProgressLineStarTable, RowPermutedStarTable, RowSubsetStarTable, SelectorStarTable

      public class WrapperStarTable
      extends java.lang.Object
      implements StarTable

  StarTable which wraps another StarTable. This class acts as a wrapper around an existing 'base' StarTable object; almost all its methods are implemented by forwarding to the corresponding methods of that base table. The exception is the `getURL()` method which returns `null` as an indication that the actual table is not a persistent one (though it may be based on, and even identical to, a persistent one).

  This class is provided so that it can be extended by subclasses which modify the view of the base table in useful ways.

  Subclasses should take care to ensure that all the data access methods are overridden in a consistent way: `getCell(long, int)`, `getRow(long)`, `getRowSequence()`, `getRowAccess()` and `getRowSplittable()`.

  See Also:
    `WrapperRowSequence`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected StarTable` | `baseTable`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WrapperStarTable(StarTable baseTable)` Constructs a new `WrapperStarTable` from a given base table.

  - ### Method Summary

    All Methods Static Methods Instance 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()` Relinquishes any resources associated with this table.
    `StarTable` | `getBaseTable()` Returns the base table underlying this wrapper table.
    `java.lang.Object` | `getCell(long irow, int icol)` Returns the contents of a given table cell.
    `java.util.List<ValueInfo>` | `getColumnAuxDataInfos()` Returns an ordered list of ValueInfo objects representing the auxiliary metadata returned by `getColumnInfo(int).getAuxData()` calls.
    `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.lang.String` | `getName()` Returns the name of this table, if it has one.
    `DescribedValue` | `getParameterByName(java.lang.String parname)` Returns a parameter (table-wide metadata item) of this table located by its name.
    `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)` Returns the contents of a given table row.
    `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.
    `RowSplittable` | `getRowSplittable()` Returns an object which can iterate over all the rows in the table, but which may also be requested to split recursively for potentially parallel processing.
    `java.net.URL` | `getURL()` Initially returns `null` to indicate that this table itself is not persistent.
    `boolean` | `isRandom()` Indicates whether random access is provided by this table.
    `void` | `setName(java.lang.String name)` Sets the name of this table.
    `void` | `setParameter(DescribedValue dval)` Adds the given DescribedValue to the list of parameter metadata objects associated with this table.
    `void` | `setURL(java.net.URL url)` Sets the URL of this table.
    `java.lang.String` | `toString()` Returns an indication of the wrapper structure of this table.

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

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

- - ### Field Detail

    - #### baseTable

          protected StarTable baseTable

  - ### Constructor Detail

    - #### WrapperStarTable

          public WrapperStarTable(StarTable baseTable)

      Constructs a new `WrapperStarTable` from a given base table.
      Parameters:
        `baseTable` - the table to which methods invoked upon the new wrapper table will be forwarded

  - ### Method Detail

    - #### getBaseTable

          public StarTable getBaseTable()

      Returns the base table underlying this wrapper table.
      Returns:
        the table to which methods invoked upon this wrappter table are forwarded

    - #### getColumnCount

          public 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 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

    - #### getURL

          public java.net.URL getURL()

      Initially returns `null` to indicate that this table itself is not 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)

      Description copied from interface: `StarTable`
      Sets the URL of this table. It ought to be possible in principle to reconstruct this table by reading the resource at `url`. If called, the supplied `url` should provide the return value for subsequent calls of `StarTable.getURL()`.
      Specified by:
        `setURL` in interface `StarTable`
      Parameters:
        `url` - table URL

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

      Description copied from interface: `StarTable`
      Sets the name of this table. If called, the supplied `name` should provide the return value for subsequent calls of `StarTable.getName()`.
      Specified by:
        `setName` in interface `StarTable`
      Parameters:
        `name` - table name

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

    - #### getParameterByName

          public DescribedValue getParameterByName(java.lang.String parname)

      Description copied from interface: `StarTable`
      Returns a parameter (table-wide metadata item) of this table located by its name. If more than one parameter with the given name exists, an arbitrary one will be returned. If no parameter with the given name exists, `null` will be returned.
      Specified by:
        `getParameterByName` in interface `StarTable`
      Parameters:
        `parname` - the name of the table parameter required

    - #### setParameter

          public void setParameter(DescribedValue dval)

      Description copied from interface: `StarTable`
      Adds the given DescribedValue to the list of parameter metadata objects associated with this table. If an item in the parameter list with the same name as the supplied value already exists, it is removed from the list.
      Specified by:
        `setParameter` in interface `StarTable`
      Parameters:
        `dval` - the new parameter datum to add

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

    - #### getColumnAuxDataInfos

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

      Description copied from interface: `StarTable`
      Returns an ordered list of ValueInfo objects representing the auxiliary metadata returned by `getColumnInfo(int).getAuxData()` calls. The idea is that the resulting list can be used to find out the kind of per-column metadata which can be expected to be found in some or all columns of this table. Each item in the returned list should have a unique name, and other characteristics which are applicable to auxData items which may be returned from any of the columns in this table.

      The order of the list may indicate some sort of natural ordering of these keys. The returned list is not guaranteed to be complete; it is legal to return an empty list if nothing is known about auxiliary metadata. The list ought not to contain duplicate elements.

      Specified by:
        `getColumnAuxDataInfos` in interface `StarTable`
      Returns:
        an unmodifiable ordered set of known metadata keys
      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`
      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`
      Returns:
        new RowAccess
      Throws:
        `java.io.IOException` - if there is an error setting up access

    - #### getRowSplittable

          public RowSplittable getRowSplittable()
                                         throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can iterate over all the rows in the table, but which may also be requested to split recursively for potentially parallel processing.

      The return value must be non-null, and may provide splitting arrangements specially appropriate for the implementation. If this table 'wraps' an upstream table, it is usually best to base the implementation on calls to the the upstream `getRowSplittable` method, so that upstream policy about how to divide up the table is respected. However, implementations without special requirements may return `Tables.getDefaultRowSplittable``(this)`.

      Specified by:
        `getRowSplittable` in interface `StarTable`
      Returns:
        new RowSplittable
      Throws:
        `java.io.IOException`
      See Also:
        `RowRunner`

    - #### isRandom

          public boolean isRandom()

      Description copied from interface: `StarTable`
      Indicates whether random access is provided by this table. Only if the result is `true` may the `StarTable.getRowAccess()`, `StarTable.getRow(long)` and `StarTable.getCell(long, int)` methods be used.
      Specified by:
        `isRandom` in interface `StarTable`
      Returns:
        `true` if table random access methods are available

    - #### getCell

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

      Description copied from interface: `StarTable`
      Returns the contents of a given table cell. The class of the returned object should be the same as, or a subclass of, the class returned by `getColumnInfo(icol).getContentClass()`.

      This method is safe for concurrent use from multiple threads, but in general it is recommended to use a `RowAccess` instead.

      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

      Description copied from interface: `StarTable`
      Returns the contents of a given table row. The returned value is equivalent to an array formed of all the objects returned by `getCell(irow,icol)` for all the columns `icol` in sequence.

      This method is safe for concurrent use from multiple threads, but in general it is recommended to use a `RowAccess` instead.

      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

      Description copied from interface: `StarTable`
      Relinquishes any resources associated with this table. This may do nothing, and calling it is often not required, but it provides an opportunity to force release of file descriptors or other resources that are not well handled by garbage collection if the table itself holds them. It is not intended for release of heap-based resources, for which garbage collection already provides adequate management.

      Following a call to this method, any attempt to use this table or objects such as RowSequences obtained from it will result in undefined behaviour.

      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`

    - #### checkedLongToInt

          public static int checkedLongToInt(long lval)

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

    - #### toString

          public java.lang.String toString()

      Returns an indication of the wrapper structure of this table.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation