uk.ac.starlink.oldfits

Class FitsArrayBuilder

java.lang.Object

uk.ac.starlink.oldfits.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

Modifier and Type	Method and Description
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