uk.ac.starlink.oldfits

Class FitsNdxHandler

java.lang.Object

uk.ac.starlink.oldfits.FitsNdxHandler

All Implemented Interfaces:

HdxDocumentFactory, NdxHandler

public class FitsNdxHandler
extends Object
implements NdxHandler, HdxDocumentFactory

Turns URLs which reference FITS files or HDUs into Ndx objects.

FITS file format for NDXs

When writing an NDX into FITS format, the image array is written as the primary HDU. The headers of this HDU also contain a card with the name "NDX_XML", whose value is a relative URL (of the form '#n', where n is an HDU number) pointing to the HDU in the same FITS file in which XML metadata concerning the NDX's structure can be found. This XML is stored as the sole (character) element of a table extension. Other HDUs may be written if more are needed, for instance the variance and quality arrays. The resulting FITS file is therefore a self-contained copy of the NDX's data (array components) and metadata (XML stored in a table component). Software which is not NDX-aware can see the data just by looking at the primary HDU.

When reading an NDX from a FITS file, the handler will look for the NDX_XML header; if one is found it will retrieve the metadata from the XML stored in the referenced table extension as described above. If this header is not present, it will make an NDX with no components apart from the image array it is pointed at and any WCS defined by FITS WCS headers in that HDU in the normal way.

The coordinate system information of an NDX written to a FITS file is currently written to the Image HDU for use by non-NDX-aware software. However, the WCS is read from the XML if present, so in the case of discrepancies between the two the WCS represented in the FITS headers may be out of date.

URL format

URLs are given in the same format as for the FitsArrayBuilder class. If an HDU other than the first one is referenced, that is where the NDX_XML header will be sought.

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

Version:

$Id$

Author:

Mark Taylor (Starlink), Norman Gray

Method Summary

Modifier and Type	Method and Description
static FitsNdxHandler	getInstance() Returns a FitsNdxHandler.
boolean	makeBlankNdx(URL url, Ndx template) Constructs a new Ndx containing writable and uninitialised array components at the given URL with characteristics matching those of a given template Ndx.
Document	makeHdxDocument(URL url) Obtains a Document representing the data referred to by the URL.
Source	makeHdxSource(URL url) Obtains a Source which can produce the data referred to by the URL.
Ndx	makeNdx(URL url, AccessMode mode) Constructs a readable Ndx based on the existing resource at a given URL.
void	outputNdx(ArrayDataOutput strm, URL url, Ndx ndx) Writes an NDX to a given output stream.
boolean	outputNdx(URL url, Ndx ndx) Constructs a new Ndx which is a copy of the given Ndx at a location determined by a given URL.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static FitsNdxHandler getInstance()

Returns a FitsNdxHandler.

Returns:

the sole instance of this class

makeNdx

public Ndx makeNdx(URL url,
                   AccessMode mode)
            throws IOException

Description copied from interface: NdxHandler

Constructs a readable Ndx 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 Ndx, 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 Ndx from this URL then a null return is preferred.

Specified by:

makeNdx in interface NdxHandler

Parameters:

url - the URL of the resource from which an Ndx is to be constructed

mode - read/write/update access mode for component arrays

Throws:

IOException - if the URL is understood but an Ndx cannot be made

makeBlankNdx

public boolean makeBlankNdx(URL url,
                            Ndx template)
                     throws IOException

Description copied from interface: NdxHandler

Constructs a new Ndx containing writable and uninitialised array components at the given URL with characteristics matching those of a given template Ndx. The scalar components will be copied directly from the template, and the new Ndx will have array components matching the array components of the template in shape and type (and whether they exist or not). They may, but are not required to, match in point of bad values and pixel ordering scheme. The initial values of the created array components are undefined, but they will be writable when subsequently opened.

If the URL is not recognised by this handler or it is not known how to construct such an Ndx then false should be returned. If the handler recognises the URL but some error occurs in creating the new Ndx, then an IOException should be thrown; however, if it is possible that a different handler could correctly construct a writable Ndx as requested then a false return is preferred.

Specified by:

makeBlankNdx in interface NdxHandler

Parameters:

url - a URL at which the new NDX should be written

template - a template Ndx object from which non-array data should be initialised - all scalar components will be copied from it, and new blank writable array components matching the ones in it will be created

Returns:

true if the handler could create the Ndx at url, false if it doesn't understand this URL

Throws:

IOException - if the URL is understood but an NDArray cannot be made

outputNdx

public boolean outputNdx(URL url,
                         Ndx ndx)
                  throws IOException

Description copied from interface: NdxHandler

Constructs a new Ndx which is a copy of the given Ndx at a location determined by a given URL. Exactly what 'copy' means is dependent on the implementation - it may be effectively a reference to the original data or it may be an independent copy.

The return status indicates whether such a resource was successfully created. If the URL is not recognised or this factory does not feel qualified to construct an Ndx with the given URL then it must return false. If some error occurs during construction then an IOException should in general be thrown; however if this factory thinks that another factory might have more luck then a false return is preferred.

Specified by:

outputNdx in interface NdxHandler

Parameters:

url - the URL at which the resource backing the Ndx is to be written

ndx - an Ndx whose data is to be copied to the resource given by url

Returns:

true if the copy can be made, false if this handler does not feel qualified to create a resource with the given URL.

Throws:

IOException - if an error occurred during the resource creation or data copying

outputNdx

public void outputNdx(ArrayDataOutput strm,
                      URL url,
                      Ndx ndx)
               throws IOException

Writes an NDX to a given output stream. The stream is not closed following the write.

Parameters:

strm - the stream to which the NDX should be written

url - the URL represented by the stream; may be null

ndx - the ndx to write

Throws:

IOException

makeHdxDocument

public Document makeHdxDocument(URL url)
                         throws HdxException

Description copied from interface: HdxDocumentFactory

Obtains a Document representing the data referred to by the URL.

Specified by:

makeHdxDocument in interface HdxDocumentFactory

Returns:

a DOM representing the data in the URL, or null if we cannot handle this type of URL.

Throws:

HdxException - if we ought to be able to read this type of URL, but processing fails for some reason. That is, do not simply fail silently in this situation.

See Also:

HdxResourceType

makeHdxSource

public Source makeHdxSource(URL url)
                     throws HdxException

Description copied from interface: HdxDocumentFactory

Obtains a Source which can produce the data referred to by the URL.

Specified by:

makeHdxSource in interface HdxDocumentFactory

Returns:

a Source representing the data, or null if we cannot handle this type of URL

Throws:

HdxException - if we ought to be able to read this type of URL, but processing fails for some reason. That is, do not simply fail silently in this situation.