uk.ac.starlink.votable

## Interface TabularData

- All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable

      public interface TabularData
      extends java.io.Closeable

  Contains the actual cell contents of a VOTable TABLE element.

  The cell data may always be retrieved sequentially from the table by acquiring a `RowSequence` object (method `getRowSequence()`) - this allows you to read all the data from the first row to the last. Multiple `RowSequences` may be simultaneously active. In some cases random access may also be available; if `isRandom()` returns true, then the `getRowAccess()`, `getRow(long)` and `getCell(long, int)` methods can be used to retrieve cell values in any order.

  The objects retrieved from cells in a given column are of course determined by the corresponding FIELD element (`FieldElement` object), in particular its `arraysize` and `datatype` attributes. What object is returned from each column is described by the following rules:

  - If the element is a scalar or (fixed-dimension) 1-element array, a primitive wrapper object (`Integer`, `Float` etc) will be normally be returned
  - If the element is an array, a java array of primitives (`int[]`, `float[]` etc) will normally be returned. This is stored in column-major order, where that makes a difference (for arrays with more than one dimension).
  - Complex types types are treated by adding an extra dimension to the shape of the data, the most rapidly varying, of size 2.
  - Character (`char` and `unicodeChar`) arrays are automatically turned into Strings or String arrays, with dimensionality one less than that suggested by the `arraysize` attribute
  - The element may be `null`
  In any case the class of returned objects in a given column may be determined by calling the `getContentClass(int)` method.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `getCell(long irow, int icol)` Returns the contents of a given table cell (optional).
    `int` | `getColumnCount()` Returns the number of columns in the table data.
    `java.lang.Class<?>` | `getContentClass(int icol)` Returns a class to which all elements in a given column can be cast.
    `java.lang.Object[]` | `getRow(long irow)` Returns the contents of a given table row (optional).
    `RowAccess` | `getRowAccess()` Returns an object which can provide random access for the table data.
    `long` | `getRowCount()` Returns the number of rows in the table data.
    `RowSequence` | `getRowSequence()` Returns an object which can iterate over all the rows in the table data sequentially.
    `boolean` | `isRandom()` Indicates whether random access is provided by this table.

    - ### Methods inherited from interface java.io.Closeable

      `close`

- - ### Method Detail

    - #### getColumnCount

          int getColumnCount()

      Returns the number of columns in the table data.
      Returns:
        number of cells in each row

    - #### getRowCount

          long getRowCount()

      Returns the number of rows in the table data. If this cannot be determined (easily), the value -1 may be returned. The result will always be positive if `isRandom()` returns true.
      Returns:
        number of rows, or -1 if unknown

    - #### getContentClass

          java.lang.Class<?> getContentClass(int icol)

      Returns a class to which all elements in a given column can be cast.
      Parameters:
        `icol` - the column (0-based)
      Returns:
        a class to which any non-null element returned by this object in column `icol` will belong

    - #### getRowSequence

          RowSequence getRowSequence()
                              throws java.io.IOException

      Returns an object which can iterate over all the rows in the table data sequentially. In general the returned object is only safe for use within a single thread.
      Returns:
        an object providing sequential access to the data
      Throws:
        `java.io.IOException`

    - #### isRandom

          boolean isRandom()

      Indicates whether random access is provided by this table. Only if the result is true may the `getRow(long)` and `getCell(long, int)` methods be used.
      Returns:
        `true` iff random access methods are available

    - #### getRowAccess

          RowAccess getRowAccess()
                          throws java.io.IOException

      Returns an object which can provide random access for the table data. In general the returned object is only safe for use within a single thread.
      Returns:
        an object providing random access to the data
      Throws:
        `java.io.IOException` - if there is I/O trouble
        `java.lang.UnsupportedOperationException` - if `isRandom` returns false

    - #### getCell

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

      Returns the contents of a given table cell (optional). The class of the returned object will be compatible with that returned by `getContentClass(icol)`. Only provided if `getRandom` returns true.
      Parameters:
        `irow` - row index
        `icol` - column index
      Returns:
        contents of the cell at `irow`, `icol`
      Throws:
        `java.io.IOException` - if there is I/O trouble
        `java.lang.UnsupportedOperationException` - if `isRandom` returns false

    - #### getRow

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

      Returns the contents of a given table row (optional). Only provided if `getRandom` returns true.
      Parameters:
        `irow` - row index
      Returns:
        array of objects giving the cells in row `irow` (one cell per column)
      Throws:
        `java.io.IOException` - if there is I/O trouble
        `java.lang.UnsupportedOperationException` - if `isRandom` returns false