libdap++ Updated for version 3.8.2

libdap::DDS Class Reference

#include <DDS.h>

Inheritance diagram for libdap::DDS:
Collaboration diagram for libdap::DDS:

List of all members.

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.
bool check_semantics (bool all=false)
 Check the semantics of each of the variables represented in the DDS.
 DDS (const DDS &dds)
 DDS (BaseTypeFactory *factory, const string &n="")
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
virtual AttrTableget_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.
BaseTypeFactoryget_factory () const
string get_request_xml_base () const
 Get the URL that will return this DDS/DDX/DataThing.
int get_timeout ()
BaseTypeget_var_index (int i)
 Get a variable.
Vars_iter get_vars_iter (int i)
 Get an iterator.
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.
DDSoperator= (const DDS &rhs)
void parse (int fd)
 Parse a DDS from a file indicated by the input file descriptor.
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 (string fname)
 Parse a DDS from a file with the given name.
void print (ostream &out)
 Print the entire DDS to the specified ostream.
void print_constrained (ostream &out)
 Print a constrained DDS to the specified ostream.
void print_xml (ostream &out, bool constrained, const string &blob="")
void set_dap_major (int p)
 Set the DAP major version (typically using info from the client)
void set_dap_minor (int p)
 Set the DAP minor version (typically using info from the client)
void set_dap_version (const string &version_string)
BaseTypeFactoryset_factory (BaseTypeFactory *factory)
void set_request_xml_base (const string &xb)
void set_timeout (int t)
void tag_nested_sequences ()
 Traverse DDS, set Sequence leaf nodes.
void timeout_off ()
void timeout_on ()
virtual void transfer_attributes (DAS *das)
BaseTypevar (const string &n, BaseType::btp_stack *s=0)
 Find the variable with the given name.
BaseTypevar (const string &n, BaseType::btp_stack &s)
Vars_iter var_begin ()
 Return an iterator to the first variable.
Vars_iter var_end ()
 Return an iterator.
Vars_riter var_rbegin ()
 Return a reverse iterator.
Vars_riter var_rend ()
 Return a reverse iterator.
virtual ~DDS ()
Dataset Name Accessors

Get and 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.

string get_dataset_name () const
void set_dataset_name (const string &n)
File Name Accessor

Get and set the dataset's filename. This is the physical location on a disk where the dataset exists. The dataset name is simply a title.

See also:
Dataset Name Accessors
string filename ()
void filename (const string &fn)
Container Name Accessor

Get and set the current container. If there are multiple files being used to build this DDS, using a container will set a virtual structure for the current container.

See also:
Dataset Name Accessors
string container_name ()
void container_name (const string &cn)
Structurecontainer ()

Protected Member Functions

void duplicate (const DDS &dds)
BaseTypeexact_match (const string &name, BaseType::btp_stack *s=0)
BaseTypeleaf_match (const string &name, BaseType::btp_stack *s=0)

Friends

class DDSTest

Detailed Description

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.

Note:
Make sure to pass a valid pointer to the DDS constructor or use the set_factory() method before actually using the DDS. Also make sure that the Factory's lifetime thereafter is the same as the DDS's. Never delete the factory until you're done using the DDS.
Update: I removed the DEFAULT_BASETYPE_FACTORY switch because it caused more confusion than it avoided. See Trac #130. jhrg
The compile-time symbol DEFAULT_BASETYPE_FACTORY controls whether the old (3.4 and earlier) DDS and DataDDS constructors are supported. These constructors now use a default factory class (BaseTypeFactory, implemented by this library) to instantiate Byte, ..., Grid variables. To use the default ctor in your code you must also define this symbol. If you do choose to define this and fail to provide a specialization of BaseTypeFactory when your software needs one, you code may not link or may fail at run time. In addition to the older ctors for DDS and DataDDS, defining the symbol also makes some of the older methods in Connect available (because those methods require the older DDS and DataDDS ctors.
See also:
BaseType
DAS

Definition at line 174 of file DDS.h.


Member Typedef Documentation

typedef std::vector<BaseType *>::const_iterator libdap::DDS::Vars_citer

Definition at line 210 of file DDS.h.

typedef std::vector<BaseType *>::iterator libdap::DDS::Vars_iter

Definition at line 211 of file DDS.h.

typedef std::vector<BaseType *>::reverse_iterator libdap::DDS::Vars_riter

Definition at line 212 of file DDS.h.


Constructor & Destructor Documentation

libdap::DDS::DDS ( BaseTypeFactory factory,
const string &  n = "" 
)

Make a DDS which uses the given BaseTypeFactory to create variables.

Parameters:
nThe name of the dataset. Can also be set using the set_dataset_name() method.
factoryBaseTypeFactory which instantiates Byte, ..., Grid. The caller is responsible for freeing the object after deleting this DDS. Can also be set using set_factory(). Never delete until just before deleting the DDS itself unless you intend to replace the factory with a new instance.
nThe name of the data set. Can also be set using set_dataset_name().

Definition at line 142 of file DDS.cc.

References DBG.

libdap::DDS::DDS ( const DDS rhs)

The DDS copy constructor.

Definition at line 153 of file DDS.cc.

References DBG, and duplicate().

Here is the call graph for this function:

libdap::DDS::~DDS ( ) [virtual]

Definition at line 160 of file DDS.cc.


Member Function Documentation

void libdap::DDS::add_var ( BaseType bt)
Note:
The copy will not copy data values.
Parameters:
btSource variable.

Definition at line 572 of file DDS.cc.

References libdap::Structure::add_var(), DBG2, and libdap::BaseType::ptr_duplicate().

Referenced by container_name(), libdap::DDXParser::ddx_end_document(), and libdap::ConstraintEvaluator::eval_function_clauses().

Here is the call graph for this function:

bool libdap::DDS::check_semantics ( bool  all = false)

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.

Returns:
TRUE if the conventions for the DDS are not violated, FALSE otherwise.
Parameters:
allIf true, recursively check the individual members of compound variables.
See also:
BaseType::check_semantics

Definition at line 1208 of file DDS.cc.

References libdap::unique_names().

Here is the call graph for this function:

Structure * libdap::DDS::container ( )

Get the current container structure.

Definition at line 559 of file DDS.cc.

string libdap::DDS::container_name ( )

Gets the dataset file name.

Definition at line 523 of file DDS.cc.

void libdap::DDS::container_name ( const string &  cn)

Set the current container name and get or create a structure for that name.

Definition at line 531 of file DDS.cc.

References add_var(), and var().

Here is the call graph for this function:

void libdap::DDS::del_var ( Vars_iter  i)

Remove the variable referenced by the iterator and free its storage.

Note:
Invalidates any iterators that reference the contents of the DDS.
Parameters:
iThe Vars_iter which refers to the variable.

Definition at line 626 of file DDS.cc.

void libdap::DDS::del_var ( Vars_iter  i1,
Vars_iter  i2 
)

Remove the variables referenced by the range of iterators and free their storage.

Note:
Invalidates any iterators that reference the contents of the DDS.
Parameters:
i1The start of the range.
i2The end of the range.

Definition at line 642 of file DDS.cc.

void libdap::DDS::del_var ( const string &  n)

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 name given.

Note:
Invalidates any iterators that reference the contents of the DDS.
Parameters:
nThe name of the variable to remove.

Definition at line 603 of file DDS.cc.

References libdap::Structure::del_var().

Here is the call graph for this function:

void libdap::DDS::dump ( ostream &  strm) const [virtual]

Displays the pointer value of this instance and then calls parent dump

Parameters:
strmC++ i/o stream to dump the information to
Returns:
void

Implements libdap::DapObj.

Reimplemented in libdap::DataDDS.

Definition at line 1312 of file DDS.cc.

References libdap::AttrTable::dump(), libdap::DapIndent::Indent(), libdap::DapIndent::LMarg(), and libdap::DapIndent::UnIndent().

Here is the call graph for this function:

void libdap::DDS::duplicate ( const DDS dds) [protected]

Definition at line 110 of file DDS.cc.

References DBG, var_begin(), and var_end().

Referenced by DDS(), and operator=().

Here is the call graph for this function:

BaseType * libdap::DDS::exact_match ( const string &  name,
BaseType::btp_stack s = 0 
) [protected]

Definition at line 733 of file DDS.cc.

References DBG2, libdap::BaseType::name(), libdap::BaseType::var(), and var().

Referenced by var().

Here is the call graph for this function:

string libdap::DDS::filename ( )

Gets the dataset file name.

Definition at line 475 of file DDS.cc.

void libdap::DDS::filename ( const string &  fn)

Set the dataset's filename.

Definition at line 482 of file DDS.cc.

AttrTable & libdap::DDS::get_attr_table ( ) [virtual]

Get the attribute table for the global attributes.

Definition at line 460 of file DDS.cc.

Referenced by libdap::DDXParser::ddx_start_document().

int libdap::DDS::get_dap_major ( ) const [inline]

Definition at line 254 of file DDS.h.

Referenced by print_xml().

int libdap::DDS::get_dap_minor ( ) const [inline]

Definition at line 256 of file DDS.h.

Referenced by print_xml().

string libdap::DDS::get_dataset_name ( ) const

Returns the dataset's name.

Definition at line 444 of file DDS.cc.

Referenced by libdap::ConstraintEvaluator::eval_function_clauses().

BaseTypeFactory* libdap::DDS::get_factory ( ) 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.

Returns:
An instance of BaseTypeFactory.

Definition at line 230 of file DDS.h.

Referenced by libdap::ConstraintEvaluator::eval_function_clauses(), libdap::Connect::request_ddx(), and libdap::Connect::request_ddx_url().

string libdap::DDS::get_request_xml_base ( ) const [inline]

Definition at line 266 of file DDS.h.

Referenced by print_xml().

int libdap::DDS::get_timeout ( )

Definition at line 838 of file DDS.cc.

BaseType * libdap::DDS::get_var_index ( int  i)

Return the ith variable.

Parameters:
ithe index
Returns:
The corresponding variable

Definition at line 802 of file DDS.cc.

DDS::Vars_iter libdap::DDS::get_vars_iter ( int  i)

Return the iterator for the ith variable.

Parameters:
ithe index
Returns:
The corresponding Vars_iter

Definition at line 793 of file DDS.cc.

BaseType * libdap::DDS::leaf_match ( const string &  name,
BaseType::btp_stack s = 0 
) [protected]

Definition at line 697 of file DDS.cc.

References DBG, libdap::BaseType::is_constructor_type(), libdap::BaseType::is_vector_type(), libdap::BaseType::name(), and libdap::BaseType::var().

Referenced by var().

Here is the call graph for this function:

bool libdap::DDS::mark ( const string &  n,
bool  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.

Note:
For aggregate types this sets each part to STATE when STATE is True. Thus, if State is True and N is `exp1.test', then both `exp1' and `test' have their SEND_P flag set to True. If STATE is False, then the SEND_P flag of the `test' is set to False, but `exp1' is left unchanged. This means that a single variable can be removed from the current projection without removing all the other children of its parent. See the mfunc set_send_p().
Returns:
True if the named variable was found, false otherwise.
Todo:
This should throw an exception on error!!!
Todo:
These methods that use the btp_stack to keep track of the path from the top of a dataset to a particular variable can be rewritten to use the parent field instead.
Todo:
All the methods that use names to identify variables should have counterparts that take BaseType pointers.

Definition at line 1254 of file DDS.cc.

References DBG2, libdap::BaseType::name(), libdap::BaseType::set_send_p(), libdap::BaseType::type_name(), and var().

Here is the call graph for this function:

void libdap::DDS::mark_all ( bool  state)

Mark the member variable send_p flags to state.

Returns:
Void

Definition at line 1298 of file DDS.cc.

int libdap::DDS::num_var ( )

Definition at line 809 of file DDS.cc.

DDS & libdap::DDS::operator= ( const DDS rhs)

Definition at line 170 of file DDS.cc.

References DBG, and duplicate().

Here is the call graph for this function:

void libdap::DDS::parse ( string  fname)
void libdap::DDS::parse ( int  fd)

Definition at line 879 of file DDS.cc.

References parse().

Here is the call graph for this function:

void libdap::DDS::parse ( FILE *  in = stdin)
Parameters:
inRead the persistent DDS from this FILE*.
Exceptions:
InternalErrThrown if in is null
ErrorThrown if the parse fails.

Definition at line 908 of file DDS.cc.

References DBG2, dds_buffer(), dds_delete_buffer(), dds_switch_to_buffer(), and ddsparse().

Here is the call graph for this function:

void libdap::DDS::print ( ostream &  out)

Definition at line 959 of file DDS.cc.

References libdap::id2www().

Referenced by main(), and libdap::DODSFilter::send_dds().

Here is the call graph for this function:

void libdap::DDS::print_constrained ( ostream &  out)

Print those parts (variables) of the DDS structure to OS that are marked to be sent after evaluating the constraint expression.

Note:
This function only works for scalars at the top level.
Returns:
true.

Definition at line 1012 of file DDS.cc.

References libdap::id2www().

Referenced by libdap::DODSFilter::dataset_constraint(), and libdap::DODSFilter::send_dds().

Here is the call graph for this function:

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 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.

Parameters:
outDestination ostream.
constrainedTrue if the output should be limited to just those variables that are in the projection of the current constraint expression.
blobThe dataBLOB href.

Definition at line 1130 of file DDS.cc.

References c_dap20_namespace, c_dap32_namespace, c_default_dap20_schema_location, c_default_dap32_schema_location, c_xml_namespace, get_dap_major(), get_dap_minor(), get_request_xml_base(), grddl_transformation_dap32, libdap::id2xml(), libdap::AttrTable::print_xml(), var_begin(), and var_end().

Referenced by libdap::DODSFilter::dataset_constraint_ddx(), main(), and libdap::DODSFilter::send_ddx().

Here is the call graph for this function:

void libdap::DDS::set_dap_major ( int  p) [inline]

Definition at line 259 of file DDS.h.

Referenced by set_dap_version().

void libdap::DDS::set_dap_minor ( int  p) [inline]

Definition at line 261 of file DDS.h.

Referenced by set_dap_version().

void libdap::DDS::set_dap_version ( const string &  version_string)

Given the dap protocol version either from a MIME header or from within the DDX Dataset element, parse that string and set the DDS fields.

See also:
set_dap_client_version()
Parameters:
version_stringThe version string from the MIME of XML document.

Definition at line 494 of file DDS.cc.

References DBG, set_dap_major(), and set_dap_minor().

Referenced by libdap::DDXParser::ddx_sax2_start_element().

Here is the call graph for this function:

void libdap::DDS::set_dataset_name ( const string &  n)

Sets the dataset name.

Definition at line 451 of file DDS.cc.

Referenced by libdap::DDXParser::ddx_sax2_start_element().

BaseTypeFactory* libdap::DDS::set_factory ( BaseTypeFactory factory) [inline]

Set the factory class used to instantiate variables during the parse of a DDS.

Parameters:
factoryThe factory this DDS should use. Caller must free factory when done with this DDS.
Returns:
The old factory.
See also:
BaseTypeFactory

Definition at line 241 of file DDS.h.

void libdap::DDS::set_request_xml_base ( const string &  xb) [inline]
See also:
get_request_xml_base

Definition at line 269 of file DDS.h.

void libdap::DDS::set_timeout ( int  t)

Definition at line 831 of file DDS.cc.

Referenced by libdap::DODSFilter::send_data(), and libdap::DODSFilter::send_data_ddx().

void libdap::DDS::tag_nested_sequences ( )
void libdap::DDS::transfer_attributes ( DAS das) [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, to it's safe to delete the source DAS object passed to this method once it's done.

Note:
To accommodate oddly built DAS objects produced by various handlers, specialize the methods there.
Parameters:
dasTransfer (copy) attributes from this DAS object.

Definition at line 367 of file DDS.cc.

References libdap::AttrTable::append_container(), libdap::AttrTable::attr_begin(), libdap::Attr_container, libdap::AttrTable::attr_end(), libdap::DAS::container_name(), DBG, libdap::AttrTable::get_name(), libdap::DAS::get_top_level_attributes(), var(), var_begin(), and var_end().

Referenced by main().

Here is the call graph for this function:

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.

Returns:
A BaseType pointer to the variable n or 0 if n could not be found.

Definition at line 659 of file DDS.cc.

Referenced by container_name(), exact_match(), mark(), and transfer_attributes().

BaseType * libdap::DDS::var ( const string &  n,
BaseType::btp_stack s = 0 
)

Returns a pointer to the named variable. If the name contains one or more field separators then the function looks for a variable whose name matches exactly. If the 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.

Note:
If a dataset contains two constructor types which have field names that are the same (say point.x and pair.x) you should use fully qualified names to get each of those variables.
Parameters:
nThe name of the variable to find.
sIf given, this value-result parameter holds the path to the returned BaseType. Thus, this method can return the FQN for the variable n.
Returns:
A BaseType pointer to the variable or null if not found.

Definition at line 683 of file DDS.cc.

References exact_match(), leaf_match(), libdap::Structure::var(), and libdap::www2id().

Here is the call graph for this function:

DDS::Vars_iter libdap::DDS::var_begin ( )

Returns the first variable in the DDS.

Definition at line 766 of file DDS.cc.

Referenced by libdap::DODSFilter::dataset_constraint(), libdap::DODSFilter::dataset_constraint_ddx(), duplicate(), print_xml(), and transfer_attributes().

DDS::Vars_riter libdap::DDS::var_rbegin ( )

Definition at line 772 of file DDS.cc.

DDS::Vars_riter libdap::DDS::var_rend ( )

Definition at line 784 of file DDS.cc.


Friends And Related Function Documentation

friend class DDSTest [friend]

Definition at line 199 of file DDS.h.


The documentation for this class was generated from the following files: