uk.ac.starlink.array
Class CopyNDArray

java.lang.Object
  extended by uk.ac.starlink.array.DefaultArrayDescription
      extended by uk.ac.starlink.array.BridgeNDArray
          extended by uk.ac.starlink.array.ScratchNDArray
              extended by uk.ac.starlink.array.CopyNDArray
All Implemented Interfaces:
ArrayDescription, NDArray

public class CopyNDArray
extends ScratchNDArray

Provides a copy of an existing NDArray with its data backed by a fast random-access scratch array in memory or on local disk. This may be used for instance to provide fast access to an NDArray whose pixel values may be passing through computationally intensive 'wrapper' layers, or to provide random access to data supplied from a non-random stream.

The data and characteristics of the returned copy, including URL, will be identical to that of the base array, except that it will have random access, read access and write access, and it is likely to have mapped access (though cannot do so in the case in which the requested dimensions imply more than Integer.MAX_VALUE pixels). Note that the guaranteed readability and writability of the returned object does not indicate that reading from or writing to it will be affected by/have effects on the data of the base array.

In construction an AccessMode parameter is used, which controls when data gets copied. If and only if the mode parameter represents read access (READ or UPDATE) then all the data will be copied from the base array to the scratch copy at construction time. If and only if it represents write access (WRITE or UPDATE) then all the data will be copied from the scratch copy to the base array when the CopyNDArray is closed. The CopyNDArray will close the base array when it is closed itself.

Author:
Mark Taylor (Starlink)

Nested Class Summary
 
Nested classes/interfaces inherited from class uk.ac.starlink.array.ScratchNDArray
ScratchNDArray.BackingStore
 
Nested classes/interfaces inherited from class uk.ac.starlink.array.BridgeNDArray
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
CopyNDArray(NDArray nda, AccessMode mode)
          Constructs a new NDArray containing the same data as a given one,
 
Method Summary
 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.
 URL getURL()
          Returns the URL of this NDArray, or null if it does not have one.
 
Methods inherited from class uk.ac.starlink.array.BridgeNDArray
getAccess, getHdxFacade, getImpl, multipleAccess, 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

CopyNDArray

public CopyNDArray(NDArray nda,
                   AccessMode mode)
            throws IOException
Constructs a new NDArray containing the same data as a given one,

Parameters:
nda - the base NDArray
mode - the access mode with which the data needs to be accessed; this controls the copying of data. If null, read/writability is taken from the isReadable/isWritable flags of nda
Throws:
IOException - if an I/O error occurs during the copy of data from the base NDArray
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
Overrides:
getURL in class BridgeNDArray
Returns:
the URL at which this NDArray resides, or null if it is not persistent

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
Overrides:
close in class BridgeNDArray
Throws:
IOException - if some I/O error occurred


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