uk.ac.starlink.ndx

Class XMLNdxHandler

java.lang.Object

uk.ac.starlink.ndx.XMLNdxHandler

All Implemented Interfaces:

NdxHandler

public class XMLNdxHandler
extends Object
implements NdxHandler

Turns URLs which reference XML files into Ndxs. This does not do such sophisticated processing as the HDX system, and is mainly intended as a stopgap until that is complete. No namespace is used in XML files, and array URL references may be either as the value of a 'url' attribute or as the text content of an element, e.g.:

    <variance url="http://archive.org/data/stars-vars.fits"/>
 

or

    <variance>http://archive.org/data/stars-vars.fits</variance>
 

URLs relative to the position of the XML file in question are allowed.

A URL is normally only considered suitable if it ends in '.xml'. However, the special URL "file:-" may be used to indicate standard input/output.

Method Summary

Modifier and Type	Method and Description
static XMLNdxHandler	getInstance() Returns an XMLNdxHandler.
boolean	makeBlankNdx(URL url, Ndx template) Writes an XML file representing a new NDX with writable array components.
Ndx	makeNdx(Source xsrc, AccessMode mode) Constructs a readable Ndx object from an XML source.
Ndx	makeNdx(URL url, AccessMode mode) Constructs an Ndx object from a URL pointing to an appropriate XML resource.
boolean	outputNdx(URL xurl, Ndx ndx) Writes an XML representation of an existing Ndx object to the given (writable) URL.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static XMLNdxHandler getInstance()

Returns an XMLNdxHandler.

Returns:

the sole instance of this class

makeNdx

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

Constructs an Ndx object from a URL pointing to an appropriate XML resource.

Specified by:

makeNdx in interface NdxHandler

Parameters:

url - a URL pointing to some XML representing an NDX

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

Throws:

IOException - if some error occurs in the I/O

makeNdx

public Ndx makeNdx(Source xsrc,
                   AccessMode mode)
            throws IOException

Constructs a readable Ndx object from an XML source.

Parameters:

xsrc - an XML source containing the XML representation of the NDX. Must represent a document or element. Note that the SystemId attribute, if present, will be used to resolve relative URLs

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

Throws:

IOException - if some error occurs in the I/O

IllegalArgumentException - if xsrc does not correspond to a document or element XML source

outputNdx

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

Writes an XML representation of an existing Ndx object to the given (writable) URL.

If any of the array components is virtual, then the array data needs to be output too. Currently, for a URL 'blah.xml' these are written into successive components of a new FITS file 'blah-data.fits'. If the FITS handlers are not installed, or url does not end in '.xml' an IOException will be thrown. This behaviour may be subject to change in future releases.

Specified by:

outputNdx in interface NdxHandler

Parameters:

xurl - the URL to which the Ndx is to be serialised in XML

ndx - the Ndx object to serialise

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:

UnknownServiceException - if the URL does not support output (most protocols, apart from file, don't)

IOException - if some other I/O error occurs

makeBlankNdx

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

Writes an XML file representing a new NDX with writable array components.

The array components themselves reside in a new fits file; currently for a URL 'blah.xml' a new fits file called 'blah-data.fits' is written. If the FITS handlers are not installed, or url does not end in '.xml' an IOException will be thrown. This behaviour may be subject to change in future releases.

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 - any title, bad bits mask, WCS component etc will be copied from here

Returns:

true if the new Ndx was written successfully

Throws:

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