uk.ac.starlink.hds
Class HDSArrayBuilder

java.lang.Object
  extended by uk.ac.starlink.hds.HDSArrayBuilder
All Implemented Interfaces:
ArrayBuilder

public class HDSArrayBuilder
extends Object
implements ArrayBuilder

Turns URLs which reference HDS array resources into NDArray 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 HDSArrayBuilder getInstance()
          Returns an HDSArrayBuilder.
 NDArray makeNDArray(ArrayStructure ary, AccessMode mode)
          Constructs an NDArray based on an existing HDS array object.
 NDArray makeNDArray(URL url, AccessMode mode)
          Constructs an NDArray based on the existing resource at a given URL.
 NDArray makeNewNDArray(URL url, NDShape shape, Type type, BadHandler bh)
          Constructs a new NDArray with the given characteristics in 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 HDSArrayBuilder getInstance()
Returns an HDSArrayBuilder.

Returns:
the sole instance of this class
Throws:
LinkageError - if the JNIHDS package is not available

makeNDArray

public NDArray makeNDArray(URL url,
                           AccessMode mode)
                    throws IOException
Description copied from interface: ArrayBuilder
Constructs an NDArray based on the existing resource at a given URL. If the resource is not recognised or it is not known how to construct such an NDArray, then null should be returned. If the resource exists but some error occurs in processing it, or if this factory knows that it understands the URL but is unable to locate such a resource then an IOException should be thrown; however, if it is possible that a different factory could correctly construct an NDArray from this URL then a null return is preferred.

If the resource storing the NDArray is incapable of storing bad values, an NDArray using the default bad value handling policy should be returned.

Specified by:
makeNDArray in interface ArrayBuilder
Parameters:
url - the URL of the resource from which an NDArray is to be constructed
mode - the read/update/write mode with which to create the array
Returns:
the NDArray at url, or null if this handler does not recognise the URL
Throws:
IOException - if the URL is understood but an NDArray cannot be made

makeNDArray

public NDArray makeNDArray(ArrayStructure ary,
                           AccessMode mode)
                    throws HDSException
Constructs an NDArray based on an existing HDS array object. The supplied HDSObject ary may be primary or secondary and may be annulled following this call.

Parameters:
ary - the ArrayStructure to be viewed as an NDArray
mode - the read/write/update mode for the NDArray
Returns:
the new NDArray based on ary
Throws:
HDSException - if there is an error in HDS

makeNewNDArray

public NDArray makeNewNDArray(URL url,
                              NDShape shape,
                              Type type,
                              BadHandler bh)
                       throws IOException
Description copied from interface: ArrayBuilder
Constructs a new NDArray with the given characteristics in a location determined by a given URL. If the URL is not recognised or this factory does not feel qualified to construct an NDArray with the given URL then null should be returned. 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 null return is preferred.

The bh parameter indicates a requested bad value handling policy. If it is not null, this handler should attempt to create a new NDArray resource with the same policy. However, if it is not possible because of limitations in the storage format it may use a different bad value policy, bearing in mind the behaviour documented in ArrayBuilder.makeNDArray(java.net.URL, uk.ac.starlink.array.AccessMode).

Specified by:
makeNewNDArray in interface ArrayBuilder
Parameters:
url - the URL at which the resource backing the NDArray is to be written
shape - the shape of the new NDArray to construct. If this object is an OrderedNDShape, its Order may be used as a hint about the pixel ordering scheme of the NDArray to be created, but no guarantee is made that the orderings will match
type - the primitive data type of the new NDArray to construct
bh - requested bad value handling policy - see above
Returns:
the new NDArray, or null if this handler does not recognise the URL
Throws:
IOException - if the URL is understood but the requested NDArray cannot be constructed there


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