## dods.dap
Class DGrid

    java.lang.Object
      dods.dap.BaseType
          dods.dap.DConstructor
              dods.dap.DGrid

All Implemented Interfaces:
  ClientIO, Cloneable

Direct Known Subclasses:
  SDGrid

public class DGrid
extends DConstructor
implements ClientIO

This class holds a `DArray` and a set of "Map" vectors. The Map vectors are one-dimensional arrays corresponding to each dimension of the central `Array`. Using this scheme, a `Grid` can represent, in a rectilinear array, data which is not in reality rectilinear. An example will help make this clear.

Assume that the following array contains measurements of some real quantity, conducted at nine different points in space: ``

     A = [ 1  2  3  4 ]
         [ 2  4  6  8 ]
         [ 3  6  9  12]

To locate this `Array` in the real world, we could note the location of one corner of the grid, and the grid spacing. This would allow us to calculate the location of any of the other points of the `Array`.

This approach will not work, however, unless the grid spacing is precisely regular. If the distance between Row 1 and Row 2 is not the same as the distance between Row 2 and Row 3, the scheme will break down. The solution is to equip the `Array` with two `Map` vectors that define the location of each row or column of the array: ``

           A = [ 1  2  3  4 ] Row = [ 0 ]
               [ 2  4  6  8 ]       [ 3 ]
               [ 3  6  9  12]       [ 8 ]

      Column = [ 0  2  8  27]

The real location of the point in the first row and column of the array is now exactly fixed at (0,0), and the point in the last row and last column is at (8,27).

See Also:
  `BaseType`, `DArray`

Nested Class Summary
`(package private) class` `DGrid.EnumerateDGrid` Private class for implemantation of the Enumeration.

Field Summary
`static int` `ARRAY` The `Array` part of the `DGrid`
`protected DArray` `arrayVar` The Array component of this `DGrid`.
`static int` `MAPS` The Map part of the `DGrid`
`protected Vector` `mapVars` The Map component of this `DGrid`.

Constructor Summary
`DGrid()` Constructs a new `DGrid`.
`DGrid(String n)` Constructs a new `DGrid` with name `n`.

Method Summary
`void` `addVariable(BaseType v, int part)` Adds a variable to the container.
`void` `checkSemantics(boolean all)` Checks for internal consistency.
`Object` `clone()` Returns a clone of this `DGrid`.
`void` `deserialize(DataInputStream source, ServerVersion sv, StatusUI statusUI)` Reads data from a `DataInputStream`.
`int` `elementCount(boolean leaves)` Returns the number of variables contained in this object.
`void` `externalize(DataOutputStream sink)` Writes data to a `DataOutputStream`.
`String` `getTypeName()` Returns the DODS type name of the class instance as a `String`.
`BaseType` `getVar(int index)` Gets the indexed variable.
`BaseType` `getVariable(String name)` Returns the named variable.
`Enumeration` `getVariables()` Return an Enumeration that can be used to iterate over the members of a Structure.
`void` `printDecl(PrintWriter os, String space, boolean print_semi, boolean constrained)` Write the variable's declaration in a C-style syntax.
`void` `printVal(PrintWriter os, String space, boolean print_decl_p)` Prints the value of the variable, with its declaration.

Methods inherited from class dods.dap.DConstructor
`addVariable`

Methods inherited from class dods.dap.BaseType
`checkSemantics, 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`

Field Detail

### ARRAY

    public static final int ARRAY

  The `Array` part of the `DGrid`

  See Also:
    Constant Field Values

### MAPS

    public static final int MAPS

  The Map part of the `DGrid`

  See Also:
    Constant Field Values

### arrayVar

    protected DArray arrayVar

  The Array component of this `DGrid`.

### mapVars

    protected Vector mapVars

  The Map component of this `DGrid`.

Constructor Detail

### DGrid

    public DGrid()

  Constructs a new `DGrid`.

### DGrid

    public DGrid(String n)

  Constructs a new `DGrid` with name `n`.

Parameters:
  `n` - the name of the variable.

Method Detail

### clone

    public Object clone()

  Returns a clone of this `DGrid`. A deep copy is performed on all data inside the variable.

  Overrides:
    `clone` in class `BaseType`
  Returns:
    a clone of this `DGrid`.

### getTypeName

    public String getTypeName()

  Returns the DODS type name of the class instance as a `String`.

  Specified by:
    `getTypeName` in class `BaseType`
  Returns:
    the DODS type name of the class instance as a `String`.

### elementCount

    public int elementCount(boolean leaves)

  Returns the number of variables contained in this object. For simple and vector type variables, it always returns 1. To count the number of simple-type variable in the variable tree rooted at this variable, set `leaves` to `true`.

  Overrides:
    `elementCount` in class `BaseType`
  Parameters:
    `leaves` - If true, count all the simple types in the `tree' of variables rooted at this variable.
  Returns:
    the number of contained variables.

### addVariable

    public void addVariable(BaseType v,
                            int part)

  Adds a variable to the container.

  Specified by:
    `addVariable` in class `DConstructor`
  Parameters:
    `v` - the variable to add.
    `part` - the part of the `DGrid` to be modified. Allowed values are `ARRAY` or `MAPS`.
  Throws:
    `IllegalArgumentException` - if an invalid part was given.

### getVariable

    public BaseType getVariable(String name)
                         throws NoSuchVariableException

  Returns the named variable.

  Specified by:
    `getVariable` in class `DConstructor`
  Parameters:
    `name` - the name of the variable.
  Returns:
    the named variable.
  Throws:
    `NoSuchVariableException` - if the named variable does not exist in this container.

### getVar

    public BaseType getVar(int index)
                    throws NoSuchVariableException

  Gets the indexed variable. For a DGrid the index 0 returns the `DArray` and indexes 1 and higher return the associated map `Vector`s.

  Specified by:
    `getVar` in class `DConstructor`
  Parameters:
    `index` - the index of the variable in the `Vector` Vars.
  Returns:
    the indexed variable.
  Throws:
    `NoSuchVariableException` - if the named variable does not exist in this container.

### getVariables

    public Enumeration getVariables()

  Return an Enumeration that can be used to iterate over the members of a Structure. This implementation provides access to the elements of the Structure. Each Object returned by the Enumeration can be cast to a BaseType.

  Specified by:
    `getVariables` in class `DConstructor`
  Returns:
    An Enumeration

### checkSemantics

    public void checkSemantics(boolean all)
                        throws BadSemanticsException

  Checks for internal consistency. For `DGrid`, verify that the map variables have unique names and match the number of dimensions of the array variable.

  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(PrintWriter os,
                          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 `BaseType`
  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(PrintWriter os,
                         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.

  Specified by:
    `printVal` in class `BaseType`
  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)`

### deserialize

    public void deserialize(DataInputStream source,
                            ServerVersion sv,
                            StatusUI statusUI)
                     throws IOException,
                            DataReadException

  Reads data from a `DataInputStream`. This method is only used on the client side of the DODS client/server connection.

  Specified by:
    `deserialize` in interface `ClientIO`
  Parameters:
    `source` - a `DataInputStream` to read from.
    `sv` - the `ServerVersion` returned by the server.
    `statusUI` - the `StatusUI` object to use for GUI updates and user cancellation notification (may be null).
  Throws:
    `EOFException` - if EOF is found before the variable is completely deserialized.
    `IOException` - thrown on any other InputStream exception.
    `DataReadException` - if an unexpected value was read.
  See Also:
    `ClientIO.deserialize(DataInputStream, ServerVersion, StatusUI)`

### externalize

    public void externalize(DataOutputStream sink)
                     throws IOException

  Writes data to a `DataOutputStream`. This method is used primarily by GUI clients which need to download DODS data, manipulate it, and then re-save it as a binary file.

  Specified by:
    `externalize` in interface `ClientIO`
  Parameters:
    `sink` - a `DataOutputStream` to write to.
  Throws:
    `IOException` - thrown on any `OutputStream` exception.