uk.ac.starlink.array

Class BridgeNDArray

java.lang.Object

uk.ac.starlink.array.DefaultArrayDescription

uk.ac.starlink.array.BridgeNDArray

All Implemented Interfaces:

ArrayDescription, NDArray

Direct Known Subclasses:

DummyNDArray, ScratchNDArray

public class BridgeNDArray
extends DefaultArrayDescription
implements NDArray

Class providing an NDArray implementation based on an implementation of the ArrayImpl interface. The idea is that all the implementation work common to any underlying implementation of array functionality is contained in this class, while the details specific to different underlying array types can be contained in different implementations of the ArrayImpl interface. In particular, this class does extensive validation on method parameters and takes care of throwing the right exceptions so that the burden of worrying about invalid parameters is removed from the ArrayImpl implementations.

This exemplifies the Bridge Pattern.

Author:

Mark Taylor (Starlink)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	BridgeNDArray.BridgeNDArrayHdxFacade

Field Summary

Fields inherited from class uk.ac.starlink.array.DefaultArrayDescription

arrayDims, arrayHandler, arrayIsRandom, arrayIsReadable, arrayIsWritable, arrayNdim, arrayNpix, arrayOrder, arrayOrigin, arrayShape, arrayType

Constructor Summary

Constructors

Constructor and Description
BridgeNDArray(ArrayImpl impl) Constructs a non-persistent BridgeNDArray (one without a URL) from an ArrayImpl.
BridgeNDArray(ArrayImpl impl, URL url) Constructs a BridgeNDArray from an ArrayImpl with a given URL.

Method Summary

Modifier and Type	Method and Description
void	close() Declares that this NDArray will not be required for further use; in particular that no further invocations will be made of the getAccess method.
ArrayAccess	getAccess() Returns an object which can read and/or write the pixels of this NDArray.
HdxFacade	getHdxFacade(HdxResourceType hdxType) Obtains a HdxFacade which can represent this object.
ArrayImpl	getImpl() Returns the ArrayImpl object supplying the implementation for this BridgeNDArray.
URL	getURL() Returns the URL of this NDArray, or null if it does not have one.
boolean	multipleAccess() Indicates whether multiple calls to the getAccess method may be made.
String	toString()

Methods inherited from class uk.ac.starlink.array.DefaultArrayDescription

getBadHandler, getShape, getType, isRandom, isReadable, isWritable

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.ac.starlink.array.ArrayDescription

getBadHandler, getShape, getType, isRandom, isReadable, isWritable

Constructor Detail

BridgeNDArray

public BridgeNDArray(ArrayImpl impl,
                     URL url)

Constructs a BridgeNDArray from an ArrayImpl with a given URL.

Parameters:

impl - an ArrayImpl on which this BridgeNDArray will be based

url - the URL at which this NDArray can be found. It is only used to dispense via the getURL method. May be null if the NDArray represented by impl is not persistent

BridgeNDArray

public BridgeNDArray(ArrayImpl impl)

Constructs a non-persistent BridgeNDArray (one without a URL) from an ArrayImpl.

Parameters:

impl - an ArrayImpl on which this BridgeNDArray will be based

Method Detail

getURL

public URL getURL()

Description copied from interface: NDArray

Returns the URL of this NDArray, or null if it does not have one. An NDArray will normally only have a URL if it has been created using one of the calls to NDArrayFactory which takes a URL argument. Feeding the returned URL to the NDArrayFactory will obtain the same NDArray as this one. Scratch NDArrays, and virtual NDArrays created by wrapping another to give access using different characteristics (type, shape etc) will in general not have a URL. The return value must not change over the lifetime of this object.

Specified by:

getURL in interface NDArray

Returns:

the URL at which this NDArray resides, or null if it is not persistent

multipleAccess

public boolean multipleAccess()

Description copied from interface: NDArray

Indicates whether multiple calls to the getAccess method may be made. This method will always return true if the ArrayDescription.isRandom() method returns true, but may do so even for non-random arrays.

Specified by:

multipleAccess in interface NDArray

Returns:

true if multiple independent accessor objects are available

getAccess

public ArrayAccess getAccess()
                      throws IOException

Description copied from interface: NDArray

Returns an object which can read and/or write the pixels of this NDArray. The returned ArrayReader should be closed when it is no longer required; this enables resources it may hold to be released.

Each call to this method returns a new and independent ArrayAccess object. However it may or may not be possible to call it more than once; the NDArray.multipleAccess() method indicates whether this is the case.

Specified by:

getAccess in interface NDArray

Returns:

an accessor for the pixel data

Throws:

IOException - if there is some I/O error

close

public void close()
           throws IOException

Description copied from interface: NDArray

Declares that this NDArray will not be required for further use; in particular that no further invocations will be made of the getAccess method.

This method should be invoked on an NDArray when it is no longer required for pixel access. This allows reclamation of non-memory resources, and in the case of writable arrays it may also be required to ensure that data is flushed from buffers back to the actual pixel array.

An array should not however be closed if some other object might still require pixel access to it via a retained reference. The general rule is that an application which obtains a new NDArray from a URL should arrange for close to be called on it at the end of its lifetime, but that utility routines which perform operations on an NDArray should not close it after use (though they should close any ArrayAccess objects which they take out). Note that closing an NDArray will normally result in closing any arrays which it wraps.

Multiple calls of this method may harmlessly be made.

Specified by:

close in interface NDArray

Throws:

IOException - if some I/O error occurred

getImpl

public ArrayImpl getImpl()

Returns the ArrayImpl object supplying the implementation for this BridgeNDArray.

Returns:

the object which supplies services to this BridgeNDArray

toString

public String toString()

Overrides:

toString in class Object

getHdxFacade

public HdxFacade getHdxFacade(HdxResourceType hdxType)

Obtains a HdxFacade which can represent this object.

Specified by:

getHdxFacade in interface NDArray

Parameters:

hdxType - the registered type which indicates which Hdx type this facade is representing as a DOM element. This may not be null nor HdxResourceType.NONE.