## dods.dap
Class DDS

    java.lang.Object
      dods.dap.DDS

All Implemented Interfaces:
  Cloneable

Direct Known Subclasses:
  DataDDS, ServerDDS

public class DDS
extends Object
implements Cloneable

The DODS Data Descriptor Object (DDS) is a data structure used by the DODS software to describe datasets and subsets of those datasets. The DDS may be thought of as the declarations for the data structures that will hold data requested by some DODS client. Part of the job of a DODS server is to build a suitable DDS for a specific dataset and to send it to the client. Depending on the data access API in use, this may involve reading part of the dataset and inferring the DDS. Other APIs may require the server simply to read some ancillary data file with the DDS in it.

On the server side, in addition to the data declarations, the DDS holds the clauses of any constraint expression that may have accompanied the data request from the DODS client. The DDS object includes methods for modifying the DDS according to the given constraint expression. It also has methods for directly modifying a DDS, and for transmitting it from a server to a client.

For the client, the DDS object includes methods for reading the persistent form of the object sent from a server. This includes parsing the ASCII representation of the object and, possibly, reading data received from a server into a data object.

Note that the class DDS is used to instantiate both DDS and DataDDS objects. A DDS that is empty (contains no actual data) is used by servers to send structural information to the client. The same DDS can becomes a DataDDS when data values are bound to the variables it defines.

For a complete description of the DDS layout and protocol, please refer to The DODS User Guide.

The DDS has an ASCII representation, which is what is transmitted from a DODS server to a client. Here is the DDS representation of an entire dataset containing a time series of worldwide grids of sea surface temperatures:

>       Dataset {
>           Float64 lat[lat = 180];
>           Float64 lon[lon = 360];
>           Float64 time[time = 404];
>           Grid {
>            ARRAY:
>               Int32 sst[time = 404][lat = 180][lon = 360];
>            MAPS:
>               Float64 time[time = 404];
>               Float64 lat[lat = 180];
>               Float64 lon[lon = 360];
>           } sst;
>       } weekly;

If the data request to this dataset includes a constraint expression, the corresponding DDS might be different. For example, if the request was only for northern hemisphere data at a specific time, the above DDS might be modified to appear like this:

>       Dataset {
>           Grid {
>            ARRAY:
>               Int32 sst[time = 1][lat = 90][lon = 360];
>            MAPS:
>               Float64 time[time = 1];
>               Float64 lat[lat = 90];
>               Float64 lon[lon = 360];
>           } sst;
>       } weekly;

Since the constraint has narrowed the area of interest, the range of latitude values has been halved, and there is only one time value in the returned array. Note that the simple arrays (lat, lon, and time) described in the dataset are also part of the sst Grid object. They can be requested by themselves or as part of that larger object.

See The DODS User Guide, or the documentation of the BaseType class for descriptions of the DODS data types.

See Also:
  `BaseType`, `BaseTypeFactory`, `DAS`

Field Summary
`protected String` `name` The dataset name.
`protected Vector` `vars` Variables at the top level.

Constructor Summary
`DDS()` Creates an empty `DDS`.
`DDS(BaseTypeFactory factory)` Creates an empty `DDS` with the given `BaseTypeFactory`.
`DDS(String n)` Creates an empty `DDS` with the given dataset name.
`DDS(String n, BaseTypeFactory factory)` Creates an empty `DDS` with the given dataset name and `BaseTypeFactory`.

Method Summary
`void` `addVariable(BaseType bt)` Adds a variable to the `DDS`.
`void` `checkSemantics()` Check the semantics of the `DDS`.
`void` `checkSemantics(boolean all)` Check the semantics of the `DDS`.
`Object` `clone()` Returns a clone of this `DDS`.
`void` `delVariable(String name)` Removes a variable from the `DDS`.
`BaseTypeFactory` `getFactory()` Get the Class factory.
`String` `getName()` Get the dataset's name.
`BaseType` `getVariable(String name)` Returns a reference to the named variable.
`Enumeration` `getVariables()` Returns an `Enumeration` of the dataset variables.
`int` `numVariables()` Returns the number of variables in the dataset.
`void` `parse(InputStream is)` Reads a `DDS` from the named `InputStream`.
`void` `print(OutputStream os)` Print the `DDS` on the given `OutputStream`.
`void` `print(PrintWriter os)` Print the `DDS` on the given `PrintWriter`.
`Stack` `search(String name, Stack compStack)` Look for `name` in the DDS.
`void` `setName(String name)` Set the dataset's name.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### name

    protected String name

  The dataset name.

### vars

    protected Vector vars

  Variables at the top level.

Constructor Detail

### DDS

    public DDS()

  Creates an empty `DDS`.

### DDS

    public DDS(String n)

  Creates an empty `DDS` with the given dataset name.

Parameters:
  `n` - the dataset name

### DDS

    public DDS(BaseTypeFactory factory)

  Creates an empty `DDS` with the given `BaseTypeFactory`. This will be used for DODS servers which need to construct subclasses of the various `BaseType` objects to hold additional server-side information.

Parameters:
  `factory` - the server `BaseTypeFactory` object.

### DDS

    public DDS(String n,
               BaseTypeFactory factory)

  Creates an empty `DDS` with the given dataset name and `BaseTypeFactory`. This will be used for DODS servers which need to construct subclasses of the various `BaseType` objects to hold additional server-side information.

Parameters:
  `n` - the dataset name
  `factory` - the server `BaseTypeFactory` object.

Method Detail

### clone

    public Object clone()

  Returns a clone of this `DDS`. A deep copy is performed on all variables inside the `DDS`.

  Returns:
    a clone of this `DDS`.

### getFactory

    public final BaseTypeFactory getFactory()

  Get the Class factory. This is the machine that builds classes for the internal representation of the data set.

  Returns:
    the BaseTypeFactory.

### getName

    public final String getName()

  Get the dataset's name. This is the name of the dataset itself, and is not to be confused with the name of the file or disk on which it is stored.

  Returns:
    the name of the dataset.

### setName

    public final void setName(String name)

  Set the dataset's name. This is the name of the dataset itself, and is not to be confused with the name of the file or disk on which it is stored.

  Parameters:
    `name` - the name of the dataset.

### addVariable

    public final void addVariable(BaseType bt)

  Adds a variable to the `DDS`.

  Parameters:
    `bt` - the new variable to add.

### delVariable

    public final void delVariable(String name)

  Removes a variable from the `DDS`. Does nothing if the variable can't be found. If there are multiple variables with the same name, only the first will be removed. To detect this, call the `checkSemantics` method to verify that each variable has a unique name.

  Parameters:
    `name` - the name of the variable to remove.
  See Also:
    `checkSemantics(boolean)`

### getVariable

    public BaseType getVariable(String name)
                         throws NoSuchVariableException

  Returns a reference to the named variable.

  Parameters:
    `name` - the name of the variable to return.
  Returns:
    the variable named `name`.
  Throws:
    `NoSuchVariableException` - if the variable isn't found.

### search

    public Stack search(String name,
                        Stack compStack)
                 throws NoSuchVariableException

  Look for `name` in the DDS. Start the search using the ctor variable (or array/list of ctors) found on the top of the Stack `compStack` (for component stack). When the named variable is found, return the stack compStack modified so that it now contains each ctor-type variable that on the path to the named variable. If the variable is not found after exhausting all possibilities, throw NoSuchVariable.

  Note: This method takes the stack as a parameter so that it can be used by a parser that is working through a list of identifiers that represents the path to a variable as well as a shorthand notation for the identifier that is the equivalent to the leaf node name alone. In the form case the caller helps build the stack by repeatedly calling `search`, in the latter case this method must build the stack itself. This method is over kill for the first case.

  Parameters:
    `name` - Search for the named variable.
    `compStack` - The component stack. This holds the BaseType variables that match the each component of a specific variable's name. This method starts its search using the element at the top of the stack and adds to the stack. The order of BaseType variables on the stack is the reverse of the tree-traverse order. That is, the top most element on the stack is the BaseType for the named variable, under that is the named variable's parent and so on.
  Returns:
    A stack of BaseType variables which hold the path from the top of the DDS to the named variable.
  Throws:
    `NoSuchvariableException.`
    `NoSuchVariableException`

### getVariables

    public final Enumeration getVariables()

  Returns an `Enumeration` of the dataset variables.

  Returns:
    an `Enumeration` of `BaseType`.

### numVariables

    public final int numVariables()

  Returns the number of variables in the dataset.

  Returns:
    the number of variables in the dataset.

### parse

    public void parse(InputStream is)
               throws ParseException,
                      DDSException

  Reads a `DDS` from the named `InputStream`. This method calls a generated parser to interpret an ASCII representation of a `DDS`, and regenerate that `DDS` in memory.

  Parameters:
    `is` - the InputStream containing the `DDS` to parse.
  Throws:
    `ParseException` - thrown on a parser error.
    `DDSException` - thrown on an error constructing the `DDS`.
  See Also:
    `DDSParser`

### checkSemantics

    public void checkSemantics(boolean all)
                        throws BadSemanticsException

  Check the semantics of the `DDS`. If `all` is true, check not only the semantics of the `DDS` itself, but also recursively check all variables in the dataset.

  Parameters:
    `all` - this flag indicates whether to check the semantics of the member variables, too.
  Throws:
    `BadSemanticsException` - if semantics are bad

### checkSemantics

    public final void checkSemantics()
                              throws BadSemanticsException

  Check the semantics of the `DDS`. Same as `checkSemantics(false)`.

  Throws:
    `BadSemanticsException` - if semantics are bad
  See Also:
    `checkSemantics(boolean)`

### print

    public void print(PrintWriter os)

  Print the `DDS` on the given `PrintWriter`.

  Parameters:
    `os` - the `PrintWriter` to use for output.

### print

    public final void print(OutputStream os)

  Print the `DDS` on the given `OutputStream`.

  Parameters:
    `os` - the `OutputStream` to use for output.
  See Also:
    `print(PrintWriter)`