|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectdods.dap.DDS
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:
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 { 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;
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.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;
See The DODS User Guide, or the documentation of the BaseType class for descriptions of the DODS data types.
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 |
protected java.lang.String name
protected java.util.Vector vars
Constructor Detail |
public DDS()
DDS
.
public DDS(java.lang.String n)
DDS
with the given dataset name.
n
- the dataset namepublic DDS(BaseTypeFactory factory)
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.
factory
- the server BaseTypeFactory
object.public DDS(java.lang.String n, BaseTypeFactory factory)
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.
n
- the dataset namefactory
- the server BaseTypeFactory
object.Method Detail |
public java.lang.Object clone()
DDS
. A deep copy is performed on
all variables inside the DDS
.
DDS
.public final BaseTypeFactory getFactory()
public final java.lang.String getName()
public final void setName(java.lang.String name)
name
- the name of the dataset.public final void addVariable(BaseType bt)
DDS
.
bt
- the new variable to add.public final void delVariable(java.lang.String name)
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.
name
- the name of the variable to remove.checkSemantics(boolean)
public BaseType getVariable(java.lang.String name) throws NoSuchVariableException
name
- the name of the variable to return.
name
.
NoSuchVariableException
- if the variable isn't found.public java.util.Stack search(java.lang.String name, java.util.Stack compStack) throws NoSuchVariableException
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.
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.
NoSuchvariableException.
NoSuchVariableException
public final java.util.Enumeration getVariables()
Enumeration
of the dataset variables.
Enumeration
of BaseType
.public final int numVariables()
public void parse(java.io.InputStream is) throws ParseException, DDSException
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.
is
- the InputStream containing the DDS
to parse.
ParseException
- thrown on a parser error.
DDSException
- thrown on an error constructing the
DDS
.DDSParser
public void checkSemantics(boolean all) throws BadSemanticsException
DDS
. If
all
is true, check not only the semantics of the
DDS
itself, but also recursively check all variables
in the dataset.
all
- this flag indicates whether to check the semantics of the
member variables, too.
BadSemanticsException
- if semantics are badpublic final void checkSemantics() throws BadSemanticsException
DDS
. Same as
checkSemantics(false)
.
BadSemanticsException
- if semantics are badcheckSemantics(boolean)
public void print(java.io.PrintWriter os)
DDS
on the given PrintWriter
.
os
- the PrintWriter
to use for output.public final void print(java.io.OutputStream os)
DDS
on the given OutputStream
.
os
- the OutputStream
to use for output.print(PrintWriter)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |