ArrayImpl (Starlink-UK API)

All Known Implementing Classes:

ArrayArrayImpl, CombineArrayImpl, ConvertArrayImpl, DeterministicArrayImpl, MouldArrayImpl, NioArrayImpl, PixelMapArrayImpl, WindowArrayImpl, WrapperArrayImpl
```
public interface ArrayImpl
```
Interface for implementation end of the NDArray Bridge pattern. If you have an ArrayImpl, you can make an NDArray out of it using BridgeNDArray. This is the basic interface via which array implementations provide services to the BridgeNDArray class. The BridgeNDArray class is intended to be the only client of ArrayImpl instances, and it does the necessary validation of arguments before passing them to ArrayImpl, so that implementations of this interface can in general assume that the arguments they receive make sense. Thus it is not necessary for an ArrayImpl implementation to check that it is writable before attempting a write, or that a requested offset is within the known bounds of the array.
BridgeNDArray also makes guarantees about the order in which calls will be made:
- There will be a maximum of one call to open(); it will not happen after a call to close
- There will be a maximum of one call to close()
- Certain methods (canMap(), getMapped(), getAccess()) will only be made following an open call and before any close call
- getAccess() will not be called more than once if multipleAccess() returns false
This means that the open method may be used to do any expensive setup which may be required by getAccess, canMap or getMapped. The close method should be used for corresponding tear-down and/or tidying up of resources allocated at construction time; however it cannot be guaranteed that a careless user will cause close to be invoked, so a responsible ArrayImpl implementation may wish to do such essential tear-down in the finalizer as well as in close (But note: don't just do it in the finalizer, since the finalizer may never be invoked either).
Author:

Mark Taylor (Starlink)

See Also:

NDArray, BridgeNDArray

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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.

- Method Detail
  - getShape
```
OrderedNDShape getShape()
```
    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.
    
    Returns:
    
    the ordered shape
  - getType
```
Type getType()
```
    Returns the primitive type of the data held by this object. The return value must not change over the lifetime of the object.
    
    Returns:
    
    an object representing the type of data held.
  - getBadValue
```
Number getBadValue()
```
    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.
    
    Returns:
    
    the bad value
  - isReadable
```
boolean isReadable()
```
    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.
    
    Returns:
    
    whether read access is available
  - isWritable
```
boolean isWritable()
```
    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.
    
    Returns:
    
    whether write access is available
  - isRandom
```
boolean isRandom()
```
    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.
    
    Returns:
    
    whether random access is available
  - multipleAccess
```
boolean multipleAccess()
```
    Indicates whether the getAccess method may be called more than once.
    
    Returns:
    
    true if getAccess may be called more than once
  - open
```
void open()
   throws IOException
```
    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.
    
    Throws:
    
    IOException - if there is an IO error
  - canMap
```
boolean canMap()
```
    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.
  - getMapped
```
Object getMapped()
```
    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.
  - getAccess
```
AccessImpl getAccess()
              throws IOException
```
    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.
    
    Returns:
    
    an accessor for the pixel data
    
    Throws:
    
    IOException - if there is an IO error
  - close
```
void close()
    throws IOException
```
    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.
    
    Throws:
    
    IOException - if there is an IO error

Interface ArrayImpl

Method Summary

Method Detail

getShape

getType

getBadValue

isReadable

isWritable

isRandom

multipleAccess

open

canMap

getMapped

getAccess

close