uk.ac.starlink.ndx
Class XMLNdxHandler

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


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