DefaultArrayAccess (Starjava ARRAY API)

java.lang.Object
- uk.ac.starlink.array.DefaultArrayDescription
- - uk.ac.starlink.array.DefaultArrayAccess

All Implemented Interfaces:

ArrayAccess, ArrayDescription
```
public class DefaultArrayAccess
extends DefaultArrayDescription
implements ArrayAccess
```
Default implementation of the ArrayAccess interface, based on an AccessImpl. The underlying AccessImpl must be private to this object, and not used by any other clients during the lifetime of this object.
Exemplifies the Bridge Pattern.

Author:

Mark Taylor (Starlink)

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
`DefaultArrayAccess(ArrayDescription adesc, AccessImpl impl, java.lang.Object mappedArray)` Constructs an ArrayAccess object from a description of the array's characteristics and a basic implementation of pixel access functionality.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`checkOpen()`
`void`	`close()` Shuts down this accessor for further data access.
`protected void`	`doClose()`
`java.lang.Object`	`getMapped()` Returns a single primitive array holding all the data of this array.
`long`	`getOffset()` Returns the current offset into the array for read/write.
`long[]`	`getPosition()` Returns the coordinates at which the next read/write will occur.
`boolean`	`isMapped()` Indicates whether mapped access is available.
`void`	`read(java.lang.Object buffer, int start, int size)` Reads a number of pixels from the current offset into a specified part of a supplied primitive array.
`void`	`readTile(java.lang.Object buffer, NDShape tile)` Reads a tile of pixels into a supplied primitive array.
`void`	`setOffset(long off)` Sets the offset into the array for the next read/write to occur.
`void`	`setPosition(long[] pos)` Sets the coordinates for the next read/write to occur.
`java.lang.String`	`toString()`
`void`	`write(java.lang.Object buffer, int start, int size)` Writes a number of pixels starting at the current offset from a specified part of a supplied primitive array.
`void`	`writeTile(java.lang.Object buffer, NDShape tile)` Writes a tile of pixels from a supplied primitive array.

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
  - DefaultArrayAccess
```
public DefaultArrayAccess(ArrayDescription adesc,
                          AccessImpl impl,
                          java.lang.Object mappedArray)
```
    Constructs an ArrayAccess object from a description of the array's characteristics and a basic implementation of pixel access functionality.
    
    Parameters:
    
    adesc - array characteristics description
    
    impl - array access service provider, available for exclusive use by this object
    
    mappedArray - a java primitve array containing all the pixel data of the accessed array. May be null if mapped access is not provided
- Method Detail
  - getOffset
```
public long getOffset()
```
    Description copied from interface: ArrayAccess
    
    Returns the current offset into the array for read/write.
    
    Specified by:
    
    getOffset in interface ArrayAccess
    
    Returns:
    
    the index of the next element to be read/written
  - setOffset
```
public void setOffset(long off)
               throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Sets the offset into the array for the next read/write to occur. Attempting to set the offset to a lower value than its current one will fail if random access is not available (isRandom is false).
    
    Specified by:
    
    setOffset in interface ArrayAccess
    
    Parameters:
    
    off - the position at which the next read/write will start
    
    Throws:
    
    java.io.IOException - if some unexpected I/O error occurs
  - getPosition
```
public long[] getPosition()
```
    Description copied from interface: ArrayAccess
    
    Returns the coordinates at which the next read/write will occur.
    
    Specified by:
    
    getPosition in interface ArrayAccess
    
    Returns:
    
    an N-element array giving the coordinates of the next read/write
  - setPosition
```
public void setPosition(long[] pos)
                 throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Sets the coordinates for the next read/write to occur. Attempting to set the coordinates so that the new offset corresponds to a lower value than its current one will fail if random access is not available (isRandom returns false).
    
    Specified by:
    
    setPosition in interface ArrayAccess
    
    Parameters:
    
    pos - an N-element array giving the coordinates for the next read/write
    
    Throws:
    
    java.io.IOException - if some unexpected I/O error occurs
  - read
```
public void read(java.lang.Object buffer,
                 int start,
                 int size)
          throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Reads a number of pixels from the current offset into a specified part of a supplied primitive array. The current offset will be updated accordingly (to the point after the read pixels).
    An IOException during the read will have the effect of closing this accessor for further access.
    
    Specified by:
    
    read in interface ArrayAccess
    
    Parameters:
    
    buffer - an array of the appropriate primitive type for this accessor into whose elements start..start+size the next size pixels will be read
    
    start - the starting offset into buffer into which the pixels should be read
    
    size - the number of pixels to read (also the amount by which the current offset will be incremented)
    
    Throws:
    
    java.io.IOException - if there is an I/O error
  - readTile
```
public void readTile(java.lang.Object buffer,
                     NDShape tile)
              throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Reads a tile of pixels into a supplied primitive array. A tile is an N-dimensional hypercuboid specified by an NDShape object. The pixels are read into a given array in the order implied by the ordering scheme of this object. The specified tile must have the same dimensionality as this accessor, but need not lie wholly or partially within its bounds -- pixels outside the intersection will be given the bad value.
    The current offset will be updated to the point after the last pixel in the intersection between the tile and this accessor.
    It is possible to read a tile when random access is not available, but only if the first pixel in the requested tile is ahead of the current offset.
    An IOException during the read will have the effect of closing this accessor for further access.
    
    Specified by:
    
    readTile in interface ArrayAccess
    
    Parameters:
    
    buffer - an array of the appropriate primitive type for this accessor and at least as long as the number of pixels in tileShape
    
    tile - an NDShape object specifying the shape of the tile to be read
    
    Throws:
    
    java.io.IOException - if there is an I/O error
  - write
```
public void write(java.lang.Object buffer,
                  int start,
                  int size)
           throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Writes a number of pixels starting at the current offset from a specified part of a supplied primitive array. The current offset will be updated accordingly (to the point after the last write).
    If an IOException occurs during the read, this will have the additional effect of closing this accessor for further access.
    
    Specified by:
    
    write in interface ArrayAccess
    
    Parameters:
    
    buffer - an array of the appropriate primitive type for this NDArray whose elements start..start+size will be written out
    
    start - the starting point in buffer from which pixels will be written
    
    size - the number of pixels to write (also the amount by which the current offset will be incremented)
    
    Throws:
    
    java.io.IOException - if there is an I/O error
  - writeTile
```
public void writeTile(java.lang.Object buffer,
                      NDShape tile)
               throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Writes a tile of pixels from a supplied primitive array. A tile is an N-dimensional hypercuboid specified by an NDShape object. The ordering of pixels in the array is implied by the ordering scheme of this object. The specified tile must have the same dimensionality as this accessor, but need not lie wholly or partially within its bounds -- pixels outside the intersection will simply be ignored.
    The current offset will be updated to the point after the last pixel in the intersection between the tile and this accessor.
    It is possible to read a tile when random access is not available, but only if the first pixel in the requested tile is ahead of the current offset.
    If an IOException occurs during the write, this will have the additional effect of closing this accessor for further access.
    
    Specified by:
    
    writeTile in interface ArrayAccess
    
    Parameters:
    
    buffer - an array of the appropriate primitive type for this NDArray and at least as long as the number of pixels in tileShape (elements after this limit will be ignored)
    
    tile - an NDShape object specifying the shape of the tile to be written
    
    Throws:
    
    java.io.IOException - if there is an I/O error
  - isMapped
```
public boolean isMapped()
```
    Description copied from interface: ArrayAccess
    
    Indicates whether mapped access is available. If true, the getMapped method will return a reference to the java primitive array containing all the pixels of this NDArray. The return value must not change over the lifetime of this object.
    
    Specified by:
    
    isMapped in interface ArrayAccess
    
    Returns:
    
    true if mapped access is possible
  - getMapped
```
public java.lang.Object getMapped()
```
    Description copied from interface: ArrayAccess
    
    Returns a single primitive array holding all the data of this array. Calling this method does not do significant work, but returns a reference to an existing mapped array. Access to the array data using this method, if available, will be more efficient than by using the read/write methods. 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 accessor which is not writable, the effect of making changes to the returned array is undefined; in particular it may result in an exception.
    The method will fail unless isMapped returns true.
    
    Specified by:
    
    getMapped in interface ArrayAccess
    
    Returns:
    
    a primitive array, of type implied by the Type of this object, containing all the pixels of this array, in its natural ordering
  - close
```
public void close()
           throws java.io.IOException
```
    Description copied from interface: ArrayAccess
    
    Shuts down this accessor for further data access. Following a call to close the offset will have an illegal value and calls to any read, write or position setting methods will fail with an IllegalStateException. A close should always be called on an ArrayAccess when it is finished with. In the case of a readable object it enables release of associated resources beyond those taken care of by the garbage collector, and in the case of writable object it may also be required to ensure that data is actually flushed to the underlying data storage. This method may harmlessly be called on an accessor which has already been closed.
    
    Specified by:
    
    close in interface ArrayAccess
    
    Throws:
    
    java.io.IOException - if there is an I/O error
  - doClose
```
protected void doClose()
```
  - checkOpen
```
protected void checkOpen()
```
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class DefaultArrayAccess

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultArrayAccess

Method Detail

getOffset

setOffset

getPosition

setPosition

read

readTile

write

writeTile

isMapped

getMapped

close

doClose

checkOpen

toString