uk.ac.starlink.fits

## Class FitsArrayBuilder

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

- All Implemented Interfaces:
    uk.ac.starlink.array.ArrayBuilder

      public class FitsArrayBuilder
      extends java.lang.Object
      implements uk.ac.starlink.array.ArrayBuilder

  Turns URLs which reference FITS array resources into NDArray objects.

  URLs are given in the format

  > fits-url.fit

  or

  > fits-url.fit`[`hdu-num`]`

  where the `[]` represent literal square brackets or

  > fits-url.fit`#`hdu-num

  where the `#` represents a literal hash sign. The fits-url.fit represents the full absolute or relative URL of a FITS file, and the hdu-num, if present, is the index of the HDU within it. If no HDU is given, the first HDU (hdu-num=0) is understood.

  When writing a new NDArray, if hdu-num==0 then any existing FITS file of the same name will be erased. It is possible to write to HDUs after the first one by specifying the appropriate hdu-num, but only if this refers to the first non-existent HDU in an existing FITS file.

  This is a singleton class; use `getInstance()` to get an instance.

  Author:
    Mark Taylor (Starlink)

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static FitsArrayBuilder` | `getInstance()` Returns a FitsArrayBuilder.
    `uk.ac.starlink.array.NDArray` | `makeNDArray(nom.tam.util.ArrayDataInput stream, uk.ac.starlink.array.AccessMode mode)` Makes a readable NDArray from a data input stream.
    `uk.ac.starlink.array.NDArray` | `makeNDArray(java.net.URL url, uk.ac.starlink.array.AccessMode mode)`
    `uk.ac.starlink.array.NDArray` | `makeNewNDArray(java.io.OutputStream stream, uk.ac.starlink.array.NDShape shape, uk.ac.starlink.array.Type type, uk.ac.starlink.array.BadHandler bh, boolean primary, nom.tam.fits.HeaderCard[] cards)` Makes a new HDU written into a given stream containing an NDArray with the type and shape as specified.
    `uk.ac.starlink.array.NDArray` | `makeNewNDArray(java.net.URL url, uk.ac.starlink.array.NDShape shape, uk.ac.starlink.array.Type type, uk.ac.starlink.array.BadHandler bh)` Makes a new HDU at a given URL containing an NDArray with the shape and type as specified.

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

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

- - ### Method Detail

    - #### getInstance

          public static FitsArrayBuilder getInstance()

      Returns a FitsArrayBuilder.
      Returns:
        the sole instance of this class

    - #### makeNDArray

          public uk.ac.starlink.array.NDArray makeNDArray(java.net.URL url,
                                                          uk.ac.starlink.array.AccessMode mode)
                                                   throws java.io.IOException

      Specified by:
        `makeNDArray` in interface `uk.ac.starlink.array.ArrayBuilder`
      Throws:
        `java.io.IOException`

    - #### makeNDArray

          public uk.ac.starlink.array.NDArray makeNDArray(nom.tam.util.ArrayDataInput stream,
                                                          uk.ac.starlink.array.AccessMode mode)
                                                   throws java.io.IOException

      Makes a readable NDArray from a data input stream. It will have no URL. Update access may be possible, but only if `stream` implements `ArrayDataOutput`.
      Parameters:
        `stream` - the input stream supplying the HDU at which the FITS array data can be found
        `mode` - read/write/update access mode
      Returns:
        the NDArray constructed from `stream`
      Throws:
        `java.io.IOException` - if some I/O error occurs or the stream does not contain FITS array data

    - #### makeNewNDArray

          public uk.ac.starlink.array.NDArray makeNewNDArray(java.net.URL url,
                                                             uk.ac.starlink.array.NDShape shape,
                                                             uk.ac.starlink.array.Type type,
                                                             uk.ac.starlink.array.BadHandler bh)
                                                      throws java.io.IOException

      Makes a new HDU at a given URL containing an NDArray with the shape and type as specified. If the URL represents the first HDU in a FITS file, or leaves the HDU index unspecified, any existing FITS file will be overwritten by a new single-HDU file. An HDU index greater than 0 may be specified only if the URL has the `file:` protocol, and if it is equal to the number of HDUs currently in the FITS file.
      Specified by:
        `makeNewNDArray` in interface `uk.ac.starlink.array.ArrayBuilder`
      Parameters:
        `url` - the URL at which the resource backing the NDArray is to be written
        `shape` - the shape of the new NDArray to construct
        `type` - the primitive data type of the new NDArray to construct
        `bh` - requested bad value handling policy
      Returns:
        the new NDArray, or `null` if the URL doesn't look like a FITS file
      Throws:
        `java.io.IOException` - if the URL is a FITS URL but the requested NDArray cannot be constructed for some reason

    - #### makeNewNDArray

          public uk.ac.starlink.array.NDArray makeNewNDArray(java.io.OutputStream stream,
                                                             uk.ac.starlink.array.NDShape shape,
                                                             uk.ac.starlink.array.Type type,
                                                             uk.ac.starlink.array.BadHandler bh,
                                                             boolean primary,
                                                             nom.tam.fits.HeaderCard[] cards)
                                                      throws java.io.IOException

      Makes a new HDU written into a given stream containing an NDArray with the type and shape as specified.
      Parameters:
        `stream` - the stream down which the NDArray is to be written
        `shape` - the shape of the new NDArray to construct
        `type` - the primitive data type of the new NDArray to construct
        `bh` - requested bad value handling policy
        `primary` - whether this is the primary HDU (first in file)
        `cards` - array of additional FITS header cards to add - may be null
      Returns:
        the new NDArray object
      Throws:
        `java.io.IOException` - if there is some I/O error

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