uk.ac.starlink.fits

## Class FitsTableBuilder

- java.lang.Object
- - uk.ac.starlink.fits.FitsTableBuilder

- All Implemented Interfaces:
    uk.ac.starlink.table.MultiTableBuilder, uk.ac.starlink.table.TableBuilder

      public class FitsTableBuilder
      extends java.lang.Object
      implements uk.ac.starlink.table.TableBuilder, 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.

  Author:
    Mark Taylor (Starlink)

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static uk.ac.starlink.table.StarTable` | `attemptReadTable(nom.tam.util.ArrayDataInput strm, boolean wantRandom, uk.ac.starlink.util.DataSource datsrc, WideFits wide, long[] pos)` Reads the next header, and returns a StarTable based on it if it represents a table.
    `boolean` | `canImport(java.awt.datatransfer.DataFlavor flavor)` Returns `true` for a flavor with the MIME type "application/fits".
    `static uk.ac.starlink.table.StarTable` | `findNamedTable(nom.tam.util.ArrayDataInput strm, uk.ac.starlink.util.DataSource datsrc, java.lang.String name, WideFits wide, long[] pos)` 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.
    `java.lang.String` | `getFormatName()` Returns "FITS".
    `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(java.io.InputStream istrm, uk.ac.starlink.table.TableSink sink, java.lang.String extnum)` Reads a FITS table from an input stream and writes it to a sink.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

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

    - #### getFormatName

          public java.lang.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 java.io.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:
        `java.io.IOException`

    - #### makeStarTables

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

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

    - #### canImport

          public boolean canImport(java.awt.datatransfer.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(java.io.InputStream istrm,
                                      uk.ac.starlink.table.TableSink sink,
                                      java.lang.String extnum)
                               throws java.io.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:
        `istrm` - 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:
        `java.io.IOException`

    - #### findNamedTable

          public static uk.ac.starlink.table.StarTable findNamedTable(nom.tam.util.ArrayDataInput strm,
                                                                      uk.ac.starlink.util.DataSource datsrc,
                                                                      java.lang.String name,
                                                                      WideFits wide,
                                                                      long[] pos)
                                                               throws nom.tam.fits.FitsException,
                                                                      java.io.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:
        `strm` - 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)
      Returns:
        a new table
      Throws:
        `nom.tam.fits.FitsException`
        `java.io.IOException`

    - #### attemptReadTable

          public static uk.ac.starlink.table.StarTable attemptReadTable(nom.tam.util.ArrayDataInput strm,
                                                                        boolean wantRandom,
                                                                        uk.ac.starlink.util.DataSource datsrc,
                                                                        WideFits wide,
                                                                        long[] pos)
                                                                 throws nom.tam.fits.FitsException,
                                                                        java.io.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:
        `strm` - 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)
      Returns:
        a StarTable made from the HDU at the start of `strm` or null
      Throws:
        `nom.tam.fits.FitsException`
        `java.io.IOException`

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