uk.ac.starlink.ndx
Class NdxIO

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

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

Author:
Mark Taylor (Starlink)

Constructor Summary
NdxIO()
          Constructs an NdxIO with a default list of handlers.
 
Method Summary
 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


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