opendap.dap
Class DArray

java.lang.Object
  extended by opendap.dap.BaseType
      extended by opendap.dap.DVector
          extended by opendap.dap.DArray
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, ClientIO
Direct Known Subclasses:
asciiArray, SDArray, wwwArray

public class DArray
extends DVector
implements java.lang.Cloneable

This class is used to hold arrays of other OPeNDAP 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: OPeNDAP uses zero-based indexing.

Version:
$Revision: 23881 $
Author:
jehamby
See Also:
DGrid, DVector, BaseType, Serialized Form

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 appendDim(int size, java.lang.String name, boolean decodeName)
          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 OPeNDAP type name of the class instance as a String.
 int numDimensions()
          Returns the number of dimensions in this array.
 void printAsMapXML(java.io.PrintWriter pw, java.lang.String pad, boolean constrained)
           
 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 pw, java.lang.String space, boolean print_decl_p)
          Prints the value of the variable, with its declaration.
 void printXML(java.io.PrintWriter pw, java.lang.String pad, boolean constrained)
           
 void squeeze()
          Use this method to "squeeze" out all of the array dimensions whose size is equal to 1.
 
Methods inherited from class opendap.dap.DVector
addVariable, deserialize, externalize, getLength, getPrimitiveVector, setLength
 
Methods inherited from class opendap.dap.BaseType
addAttributeAlias, addAttributeContainer, appendAttribute, appendAttribute, appendAttributeContainer, checkSemantics, delAttribute, delAttribute, elementCount, elementCount, getAttribute, getAttribute, getAttributeNames, getAttributeTable, getClearName, getLongName, getName, getParent, hasAttributes, newPrimitiveVector, printAttributes, printAttributes, printAttributes, printAttributes, printDecl, printDecl, printDecl, printDecl, printDecl, printDecl, printDecl, printVal, printVal, printVal, printXML, printXML, printXML, printXML, setClearName, 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 OPeNDAP type name of the class instance as a String.

Overrides:
getTypeName in class DVector
Returns:
the OPeNDAP 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 OPeNDAP 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 pw,
                     java.lang.String space,
                     boolean print_decl_p)
Prints the value of the variable, with its declaration. This function is primarily intended for debugging OPeNDAP applications and text-based clients such as geturl.

Overrides:
printVal in class DVector
Parameters:
pw - 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,
                      java.lang.String name,
                      boolean decodeName)
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.

squeeze

public void squeeze()
Use this method to "squeeze" out all of the array dimensions whose size is equal to 1.
Many queries that contstrain Arrays return an Array that has dimensions whose size has been reduced to 1. In effect that the dimension no longer really exists, except as a notational convention for tracking the hyperslab that the array represents. Since many clients have difficulty handling n-dimensional arrays this method was added to allow the client to easily "squeeze" the "extra" dimensions out of the 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.


printXML

public void printXML(java.io.PrintWriter pw,
                     java.lang.String pad,
                     boolean constrained)
Overrides:
printXML in class BaseType
Parameters:
pw -
pad -
constrained -

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


printAsMapXML

public void printAsMapXML(java.io.PrintWriter pw,
                          java.lang.String pad,
                          boolean constrained)
Parameters:
pw -
pad -
constrained -

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.