libdap::Connect Class Reference

Holds information about the link from a DAP2 client to a dataset. More...

`#include <Connect.h>`

## Suppress the C++ defaults for these.

| Connect (const Connect &)
Connect & | operator= (const Connect &)
| Connect (const string &name, string uname="", string password="")
| Create an instance of Connect.
bool | is_local ()
virtual string | URL (bool CE=true)
| Get the object's URL.
virtual string | CE ()
| Get the Connect's constraint expression.
void | set_credentials (string u, string p)
| Set the credentials for responding to challenges while dereferencing URLs.
void | set_accept_deflate (bool deflate)
void | set_xdap_protocol (int major, int minor)
void | set_cache_enabled (bool enabled)
bool | is_cache_enabled ()
void | set_xdap_accept (int major, int minor)
string | get_version ()
string | get_protocol ()
virtual string | request_version ()
virtual string | request_protocol ()
virtual void | request_das (DAS &das)
| Get the DAS from a server.
virtual void | request_das_url (DAS &das)
| Get the DAS from a server.
virtual void | request_dds (DDS &dds, string expr="")
| Get the DDS from a server.
virtual void | request_dds_url (DDS &dds)
| Get the DDS from a server.
virtual void | request_ddx (DDS &dds, string expr="")
| Get the DDX from a server.
virtual void | request_ddx_url (DDS &dds)
| The 'url' version of request_ddx.
virtual void | request_data (DataDDS &data, string expr="")
| Get the DAS from a server.
virtual void | request_data_url (DataDDS &data)
| Get the DAS from a server.
virtual void | request_data_ddx (DataDDS &data, string expr="")
virtual void | request_data_ddx_url (DataDDS &data)
virtual void | read_data (DataDDS &data, Response *rs)
| Read data which is preceded by MIME headers. This method works for both data dds and data ddx responses.
virtual void | read_data_no_mime (DataDDS &data, Response *rs)
| Read data from a file which does not have response MIME headers. This method is a companion to read_data(). While read_data() assumes that the response has MIME headers, this method does not. If you call this with a Response that does contain headers, it will throw an Error (and the message is likely to be inscrutable).
virtual void | read_data (DDS &data, Response *rs)
virtual void | read_data_no_mime (DDS &data, Response *rs)

## Detailed Description

Holds information about the link from a DAP2 client to a dataset.

Connect objects are used as containers for information pertaining to the connection a user program makes to a dataset. The dataset may be either local (for example, a file on the user's own computer) or a remote dataset. In the latter case a DAP2 URL will be used to reference the dataset, instead of a filename.

Connect contains methods which can be used to read the DAP2 DAS and DDS objects from the remote dataset as well as reading data. The class understands in a rudimentary way how DAP2 constraint expressions are formed and how to manage them.

Connect also provides additional services such as automatic decompression of compressed data and and error processing.

Note
  Update: I removed the DEFAULT_BASETYPE_FACTORY switch because it caused more confusion than it avoided. See Trac #130.
  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
  DDS
  DAS
  Error

Author
  jhrg

Definition at line 129 of file Connect.h.

## Constructor & Destructor Documentation

## Connect()

libdap::Connect::Connect | ( | const string & | n,
|  | string | uname = `""`,
|  | string | password = `""`
| ) |  |

Create an instance of Connect.

The Connect constructor requires a `name`, which is the URL to which the connection is to be made.

Parameters

  n | The URL for the virtual connection.
  uname | Use this username for authentication. Null by default.
  password | Password to use for authentication. Null by default.

Definition at line 298 of file Connect.cc.

## ~Connect()

libdap::Connect::~Connect | ( |  | ) |

virtual

Definition at line 344 of file Connect.cc.

## Member Function Documentation

## CE()

string libdap::Connect::CE | ( |  | ) |

virtual

Get the Connect's constraint expression.

Return the constraint expression (CE) part of the Connect URL. Note that this CE is supplied as part of the URL passed to the Connect's constructor. It is not the CE passed to the `request_data()` function.

Returns
  A string containing the constraint expression (if any) submitted to the Connect object's constructor.

Definition at line 1146 of file Connect.cc.

## get_protocol()

string libdap::Connect::get_protocol | ( |  | ) |

inline

Return the DAP protocol version of the most recent response. Before a response is made, this contains the string "2.0."

Definition at line 193 of file Connect.h.

## get_version()

string libdap::Connect::get_version | ( |  | ) |

inline

Return the protocol/implementation version of the most recent response. This is a poorly designed method, but it returns information that is useful when used correctly. Before a response is made, this contains the string "unknown." This should ultimately hold the protocol version; it currently holds the implementation version.

    @see get_protocol()
    @deprecated

Definition at line 185 of file Connect.h.

## is_cache_enabled()

bool libdap::Connect::is_cache_enabled | ( |  | ) |

Definition at line 1194 of file Connect.cc.

## is_local()

bool libdap::Connect::is_local | ( |  | ) |

Definition at line 1106 of file Connect.cc.

## read_data() [1/2]

void libdap::Connect::read_data | ( | DataDDS & | data,
|  | Response * | rs
| ) |  |

virtual

Read data which is preceded by MIME headers. This method works for both data dds and data ddx responses.

Note
  If you need the DataDDS to hold specializations of the type classes, be sure to include the factory class which will instantiate those specializations in the DataDDS. Either pass a pointer to the factory to DataDDS constructor or use the DDS::set_factory() method after the object is built.

See also
  read_data_no_mime()

Parameters

  data | Result.
  rs | Read from this Response object.

Definition at line 989 of file Connect.cc.

## read_data() [2/2]

void libdap::Connect::read_data | ( | DDS & | data,
|  | Response * | rs
| ) |  |

virtual

Definition at line 1000 of file Connect.cc.

## read_data_no_mime() [1/2]

void libdap::Connect::read_data_no_mime | ( | DataDDS & | data,
|  | Response * | rs
| ) |  |

virtual

Read data from a file which does not have response MIME headers. This method is a companion to read_data(). While read_data() assumes that the response has MIME headers, this method does not. If you call this with a Response that does contain headers, it will throw an Error (and the message is likely to be inscrutable).

Note
  This method will use the 'type' information in the Response object to choose between processing the response as a data dds or data ddx. If there is no type information, it will attempt to figure it out.

Parameters

  data | Result.
  rs | Read from this Response object.

Definition at line 1062 of file Connect.cc.

## read_data_no_mime() [2/2]

void libdap::Connect::read_data_no_mime | ( | DDS & | data,
|  | Response * | rs
| ) |  |

virtual

Definition at line 1082 of file Connect.cc.

## request_das()

void libdap::Connect::request_das | ( | DAS & | das | ) |

virtual

Get the DAS from a server.

Reads the DAS corresponding to the dataset in the Connect object's URL. Although DAP does not support using CEs with DAS requests, if present in the Connect object's instance, they will be escaped and passed as the query string of the request.

Parameters

  das | Result.

Definition at line 430 of file Connect.cc.

## request_das_url()

void libdap::Connect::request_das_url | ( | DAS & | das | ) |

virtual

Get the DAS from a server.

Reads the DAS corresponding to the dataset in the Connect object's URL. Although DAP does not support using CEs with DAS requests, if present in the Connect object's instance, they will be escaped and passed as the query string of the request.

Different from request_das method in that this method uses the URL as given without attaching .das or projections or selections.

Parameters

  das | Result.

Definition at line 496 of file Connect.cc.

## request_data()

void libdap::Connect::request_data | ( | DataDDS & | data,
|  | string | expr = `""`
| ) |  |

virtual

Get the DAS from a server.

Reads the DataDDS object corresponding to the dataset in the Connect object's URL. If present in the Connect object's instance, a CE will be escaped, combined with `expr` and passed as the query string of the request. The result is a DataDDS which contains the data values bound to variables.

Note
  If you need the DataDDS to hold specializations of the type classes, be sure to include the factory class which will instantiate those specializations in the DataDDS. Either pass a pointer to the factory to DataDDS constructor or use the DDS::set_factory() method after the object is built.

Parameters

  data | Result.
  expr | Send this constraint expression to the server.

Definition at line 845 of file Connect.cc.

## request_data_ddx()

void libdap::Connect::request_data_ddx | ( | DataDDS & | data,
|  | string | expr = `""`
| ) |  |

virtual

Definition at line 919 of file Connect.cc.

## request_data_ddx_url()

void libdap::Connect::request_data_ddx_url | ( | DataDDS & | data | ) |

virtual

Definition at line 954 of file Connect.cc.

## request_data_url()

void libdap::Connect::request_data_url | ( | DataDDS & | data | ) |

virtual

Get the DAS from a server.

Reads the DataDDS object corresponding to the dataset in the Connect object's URL. If present in the Connect object's instance, a CE will be escaped, combined with `expr` and passed as the query string of the request. The result is a DataDDS which contains the data values bound to variables.

Different from request_data in that this method uses the syntax of the new OPeNDAP server commands using dispatch

Note
  If you need the DataDDS to hold specializations of the type classes, be sure to include the factory class which will instantiate those specializations in the DataDDS. Either pass a pointer to the factory to DataDDS constructor or use the DDS::set_factory() method after the object is built.

Parameters

  data | Result.

Definition at line 896 of file Connect.cc.

## request_dds()

void libdap::Connect::request_dds | ( | DDS & | dds,
|  | string | expr = `""`
| ) |  |

virtual

Get the DDS from a server.

Reads the DDS corresponding to the dataset in the Connect object's URL. If present in the Connect object's instance, a CE will be escaped, combined with `expr` and passed as the query string of the request.

Note
  If you need the DDS to hold specializations of the type classes, be sure to include the factory class which will instantiate those specializations in the DDS. Either pass a pointer to the factory to DDS constructor or use the DDS::set_factory() method after the object is built.

Parameters

  dds | Result.
  expr | Send this constraint expression to the server.

Definition at line 562 of file Connect.cc.

## request_dds_url()

void libdap::Connect::request_dds_url | ( | DDS & | dds | ) |

virtual

Get the DDS from a server.

Reads the DDS corresponding to the dataset in the Connect object's URL. If present in the Connect object's instance, a CE will be escaped, combined with `expr` and passed as the query string of the request.

Different from request_dds method above in that this method assumes URL is complete and does not add anything to the command, such as .dds or projections or selections.

Note
  If you need the DDS to hold specializations of the type classes, be sure to include the factory class which will instantiate those specializations in the DDS. Either pass a pointer to the factory to DDS constructor or use the DDS::set_factory() method after the object is built.

Parameters

  dds | Result.

Definition at line 642 of file Connect.cc.

## request_ddx()

void libdap::Connect::request_ddx | ( | DDS & | dds,
|  | string | expr = `""`
| ) |  |

virtual

Get the DDX from a server.

Reads the DDX corresponding to the dataset in the Connect object's URL. If present in the Connect object's instance, a CE will be escaped, combined with `expr` and passed as the query string of the request.

Note
  A DDX is represented as XML on the wire but in memory libdap uses a DDS object with variables that hold their own attributes (the DDS itself holds the global attributes).

Parameters

  dds | Result.
  expr | Send this constraint expression to the server.

Definition at line 705 of file Connect.cc.

## request_ddx_url()

void libdap::Connect::request_ddx_url | ( | DDS & | dds | ) |

virtual

The 'url' version of request_ddx.

See also
  Connect::request_ddx.

Definition at line 773 of file Connect.cc.

## request_protocol()

string libdap::Connect::request_protocol | ( |  | ) |

virtual

Get protocol version information from the server. This is a new method which will ease the transition to DAP 4. Note that this method returns the version of the DAP protocol implemented by the server. The request_version() method returns the server's version number, not the DAP protocol version.

Note
  This method actually asks the server for the protocol version - use get_protocol() to get the protocol information from the most recent response (e.g., from the last DDX response returned by the server).

Returns
  The DAP protocol version string.

Definition at line 398 of file Connect.cc.

## request_version()

string libdap::Connect::request_version | ( |  | ) |

virtual

Get version information from the server. This is a new method which will ease the transition to DAP 4.

Note
  Use request_protocol() to get the DAP protocol version.

Returns
  The DAP version string.

See also
  request_protocol()

Definition at line 362 of file Connect.cc.

## set_accept_deflate()

void libdap::Connect::set_accept_deflate | ( | bool | deflate | ) |

Set the accept deflate property.

Parameters

  deflate | True if the client can accept compressed responses, False otherwise.

Definition at line 1168 of file Connect.cc.

## set_cache_enabled()

void libdap::Connect::set_cache_enabled | ( | bool | cache | ) |

Disable any further use of the client-side cache. In a future version of this software, this should be handled so that the www library is not initialized with the cache running by default.

Definition at line 1188 of file Connect.cc.

## set_credentials()

void libdap::Connect::set_credentials | ( | string | u,
|  | string | p
| ) |  |

Set the credentials for responding to challenges while dereferencing URLs.

Parameters

  u | The username.
  p | The password.

See also
  extract_auth_info()

Definition at line 1159 of file Connect.cc.

## set_xdap_protocol()

void libdap::Connect::set_xdap_protocol | ( | int | major,
|  | int | minor
| ) |  |

Set the XDAP-Accept property/header. This is used to send to a server the (highest) DAP protocol version number that this client understands.

Parameters

  major | The client dap protocol major version
  minor | The client dap protocol minor version

Definition at line 1179 of file Connect.cc.

## URL()

string libdap::Connect::URL | ( | bool | ce = `true` | ) |

virtual

Get the object's URL.

Return the Connect object's URL in a string. The URL was set by the class constructor, and may not be reset. If you want to open another URL, you must create another Connect object. There is a Connections class created to handle the management of multiple Connect objects.

See also
  Connections

Returns
  A string containing the URL of the data to which the Connect object refers. If the object refers to local data, the function returns the null string.

Parameters

  ce | If TRUE, the returned URL will include any constraint expression enclosed with the Connect object's URL (including the `?`). If FALSE, any constraint expression will be removed from the URL. The default is TRUE.

Definition at line 1127 of file Connect.cc.

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

- Connect.h
- Connect.cc