uk.ac.starlink.fits
Class FitsArrayBuilder

java.lang.Object
  extended by uk.ac.starlink.fits.FitsArrayBuilder
All Implemented Interfaces:
ArrayBuilder

public class FitsArrayBuilder
extends Object
implements 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
static FitsArrayBuilder getInstance()
          Returns a FitsArrayBuilder.
 NDArray makeNDArray(ArrayDataInput stream, AccessMode mode)
          Makes a readable NDArray from a data input stream.
 NDArray makeNDArray(URL url, AccessMode mode)
          Constructs an NDArray based on the existing resource at a given URL.
 NDArray makeNewNDArray(OutputStream stream, NDShape shape, Type type, BadHandler bh, boolean primary, HeaderCard[] cards)
          Makes a new HDU written into a given stream containing an NDArray with the type and shape as specified.
 NDArray makeNewNDArray(URL url, NDShape shape, Type type, 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 NDArray makeNDArray(URL url,
                           AccessMode mode)
                    throws IOException
Description copied from interface: ArrayBuilder
Constructs an NDArray based on the existing resource at a given URL. If the resource is not recognised or it is not known how to construct such an NDArray, then null should be returned. If the resource exists but some error occurs in processing it, or if this factory knows that it understands the URL but is unable to locate such a resource then an IOException should be thrown; however, if it is possible that a different factory could correctly construct an NDArray from this URL then a null return is preferred.

If the resource storing the NDArray is incapable of storing bad values, an NDArray using the default bad value handling policy should be returned.

Specified by:
makeNDArray in interface ArrayBuilder
Parameters:
url - the URL of the resource from which an NDArray is to be constructed
mode - the read/update/write mode with which to create the array
Returns:
the NDArray at url, or null if this handler does not recognise the URL
Throws:
IOException - if the URL is understood but an NDArray cannot be made

makeNDArray

public NDArray makeNDArray(ArrayDataInput stream,
                           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 NDArray makeNewNDArray(URL url,
                              NDShape shape,
                              Type type,
                              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 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 NDArray makeNewNDArray(OutputStream stream,
                              NDShape shape,
                              Type type,
                              BadHandler bh,
                              boolean primary,
                              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


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