ucar.multiarray
Interface Accessor

All Known Subinterfaces:
MultiArray, RemoteAccessor
All Known Implementing Classes:
AbstractAccessor, ArrayMultiArray, MultiArrayImpl, MultiArrayProxy, RemoteAccessorImpl, ScalarMultiArray, StringCharAdapter, Variable

public interface Accessor

Interface for multidimensional array data access. Given an index (array of integers), get or set the value at index.

Netcdf Variables implement this, but more general objects, such as java arrays, can be simply wrapped to provide this interface.

For lack of a better model, we use use naming conventions from java.lang.reflect.Array. In particular, we name the primitive specific "set" functions by type, rather than using overloading. This is symmetric with the "get" operations.

The primitive specific get and set methods are useful only if the the componentType is primitive (like java.lang.Double.TYPE).

Like java.lang.reflect.Array, classes that implement this interface should permit widening conversions to occur during a get or set operation, and throw IllegalArgumentException otherwise. Classes which implement this interface may be more lenient, however, only throwing the exception for narrowing conversions if the unconverted value is out of range for the target type. Implementations may throw UnsupportedOperationException, IllegalArgumentException, or ? for conversions to primitive which don't make sense.

The implementations may be file based or remote, so the methods throw java.io.IOException.

See Also:
AbstractAccessor, MultiArray, RemoteAccessor

Method Summary
 void copyin(int[] origin, MultiArray source)
          Aggregate write access.
 MultiArray copyout(int[] origin, int[] shape)
          Aggregate read access.
 java.lang.Object get(int[] index)
          Get (read) the array element at index.
 boolean getBoolean(int[] index)
          Get the array element at index, as a boolean.
 byte getByte(int[] index)
          Get the array element at index, as a byte.
 char getChar(int[] index)
          Get the array element at index, as a char.
 double getDouble(int[] index)
          Get the array element at index, as a double.
 float getFloat(int[] index)
          Get the array element at index, as a float.
 int getInt(int[] index)
          Get the array element at index, as an int.
 long getLong(int[] index)
          Get the array element at index, as a long.
 short getShort(int[] index)
          Get the array element at index, as a short.
 void set(int[] index, java.lang.Object value)
          Set (modify, write) the array element at index to the specified value.
 void setBoolean(int[] index, boolean value)
          Set the array element at index to the specified boolean value.
 void setByte(int[] index, byte value)
          Set the array element at index to the specified byte value.
 void setChar(int[] index, char value)
          Set the array element at index to the specified char value.
 void setDouble(int[] index, double value)
          Set the array element at index to the specified double value.
 void setFloat(int[] index, float value)
          Set the array element at index to the specified float value.
 void setInt(int[] index, int value)
          Set the array element at index to the specified int value.
 void setLong(int[] index, long value)
          Set the array element at index to the specified long value.
 void setShort(int[] index, short value)
          Set the array element at index to the specified short value.
 java.lang.Object toArray()
          Returns a new array containing all of the elements in this MultiArray.
 java.lang.Object toArray(java.lang.Object anArray, int[] origin, int[] shape)
          Returns an array containing elements of this MultiArray specified by origin and shape, possibly converting the component type.
 

Method Detail

get

java.lang.Object get(int[] index)
                     throws java.io.IOException
Get (read) the array element at index. The returned value is wrapped in an object if it has a primitive type. Length of index must be greater than or equal to the rank of this. Values of index components must be less than corresponding values from getLengths().

Parameters:
index - MultiArray index
Returns:
Object value at index
Throws:
java.lang.NullPointerException - If the argument is null.
java.lang.IllegalArgumentException - If the array length of index is too small
java.lang.ArrayIndexOutOfBoundsException - If an index component argument is negative, or if it is greater than or equal to the corresponding dimension length.
java.io.IOException

getBoolean

boolean getBoolean(int[] index)
                   throws java.io.IOException
Get the array element at index, as a boolean.

Throws:
java.io.IOException
See Also:
get(int[])

getChar

char getChar(int[] index)
             throws java.io.IOException
Get the array element at index, as a char.

Throws:
java.io.IOException
See Also:
get(int[])

getByte

byte getByte(int[] index)
             throws java.io.IOException
Get the array element at index, as a byte.

Throws:
java.io.IOException
See Also:
get(int[])

getShort

short getShort(int[] index)
               throws java.io.IOException
Get the array element at index, as a short.

Throws:
java.io.IOException
See Also:
get(int[])

getInt

int getInt(int[] index)
           throws java.io.IOException
Get the array element at index, as an int.

Throws:
java.io.IOException
See Also:
get(int[])

getLong

long getLong(int[] index)
             throws java.io.IOException
Get the array element at index, as a long.

Throws:
java.io.IOException
See Also:
get(int[])

getFloat

float getFloat(int[] index)
               throws java.io.IOException
Get the array element at index, as a float.

Throws:
java.io.IOException
See Also:
get(int[])

getDouble

double getDouble(int[] index)
                 throws java.io.IOException
Get the array element at index, as a double.

Throws:
java.io.IOException
See Also:
get(int[])

set

void set(int[] index,
         java.lang.Object value)
         throws java.io.IOException
Set (modify, write) the array element at index to the specified value. If the array has a primitive component type, the value may be unwrapped. Values of index components must be less than corresponding values from getLengths().

Parameters:
index - MultiArray index
value - the new value.
Throws:
java.lang.NullPointerException - If the index argument is null, or if the array has a primitive component type and the value argument is null
java.lang.IllegalArgumentException - If the array length of index is too small
java.lang.ArrayIndexOutOfBoundsException - If an index component argument is negative, or if it is greater than or equal to the corresponding dimension length.
java.io.IOException

setBoolean

void setBoolean(int[] index,
                boolean value)
                throws java.io.IOException
Set the array element at index to the specified boolean value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setChar

void setChar(int[] index,
             char value)
             throws java.io.IOException
Set the array element at index to the specified char value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setByte

void setByte(int[] index,
             byte value)
             throws java.io.IOException
Set the array element at index to the specified byte value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setShort

void setShort(int[] index,
              short value)
              throws java.io.IOException
Set the array element at index to the specified short value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setInt

void setInt(int[] index,
            int value)
            throws java.io.IOException
Set the array element at index to the specified int value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setLong

void setLong(int[] index,
             long value)
             throws java.io.IOException
Set the array element at index to the specified long value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setFloat

void setFloat(int[] index,
              float value)
              throws java.io.IOException
Set the array element at index to the specified float value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

setDouble

void setDouble(int[] index,
               double value)
               throws java.io.IOException
Set the array element at index to the specified double value.

Throws:
java.io.IOException
See Also:
set(int[], java.lang.Object)

copyout

MultiArray copyout(int[] origin,
                   int[] shape)
                   throws java.io.IOException
Aggregate read access. Return a new MultiArray of the same componentType as this, and with shape as specified, which is initialized to the values of this, as clipped to (origin, origin + shape).

It is easier to implement than to specify :-).

The main reason to implement this instead of using the equivalent proxy is for remote or file access.

assert(origin[ii] + shape[ii] <= lengths[ii]);

Parameters:
origin - int array specifying the starting index.
shape - int array specifying the extents in each dimension. This becomes the shape of the return.
Returns:
the MultiArray with the specified shape
Throws:
java.io.IOException

copyin

void copyin(int[] origin,
            MultiArray source)
            throws java.io.IOException
Aggregate write access. Given a MultiArray, copy it into this at the specified starting index. TODO: clearer specification.

Hopefully this member can be optimized in various situations.

assert(origin[ii] + (source.getLengths())[ii] <= (getLengths())[ii]);

Parameters:
origin - int array specifying the starting index.
source - MultiArray with the same componentType as this and shape smaller than this.getLengths() - origin
Throws:
java.io.IOException

toArray

java.lang.Object toArray()
                         throws java.io.IOException
Returns a new array containing all of the elements in this MultiArray. The returned array is one dimensional. The order of the elements in the result is natural, as if we used an IndexIterator to step through the elements of this MultiArray. The component type of the result is the same as this.

This method acts as bridge between array-based and MultiArray-based APIs.

This method is functionally equivalent to

                Object anArray = Array.newInstance(getComponentType(), 1);
                int [] origin = new int[getRank()]
                int [] shape = getDimensions();
                return toArray(anArray, origin, shape);
 

Returns:
a one dimensional Array containing all the elements in this MultiArray
Throws:
java.io.IOException

toArray

java.lang.Object toArray(java.lang.Object anArray,
                         int[] origin,
                         int[] shape)
                         throws java.io.IOException
Returns an array containing elements of this MultiArray specified by origin and shape, possibly converting the component type. The returned array is one dimensional. The order of the elements in the result is natural, as if we used an IndexIterator to step through the elements of this MultiArray.

The anArray argument should be an array. If it is large enough to contain the output, it is used and no new storage is allocated. Otherwise, new storage is allocated with the same component type as the argument, and the data is copied into it.

This method acts as bridge between array-based and MultiArray-based APIs.

This method is similar to copyout(origin, shape).toArray(), but avoids a copy operation and (potentially) an allocation.

NOTE: Implementation of type conversion is deferred until JDK 1.2. Currently, the componentType of anArray must be the same as this

Returns:
a one dimensional Array containing the specified elements
Throws:
java.io.IOException