uk.ac.starlink.hds

Class NDFNdxHandler

java.lang.Object

uk.ac.starlink.hds.NDFNdxHandler

All Implemented Interfaces:

HdxDocumentFactory, NdxHandler

public class NDFNdxHandler
extends Object
implements NdxHandler, HdxDocumentFactory

Turns URLs which reference NDF structures into Ndx objects.

URLs are given in the format:

container.sdf

or

container.sdf#path

where the container.sdf part is a full absolute or relative URL referring to the HDS container file, and the optional fragment identifier gives the HDS path within that container file in the traditional dot-separated format. If there is no fragment identifier (no #), the object at the top level of the HDS container file is understood.

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

Author:

Mark Taylor (Starlink)

See Also:

HDSReference

Method Summary

Modifier and Type	Method and Description
static NDFNdxHandler	getInstance() Returns an NDFNdxHandler.
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(HDSObject hobj, URL persistentURL, AccessMode mode) Constructs an Ndx based on an existing HDS object.
Ndx	makeNdx(URL url, AccessMode mode) Creates an NDX with the given mode from a URL referening an HDS file.
boolean	outputNdx(URL url, Ndx orig) 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 NDFNdxHandler getInstance()

Returns an NDFNdxHandler.

Returns:

the sole instance of this class

Throws:

LinkageError - if the JNIHDS package is not available

makeNdx

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

Creates an NDX with the given mode from a URL referening an HDS file. Note that the primary locator via which the resulting NDX is accessed will not be annulled except under control of the garbage collector at such time as all references are known to have disappeared. This means that a writable NDX may not get flushed until the GC wakes up or the controlling process ends.

Specified by:

makeNdx in interface NdxHandler

Parameters:

url - the location of the HDS object

mode - the read/write/update mode for data access

Throws:

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

makeNdx

public Ndx makeNdx(HDSObject hobj,
                   URL persistentURL,
                   AccessMode mode)
            throws HDSException

Constructs an Ndx based on an existing HDS object.

Parameters:

hobj - the HDS object to be viewed as an Ndx

persistentURL - the URL at which this NDX persists. Use null if hobj resides in a temporary file or is otherwise transient.

mode - the read/write/update mode for the Ndx array data

Returns:

the new Ndx based on hobj, or null if it doesn't look like an NDF

Throws:

HDSException - if there is an error in HDS

IllegalArgumentException - if hobj doesn't look like and NDF structure

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 orig)
                  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

orig - 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

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.