Package nom.tam.fits

Class BinaryTable

    • Field Detail

      • LOG

        private static final java.util.logging.Logger LOG

      • heap

        private final FitsHeap heap
        This is the area in which variable length column data lives.

      • heapOffset

        private int heapOffset
        The number of bytes between the end of the data and the heap

      • heapReadFromStream

        private boolean heapReadFromStream
        Switched to an initial value of true TAM, 11/20/12, since the heap may be generated without any I/O. In that case it's valid. We set heapReadFromStream to false when we skip input.

      • warnedOnVariableConversion

        private boolean warnedOnVariableConversion

      • columnList

        private java.util.List<BinaryTable.ColumnDesc> columnList
        A list describing each of the columns in the table

      • nRow

        private int nRow
        The number of rows in the table.

      • rowLen

        private int rowLen
        The length in bytes of each row.

      • currInput

        private ArrayDataInput currInput
        The stream used to input the data. This is saved so that we possibly skip reading the data if the user doesn't wish to read all or parts of this table.

    • Constructor Detail

      • BinaryTable

        public BinaryTable()
        Create a null binary table data segment.

      • BinaryTable

        public BinaryTable​(ColumnTable<?> tabIn)
        Create a binary table from an existing ColumnTable
        Parameters:
        tabIn - the column table to create the binary table from

      • BinaryTable

        public BinaryTable​(Header myHeader)
            throws FitsException
        Create a binary table from given header information.
        Parameters:
        myHeader - A header describing what the binary table should look like.
        Throws:
        FitsException - if the specified header is not usable for a binary table

      • BinaryTable

        public BinaryTable​(java.lang.Object[] o)
            throws FitsException
        Create a binary table from existing data in column order.
        Parameters:
        o - array of columns
        Throws:
        FitsException - if the data for the columns could not be used as coulumns

      • BinaryTable

        public BinaryTable​(java.lang.Object[][] data)
            throws FitsException
        Create a binary table from existing data in row order.
        Parameters:
        data - The data used to initialize the binary table.
        Throws:
        FitsException - if the data could not be converted to a binary table

    • Method Detail

      • createColumnDataFor

        public static void createColumnDataFor​(BinaryTable table)
                                throws FitsException
        TODO: this is only for internal access!
        Parameters:
        table - the table to create the column data.
        Throws:
        FitsException - if the data could not be created.

      • getTDims

        public static int[] getTDims​(java.lang.String tdims)
        Parse the TDIMS value. If the TDIMS value cannot be deciphered a one-d array with the size given in arrsiz is returned.
        Parameters:
        tdims - The value of the TDIMSn card.
        Returns:
        An int array of the desired dimensions. Note that the order of the tdims is the inverse of the order in the TDIMS key.

      • convertToColumns

        private static java.lang.Object[] convertToColumns​(java.lang.Object[][] data)
        Convert a two-d table to a table of columns. Handle String specially. Every other element of data should be a primitive array of some dimensionality. Basically the translates a table expressed as objects in row order to a table with objects in column order.

      • addColumn

        public int addColumn​(java.lang.Object o)
              throws FitsException
        Description copied from interface: TableData
        Add a column to the table without any associated header information. Users should be cautious of calling this routine directly rather than the corresponding routine in AsciiTableHDU since this routine knows nothing of the FITS header modifications required.
        Parameters:
        o - the new column information. the newCol should be an Object[] where type of all of the constituents is identical. The length of data should match the other columns. Note: It is valid for data to be a 2 or higher dimensionality primitive array. In this case the column index is the first (in Java speak) index of the array. E.g., if called with int[30][20][10], the number of rows in the table should be 30 and this column will have elements which are 2-d integer arrays with TDIM = (10,20).
        Returns:
        the number of columns in the adapted table
        Throws:
        FitsException - if the operation failed

      • addFlattenedColumn

        public int addFlattenedColumn​(java.lang.Object o,
                              int[] dims)
                       throws FitsException
        Add a column where the data is already flattened.
        Parameters:
        o - The new column data. This should be a one-dimensional primitive array.
        dims - The dimensions of one row of the column.
        Returns:
        the new column size
        Throws:
        FitsException - if the array could not be flattened

      • addRow

        public int addRow​(java.lang.Object[] o)
           throws FitsException
        Description copied from interface: TableData
        Add a row at the end of the table. Given the way the table is structured this will normally not be very efficient.Users should be cautious of calling this routine directly rather than the corresponding routine in AsciiTableHDU since this routine knows nothing of the FITS header modifications required.
        Parameters:
        o - An array of elements to be added. Each element of o should be an array of primitives or a String.
        Returns:
        the number of rows in the adapted table
        Throws:
        FitsException - if the operation failed

      • deleteColumns

        public void deleteColumns​(int start,
                          int len)
                   throws FitsException
        Delete a set of columns. Note that this does not fix the header, so users should normally call the routine in TableHDU. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • deleteRows

        public void deleteRows​(int row,
                       int len)
                throws FitsException
        Delete rows from a table.
        Parameters:
        row - The 0-indexed start of the rows to be deleted.
        len - The number of rows to be deleted. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • fillHeader

        public void fillHeader​(Header h)
                throws FitsException
        Update a FITS header to reflect the current state of the data. * @throws FitsException if the operation failed
        Specified by:
        fillHeader in class Data
        Parameters:
        h - header to fill with the data from the current data object
        Throws:
        FitsException - if the operation fails

      • getBases

        public java.lang.Class<?>[] getBases()
        Returns:
        the types in the table, not the underlying types (e.g., for varying length arrays or booleans).

      • getColumn

        public java.lang.Object getColumn​(int col)
                           throws FitsException
        Get a given column
        Parameters:
        col - The index of the column. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • getDimens

        public int[][] getDimens()

      • getElement

        public java.lang.Object getElement​(int i,
                                   int j)
                            throws FitsException
        Get a particular element from the table.
        Parameters:
        i - The row of the element.
        j - The column of the element. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • getFlatColumns

        public java.lang.Object[] getFlatColumns()

      • getFlattenedColumn

        public java.lang.Object getFlattenedColumn​(int col)
                                    throws FitsException
        Parameters:
        col - the column to flatten
        Returns:
        column in flattened format. For large tables getting a column in standard format can be inefficient because a separate object is needed for each row. Leaving the data in flattened format means that only a single object is created.
        Throws:
        FitsException - if the column could not be flattened

      • getHeapOffset

        public int getHeapOffset()
        Returns:
        the offset to the heap

      • getHeapSize

        public int getHeapSize()
        Returns:
        the size of the heap -- including the offset from the end of the table data.

      • getModelRow

        public java.lang.Object[] getModelRow()
        Returns:
        a row that may be used for direct i/o to the table.

      • getNCols

        public int getNCols()
        Get the number of columns in the table.

      • getNRows

        public int getNRows()
        Get the number of rows in the table

      • getRawElement

        public java.lang.Object getRawElement​(int i,
                                      int j)
                               throws FitsException
        Parameters:
        i - The row of the element.
        j - The column of the element.
        Returns:
        a particular element from the table but do no processing of this element (e.g., dimension conversion or extraction of variable length array elements/)
        Throws:
        FitsException - if the operation failed

      • getRow

        public java.lang.Object[] getRow​(int row)
                          throws FitsException
        Get a given row
        Parameters:
        row - The index of the row to be returned.
        Returns:
        A row of data. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • getSizes

        public int[] getSizes()

      • getTrueSize

        public long getTrueSize()
        Get the size of the data in the HDU sans padding.
        Specified by:
        getTrueSize in class Data

      • getTypes

        public char[] getTypes()

      • read

        public void read​(ArrayDataInput i)
          throws FitsException
        Read the data -- or defer reading on random access. * @throws FitsException if the operation failed
        Specified by:
        read in interface FitsElement
        Specified by:
        read in class Data
        Parameters:
        i - The input data stream
        Throws:
        FitsException - if the read was unsuccessful.

      • setColumn

        public void setColumn​(int col,
                      java.lang.Object xcol)
               throws FitsException
        Replace a column in the table.
        Parameters:
        col - The index of the column to be replaced.
        xcol - The new data for the column
        Throws:
        FitsException - Thrown if the data does not match the current column description.

      • setElement

        public void setElement​(int i,
                       int j,
                       java.lang.Object o)
                throws FitsException
        Replace a single element within the table.
        Parameters:
        i - The row of the data.
        j - The column of the data.
        o - The replacement data. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • setFlattenedColumn

        public void setFlattenedColumn​(int col,
                               java.lang.Object data)
                        throws FitsException
        Set a column with the data already flattened.
        Parameters:
        col - The index of the column to be replaced.
        data - The new data array. This should be a one-d primitive array.
        Throws:
        FitsException - Thrown if the type of length of the replacement data differs from the original.

      • setRow

        public void setRow​(int row,
                   java.lang.Object[] data)
            throws FitsException
        Replace a row in the table.
        Parameters:
        row - The index of the row to be replaced.
        data - The new values for the row.
        Throws:
        FitsException - Thrown if the new row cannot match the existing data.

      • updateAfterDelete

        public void updateAfterDelete​(int oldNcol,
                              Header hdr)
                       throws FitsException
        Update the header after a deletion.
        Throws:
        FitsException - if the operation failed

      • write

        public void write​(ArrayDataOutput os)
           throws FitsException
        Write the table, heap and padding. * @throws FitsException if the operation failed
        Specified by:
        write in interface FitsElement
        Specified by:
        write in class Data
        Parameters:
        os - The output stream on which to write the data.
        Throws:
        FitsException - if the write was unsuccessful.

      • arrayToColumn

        private java.lang.Object arrayToColumn​(BinaryTable.ColumnDesc added,
                                       java.lang.Object o)
                                throws FitsException
        Convert the external representation to the BinaryTable representation. Transformation include boolean -> T/F, Strings -> byte arrays, variable length arrays -> pointers (after writing data to heap).
        Throws:
        FitsException - if the operation failed

      • checkCompVary

        private boolean checkCompVary​(float[][][] o)

      • checkDCompVary

        private boolean checkDCompVary​(double[][][] o)

      • columnToArray

        private java.lang.Object columnToArray​(BinaryTable.ColumnDesc colDesc,
                                       java.lang.Object o,
                                       int rows)
                                throws FitsException
        Convert data from binary table representation to external Java representation. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • createTable

        private ColumnTable<BinaryTable.SaveState> createTable()
                                                throws FitsException
        Create a column table given the number of rows and a model row. This is used when we defer instantiation of the ColumnTable until the user requests data from the table. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • encapsulate

        private java.lang.Object encapsulate​(java.lang.Object o)

      • encurl

        private java.lang.Object encurl​(java.lang.Object res,
                                int col,
                                int rows)

      • ensureDataSilent

        private void ensureDataSilent()

      • getFileRow

        private java.lang.Object[] getFileRow​(int row)
                               throws FitsException
        Returns:
        row from the file.
        Throws:
        FitsException - if the operation failed

      • getMemoryRow

        private java.lang.Object[] getMemoryRow​(int row)
                                 throws FitsException
        Get a row from memory. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • initialNumber

        private int initialNumber​(java.lang.String tform)
        Get an unsigned number at the beginning of a string

      • isVarying

        private boolean isVarying​(java.lang.Object o)
        Is this a variable length column? It is if it's a two-d primitive array and the second dimension is not constant. It may also be a 3-d array of type float or double where the last index is always 2 (when the second index is non-zero). In this case it can be a complex varying column.

      • isVaryingComp

        private boolean isVaryingComp​(java.lang.Object o)

      • processCol

        private int processCol​(Header header,
                       int col)
                throws FitsException
        Process one column from a FITS Header. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • saveExtraState

        private void saveExtraState()

      • readHeap

        protected void readHeap​(ArrayDataInput input)
                 throws FitsException
        Read the heap which contains the data for variable length arrays. A. Kovacs (4/1/08) Separated heap reading, s.t. the heap can be properly initialized even if in deferred read mode. columnToArray() checks and initializes the heap as necessary.
        Parameters:
        input - stream to read from.
        Throws:
        FitsException - if the heap could not be read from the stream

      • readTrueData

        protected void readTrueData​(ArrayDataInput i)
                     throws FitsException
        Read table, heap and padding
        Parameters:
        i - the stream to read the data from.
        Throws:
        FitsException - if the reading failed

      • validColumn

        protected boolean validColumn​(int j)
        Check if the column number is valid.
        Parameters:
        j - The Java index (first=0) of the column to check.
        Returns:
        true if the column is valid

      • validRow

        protected boolean validRow​(int i)
        Check to see if this is a valid row.
        Parameters:
        i - The Java index (first=0) of the row to check.
        Returns:
        true if the row is valid

      • addFlattenedColumn

        int addFlattenedColumn​(java.lang.Object o,
                       int[] dims,
                       boolean allocated)
                throws FitsException
        This function is needed since we had made addFlattenedColumn public so in principle a user might have called it directly.
        Parameters:
        o - The new column data. This should be a one-dimensional primitive array.
        dims - The dimensions of one row of the column.
        allocated - is it already in the columnList?
        Returns:
        the new column size
        Throws:
        FitsException

      • fillForColumn

        void fillForColumn​(Header h,
                   int col,
                   Cursor<java.lang.String,​HeaderCard> iter)
            throws FitsException
        Update the header to reflect the details of a given column. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • getTFORMLength

        int getTFORMLength​(java.lang.String tform)
        Get the explicit or implied length of the TFORM field

      • getTFORMType

        char getTFORMType​(java.lang.String tform)
        Get the type in the TFORM field

      • getTFORMVarType

        char getTFORMVarType​(java.lang.String tform)
        Get the type in a varying length column TFORM

      • pointToColumn

        void pointToColumn​(int col,
                   Header hdr)
            throws FitsException
        Update the header to reflect information about a given column. This routine tries to ensure that the Header is organized by column. * @throws FitsException if the operation failed
        Throws:
        FitsException

      • setComplexColumn

        boolean setComplexColumn​(int index)
                  throws FitsException
        Convert a column from float/double to float complex/double complex. This is only possible for certain columns. The return status indicates if the conversion is possible.
        Parameters:
        index - The 0-based index of the column to be reset.
        Returns:
        Whether the conversion is possible. * @throws FitsException if the operation failed
        Throws:
        FitsException