Package nom.tam.util

Class ColumnTable<T>

java.lang.Object
nom.tam.util.ColumnTable<T>
Type Parameters:
T - dummy generic type parameter that is no longer used. We'll stick to it a a memento of the bad design decisions of the past...
All Implemented Interfaces:
Cloneable, DataTable
public class ColumnTable<T> extends Object implements DataTable, Cloneable

Table data that is stored (internally) in column major format. This class has been completely re-written by A. Kovacs for 1.18. We keep the old API for compatibility, but make some practical additions to it.

Note that while column tables are fine to use for accessing data from FITS ASCII tables, they are generally not suitable for user-access of binary table data, because the column tables contain data in the format that is used for storing values in the regular FITS table in the file. That is:
  • logical values are represented by byte entries of 'T', 'F' or '0'.
  • String values are represented as ASCII arrays bytes.
  • Complex values are represented by float[2] or double[2].
  • Variable length columns of all types are represented by heap pointers of int[2] or long[2].

  • Constructor Summary

    Constructors
    Constructor
    Description
    ColumnTable()
    Creates an empty column table.
    ColumnTable(Object[] arrays, int[] sizes)
    Create the object after checking consistency.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addColumn(Class<?> type, int size)
    Adds a new column with the specified primitive base class and element count.
    void
    addColumn(Object newColumn, int size)
    Adds a column in flattened 1D format, specifying the size of array 'elements'.
    void
    addRow(Object[] row)
    Add a row to the table.
    void
    addWrappedColumn(Object newColumn)
    Adds a column as an array of scalars or regular 1D primitve array elements.
    void
    clear()
    Clears the table, discarding all columns.
    ColumnTable<T>
    copy()
    Returns a deep copy of this column table, such that modification to either the original or the copy will not affect the other.
    final void
    deleteAllRows()
    Delete all rows from the table, but leaving the column structure intact.
    void
    deleteColumn(int col)
    Deletes a column from this table.
    void
    deleteColumns(int start, int len)
    Delete a contiguous set of columns from the table.
    final void
    deleteRow(int row)
    Delete a row from the table.
    void
    deleteRows(int from, int length)
    Delete a contiguous set of rows from the table.
    void
    ensureSize(int rows)
    Makes sure that the table is expanded to hold up to the specified number of rows without having to grow dynamically.
    Class<?>[]
    getBases()
    Deprecated.
    Use getElementClass(int) instead.
    Object
    getColumn(int col)
    Returns the data for a particular column in as a single 1D array of primitives.
    Object[]
    getColumns()
    Returns the data for all columns as an array of flattened 1D primitive arrays.
    Object
    getElement(int row, int col)
    Returns the data element in this table
    final Class<?>
    getElementClass(int col)
    Returns the primitive based class of the elements in a given colum.
    final int
    getElementSize(int col)
    Returns the size of 1D array elements stored in a given column
    T
    getExtraState()
    Deprecated.
    (for internal use) No longer used, will be removed in the future.
    final int
    getNCols()
    Returns the number of columns contained in this table.
    final int
    getNRows()
    Returns the number of rows contained in this table.
    Object
    getRow(int row)
    Indexed access to data by row
    int[]
    getSizes()
    Deprecated.
    Use getElementSize(int) instead.
    final char
    getTypeChar(int col)
    Returns the Java array type character for the elements stored in a given column.
    char[]
    getTypes()
    Deprecated.
    Use getTypeChar(int) instead.
    Object
    getWrappedColumn(int col)
    Returns the wrapped column data, in which each entry correspond to data for a given row.
    final boolean
    isEmpty()
    Checks if the table is empty (contains no data and no column definitions)
    void
    read(ArrayDataInput in)
    Reads the table's data from the input, in row-major format
    void
    read(ArrayDataInput in, int rowStart, int rowEnd, int col)
    Reads a column of a table from a
    void
    setColumn(int col, Object newColumn)
    Sets new data for a table column.
    void
    setElement(int row, int col, Object x)
    Sets new data element in this table
    void
    setExtraState(T opaque)
    Deprecated.
    (for internal use) No longer used, will be removed in the future.
    void
    setRow(int row, Object data)
    Sets new data for a table row
    void
    setWrappedColumn(int col, Object newColumn)
    Sets new data for a column, in wrapped format.
    void
    write(ArrayDataOutput out)
    Writes the table's data to an output, in row-major format.
    void
    write(ArrayDataOutput out, int rowStart, int rowEnd, int col)
    Write a column of a table.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ColumnTable

      public ColumnTable()
      Creates an empty column table.
      Since:
      1.18

    • ColumnTable

      public ColumnTable(Object[] arrays, int[] sizes) throws TableException
      Create the object after checking consistency.
      Parameters:
      arrays - An array of one-d primitive arrays.
      sizes - The number of elements in each row for the corresponding column
      Throws:
      TableException - if the structure of the columns is not consistent

  • Method Details

    • isEmpty

      public final boolean isEmpty()
      Checks if the table is empty (contains no data and no column definitions)
      Returns:
      true if the table has no columns defined, otherwise false
      Since:
      1.18
      See Also:

    • clear

      public void clear()
      Clears the table, discarding all columns.
      Since:
      1.18
      See Also:

    • ensureSize

      public void ensureSize(int rows)
      Makes sure that the table is expanded to hold up to the specified number of rows without having to grow dynamically. Typically it not necessary when adding new rows to the table, as the automatic dynamic allocation is quite efficient, but if you know in advance how many rows you want to add to the table, it does not hurt to just grow the table once, raher than a few times potentially. Note, that if deleting rows may annul the effect of this call, and shrink the table to a reasonable size after the deletions.
      Parameters:
      rows - the number of rows we will want the table to hold at some point in the future...
      See Also:

    • addWrappedColumn

      public void addWrappedColumn(Object newColumn) throws TableException
      Adds a column as an array of scalars or regular 1D primitve array elements.
      Parameters:
      newColumn - the column to add, either as a 1D array of scalar primitives, or a regular 2D array of primitives, in which each row contains the same type of 1D primitive array of the same sizes.
      Throws:
      TableException - if the new column is not a 1D or 2D array of primitives, or it it does not match the number of existing table rows or if the column contains an irregular 2D array.
      Since:
      1.18
      See Also:

    • addColumn

      public void addColumn(Class<?> type, int size) throws TableException
      Adds a new column with the specified primitive base class and element count.
      Parameters:
      type - the primitive class of the elements in this colymn, such as boolean.class
      size - the number of primitive elements (use 1 to create scalar columns)
      Throws:
      TableException - if the type is not a primitive type or the size is invalid.
      Since:
      1.18
      See Also:

    • addColumn

      public void addColumn(Object newColumn, int size) throws TableException
      Adds a column in flattened 1D format, specifying the size of array 'elements'.
      Parameters:
      newColumn - the column to add.
      size - size for the column
      Throws:
      TableException - if the new column is not a 1D array of primitives, or it it does not conform to the number of existing table rows for the given element size.
      See Also:

    • addRow

      public void addRow(Object[] row) throws TableException
      Add a row to the table. Each element of the row must be a 1D primitive array. If this is not the first row in the table, each element must match the types and sizes of existing rows.
      Parameters:
      row - the row to add
      Throws:
      TableException - if the row contains other than 1D primitive array elements or if the elements do not match the types and sizes of existing table columns.
      See Also:

    • copy

      public ColumnTable<T> copy() throws TableException
      Returns a deep copy of this column table, such that modification to either the original or the copy will not affect the other.
      Returns:
      A deep (independent) copy of this column table
      Throws:
      TableException - (for back compatibility) never thrown.

    • deleteColumn

      public void deleteColumn(int col) throws TableException
      Deletes a column from this table.
      Parameters:
      col - the 0-based column index.
      Throws:
      TableException - if the column index is out of bounds
      Since:
      1.18
      See Also:

    • deleteColumns

      public void deleteColumns(int start, int len) throws TableException
      Delete a contiguous set of columns from the table.
      Parameters:
      start - The first column (0-indexed) to be deleted.
      len - The number of columns to be deleted.
      Throws:
      TableException - if the request goes outside the boundaries of the table or if the length is negative.
      See Also:

    • deleteAllRows

      public final void deleteAllRows() throws TableException
      Delete all rows from the table, but leaving the column structure intact.
      Throws:
      TableException - if the request goes outside the boundaries of the table or if the length is negative.
      See Also:

    • deleteRow

      public final void deleteRow(int row) throws TableException
      Delete a row from the table.
      Parameters:
      row - The row (0-indexed) to be deleted.
      Throws:
      TableException - if the request goes outside the boundaries of the table or if the length is negative.
      See Also:

    • deleteRows

      public void deleteRows(int from, int length) throws TableException
      Delete a contiguous set of rows from the table.
      Parameters:
      from - the 0-based index of the first tow to be deleted.
      length - The number of rows to be deleted.
      Throws:
      TableException - if the request goes outside the boundaries of the table or if the length is negative.
      See Also:

    • getElementClass

      public final Class<?> getElementClass(int col)
      Returns the primitive based class of the elements in a given colum.
      Parameters:
      col - the 0-based column index
      Returns:
      the primitive base class of the elements in the column, e.g. short.class.
      Since:
      1.18

    • getBases

      public Class<?>[] getBases()
      Deprecated.
      Use getElementClass(int) instead. This method may be removed in the future.
      Get the base classes of the columns. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      An array of Class objects, one for each column.
      See Also:

    • getWrappedColumn

      public Object getWrappedColumn(int col)
      Returns the wrapped column data, in which each entry correspond to data for a given row. If the column contains non-scalar elements, then each entry in the returned array will be a primitive array of the column's element size.
      Parameters:
      col - the 0-based column index
      Returns:
      the array in which each entry corresponds to table row. For scalar columns this will be a primitive array of getNRows() entries. Otherwise, it will be an array, whch contains the primitive array elements for each row.
      Since:
      1.18
      See Also:

    • getColumn

      public Object getColumn(int col)

      Returns the data for a particular column in as a single 1D array of primitives. See TableData.addColumn(Object) for more information about the format of data elements in general.

      Specified by:
      getColumn in interface DataTable
      Parameters:
      col - The 0-based column index.
      Returns:
      an array of primitives (for scalar columns), or else an Object[] array, or possibly null
      See Also:

    • getColumns

      public Object[] getColumns()
      Returns the data for all columns as an array of flattened 1D primitive arrays.
      Returns:
      An array containing the flattened data for each column. Each columns's data is represented by a single 1D array holding all elements for that column. Because this is not an easily digestible format, you are probably better off using getElement(int, int) or getRow(int) instead.
      See Also:

    • getElement

      public Object getElement(int row, int col)
      Description copied from interface: DataTable
      Returns the data element in this table
      Specified by:
      getElement in interface DataTable
      Parameters:
      row - the row index of the element
      col - the column index of the element
      Returns:
      the object to store at the specified row, col in the table.
      See Also:

    • getExtraState

      public T getExtraState()
      Deprecated.
      (for internal use) No longer used, will be removed in the future.
      Returns the extra state information of the table. The type and nature of this information is implementation dependent.
      Returns:
      the object capturing the implementation-specific table state

    • getNCols

      public final int getNCols()
      Description copied from interface: DataTable
      Returns the number of columns contained in this table.
      Specified by:
      getNCols in interface DataTable
      Returns:
      the current number of columns in the table.
      See Also:

    • getNRows

      public final int getNRows()
      Description copied from interface: DataTable
      Returns the number of rows contained in this table.
      Specified by:
      getNRows in interface DataTable
      Returns:
      the current number of rows in the table.
      See Also:

    • getRow

      public Object getRow(int row)
      Description copied from interface: DataTable
      Indexed access to data by row
      Specified by:
      getRow in interface DataTable
      Parameters:
      row - the row index
      Returns:
      an object containing the row data (for all column) of the specified row, or possubly null.
      See Also:

    • getElementSize

      public final int getElementSize(int col)
      Returns the size of 1D array elements stored in a given column
      Parameters:
      col - the 0-based column index
      Returns:
      the array size in the column (scalars return 1)
      Since:
      1.18

    • getSizes

      public int[] getSizes()
      Deprecated.
      Use getElementSize(int) instead. This method may be removed in the future.
      Returns the flattened (1D) size of elements in each column of this table. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      an array with the byte sizes of each column
      Since:
      1.18
      See Also:

    • getTypeChar

      public final char getTypeChar(int col)
      Returns the Java array type character for the elements stored in a given column.
      Parameters:
      col - the 0-based column index
      Returns:
      the Java array type of the elements in the column, such as 'I' if the array is class is I[ (that is for int[]).

    • getTypes

      public char[] getTypes()
      Deprecated.
      Use getTypeChar(int) instead. This method may be removed in the future.
      Get the characters describing the base classes of the columns. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      An array of type characters (Java array types), one for each column.
      See Also:

    • read

      public void read(ArrayDataInput in) throws EOFException, IOException
      Reads the table's data from the input, in row-major format
      Parameters:
      in - The input to read from.
      Throws:
      EOFException - is already at the end of file.
      IOException - if the reading failed
      See Also:

    • setColumn

      public void setColumn(int col, Object newColumn) throws TableException
      Description copied from interface: DataTable
      Sets new data for a table column. See TableData.addColumn(Object) for more information about the expected column data format.
      Specified by:
      setColumn in interface DataTable
      Parameters:
      col - the column index
      newColumn - an object containing the new column data (for all rows) of the specified column.
      Throws:
      TableException - if the table could not be modified
      See Also:

    • setWrappedColumn

      public void setWrappedColumn(int col, Object newColumn) throws TableException
      Sets new data for a column, in wrapped format. The argument is an 1D or 2D array of primitives, in which the eading dimension must match the number of rows already in the table (if any).
      Parameters:
      col - the zero-based column index
      newColumn - the new column data, either as a 1D array of scalar primitives, or a regular 2D array of primitives, in which each row contains the same type of 1D primitive array of the same sizes.
      Throws:
      TableException - if the new column data is not a 1D or 2D array of primitives, or it it does not match the number of existing table rows or if the column contains an irregular 2D array.
      Since:
      1.18
      See Also:

    • setElement

      public void setElement(int row, int col, Object x) throws TableException
      Description copied from interface: DataTable
      Sets new data element in this table
      Specified by:
      setElement in interface DataTable
      Parameters:
      row - the row index of the element
      col - the column index of the element
      x - the object to store at the specified row, col in the table.
      Throws:
      TableException - if the table could not be modified
      See Also:

    • setExtraState

      public void setExtraState(T opaque)
      Deprecated.
      (for internal use) No longer used, will be removed in the future. We used the extra state to carry properties of an enclosing class in this enclosed object, so we could inherit those to new enclosing class instances. This is bad practie. If one needs data from the enclosing object, it should be handled by passing the enclsing object, and not this enclosed table.
      Store additional information that may be needed by the client to regenerate initial arrays.
      Parameters:
      opaque - the extra state to set.

    • setRow

      public void setRow(int row, Object data) throws TableException
      Description copied from interface: DataTable
      Sets new data for a table row
      Specified by:
      setRow in interface DataTable
      Parameters:
      row - the column index
      data - an object containing the new row data (for all columns) of the specified row.
      Throws:
      TableException - if the table could not be modified
      See Also:

    • write

      public void write(ArrayDataOutput out) throws IOException
      Writes the table's data to an output, in row-major format.
      Parameters:
      out - the output stream to write to.
      Throws:
      IOException - if the write operation failed
      See Also:

    • write

      public void write(ArrayDataOutput out, int rowStart, int rowEnd, int col) throws IOException
      Write a column of a table.
      Parameters:
      out - the output stream to write to.
      rowStart - first row to write
      rowEnd - the exclusive ending row index (not witten)
      col - the zero-based column index to write.
      Throws:
      IOException - if the write operation failed

    • read

      public void read(ArrayDataInput in, int rowStart, int rowEnd, int col) throws EOFException, IOException
      Reads a column of a table from a
      Parameters:
      in - The input stream to read from.
      rowStart - first row to read
      rowEnd - the exclusive ending row index (not read)
      col - the zero-based column index to read.
      Throws:
      EOFException - is already at the end of file.
      IOException - if the reading failed