uk.ac.starlink.array
Class NioArrayImpl

java.lang.Object
  extended by uk.ac.starlink.array.NioArrayImpl
All Implemented Interfaces:
ArrayImpl

public class NioArrayImpl
extends Object
implements ArrayImpl

Implementation of ArrayImpl which uses a Buffer for the data storage. Can be used in such a way that the buffer itself is not actually created until it is required (and hence is never created if it is not required).

Author:
Mark Taylor (Starlink)
See Also:
Buffer

Nested Class Summary
static interface NioArrayImpl.BufferGetter
          Defines an object which can provide deferred access to a Buffer.
 
Constructor Summary
NioArrayImpl(Buffer buf, OrderedNDShape oshape, Type type, Number badval)
          Constructs an ArrayImpl from a Buffer.
NioArrayImpl(NioArrayImpl.BufferGetter bufget, OrderedNDShape oshape, Type type, Number badval)
          Constructs an ArrayImpl using a deferred-access buffer object.
 
Method Summary
 boolean canMap()
          Indicates whether mapped access is available.
 void close()
          Shuts down this ArrayImpl for pixel access.
 AccessImpl getAccess()
          Returns an object which can access the pixels of this ArrayImpl.
 Number getBadValue()
          The magic bad value for data.
 Object getMapped()
          Returns a single primitive array holding all the pixel data of this array.
 OrderedNDShape getShape()
          Returns an object representing the shape (origin and dimensions) and pixel sequence of this object.
 Type getType()
          Returns the primitive type of the data held by this object.
 boolean isRandom()
          Indicates whether random access is possible.
 boolean isReadable()
          Indicates whether read access is possible.
 boolean isWritable()
          Indicates whether write access is possible.
 boolean multipleAccess()
          Indicates whether the getAccess method may be called more than once.
 void open()
          Prepares this ArrayImpl for pixel access.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NioArrayImpl

public NioArrayImpl(NioArrayImpl.BufferGetter bufget,
                    OrderedNDShape oshape,
                    Type type,
                    Number badval)
Constructs an ArrayImpl using a deferred-access buffer object. This constructor will only create the NIO buffer when it is required - if pixel access is never performed the buffer is never created.

Parameters:
bufget - an object which can do deferred creation of a Buffer
oshape - the shape of the array
type - the data type of the array
badval - the magic bad value for the array (may be null)

NioArrayImpl

public NioArrayImpl(Buffer buf,
                    OrderedNDShape oshape,
                    Type type,
                    Number badval)
Constructs an ArrayImpl from a Buffer.

Parameters:
buf - an NIO buffer
oshape - the shape of the array
type - the data type of the array
badval - the magic bad value for the array (may be null)
Method Detail

open

public void open()
          throws IOException
Description copied from interface: ArrayImpl
Prepares this ArrayImpl for pixel access. This method will be called no more than once, and it will be called prior to any calls of the getAccess method.

Specified by:
open in interface ArrayImpl
Throws:
IOException - if there is an IO error

canMap

public boolean canMap()
Description copied from interface: ArrayImpl
Indicates whether mapped access is available. If true, then following an open call, the getMapped method will return a reference to the java primitive array containing all the pixels of this array.

Will only be called after an open call, and before any close call.

Specified by:
canMap in interface ArrayImpl

getMapped

public Object getMapped()
Description copied from interface: ArrayImpl
Returns a single primitive array holding all the pixel data of this array. This should be a cheap operation, returning a reference to an existing array rather than doing work to generate one. In the case of a writable accessor, making changes to the returned primitive array will result in changes to the accessor pixel data. In the case of an NDArray which is not writable, the effect of making changes to the returned array is undefined; in particular it may result in an exception.

Will only be called if canMap returns true, and only after an open call and before any close call.

Specified by:
getMapped in interface ArrayImpl

close

public void close()
           throws IOException
Description copied from interface: ArrayImpl
Shuts down this ArrayImpl for pixel access. This method will be called no more than once. No calls to getAccess, getMapped or open will be made after it is called. If the user makes proper use of the NDArray classes, it will be called after any AccessImpl objects and references to the mapped array are no longer required. If the user misbehaves however it may not get called at all, so an effort should be made to realease non-memory resources and flush buffers where appropriate in the finalizer.

Specified by:
close in interface ArrayImpl
Throws:
IOException - if there is an IO error

getShape

public OrderedNDShape getShape()
Description copied from interface: ArrayImpl
Returns an object representing the shape (origin and dimensions) and pixel sequence of this object. The return value must not change over the lifetime of the object.

Specified by:
getShape in interface ArrayImpl
Returns:
the ordered shape

getType

public Type getType()
Description copied from interface: ArrayImpl
Returns the primitive type of the data held by this object. The return value must not change over the lifetime of the object.

Specified by:
getType in interface ArrayImpl
Returns:
an object representing the type of data held.

getBadValue

public Number getBadValue()
Description copied from interface: ArrayImpl
The magic bad value for data. The returned type should be one of the primitive wrapper types, Byte, Short, Integer, Float, Double as appropriate for the type of this array. It may be null if there is no bad value. The return value must not change over the lifetime of the object.

Specified by:
getBadValue in interface ArrayImpl
Returns:
the bad value

isRandom

public boolean isRandom()
Description copied from interface: ArrayImpl
Indicates whether random access is possible. If this method returns true, then it is permissible to set the offset to a value lower than its current value. If it is false, then no such invocations will be attempted. The return value must not change over the lifetime of the object.

Specified by:
isRandom in interface ArrayImpl
Returns:
whether random access is available

isReadable

public boolean isReadable()
Description copied from interface: ArrayImpl
Indicates whether read access is possible. Reads will only be attempted if this method returns true. The return value must not change over the lifetime of the object.

Specified by:
isReadable in interface ArrayImpl
Returns:
whether read access is available

isWritable

public boolean isWritable()
Description copied from interface: ArrayImpl
Indicates whether write access is possible. Writes will only be attempted if this method returns true. The return value must not change over the lifetime of the object.

Specified by:
isWritable in interface ArrayImpl
Returns:
whether write access is available

multipleAccess

public boolean multipleAccess()
Description copied from interface: ArrayImpl
Indicates whether the getAccess method may be called more than once.

Specified by:
multipleAccess in interface ArrayImpl
Returns:
true if getAccess may be called more than once

getAccess

public AccessImpl getAccess()
Description copied from interface: ArrayImpl
Returns an object which can access the pixels of this ArrayImpl. Each call to this method returns a new and independent AccessImpl, with an offset initialised to 0 (the start of the array data).

This method will only be called after the sole call to open and before the sole call to close.

This method will only be called more than once if the multipleAccess method returns true.

It is the responsibility of the caller to close the returned AccessImpl when it is no longer required; this enables resources it may hold to be released.

Specified by:
getAccess in interface ArrayImpl
Returns:
an accessor for the pixel data


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