Making the transition to DAP4

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽

This How-To describes modifying existing modules written for the Hyrax Back End Server (BES) so that they support both DAP4 as well as the older DAP2 protocol. The information here is mostly anecdotal, based on experience working with five existing handlers that read data and return DAP2 metadata and data responses. The libdap and bes software have been modified to provide support for all but a very few of the features described in the DAP4 draft specification document. The versions of those packages that include this support are accessible from our SVN repository on a special branch that exists for DAP4 development and testing.

In the following, I assume you're going to modify a module so that it will support DAP4, in addition to supporting DAP2. The basic steps are pretty simple:

  • Get the dap4 Shrew branch
  • Move your working copy of the module to a dap4 branch
  • Modify the module
  • Write tests
  • Check in the result

How long does this take? On average it take about a day to two days for any given module.

Note: I'm using $svn as if it were a shell variable defined as https://scm.opendap.org/svn.

Get the DAP4 branch

The short version of this is to svn co $svn/branch/shrew/dap4. See Hyrax - Build the Shrew Project for more information on shrew (caveat: that's a fairly old article and unlikely to be completely accurate). Build the code, run the tests, make sure the libdap and bes libraries are installed, etc., so that you are comfortable that the code you're working with is functioning.

Move your module working copy to a dap4 branch

In the shrew project there is a a file names externals.txt that lists the external projects that are checked out to make up shrew. You will see that libdap, bes, and at least 5 of the 14 modules are on a branch. The externals.txt file will look something like this: 

^/trunk/hyrax-dependencies/ src/dependencies

^/branch/libdap/dap4 src/libdap
^/branch/bes/dap4 src/bes

^/trunk/olfs/ src/olfs

^/branch/csv_handler/dap4 src/modules/csv_handler
...
^/branch/gdal_handler/dap4 src/modules/gdal_handler

^/trunk/hdf4_handler/ src/modules/hdf4_handler
^/trunk/hdf5_handler/ src/modules/hdf5_handler

^/branch/ncml_module/dap4 src/modules/ncml_module
^/trunk/gateway_module/ src/modules/gateway_module
...

I'm assuming you're working on a module that does not support DAP4 and so probably does not have a dap4 branch. Beware the old DAP4 branches in our repository; they are evil and should be avoided.

What you need to do to move your module to a dap4 branch in shrew/dap4:

  1. Go to the top-level shrew directory: cd ~/src/dap4 (for example)
  2. Make a branch called dap4 for your module: svn cp $svn/trunk/module $svn/branch/module/dap4 It'll ask for a comment, mumble about dap4...
  3. Edit externals.txt so that the reference to the external module is not ^/trunk/module but instead ^/branch/module/dap4
  4. Run the set-externals.sh script: ./set-externals.sh
  5. Check in the changes to the top-level shrew directory: svn ci -N Again, comment about dap4 and your module in the comment...
  6. Verify the new property value: svn pg svn:externals This should look very similar to the stuff int he externals.txt file and should show the branch is to be checked out into src/modules/module.
  7. Go to the directory that holds your module: cd src/modules/module
  8. Switch to the newly made branch: svn switch $svn/branch/module/dap4 . <-- Note the trailing dot; it means do the switch to the current directory
  9. Verify that the switch worked: svn info The repository URL should point toward the branch.

OK, now we are done with SVN and revision control monkey shines for a while...

Modify the module

Retrieved from "https://docs.opendap.org/index.php?title=Making_the_transition_to_DAP4&oldid=10745"