Developers

Object:	Response
ASCII	Data can be requested in CSV form.
HTML	Each server can return an HTML form that facilitates building URLs.
INFO]	Each server can combine the DDS and DAS and present that as HTML.
VERSION	Each server must be able to respond to a request for it's version and the version of the DAP it implements.
HELP	Each server must be able to provide a rudimentary help response.

DataseProvider	DatasetASCIIURL:	HTML:	INFO:
COADS Climatology	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/nc/coads_climatology.nc.asc?SST	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/nc/coads_climatology.nc.html	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/nc/coads_climatology.nc.info
NASA Scatterometer Data	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/hdf/S2000415.HDF.ascii?Wind_Speed	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/hdf/S2000415.HDF.das	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/hdf/S2000415.HDF.dds
Catalog of AVHRR Files	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/ff/1998-6-avhrr.dat.ascii?year,day_num,DODS_URL&day_num	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/ff/1998-6-avhrr.dat.html	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/ff/1998-6-avhrr.dat.info
AHVRR Image	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/dsp/east.coast.pvu.ascii?dsp_band_1"	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/dsp/east.coast.pvu.html	http://dodsdev.gso.uri.edu/dods-3.4/nph-dods/data/dsp/east.coast.pvu.info

This code snippet instantiates a new instance of the {DConnect}

This code fragment declares an instance of the {Connect} class,

Above, the {Connect} method

{request_dds} is called, passing a

-- YuanHo - 10 Mar 2007

Preface

This tutorial describes the steps required to enable your client application to interact with the OPeNDAP Data Access Protocol by using the Java or C++ classes provided in the OPeNDAP class libraries. It also describes the trade offs between using these toolkits and a client-library interface such as netCDF. The C++ and Java toolkis are class libraries which provide for direct interaction with a remote OPeNDAP server. You'll need to write some code. If your client application currently uses one of the netCDF, GDAL or OGR APIs, then you only need to relink your application with the OPeNDAP-enabled version of the API library, allowing you to skip this tutorial entirely.

Writing your own OPeNDAP client

Choose a language

The OPeNDAP project provides both [<\OPDapiUrl>] and [<\OPDjavaUrl>] implementations of the DAP. Each library includes classes that implement the various objects which comprise the DAP software for building clients. Each also includes some extra software which simplifies building clients by managing virtual connections, handling data caching, et cetera. To choose one of the toolkits, several factors should be weighed. With which of the two programming languages are you most comfortable? What type of computer will the client run on? For client development, both Java and C++ are supported on win32 and Unix architectures. Java is more likely to be supported on other architectures, such as Mac. The DAP library is middle-ware. You can use it to build a completely new client or to add network data access to an existing program (making it a client). If you're interested in writing a client from scratch, simply choose the toolkit/language you feel most comfortable. If you're going to take an existing program and transform it into a client there are several additional factors beyond programming language you should consider. If the program you want to DAP-enable can read netCDF files, by far the easiest way to achieve your goal is to use our DAP-enable netCDF ''client library'' (CL). This piece of software works like the standard netCDF CL but has been modified to recognize DAP URLs when they are presented in place of local file names. The OPeNDAP netCDF CL has exactly the same functional interface as the standard netCDF library available from Unidata. That makes it a very powerful tool because it is possible to tap into a large number of existing programs and build OPeNDAP clients. Ferret, GRrADS and IDV are complex programs which have been OPeNDAP-enabled using the netCDF CL. Using the netCDF CL is not without its caveats. First netCDF does not do a good job of representing the entire OPeNDAP data model (That's not a dig at netCDF, it's a reflection of different design goals for two pieces of software). It's very hard to access point data using the netCDF CL, although we're working on this problem. Second, the C++ DAP library is used to build the C version of the netCDF CL\footnote{Unidata bundles OPeNDAP access with their standard release of the Java version of netCDF.} which means that the application programs ''must'' be linked use a C++ compiler. Finally, it can be tricky to build a shared object (aka DLL) using the C++ DAP library.\footnote{As the C++ ABI becomes more widely supported, this situation should change.} If you're going to do that, please contact us through user support or the technical discussion list. However, while the previous points are true, the principle distinction between using the netCDF CL and one of the DAP class libraries is that with the netcDF CL you often do not have to write any new software at all! If you choose to use one of the DAP libraries, you're going to have to write some code. If you plan to OPeNDAP-enable an existing application using the Java toolkit, the application typically must provide a Java Virtual Machine (VM). You may be able to side-step this if you feel you can rely on the host OS to provide a JVM and/or your target program already has a JVM embedded in it. Still you must be sure there is a way to communicate data values between the DAP library and the application. To use the C++ toolkit you should insure that your client application can be built with, or link with libraries constructed using C++ compilers.\footnote{As of winter 2004 we're using gcc 2.95.x, 3.2, 3.3 and MS Visual C++.} Check the current list of supported architectures on the web-site, or contact the DODS technical support (\OPDsupport), or write to the \OPDtechList\ mailing list for information and/or help. This tutorial will focus on using the C++ toolkit. In Section~2 the main programmatic differences between the two class libraries is listed. Both toolkits are essentially the same, with only minor differences between them.

Client Architecture

In essence, an OPeNDAP-enabled client uses overloaded URLs to form the requests to a remote data server. Through the URL, the client connects to the remote server and issues one of several requests. In response to each request, the server will return a well-defined response that the client can use to intern the structure and content of the remote data into local data structures, as well as retrieve any attributes associated with the remote data. The C++ and Java toolkits share the same characteristics, though the names of the objects and their methods may be slightly different. If you understand how the clients are built, it will be easy to see how your own client application can be OPeNDAP-enabled with minimal effort. The \OPDapi\ provides a complete description of the C++ Toolkit and the \OPDjavaUrl\ provides a complete description of the Java toolkit.

The DAP Architecture

The DAP can be thought of as a layered protocol composed of MIME, HTTP, basic objects, and complex, presentation-style, responses.

The DAP uses HTTP which in turn uses MIME

Clients use HTTP when they make requests of DAP servers. HTTP is a fairly straightforward protocol ([], []). It uses pseudo-MIME documents to encapsulate both the request sent from client to server and the response sent back. This is important for the DAP because the DAP uses headers in both the [] and [] documents to transfer information. However, for a programmer who intends to write a DAP server, exactly what gets written into those headers and how it gets written is not important. Both the C++ and Java class libraries will handle these tasks for you (look at the [] to see how). It's important to know about, however, because if you decide not to use the libraries, or the parts that automate generating the correct MIME documents, then your server will have to generate the correct headers itself.

The DAP defines three objects

To transfer information from servers to clients, the DAP uses three objects. Whenever a client asks a server for information, it does so by requesting one of these three objects (note: this is not strictly true, but the whole truth will be told in just a bit. For now, assume it's true). These are the Dataset Descriptor Structure (DDS), Dataset Attribute Structure (DAS), and Data object (DataDDS). These are described in considerable detail in other documentation. The Programmer's Guide contains a description of the []. These objects contain the name and types of the variables in a dataset, along with any attributes (name-value pairs) bound to the variables. The DataDDS contains data values. We have implemented the SDKs so that the DataDDS is a subclass of the DDS object that adds the capacity to store values with each variable.

\begin{tabular}[c]{lll} \[] & [] & [] \[] & [] \Catalog of AVHRR Files & [] & [] \[] & [] \\end{tabular}

The DAP models all datasets as collections of []. The [] objects are containers for those variables. How you represent your dataset using the three objects and the DAP's data type hierarchy is covered in

\begin \"Implementing the DDS object" in ''Writing an OPeNDAP Server'' .\\end \ \begin \[<../ws-html/server-implementing-dds.html>] \in ''Writing an OPeNDAP Server'' . \end \ The DAP also defines services

Information of the DAP services is presented here for completeness and because using these can help speed and simplify development of you client. For example, you can use the HTML and ASCII services to look at a data source using only a web browser. Similarly, the INFO response can be used to look at the attributes and variables in a given data source.

In the previous section we said that the DAP defined three objects and all interaction with the server involved those three objects. In fact, the DAP also defines other responses. They are:

\begin{description} \item[ASCII] Data can be requested in CSV form. \item[HTML] Each server can return an HTML form that facilitates building URLs. \item[INFO] Each server can combine the DDS and DAS and present that as HTML. \item[VERSION] Each server must be able to respond to a request for it's version and the version of the DAP it implements. \item[HELP] Each server must be able to provide a rudimentary help response. \end{description} In each case the server's response to these requests is built using one or more of the basic three objects. Here are some links to various datasets' ASCII, HTML and INFO responses: \begin{tabular}[c]{llll} \[] & [] & [] & [] \[] & [] \Catalog of AVHRR Files & [] & [] \[] & [] \\end{tabular}

The VERSION and HELP responses can be see by appending

{help} or
{version} to the end of the server's base URL. For example:
\begin{tabular}[c]{l} \[]\[]\\end{tabular}

==Connecting to the server==

  
To manage the connection between the client application and the remote
server, the DAP uses two objects.  The \class{Connect} class manages
one connection to either a remote data server, or a local access.  The
\class{Connections} class is used to manage a set of instances to the
class \class{Connect}.  For each data source that the client
opens, there must be exactly one instance of the \class{Connect}
class.  The \OPDapi\ provides a description for the C++ toolkit's
usage.

=Getting ready to write your client=

  
An OPeNDAP-enabled client application creates a connection to the
remote server using the \class{Connect} class, and then issues
requests to the remote server through the \class{Connect} class
methods. Please refer to the [<
{Geturl.java}>] and
[<
{geturl.cc}>] sources as examples of command-line
based DAP client applications written in Java and C++, respectively.
Most of the software is boilerplate. Following are sections of the
Geturl.java client application, later a description of the same
example in C++ will be provided.  Again, please refer to the complete
source listings referenced above.


 DConnect url = null;
 try {
    url = new DConnect(nextURL, accept_deflate);
 }


This code snippet instantiates a new instance of the \class{DConnect}
class, passing the URL referencing the remote data server, and a
boolean flag indicating that the client can accept responses from the
server which are compressed.


 if (get_data) {
    if ((cexpr==false) && (nextURL.indexOf('?') == -1)) {
        System.err.println("Must supply a constraint expression with -D.");
        continue;
    }
    for (int j=0; j
  
This compound statement block initiaties a data request to the remote
server.  The \class{DConnect} method 
{getData} forms the data
request to the remote server by appending the string, {expr},
containing the constraint-expression, onto the URL used in creating
the initial \class{DConnect} to the remote site.  The parameter,
{ui}, provides an optional 
{StatusWindow} object to provide
the status of the current request to the client.

 
 catch (DODSException e) {
   System.err.println(e);
   System.exit(1);
 }
 catch (java.io.FileNotFoundException e) {
   System.err.println(e);
   System.exit(1);
 }
 catch (Exception e) {
   System.err.println(e);
   e.printStackTrace();
   System.exit(1);
 }


  
Completing the try block is a series of catch blocks that catch
exceptions thrown by the DAP library code, and Java input/output and
general exceptions.
The C++ toolkit provides similar functionality as the Java toolkit
though the parameters to the individual \class{Connect} methods may vary.
The C++ client application []
uses the similar C++ toolkit classes as the Java toolkit to implement the
Geturl client application:


  string name = argv[i];
  Connect url(name, trace, accept_deflate);


This code fragment declares an instance of the \class{Connect} class,
passing the URL referencing the remote data server, and a boolean
flag indicating that the client can accept responses from the server
that are compressed.


else if (get_data) {
    if (expr.empty() && name.find('?') == string::npos)
   expr = "";
    for (int j = 0; j < times; ++j) {
 DataDDS dds;
   try {
       DBG(cerr << "URL: " << url->URL(false) << endl);
       DBG(cerr << "CE: " << expr << endl);
       url->request_data(dds, expr