libdap Updated for version 3.20.10
libdap4 is an implementation of OPeNDAP's DAP protocol.
|
#include <DDS.h>
Public Types | |
typedef std::vector< BaseType * >::const_iterator | Vars_citer |
typedef std::vector< BaseType * >::iterator | Vars_iter |
typedef std::vector< BaseType * >::reverse_iterator | Vars_riter |
Public Member Functions | |
void | add_var (BaseType *bt) |
Adds a copy of the variable to the DDS. Using the ptr_duplicate() method, perform a deep copy on the variable bt and adds the result to this DDS. | |
void | add_var_nocopy (BaseType *bt) |
Adds the variable to the DDS. | |
bool | check_semantics (bool all=false) |
Check the semantics of each of the variables represented in the DDS. | |
Structure * | container () |
string | container_name () |
void | container_name (const string &cn) |
DDS (BaseTypeFactory *factory, const string &name, const string &version) | |
DDS (BaseTypeFactory *factory, const string &name="") | |
DDS (const DDS &dds) | |
void | del_var (const string &n) |
Removes a variable from the DDS. | |
void | del_var (Vars_iter i) |
Removes a variable from the DDS. | |
void | del_var (Vars_iter i1, Vars_iter i2) |
Removes a range of variables from the DDS. | |
virtual void | dump (ostream &strm) const |
dumps information about this object | |
string | filename () const |
void | filename (const string &fn) |
virtual AttrTable & | get_attr_table () |
int | get_dap_major () const |
Get the DAP major version as sent by the client. | |
int | get_dap_minor () const |
Get the DAP minor version as sent by the client. | |
string | get_dap_version () const |
DAS * | get_das () |
Get a DAS object. | |
void | get_das (DAS *das) |
string | get_dataset_name () const |
string | get_dmr_version () const |
BaseTypeFactory * | get_factory () const |
string | get_namespace () const |
Get the namespace associated with the DDS - likely set only by DDX responses. | |
int | get_request_size (bool constrained) |
Get the estimated response size in bytes. | |
uint64_t | get_request_size_kb (bool constrained) |
Get the estimated response size in kilobytes. | |
string | get_request_xml_base () const |
Get the URL that will return this DDS/DDX/DataThing. | |
long | get_response_limit () |
Get the maximum response size, in bytes. Zero indicates no limit. | |
uint64_t | get_response_limit_kb () const |
The maximum allowed response size, in kilobytes. Zero indicates no limit (default). | |
BaseType * | get_var_index (int i) |
Get a variable. | |
Vars_iter | get_vars_iter (int i) |
Get an iterator. | |
void | insert_var (Vars_iter i, BaseType *ptr) |
Insert a variable before the referenced element. | |
void | insert_var_nocopy (Vars_iter i, BaseType *ptr) |
bool | mark (const string &name, bool state) |
Mark the send_p flag of the named variable to state. | |
void | mark_all (bool state) |
int | num_var () |
Returns the number of variables in the DDS. | |
DDS & | operator= (const DDS &rhs) |
void | parse (FILE *in=stdin) |
Parse a DDS from a file indicated by the input file descriptor. Read the persistent representation of a DDS from the FILE *in, parse it and create a matching binary object. | |
void | parse (int fd) |
Parse a DDS from a file indicated by the input file descriptor. | |
void | parse (string fname) |
Parse a DDS from a file with the given d_name. | |
void | print (FILE *out) |
Print the entire DDS to the specified file. | |
void | print (ostream &out) |
Print the entire DDS to the specified ostream. | |
void | print_constrained (FILE *out) |
Print a constrained DDS to the specified file. | |
void | print_constrained (ostream &out) |
Print a constrained DDS to the specified ostream. | |
void | print_das (ostream &out) |
write the DAS response given the attribute information in the DDS | |
void | print_dmr (ostream &out, bool constrained) |
Print the DAP4 DMR object using a DDS. | |
void | print_xml (FILE *out, bool constrained, const string &blob="") |
void | print_xml (ostream &out, bool constrained, const string &blob="") |
void | print_xml_writer (ostream &out, bool constrained, const string &blob="") |
void | set_dap_major (int p) |
void | set_dap_minor (int p) |
void | set_dap_version (const string &version_string="2.0") |
void | set_dap_version (double d) |
void | set_dataset_name (const string &n) |
BaseTypeFactory * | set_factory (BaseTypeFactory *factory) |
void | set_namespace (const string &ns) |
Set the namespace for this DDS/DDX object/response. | |
void | set_request_xml_base (const string &xb) |
void | set_response_limit (long size) |
void | set_response_limit_kb (uint64_t size) |
Set the maximum response size, in kilobytes. The size is given in kilobytes.. | |
void | tag_nested_sequences () |
Traverse DDS, set Sequence leaf nodes. | |
bool | too_big () |
virtual void | transfer_attributes (DAS *das) |
BaseType * | var (const string &n, BaseType::btp_stack &s) |
BaseType * | var (const string &n, BaseType::btp_stack *s=0) |
Find the variable with the given d_name. | |
Vars_iter | var_begin () |
Vars_iter | var_end () |
Return an iterator. | |
Vars_riter | var_rbegin () |
Return a reverse iterator. | |
Vars_riter | var_rend () |
Return a reverse iterator. | |
const vector< BaseType * > & | variables () const |
DDS_timeout | |
Old deprecated DDS timeout code | |
void | timeout_on () |
void | timeout_off () |
void | set_timeout (int t) |
int | get_timeout () |
Protected Member Functions | |
void | duplicate (const DDS &dds) |
BaseType * | exact_match (const string &name, BaseType::btp_stack *s=0) |
BaseType * | leaf_match (const string &name, BaseType::btp_stack *s=0) |
Friends | |
class | DDSTest |
The DAP2 Data Descriptor Object (DDS) is a data structure used by the DAP2 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 DAP2 client. Part of the job of a DAP2 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 DAP2 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 OPeNDAP User Guide.
The DDS has an ASCII representation, which is what is transmitted from a DAP2 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 The OPeNDAP User Guide, or the documentation of the BaseType class for descriptions of the DAP2 data types.
typedef std::vector<BaseType*>::const_iterator libdap::DDS::Vars_citer |
typedef std::vector<BaseType*>::iterator libdap::DDS::Vars_iter |
typedef std::vector<BaseType*>::reverse_iterator libdap::DDS::Vars_riter |
libdap::DDS::DDS | ( | BaseTypeFactory * | factory, |
const string & | name = "" ) |
Make a DDS which uses the given BaseTypeFactory to create variables.
factory | The BaseTypeFactory to use when creating instances of DAP variables. The caller must ensure the factory's lifetime is at least that of the DDS instance. |
name | The name of the DDS - usually derived from the name of the pathname or table name of the dataset. |
libdap::DDS::DDS | ( | BaseTypeFactory * | factory, |
const string & | name, | ||
const string & | version ) |
Make a DDS with the DAP protocol set to a specific value. This method provides an easy way to build DDS objects for use in a server or client that will process DAP4, for example. It's roughly equivalent to calling set_dap_version() after making an instance using DDS::DDS(BaseTypeFactory *, const string &).
factory | The BaseTypeFactory to use when creating instances of DAP variables. The caller must ensure the factory's lifetime is at least that of the DDS instance. |
name | The name of the DDS - usually derived from the name of the pathname or table name of the dataset. |
version | The DAP version to support. This sets the DAP version, as well as a number of other dependent constants. |
libdap::DDS::DDS | ( | const DDS & | rhs | ) |
void libdap::DDS::add_var | ( | BaseType * | bt | ) |
void libdap::DDS::add_var_nocopy | ( | BaseType * | bt | ) |
bool libdap::DDS::check_semantics | ( | bool | all = false | ) |
Check the semantics of each of the variables represented in the DDS.
Check the semantics of the DDS describing a complete dataset. If ALL is true, check not only the semantics of THIS->TABLE, but also recursively all ctor types in the THIS->TABLE. By default, ALL is false since parsing a DDS input file runs semantic checks on all variables (but not the dataset itself.
all | If true, recursively check the individual members of compound variables. |
Structure * libdap::DDS::container | ( | ) |
string libdap::DDS::container_name | ( | ) |
void libdap::DDS::container_name | ( | const string & | cn | ) |
void libdap::DDS::del_var | ( | const string & | n | ) |
Removes a variable from the DDS.
Remove the named variable from the DDS. This method is not smart about looking up names. The variable must exist at the top level of the DDS and must match exactly the d_name given.
n | The d_name of the variable to remove. |
void libdap::DDS::del_var | ( | Vars_iter | i | ) |
void libdap::DDS::del_var | ( | Vars_iter | i1, |
Vars_iter | i2 ) |
|
virtual |
dumps information about this object
Displays the pointer value of this instance and then calls parent dump
strm | C++ i/o stream to dump the information to |
Implements libdap::DapObj.
Reimplemented in libdap::DataDDS.
|
protected |
string libdap::DDS::filename | ( | ) | const |
void libdap::DDS::filename | ( | const string & | fn | ) |
|
virtual |
|
inline |
|
inline |
DAS * libdap::DDS::get_das | ( | ) |
string libdap::DDS::get_dataset_name | ( | ) | const |
|
inline |
Return the factory which makes instances of the Byte, ..., Grid type classes. Specialize BaseTypeFactory so that a DDS will be populated with your client or server's specialized types.
|
inline |
int libdap::DDS::get_request_size | ( | bool | constrained | ) |
Get the estimated response size in bytes.
Get the size of a response. This method looks at the variables in the DDS a computes the number of bytes in the response.
constrained | Should the size of the whole DDS be used or should the current constraint be taken into account? |
uint64_t libdap::DDS::get_request_size_kb | ( | bool | constrained | ) |
Get the estimated response size in kilobytes.
Get the estimated size of a response in kilobytes. This method looks at the variables in the DDS and computes the number of bytes in the response.
constrained | Should the size of the whole DDS be used or should the current constraint be taken into account? |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
void libdap::DDS::insert_var | ( | Vars_iter | i, |
BaseType * | ptr ) |
void libdap::DDS::insert_var_nocopy | ( | Vars_iter | i, |
BaseType * | ptr ) |
|
protected |
bool libdap::DDS::mark | ( | const string & | n, |
bool | state ) |
Mark the send_p
flag of the named variable to state.
Mark the named variable by setting its SEND_P flag to STATE (true indicates that it is to be sent). Names must be fully qualified.
void libdap::DDS::mark_all | ( | bool | state | ) |
int libdap::DDS::num_var | ( | ) |
void libdap::DDS::parse | ( | FILE * | in = stdin | ) |
Parse a DDS from a file indicated by the input file descriptor. Read the persistent representation of a DDS from the FILE *in, parse it and create a matching binary object.
in | Read the persistent DDS from this FILE*. |
InternalErr | Thrown if in is null |
Error | Thrown if the parse fails. |
void libdap::DDS::parse | ( | int | fd | ) |
void libdap::DDS::parse | ( | string | fname | ) |
void libdap::DDS::print | ( | FILE * | out | ) |
void libdap::DDS::print | ( | ostream & | out | ) |
void libdap::DDS::print_constrained | ( | FILE * | out | ) |
void libdap::DDS::print_constrained | ( | ostream & | out | ) |
void libdap::DDS::print_das | ( | ostream & | out | ) |
void libdap::DDS::print_dmr | ( | ostream & | out, |
bool | constrained ) |
Print the DAP4 DMR object using a DDS.
This method prints the DMR from a DDS. If the dap version is not >= 4.0, it's an error to call this method.
out | Write the XML to this stream |
constrained | Should the DMR be subject to a constraint? |
void libdap::DDS::print_xml | ( | FILE * | out, |
bool | constrained, | ||
const string & | blob = "" ) |
Print an XML representation of this DDS. This method is used to generate the part of the DDX response. The Dataset
tag is not written by this code. The caller of this method must handle writing that and including the dataBLOB
tag.
out | Destination. |
constrained | True if the output should be limited to just those variables that are in the projection of the current constraint expression. |
blob | The dataBLOB href. |
void libdap::DDS::print_xml | ( | ostream & | out, |
bool | constrained, | ||
const string & | blob = "" ) |
Print an XML representation of this DDS. This method is used to generate the DDX response. The Dataset
tag is not written by this code. The caller of this method must handle writing that and including the dataBLOB
tag.
out | Destination ostream. |
constrained | True if the output should be limited to just those variables that are in the projection of the current constraint expression. |
blob | The dataBLOB href. |
void libdap::DDS::print_xml_writer | ( | ostream & | out, |
bool | constrained, | ||
const string & | blob = "" ) |
Print the DDX. This code uses the libxml2 'TextWriter' interface; something that seems to be a good compromise between doing it by hand (although more verbose it is also more reliable) and DOM.
out | Write the XML to this output sink |
constrained | True if the only variables to print are those in the current projection. If true, this will also suppress printing attributes. |
blob | This is an href (DAP2) or a cid (DAP3.4 and 4). The href points to the binary data; the cid is the M-MIME separator for the binary data. |
void libdap::DDS::set_dap_major | ( | int | p | ) |
void libdap::DDS::set_dap_minor | ( | int | p | ) |
void libdap::DDS::set_dap_version | ( | const string & | v = "2.0" | ) |
void libdap::DDS::set_dap_version | ( | double | d | ) |
Old way to set the DAP version.
d | The protocol version requested by the client, as a double. |
void libdap::DDS::set_dataset_name | ( | const string & | n | ) |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
void libdap::DDS::tag_nested_sequences | ( | ) |
|
inline |
|
virtual |
This is the main method used to transfer attributes from a DAS object into a DDS. This uses the BaseType::transfer_attributes() method and the various implementations found here (in the constructors classes) and in handlers.
This method uses a deep copy to transfer the attributes, so it is safe to delete the source DAS object passed to this method once it is done.
das | Transfer (copy) attributes from this DAS object. |
BaseType * libdap::DDS::var | ( | const string & | n, |
BaseType::btp_stack & | s ) |
Search for for variable n as above but record all compound type variables which ultimately contain n on s. This stack can then be used to mark the contained compound-type variables as part of the current projection.
BaseType * libdap::DDS::var | ( | const string & | n, |
BaseType::btp_stack * | s = 0 ) |
Find the variable with the given d_name.
Returns a pointer to the named variable. If the d_name contains one or more field separators then the function looks for a variable whose name matches exactly. If the d_name contains no field separators then the function looks first in the top level and then in all subsequent levels and returns the first occurrence found. In general, this function searches constructor types in the order in which they appear in the DDS, but there is no requirement that it do so.
n | The name of the variable to find. |
s | If given, this value-result parameter holds the path to the returned BaseType. Thus, this method can return the FQN for the variable n. |
|
inline |
Return an iterator to the first variable
|
inline |
|
inline |
|
inline |