dods.dap
Class DDS

java.lang.Object
  extended bydods.dap.DDS
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
DataDDS, ServerDDS

public class DDS
extends java.lang.Object
implements java.lang.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.

Version:
$Revision: 1.15 $
Author:
jehamby
See Also:
BaseType, BaseTypeFactory, DAS

Field Summary
protected  java.lang.String name
          The dataset name.
protected  java.util.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(java.lang.String n)
          Creates an empty DDS with the given dataset name.
DDS(java.lang.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.
 java.lang.Object clone()
          Returns a clone of this DDS.
 void delVariable(java.lang.String name)
          Removes a variable from the DDS.
 BaseTypeFactory getFactory()
          Get the Class factory.
 java.lang.String getName()
          Get the dataset's name.
 BaseType getVariable(java.lang.String name)
          Returns a reference to the named variable.
 java.util.Enumeration getVariables()
          Returns an Enumeration of the dataset variables.
 int numVariables()
          Returns the number of variables in the dataset.
 void parse(java.io.InputStream is)
          Reads a DDS from the named InputStream.
 void print(java.io.OutputStream os)
          Print the DDS on the given OutputStream.
 void print(java.io.PrintWriter os)
          Print the DDS on the given PrintWriter.
 java.util.Stack search(java.lang.String name, java.util.Stack compStack)
          Look for name in the DDS.
 void setName(java.lang.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 java.lang.String name
The dataset name.


vars

protected java.util.Vector vars
Variables at the top level.

Constructor Detail

DDS

public DDS()
Creates an empty DDS.


DDS

public DDS(java.lang.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(java.lang.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 java.lang.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 java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.util.Stack search(java.lang.String name,
                              java.util.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 java.util.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(java.io.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(java.io.PrintWriter os)
Print the DDS on the given PrintWriter.

Parameters:
os - the PrintWriter to use for output.

print

public final void print(java.io.OutputStream os)
Print the DDS on the given OutputStream.

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