# Class FitsTableBuilder

java.lang.Object
uk.ac.starlink.table.formats.DocumentedTableBuilder
uk.ac.starlink.fits.FitsTableBuilder

All Implemented Interfaces:
  `uk.ac.starlink.table.Documented, uk.ac.starlink.table.formats.DocumentedIOHandler, uk.ac.starlink.table.MultiTableBuilder, uk.ac.starlink.table.TableBuilder`

public class FitsTableBuilder extends uk.ac.starlink.table.formats.DocumentedTableBuilder implements uk.ac.starlink.table.MultiTableBuilder
Implementation of the `TableBuilder` interface which gets `StarTable`s from FITS files.

The table implementation used by uncompressed binary FITS tables stored on disk maps the file into memory (`MappedByteBuffer`) rather than reading the stream as such; this makes table construction very fast and cheap on memory, regardless of storage policy. This behaviour can be inhibited by referring to the file location as a URL (e.g. "file:spec23.fits" rather than "spec23.fits"), which fools the handler into thinking that it can't be mapped.

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 (Starlink)

## Constructor Summary

Constructors
Constructor
Description
`FitsTableBuilder()`
Default constructor.
`FitsTableBuilder(WideFits wide)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static uk.ac.starlink.table.StarTable`
`attemptReadTable(InputStream in, boolean wantRandom, uk.ac.starlink.util.DataSource datsrc, WideFits wide, long[] pos, uk.ac.starlink.table.StoragePolicy policy)`
Reads the next header, and returns a StarTable based on it if it represents a table.
`boolean`
`canImport(DataFlavor flavor)`
Returns `true` for a flavor with the MIME type "application/fits".
`boolean`
`canStream()`
`boolean`
`docIncludesExample()`
`static uk.ac.starlink.table.StarTable`
`findNamedTable(InputStream in, uk.ac.starlink.util.DataSource datsrc, String name, WideFits wide, long[] pos, uk.ac.starlink.table.StoragePolicy policy)`
Looks through the HDUs in a given FITS stream and if it finds one which has a given name, attempts to make a table out of it.
`String`
`getFormatName()`
Returns "FITS".
`String`
`getXmlDescription()`
`uk.ac.starlink.table.StarTable`
`makeStarTable(uk.ac.starlink.util.DataSource datsrc, boolean wantRandom, uk.ac.starlink.table.StoragePolicy policy)`
Creates a StarTable from a DataSource which refers to a FITS file or stream.
`uk.ac.starlink.table.TableSequence`
`makeStarTables(uk.ac.starlink.util.DataSource datsrc, uk.ac.starlink.table.StoragePolicy policy)`
`void`
`streamStarTable(InputStream in, uk.ac.starlink.table.TableSink sink, String extnum)`
Reads a FITS table from an input stream and writes it to a sink.

### Methods inherited from class uk.ac.starlink.table.formats.DocumentedTableBuilder

`getExtensions, looksLikeFile`

### Methods inherited from class Object

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

### Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler

`readText`

### Methods inherited from interface uk.ac.starlink.table.TableBuilder

`looksLikeFile`

## Constructor Details

### FitsTableBuilder

public FitsTableBuilder()
Default constructor.

### FitsTableBuilder

public FitsTableBuilder(WideFits wide)
Constructor.

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

## Method Details

### getFormatName

public String getFormatName()
Returns "FITS".

Specified by:
  `getFormatName` in interface `uk.ac.starlink.table.TableBuilder`

### makeStarTable

public uk.ac.starlink.table.StarTable makeStarTable(uk.ac.starlink.util.DataSource datsrc, boolean wantRandom, uk.ac.starlink.table.StoragePolicy policy) throws IOException
Creates a StarTable from a DataSource which refers to a FITS file or stream. If the source has a position attribute, it will be interpreted in one of two ways:

- If it's an integer, it will be interpreted as the index of the HDU holding the table. The first HDU is number 0 (though being primary this one can't hold a table), the first extension is number 1, etc.
- Otherwise it's interpreted as the name of the extension. Either of the forms "EXTNAME" or "EXTNAME-EXTVER" is permitted, where EXTNAME and EXTVER are the values of the corresponding FITS header cards, as per the FITS standard.

If the EXTNAME happens to be in the form of a positive integer, this means you can't refer to the extension by name. Too bad.

If there is no position attribute, the first HDU which does hold a table is used.

Specified by:
  `makeStarTable` in interface `uk.ac.starlink.table.TableBuilder`
Parameters:
  `datsrc` - the source of the FITS table data
  `wantRandom` - whether a random-access table is preferred
  `policy` - a StoragePolicy object which may be used to supply scratch storage if the builder needs it
Returns:
  a new StarTable based on `datsrc`, or `null` if it doesn't look like a FITS table
Throws:
  `IOException`

### makeStarTables

public uk.ac.starlink.table.TableSequence makeStarTables(uk.ac.starlink.util.DataSource datsrc, uk.ac.starlink.table.StoragePolicy policy) throws IOException

Specified by:
  `makeStarTables` in interface `uk.ac.starlink.table.MultiTableBuilder`
Throws:
  `IOException`

### canImport

public boolean canImport(DataFlavor flavor)
Returns `true` for a flavor with the MIME type "application/fits".

Specified by:
  `canImport` in interface `uk.ac.starlink.table.TableBuilder`

### streamStarTable

public void streamStarTable(InputStream in, uk.ac.starlink.table.TableSink sink, String extnum) throws IOException
Reads a FITS table from an input stream and writes it to a sink.

Specified by:
  `streamStarTable` in interface `uk.ac.starlink.table.TableBuilder`
Parameters:
  `in` - input stream containing the FITS data
  `sink` - destination for table data
  `extnum` - may contain a string representation of the HDU number in which the required table is found (otherwise the first table HDU will be used)
Throws:
  `IOException`

### canStream

public boolean canStream()

Specified by:
  `canStream` in class `uk.ac.starlink.table.formats.DocumentedTableBuilder`

### docIncludesExample

public boolean docIncludesExample()

Specified by:
  `docIncludesExample` in interface `uk.ac.starlink.table.formats.DocumentedIOHandler`

### getXmlDescription

public String getXmlDescription()

Specified by:
  `getXmlDescription` in interface `uk.ac.starlink.table.Documented`

### findNamedTable

public static uk.ac.starlink.table.StarTable findNamedTable(InputStream in, uk.ac.starlink.util.DataSource datsrc, String name, WideFits wide, long[] pos, uk.ac.starlink.table.StoragePolicy policy) throws IOException
Looks through the HDUs in a given FITS stream and if it finds one which has a given name, attempts to make a table out of it. The supplied `name` is checked against the EXTNAME header value (if present), and if that fails, against EXTNAME-EXTVER (if EXTVER is present too). Matching is case-insensitive.

Parameters:
  `in` - stream to read from, positioned at the start of an HDU (before the header)
  `datsrc` - a DataSource which can supply the data in `strm`
  `name` - target extension name or name-version
  `wide` - convention for representing extended columns; use null to avoid use of extended columns
  `pos` - a 1-element array holding the position in `datsrc` at which `strm` is positioned - it's an array so it can be updated by this routine (sorry)
  `policy` - storage policy, or null for default (normally not used)
Returns:
  a new table
Throws:
  `IOException`

### attemptReadTable

public static uk.ac.starlink.table.StarTable attemptReadTable(InputStream in, boolean wantRandom, uk.ac.starlink.util.DataSource datsrc, WideFits wide, long[] pos, uk.ac.starlink.table.StoragePolicy policy) throws IOException
Reads the next header, and returns a StarTable based on it if it represents a table. If a StarTable is returned, it may not be safe to use the supplied input stream subsequently for other purposes. If the next HDU is some non-table type, `null` is returned and the stream is advanced to the end of that HDU; in this case the stream may continue to be used (e.g. for further calls to this method).

On exit, the first element of the `pos` array contains the position after the current HDU.

Parameters:
  `in` - stream to read from, positioned at the start of an HDU (before the header)
  `wantRandom` - whether a random-access table is preferred
  `datsrc` - a DataSource which can supply the data in `strm`
  `wide` - convention for representing extended columns; use null to avoid use of extended columns
  `pos` - a 1-element array holding the position in `datsrc` at which `strm` is positioned - it's an array so it can be updated by this routine (sorry)
  `policy` - storage policy, or null for default (normally not used)
Returns:
  a StarTable made from the HDU at the start of `strm` or null
Throws:
  `IOException`