uk.ac.starlink.hds
Class NDFNdxHandler

java.lang.Object
  extended by 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
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.


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