# Interface StarTable

All Superinterfaces:
  `AutoCloseable, Closeable`

All Known Implementing Classes:
  `AbstractStarTable, AsciiStarTable, BeanStarTable, CalcStarTable, ColumnPermutedStarTable, ColumnStarTable, ColumnStoreStarTable, ConcatStarTable, ConstantStarTable, CsvStarTable, EmptyStarTable, ExplodedStarTable, JDBCStarTable, JoinStarTable, LoopStarTable, MetaCopyStarTable, MetadataStarTable, ProgressBarStarTable, ProgressLineStarTable, RandomResultSetStarTable, RandomStarTable, RowListStarTable, RowPermutedStarTable, RowSubsetStarTable, SelectorStarTable, SequentialResultSetStarTable, StreamStarTable, WrapperStarTable`

public interface StarTable extends Closeable
Defines basic table functionality. A table has a fixed number of columns, and a sequence of rows, each of which has one entry for each column. The entry in each column is of the same type (or at least a subtype of a given type) for each row; this type can be determined using the `ColumnInfo` objects returned by `getColumnInfo(int)`. The first row and the first column are numbered 0.

All `StarTable`s allow sequential access, provided by calling `getRowSequence()`. This may in general be called multiple times so that more than one iteration can be made through the rows of the table from start to finish. The `getRowSplittable()` method supports multi-threaded sequential access, and is used by `RowRunner`. Additionally, if the `isRandom()` method returns `true` then the random access methods `getRowAccess()`, `getRow(long)` and `getCell(long, int)` may be used to access table contents directly.

For random tables, the `getRow` and `getCell` methods should be thread-safe. Separate `RowSequence` and `RowAccess` objects obtained from the same table should be safely usable from different threads, but a given `RowSequence`/`RowAccess` in general will not.

In general it is preferred to use `getRowAccess()` than the equivalent `getRow`/`getCell` methods of the table itself, since the assumption of single-threaded use may permit more efficient implementation.

Author:
  Mark Taylor (Starlink)

## Method Summary

Modifier and Type
Method
Description
`void`
`close()`
Relinquishes any resources associated with this table.
`Object`
`getCell(long irow, int icol)`
Returns the contents of a given table cell.
`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.
`String`
`getName()`
Returns the name of this table, if it has one.
`default DescribedValue`
`getParameterByName(String parname)`
Returns a parameter (table-wide metadata item) of this table located by its name.
`List<DescribedValue>`
`getParameters()`
Returns a list of table parameters, that is metadata items which pertain to the entire table.
`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.
`URL`
`getURL()`
Returns the URL of this table, if it has one.
`boolean`
`isRandom()`
Indicates whether random access is provided by this table.
`void`
`setName(String name)`
Sets the name of this table.
`default void`
`setParameter(DescribedValue dval)`
Adds the given DescribedValue to the list of parameter metadata objects associated with this table.
`void`
`setURL(URL url)`
Sets the URL of this table.

## Method Details

### getColumnCount

int getColumnCount()
Returns the number of columns in this table.

Returns:
  the number of columns

### getRowCount

long getRowCount()
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.

Returns:
  the number of rows, or -1

### getURL

URL getURL()
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.

Returns:
  the URL of this table, or `null` if none is known

### setURL

void setURL(URL url)
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 `getURL()`.

Parameters:
  `url` - table URL

### getName

String getName()
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.

Returns:
  a name for this table, or `null` if no suitable one exists

### setName

void setName(String name)
Sets the name of this table. If called, the supplied `name` should provide the return value for subsequent calls of `getName()`.

Parameters:
  `name` - table name

### getParameters

List<DescribedValue> getParameters()
Returns a list of table parameters, that is metadata items which pertain to the entire table.

Returns:
  a `List` of `DescribedValue` objects constituting table-wide metadata not covered elsewhere in this interface

### getParameterByName

default DescribedValue getParameterByName(String parname)
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.

Parameters:
  `parname` - the name of the table parameter required

### setParameter

default void setParameter(DescribedValue dval)
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.

Parameters:
  `dval` - the new parameter datum to add

### getColumnInfo

ColumnInfo getColumnInfo(int icol)
Returns the object describing the data in a given column.

Parameters:
  `icol` - the column for which header information is required
Returns:
  a ValueInfo object for column `icol`

### getColumnAuxDataInfos

List<ValueInfo> getColumnAuxDataInfos()
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.

Returns:
  an unmodifiable ordered set of known metadata keys
See Also:
  - `DefaultValueInfo.getAuxData()`

### getRowSequence

RowSequence getRowSequence() throws IOException
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.

Returns:
  new RowSequence
Throws:
  `IOException` - if there is an error providing access

### getRowAccess

RowAccess getRowAccess() throws IOException
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.

Returns:
  new RowAccess
Throws:
  `IOException` - if there is an error setting up access
  `UnsupportedOperationException` - if `isRandom` returns `false`

### getRowSplittable

RowSplittable getRowSplittable() throws IOException
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)`.

Returns:
  new RowSplittable
Throws:
  `IOException`
See Also:
  - `RowRunner`

### isRandom

boolean isRandom()
Indicates whether random access is provided by this table. Only if the result is `true` may the `getRowAccess()`, `getRow(long)` and `getCell(long, int)` methods be used.

Returns:
  `true` if table random access methods are available

### getCell

Object getCell(long irow, int icol) throws IOException
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.

Parameters:
  `irow` - the index of the cell's row
  `icol` - the index of the cell's column
Returns:
  the contents of this cell
Throws:
  `IOException` - if there is an error reading the data
  `UnsupportedOperationException` - if `isRandom` returns `false`

### getRow

Object[] getRow(long irow) throws IOException
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.

Parameters:
  `irow` - the index of the row to retrieve
Returns:
  an array of the objects in each cell in row `irow`
Throws:
  `IOException` - if there is an error reading the data
  `UnsupportedOperationException` - if `isRandom` returns `false`

### close

void close() throws IOException
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 `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `IOException`