uk.ac.starlink.fits

Class BintableStarTable

java.lang.Object

uk.ac.starlink.table.AbstractStarTable

uk.ac.starlink.fits.BintableStarTable

All Implemented Interfaces:

Closeable, AutoCloseable, StarTable

public abstract class BintableStarTable
extends AbstractStarTable

An implementation of the StarTable interface which uses a FITS BINTABLE extension.

The implementation varies according to whether random or sequential-only access is provided by the underlying data access. A factory method is provided to create an appropriate instance.

Some instances of this class hang on to file descriptors. If you are in danger of running out of that resource before instances are garbage collected, you can call the AbstractStarTable.close() method to release them. Attempting to read data following such a call may result in an exception.

Limited support is provided for the HEALPix-FITS convention; the relevant HealpixTableInfo table parameters are added, but any BAD_DATA keyword value is ignored, and the 1024-element array-valued column variant of the format is not understood.

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static ValueInfo	LONGOFF_INFO Column aux metadata key for stringified longs offset.
static ValueInfo	TBCOL_INFO Column aux metadata key for TBCOLn cards.
static ValueInfo	TDISP_INFO Column aux metadata key for TDISPn cards.
static ValueInfo	TFORM_INFO Column aux metadata key for TFORMn cards.
static ValueInfo	TNULL_INFO Column aux metadata key for TNULLn cards.
static ValueInfo	TSCAL_INFO Column aux metadata key for TSCALn cards.
static ValueInfo	TZERO_INFO Column aux metadata key for TZEROn cards.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BintableStarTable(FitsHeader hdr, boolean isRandom, WideFits wide) Constructor.

Method Summary

Modifier and Type	Method and Description
static BintableStarTable	createTable(FitsHeader hdr, InputFactory inputFact, WideFits wide) Returns an instance of this class given a data access instance.
List<ValueInfo>	getColumnAuxDataInfos() Goes through the table columns (ColumnInfo objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name.
int	getColumnCount() Returns the number of columns in this table.
ColumnInfo	getColumnInfo(int icol) Returns the object describing the data in a given column.
protected long[]	getColumnOffsets() Returns the array of byte offsets from the start of the row at which each column starts.
long	getRowCount() Returns the number of rows in this table, if known.
protected long	getRowLength() Returns the number of bytes occupied in the data stream by a single row of the table.
protected Object	readCell(BasicInput stream, int icol) Reads a cell from a given column from the current position in a stream.
protected Object[]	readRow(BasicInput stream) Reads a whole row of the table from the current position in a stream, returning a new Object[] array.
static void	streamStarTable(FitsHeader hdr, BasicInput input, WideFits wide, TableSink sink) Reads a BINTABLE extension from a stream and writes the result to a table sink.

Methods inherited from class uk.ac.starlink.table.AbstractStarTable

checkedLongToInt, close, getCell, getName, getParameters, getRow, getRowAccess, getRowSequence, getRowSplittable, getURL, isRandom, setName, setParameters, setURL

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.ac.starlink.table.StarTable

getParameterByName, setParameter

Field Detail

TNULL_INFO

public static final ValueInfo TNULL_INFO

Column aux metadata key for TNULLn cards.

TSCAL_INFO

public static final ValueInfo TSCAL_INFO

Column aux metadata key for TSCALn cards.

TZERO_INFO

public static final ValueInfo TZERO_INFO

Column aux metadata key for TZEROn cards.

TDISP_INFO

public static final ValueInfo TDISP_INFO

Column aux metadata key for TDISPn cards.

TBCOL_INFO

public static final ValueInfo TBCOL_INFO

Column aux metadata key for TBCOLn cards.

TFORM_INFO

public static final ValueInfo TFORM_INFO

Column aux metadata key for TFORMn cards.

LONGOFF_INFO

public static final ValueInfo LONGOFF_INFO

Column aux metadata key for stringified longs offset.

Constructor Detail

BintableStarTable

protected BintableStarTable(FitsHeader hdr,
                            boolean isRandom,
                            WideFits wide)
                     throws IOException

Constructor.

Parameters:

hdr - FITS header cards

isRandom - true if the data access will be random-access, false for sequential-only

wide - convention for representing extended columns; use null to avoid use of extended columns

Throws:

IOException

Method Detail

getRowCount

public long getRowCount()

Description copied from interface: StarTable

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.

Specified by:

getRowCount in interface StarTable

Specified by:

getRowCount in class AbstractStarTable

Returns:

the number of rows, or -1

getColumnCount

public int getColumnCount()

Description copied from interface: StarTable

Returns the number of columns in this table.

Specified by:

getColumnCount in interface StarTable

Specified by:

getColumnCount in class AbstractStarTable

Returns:

the number of columns

getColumnInfo

public ColumnInfo getColumnInfo(int icol)

Description copied from interface: StarTable

Returns the object describing the data in a given column.

Specified by:

getColumnInfo in interface StarTable

Specified by:

getColumnInfo in class AbstractStarTable

Parameters:

icol - the column for which header information is required

Returns:

a ValueInfo object for column icol

getColumnAuxDataInfos

public List<ValueInfo> getColumnAuxDataInfos()

Description copied from class: AbstractStarTable

Goes through the table columns (ColumnInfo objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name. Subclasses should override this if they can do better, for instance providing an order for the keys.

Specified by:

getColumnAuxDataInfos in interface StarTable

Overrides:

getColumnAuxDataInfos in class AbstractStarTable

Returns:

a list of all the auxiliary metadata ValueInfo items which in fact crop up in column metadata

See Also:

DefaultValueInfo.getAuxData()

readCell

protected Object readCell(BasicInput stream,
                          int icol)
                   throws IOException

Reads a cell from a given column from the current position in a stream.

Parameters:

icol - the column index corresponding to the cell to be read

stream - a stream containing the byte data, positioned to the right place

Throws:

IOException

readRow

protected Object[] readRow(BasicInput stream)
                    throws IOException

Reads a whole row of the table from the current position in a stream, returning a new Object[] array.

Parameters:

stream - a stream containing the byte data, positioned to the right place

Returns:

ncol-element array of cells for this row

Throws:

IOException

getRowLength

protected long getRowLength()

Returns the number of bytes occupied in the data stream by a single row of the table. This is equal to the sum of the column offsets array.

Returns:

row length in bytes

getColumnOffsets

protected long[] getColumnOffsets()

Returns the array of byte offsets from the start of the row at which each column starts.

Returns:

ncol-element array of byte offsets

createTable

public static BintableStarTable createTable(FitsHeader hdr,
                                            InputFactory inputFact,
                                            WideFits wide)
                                     throws IOException

Returns an instance of this class given a data access instance.

Parameters:

hdr - FITS header cards

inputFact - factory for access to the data part of the HDU representing a FITS BINTABLE extension

wide - convention for representing extended columns; use null to avoid use of extended columns

Returns:

StarTable instance; it will be random-access according to whether the input factory is

Throws:

IOException

streamStarTable

public static void streamStarTable(FitsHeader hdr,
                                   BasicInput input,
                                   WideFits wide,
                                   TableSink sink)
                            throws IOException

Reads a BINTABLE extension from a stream and writes the result to a table sink.

Parameters:

hdr - FITS header object describing the BINTABLE extension

input - input stream positioned at the start of the data part of the BINTABLE extension

wide - convention for representing extended columns; use null to avoid use of extended columns

sink - destination for the table

Throws:

IOException