This chapter describes how to use the toolkit software to build new client libraries and data servers. Before beginning to build either part of a new DODS application, it is very important to be intimate with the details of the API to be replaced.
To create a client library that can replace the original API implementation at link time means that the client library must present exactly the same interface as the original library. This includes, to the extent that they are widely used, any undocumented features of the original implementation that manifest themselves as symbols that require link-time resolution. Building a client-library requires great understanding of the existing implementation as well as current use of the target API.
To build a good data server for files or data sets encoded using an API it is important to understand the data model(s) the API supports and how they relate to the DODS data models. Each of the various data types that the API supports must be translated into a DODS data type (i.e., one of the DODS classes that descend from BaseType). However, there is often not a one-to-one match between the API's types and the DODS types. Thus, the data server author must decide how to best translate the API's types into DODS types so as to preserve as much of the data set author's intent. This is exacerbated by the use of various conventions that (implicitly) bind several variables together with a data set. When this pattern shows up (as it does with NetCDF) you must decide whether to lump all variables together that appear to use the convention (and thus falsely group some variables) or to group only those which actually are explicitly grouped using whatever the API provides. If you choose the latter then any data sets which follow the convention will lose information. When building the data server it is important to keep such tradeoffs in mind.
The following sections discuss the specifics of building a data server
and a client library. The existing NetCDF server and client library
are used as examples. Many APIs are very similar in their overall
organization. The source code used for these examples can be found in
$(DODS_ROOT)/src/nc-dods/. Much of the NetCDF example will be
relevant to your task, even if your target API is significantly
different. The $(DODS_ROOT)/src/jg-dods/ directory contains
both a data server and client library for the Joint Geophysical Ocean Flux Study relational data
system.