Package uk.ac.starlink.oldfits

# Class FitsArrayBuilder

java.lang.Object
uk.ac.starlink.oldfits.FitsArrayBuilder

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

public class FitsArrayBuilder extends 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

Modifier and Type
Method
Description
`static FitsArrayBuilder`
`getInstance()`
Returns a FitsArrayBuilder.
`uk.ac.starlink.array.NDArray`
`makeNDArray(URL url, uk.ac.starlink.array.AccessMode mode)`
`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`
`makeNewNDArray(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(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 Details

### getInstance

public static FitsArrayBuilder getInstance()
Returns a FitsArrayBuilder.

Returns:
  the sole instance of this class

### makeNDArray

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

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

### makeNDArray

public uk.ac.starlink.array.NDArray makeNDArray(nom.tam.util.ArrayDataInput stream, uk.ac.starlink.array.AccessMode mode) throws 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:
  `IOException` - if some I/O error occurs or the stream does not contain FITS array data

### makeNewNDArray

public uk.ac.starlink.array.NDArray makeNewNDArray(URL url, uk.ac.starlink.array.NDShape shape, uk.ac.starlink.array.Type type, uk.ac.starlink.array.BadHandler bh) throws 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:
  `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(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 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:
  `IOException` - if there is some I/O error