uk.ac.starlink.ndx

Class NdxIO

java.lang.Object

uk.ac.starlink.ndx.NdxIO

public class NdxIO
extends Object

Performs I/O between Ndx objects and resources named by URLs. Methods are available to construct a readable Ndx from a URL pointing to an existing resource, or to construct a new Ndx located at a given URL and populate it from the content of an existing Ndx.

This factory delegates the actual Ndx I/O to external NdxHandler objects; the URL is passed to each one in turn until one recognises the URL as one it can deal with, at which point the rest of the work is handed off to that object.

By default, if the corresponding classes are present, the following NdxHandlers are installed:

• NDFNdxHandler
• FitsNdxHandler
• XMLNdxHandler

Consult the documentation of these classes to find out about the format of URLs understood by each.

Author:

Mark Taylor (Starlink)

Constructor Summary

Constructors

Constructor and Description
NdxIO() Constructs an NdxIO with a default list of handlers.

Method Summary

Modifier and Type	Method and Description
List	getHandlers() Gets the list of handlers which actually do the URL->Ndx construction.
boolean	makeBlankNdx(String location, Ndx template) Constructs a new Ndx containing writable and uninitialised data arrays at a given location.
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.
Ndx	makeNdx(String location, AccessMode mode) Constructs a readable Ndx from a location representing an existing resource.
Ndx	makeNdx(URL url, AccessMode mode) Constructs a readable Ndx from a URL representing an exisiting resource.
void	outputNdx(String location, Ndx ndx) Writes a new resource at a given location containing an Ndx with data copied from an existing Ndx.
void	outputNdx(URL url, Ndx ndx) Writes a new resource at a given URL containing an Ndx with data copied from an existing Ndx.
void	setHandlers(NdxHandler[] handlers) Sets the list of handlers which actually do the URL->Ndx construction.

Methods inherited from class java.lang.Object

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

Constructor Detail

NdxIO

public NdxIO()

Constructs an NdxIO with a default list of handlers.

Method Detail

getHandlers

public List getHandlers()

Gets the list of handlers which actually do the URL->Ndx construction. Handlers earlier in the list are given a chance to handle a URL before ones later in the list. This list is mutable and may be modified to change the behaviour of the NdxIO.

Returns:

a List of NdxHandler objects used for turning URLs into Ndxs

setHandlers

public void setHandlers(NdxHandler[] handlers)

Sets the list of handlers which actually do the URL->Ndx construction. Handlers earlier in the list are given a chance to handle a URL before ones later in the list.

Parameters:

handlers - an array of NdxHandler objects used for turning URLs into Ndxs

makeNdx

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

Constructs a readable Ndx from a URL representing an exisiting resource. A null result will be returned if none of the available handlers understands the URL; an IOException will result if one of the handlers is willing to handle the URL but fails to find an Ndx resource at it.

Parameters:

url - a URL pointing to a resource representing an Ndx

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

Returns:

a readable Ndx object view of the resource at url, or null if one could not be found

Throws:

IOException - if there is any I/O error

makeBlankNdx

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

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 match in point of bad values and ordering scheme, but this is dependent on the details of the output format. The initial values of the created array components are undefined, but they will be writable. Applications which call this method should in general then open the new NDX using makeNdx(java.net.URL, uk.ac.starlink.array.AccessMode) and write values to the array components so that it has valid array components.

The classes DefaultMutableNdx and DummyNDArray may be useful in constructing a suitable template Ndx object.

The method will return true if the Ndx was created successfully, and false if none of the available handlers is able to handle the URL. An IOException will result if one of the handlers is willing to handle the URL but encounters some problem when attempting to write the new resource.

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 iff a new blank Ndx was written at url

Throws:

IOException - if there is any I/O error

outputNdx

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

Writes a new resource at a given URL containing an Ndx with data copied from an existing Ndx. An UnsupportedOperationException will result if none of the available handlers understands the URL; an IOException will result if one of the handlers is willing to handle the URL but fails to make an Ndx out of it or some error is encountered during the copy.

Parameters:

url - a URL pointing to a writable resource. This may be a suitable file:-protocol URL or one with some other protocol which can provide an output-capable connection

ndx - an existing Ndx object whose data will be copied to url

Throws:

IOException - if an I/O error occurs

UnsupportedOperationException - no handler exists for this URL

makeNdx

public Ndx makeNdx(String location,
                   AccessMode mode)
            throws IOException

Constructs a readable Ndx from a location representing an existing resource. This convenience method just turns the location into a URL and calls makeNdx(URL,AccessMode).

Parameters:

location - the location of the resource. If it cannot be parsed as a URL it will be treated as a filename

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

Returns:

a readable Ndx object view of the resource at url, or null if one could not be found

Throws:

IOException - if there is any I/O error

FileNotFoundException - if the location doesn't look like a file or URL

makeBlankNdx

public boolean makeBlankNdx(String location,
                            Ndx template)
                     throws IOException

Constructs a new Ndx containing writable and uninitialised data arrays at a given location. This convenience method just turns the location into a URL and calls makeBlankNdx(URL,Ndx).

Parameters:

location - the location of the new resource. If it cannot be parsed as a URL it will be treated as a filename

template - a template Ndx object on which to base the new one

Returns:

true if the Ndx was written successfully

Throws:

IOException - if there is any I/O error

outputNdx

public void outputNdx(String location,
                      Ndx ndx)
               throws IOException

Writes a new resource at a given location containing an Ndx with data copied from an existing Ndx. This convenience method just turns the location into a URL and calls outputNdx(URL,Ndx).

Parameters:

location - the location of the resource. If it cannot be parsed as a URL it will be treated as a filename

ndx - an existing Ndx object whose data will be copied

Throws:

IOException - if there is any I/O error

FileNotFoundException - if the location doesn't look like a file or URL