dods.dap
Class DArray

java.lang.Object
  extended by dods.dap.BaseType
      extended by dods.dap.DVector
          extended by dods.dap.DArray
All Implemented Interfaces:
ClientIO, java.lang.Cloneable
Direct Known Subclasses:
SDArray

public class DArray
extends DVector
implements java.lang.Cloneable

This class is used to hold arrays of other DODS data. The elements of the array can be simple or compound data types. There is no limit on the number of dimensions an array can have, or on the size of each dimension.

If desired, the user can give each dimension of an array a name. You can, for example, have a 360x180 array of temperatures, covering the whole globe with one-degree squares. In this case, you could name the first dimension "Longitude" and the second dimension "Latitude". This can help prevent a great deal of confusion.

The DArray is used as part of the DGrid class, where the dimension names are crucial to its structure. The dimension names correspond to "Map" vectors, holding the actual values for that column of the array.

Each array dimension carries with it its own projection information. The projection inforamtion takes the form of three integers: the start, stop, and stride values. This is clearest with an example. Consider a one-dimensional array 10 elements long. If the start value of the dimension constraint is 3, then the constrained array appears to be seven elements long. If the stop value is changed to 7, then the array appears to be five elements long. If the stride is changed to two, the array will appear to be 3 elements long. Array constraints are written as [start:stride:stop].

 A = [1 2 3 4 5 6 7 8 9 10]
 A[3::] = [4 5 6 7 8 9 10]
 A[3::7] = [4 5 6 7 8]
 A[3:2:7] = [4 6 8]
 A[0:3:9] = [1 4 7 10]
 
NB: DODS uses zero-based indexing.

See Also:
DGrid, DVector, BaseType

Constructor Summary
DArray()
          Constructs a new DArray.
DArray(java.lang.String n)
          Constructs a new DArray with name n.
 
Method Summary
 void appendDim(int size)
          Add a dimension to the array.
 void appendDim(int size, java.lang.String name)
          Given a size and a name, this function adds a dimension to the array.
 void checkSemantics(boolean all)
          Checks for internal consistency.
 java.lang.Object clone()
          Returns a clone of this DArray.
 DArrayDimension getDimension(int dimension)
          Returns the DArrayDimension object for the dimension requested.
 java.util.Enumeration getDimensions()
          Returns an Enumeration of DArrayDimensions in this array.
 DArrayDimension getFirstDimension()
          Returns the DArrayDimension object for the first dimension.
 java.lang.String getTypeName()
          Returns the DODS type name of the class instance as a String.
 int numDimensions()
          Returns the number of dimensions in this array.
 void printDecl(java.io.PrintWriter os, java.lang.String space, boolean print_semi, boolean constrained)
          Write the variable's declaration in a C-style syntax.
 void printVal(java.io.PrintWriter os, java.lang.String space, boolean print_decl_p)
          Prints the value of the variable, with its declaration.
 
Methods inherited from class dods.dap.DVector
addVariable, deserialize, externalize, getLength, getPrimitiveVector, setLength
 
Methods inherited from class dods.dap.BaseType
checkSemantics, elementCount, elementCount, getLongName, getName, getParent, newPrimitiveVector, printDecl, printDecl, printDecl, printDecl, printDecl, printDecl, printDecl, printVal, printVal, printVal, setName, setParent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DArray

public DArray()
Constructs a new DArray.


DArray

public DArray(java.lang.String n)
Constructs a new DArray with name n.

Parameters:
n - the name of the variable.
Method Detail

clone

public java.lang.Object clone()
Returns a clone of this DArray. A deep copy is performed on all data inside the variable.

Overrides:
clone in class DVector
Returns:
a clone of this DArray.

getTypeName

public java.lang.String getTypeName()
Returns the DODS type name of the class instance as a String.

Overrides:
getTypeName in class DVector
Returns:
the DODS type name of the class instance as a String.

checkSemantics

public void checkSemantics(boolean all)
                    throws BadSemanticsException
Checks for internal consistency. For DArray, verify that the dimension vector is not empty.

Overrides:
checkSemantics in class BaseType
Parameters:
all - for complex constructor types, this flag indicates whether to check the semantics of the member variables, too.
Throws:
BadSemanticsException - if semantics are bad, explains why.
See Also:
BaseType.checkSemantics(boolean)

printDecl

public void printDecl(java.io.PrintWriter os,
                      java.lang.String space,
                      boolean print_semi,
                      boolean constrained)
Write the variable's declaration in a C-style syntax. This function is used to create textual representation of the Data Descriptor Structure (DDS). See The DODS User Manual for information about this structure.

Overrides:
printDecl in class DVector
Parameters:
os - The PrintWriter on which to print the declaration.
space - Each line of the declaration will begin with the characters in this string. Usually used for leading spaces.
print_semi - a boolean value indicating whether to print a semicolon at the end of the declaration.
constrained - a boolean value indicating whether to print the declartion dependent on the projection information. This is only used by Server side code.
See Also:
BaseType.printDecl(PrintWriter, String, boolean)

printVal

public void printVal(java.io.PrintWriter os,
                     java.lang.String space,
                     boolean print_decl_p)
Prints the value of the variable, with its declaration. This function is primarily intended for debugging DODS applications and text-based clients such as geturl.

Overrides:
printVal in class DVector
Parameters:
os - the PrintWriter on which to print the value.
space - this value is passed to the printDecl method, and controls the leading spaces of the output.
print_decl_p - a boolean value controlling whether the variable declaration is printed as well as the value.
See Also:
BaseType.printVal(PrintWriter, String, boolean)

appendDim

public void appendDim(int size,
                      java.lang.String name)
Given a size and a name, this function adds a dimension to the array. For example, if the DArray is already 10 elements long, calling appendDim with a size of 5 will transform the array into a 10x5 matrix. Calling it again with a size of 2 will create a 10x5x2 array, and so on.

Parameters:
size - the size of the desired new dimension.
name - the name of the new dimension.

appendDim

public void appendDim(int size)
Add a dimension to the array. Same as appendDim(size, null).

Parameters:
size - the size of the desired new dimension.
See Also:
appendDim(int, String)

getDimensions

public final java.util.Enumeration getDimensions()
Returns an Enumeration of DArrayDimensions in this array.

Returns:
an Enumeration of DArrayDimensions in this array.

numDimensions

public final int numDimensions()
Returns the number of dimensions in this array.

Returns:
the number of dimensions in this array.

getDimension

public DArrayDimension getDimension(int dimension)
                             throws InvalidParameterException
Returns the DArrayDimension object for the dimension requested. It makes sure that the dimension requested exists.

Throws:
InvalidParameterException

getFirstDimension

public DArrayDimension getFirstDimension()
Returns the DArrayDimension object for the first dimension.