uk.ac.starlink.votable

## Interface TabularData

-     public interface TabularData

  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 `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.
  Author:
    Mark Taylor

- - ### 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).
    `long` | `getRowCount()` Returns the number of rows in the table data.
    `uk.ac.starlink.table.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.

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

          uk.ac.starlink.table.RowSequence getRowSequence()
                                                   throws java.io.IOException

      Returns an object which can iterate over all the rows in the table data sequentially.
      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

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

Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.