Re: Java netCDF inquiry address@hidden

We have a working, though incomplete java netcdf implementation.
We are working on the details of the data access interface.
We hope to have an alpha level release available soon, probabably
by the end of the month.

Documentation of what the proposed system is available at
http://www.unidata.ucar.edu/packages/netcdf/java.

The data access interface is changing, attached find the current thinking.

We would apprecicate feedback on this.

-glenn

Wed Oct 29 16:45:11 MST 1997

MultiArray and friends, a proposed interface.
--------------------------------------------

This document describes a set of interfaces to
abstract the idea of a multidimensional array
as presented by netcdf variables.


interface MultiArray
{
        /**
         * Returns the Class object representing the component
         * type of the array.
         * @see java.lang.Class#getComponentType
         */
        public Class
        getComponentType();

        /**
         * returns the number of dimension
         */
        int
        getRank();
                // ?? is rank the proper term?

        /**
         * Returns a new int array of length getRank().
         * The elements of the array are the lengths of the
         * corresponding dimensions.
         */
        int []
        getLengths();
                // ?? Better name might be getDimensionLengths?
                // getDimensions() is in use in the package, returns
                // container of Dimension objects.

        /**
         * Read Access functions.
         *
         * Get (read) the array element at index.
         * Length of index must equal rank of this.
         * Values of index components must be less than corresponding
         * values from getLengths().
         * @return Object value (or primitive for primitive functions)
         * at <code>index</code>
         */
        public Object
        get(int [] index);

        public boolean
        getBoolean(int [] index);

        public char
        getChar(int [] index);

        public byte
        getByte(int [] index);

        public short
        getShort(int [] index);

        public int
        getInt(int [] index);

        public long
        getLong(int [] index);

        public float
        getFloat(int [] index);

        public double
        getDouble(int [] index);

                // Names follow pattern of java.lang.reflect.Array
                // TODO: characterize possible exceptions.

        /**
         * Write Access functions.
         *
         * Set the array element at index to value. (write)
         * Length of index must equal rank of this.
         * Values of index components must be less than corresponding
         * values from getLengths().
         */
        public void set(int [] index, Object value)

        public void
        setBoolean(int [] index, boolean value)

        public void
        setChar(int [] index, char value)

        public void
        setByte(int [] index, byte value)

        public void
        setShort(int [] index, short value)

        public void
        setInt(int [] index, int value)

        public void
        setLong(int [] index, long value)

        public void
        setFloat(int [] index, float value)

        public void
        setDouble(int [] index, double value)

                // Names follow pattern of java.lang.reflect.Array
                //  Do we prefer setXXX name symmetry with getXXX() as
                //  java.lang.reflect.Array,
                //  or do we wish to use overloading on type of value argument,
                //  or both?
                // TODO: characterize possible exceptions.
}

###
Concrete Classes which derive from MultiArray
(netcdf Variables would be on this list as well.)

public class MultiArrayImpl extends MultiArray
{
/**
 * high performance, low memory waste, implementation in
 * local memory. Manages data storage as a private 1-d array
 * of componentType.
 */
    public
    MultiArrayImpl(Class theComponentType, int [] dimensions);

    public
    MultiArrayImpl(MultiArray ma);
}


public class ArrayMultiArray extends MultiArray
{
/**
 *  Adapts java arrays for use by the MultiArray interface.
 *  Storage is "external", provided by constructor.
 */
    /**
     * Provide a MultiArray given a java Object,
     * typically an array of primitive, or an array of array of primitive,
     * or ...
     * @param aro a multi-dimensional array of primitives.
     */
    public
    ArrayMultiArray(Object aro);
}


public class ScalarMultiArray extends MultiArray
{
/**
 * MultiArray implementation based on Object wrappers for primitives.
 * Rank of these is always zero
 */
    /**
     * Provide a ScalarMultiArray given a java Object,
     * typically a primitive class wrapper
     */
    public
    ScalarMultiArray(Object aro);
}

####

Special interface wrapper.

public class MultiArrayAdaptor implements MultiArray {
/**
 * This class stores a reference to a MultiArray
 * and an IndexMapping (described below).
 * The IndexMapping is used to provides a view of the referenced
 * MulitArray which is clipped, sliced, decimated or otherwise
 * transformed.

    protected
    MultiArrayAdaptor(MultiArray ma, IndexMapping im);
        // ?? public or protected
        // Do we allow clients to create IndexMapping's
        // or do we hide the details?
}


public interface IndexMapping {
    /**
     * Performs prescribed mapping from
     * domainElem to rangeElem.
     * rangeElem is modified on return.
     *
     * @return int [] rangeElem as modified.
     */
    public abstract int []
    map(int [] domainElem, int [] rangeElem); // TODO: throws

    /**
     * Given rank of the range, return rank of domain.
     */
    public abstract int
    rankInverseMap(int rangeRank);

    /**
     * Given the dimensions of the range, return dimensions of domain.
     */
    public abstract int []
    dimensionsInverseMap(int [] rangeDims, int [] domainDims);
}


public final class IndexMappingList implements IndexMapping
        // extends java.util.Collection
{
/**
 * Manages an ordered list of IndexMappings
 * (composition of functions) and presents
 * an IndexMapping interface.
}

Concrete IndexMappings:

        ClipIndexMapping
        SliceIndexMapping
        DecimateIndexMapping