THREDDS DQC Servlet - Version 0.3

Comments to THREDDS mail list

Version 0.3 (5 August 2004).

The THREDDS DQC Servlet is a framework for providing DQC services. It can be set up to handle any number of DQC services each of which consists of a DQC document, the queries allowed by that DQC document, and the responses to those queries. To use the DQC Servlet for a new dataset collection and corresponding DQC, requires extending thredds.dqc.DqcHandler (an abstract java class) and implementing several methods to handle your dataset collection setup (more details on this below). The DqcServlet comes with two example DqcHandler subclasses: LastModel and JplQuikSCAT.

Content

• DQC Servlet
  

DQC Servlet

Download

The DQC Servlet as of version 0.3 is part of the THREDDS servlet which includes a variety of other tools including a THREDDS catalog validator and catalog to HTML converter. For more details and to download the THREDDS servlet, see the THREDDS server status page.

Installation

Follow the instructions for installing the THREDDS server on the THREDDS server documentation page.

Configure

The configuration file (config.xml) for your DqcServlet goes in the WEB-INF/dqcServlet/config/ directory. The config file is a ucar.prefs.XMLStore file. There is an example config file (config.mlode.xml) located in the example/ subdirectory that is setup to run the two example DqcHandlers. It looks like this:

<?xml version='1.0' encoding='UTF-8'?>
<preferences EXTERNAL_XML_VERSION='1.0'>
  <root type='user'>
    <map>
      <beanCollection key='config' class='thredds.dqc.server.DqcServletConfigItem'>

        <bean name='latestModel'
          description='Handle DQC requests for Unidata IDD model data on motherlode.'
          handlerName='thredds.dqc.server.LatestModel'
          handlerConfigFileName='configDqcHandler.mlodeLatestModel.xml'
          dqcFileName='dqc.mlodeLatestModel.xml' />

        <bean name='jplQuikScat' description='Handle JPL QuikSCAT DQC requests.'
          handlerName='thredds.dqc.server.jplQuikSCAT.JplQuikSCAT'
          handlerConfigFileName='configDqcHandler.JplQuikScat.xml'
          dqcFileName='dqc.JplQuikScat.xml' />

      </beanCollection>
    </map>
  </root>
</preferences>

Each bean in the bean collection represents one DQC service. The bean "name" identifies this service in the URL and the "description" is a brief description of this service. The "hanlderName" is the DqcHandler subclass and the "handlerConfigFileName" is the name of the config document used by the DqcHandler [TODO: currently a config doc is actually required even if the handler doesn't use one so allow handlerConfigFileName to be empty string]. The "dqcFileName" is the DQC file for this service [TODO: this should be handled by each DqcHandler as appropriate (e.g., in handler config) ]. The DQC document for the "latestModel" service configuration above would be referenced with http://localhost:8080/dqcServlet/latestModel/dqc.xml

Writing a DqcHandler

Minimal

To write your own DqcHandler, you need to subclass the DqcHandler and implement two methods:

• initWithHandlerConfigDoc( InputStream, InputStream), and
• handleQuery( HttpServletRequest, HttpServletResponse) .

The initWithHandlerConfigDoc() method can be used to initializes your DqcHandler. This method is not handled very well and has some weird requirements; I'll be cleaning it up in a future version. [TODO: get rid of the two inputStream requirement, implement default version that returns without doing anything]. This method must be implemented in your handler though it is not required to do anything. Two InputStreams are required because the first handler developed used a ucar.util.prefs.XMLStore document to store the configuration information. For various reasons, the XMLStore.createFromInputStream() method requires two different InputStreams for the same document (not the same InputStream twice). See the ucar.util.prefs documentation for more information.

The handleQuery() method handles all queries to a DqcHandler. From the HttpServletRequest, figure out what the user is requesting and then formulate the correct response. [TODO: decide what the IOException and ServletExceptions really mean. Is the ServletException anything on the servlet that makes the request unhandlable? Is the IOException only for IO problems between servlet and client or if IO problems happen on servlet, e.g., reading a config file.]

See the online javadocs for more details.

Extended Framework

I have started working on an extended framework to simplify the development of new DqcHandlers. This framework provides some classes for dealing with the allowed queries described in a DQC [TODO: look at John's thredds.catalog.query package], user requests, and encapsulation of the backend storage for the dataset collection framework.  Things that might currently be useful are the SelectFromRange class, the UserQuery interface (the JplQuikScatUserQuery might be more useful to look at than the interface), and the BackendStorage interface (doesn't exist yet, see JplQuikScatDodsFileServer). The rest (and some of this) isn't very well developed or defined. This will be extended in a future release.

There are a number of the thredds.dqc classes that are not used (just things I started trying), i.e., Dqc, QueryAction, and Selection.