Servlet Configuration And General Information

Servlets

This document should help you get started configuring your OPeNDAP servlets. These servlets were developed, compiled, and tested using the javac 1.4.1 compiler, the 1.4.1 Java Virtual Machine, and Jakarta Tomcat 4.1.18 (which also provided the javax.servlet packages).

The specific configuration details for servlets distributed with the core Java-OPeNDAP software can be found below:

There are a number of ways to customize the .info service of your OPeNDAP servlet. See:

for instructions on how to perform this customization.

Note: All Examples of web.xml configurations in this document were check against Jakarta Tomcat 4.1.18

Servlet Configuration

The OPeNDAP servlets get their configuration from the servlet's web.xml file. The default location of the web.xml file is (at least in Tomcat 4.1) in $TOMCATHOME/webapps/opendap/WEB-INF (Obviously if the opendap directory gets renamed then things change accordingly.)

Each instance of a servlet running in the opendap servlet area needs an entry in the web.xml file. Multiple instances of a servlet and/or several different servlets can be configured in the one web.xml file. For instance you can have a DTS and 2 instances of the DRDS configured through one web.xml file.

Each instance of a servlet needs a unique name which is specified inside a <servlet> element in the web.xml file using the <servlet-name> tag. This is a name of convenience, for example if you where serving data from an ARGOS satellite you might call that servlet argos.

Additionally each instance of a <servlet> must specify which Java class contains the actual servlet to run. This is done in the <servlet-class> element. For example the DRDS's class name is opendap.servers.sql.drds

Here is a syntax example combining the two previous example values:

    <servlet>
    <servlet-name>argos</servlet-name>
    <servlet-class>opendap.servers.sql.drds</servlet-name>
    .
    .
    .
    </servlet>

This servlet could then be accessed as:

http://hostname/opendap/servlet/argos

You may also add to the end of the web.xml file a set of <servlet-mapping> elements. These allow you to abbreviate the URL or the servlet. By placing the servlet mappings:

        <servlet-mapping>
        <servlet-name>argos</servlet-name>
        <url-pattern>/argos</url-pattern>
        </servlet-mapping>
        <servlet-mapping>
        <servlet-name>argos</servlet-name>
        <url-pattern>/argos/*</url-pattern>
        </servlet-mapping>

At the end of the web.xml file our previous example changes it's URL to:

http://hostname/opendap/argos

Eliminating the need for the word servlet in the URL. For more on the <servlet-mapping> element see the Jakarta-Tomcat documentation.

<init-param> Elements

The OPeNDAP servlets use <init-param> elements inside of each <servlet> element to get specific configuration information.

<init-param>'s common to all OPeNDAP servlets are:

 

DAP2 Test Server (DTS) classname: opendap.servers.test.dts

This servlet is primarily used to test the core code (in particular the DAP). This servlet will take any DDS in it's DDScache (see below) and populate it with invented data per client request. This allows the testing of unusual DDS structures.

DTS Configuration

<init-param>'s unique to the DTS:

Example of web.xml content:

    <servlet>
    <servlet-name>
    dts
    </servlet-name>
    <servlet-class>
    opendap.servers.test.dts
    </servlet-class>
    <init-param>
    <param-name>DebugOn</param-name>
    <param-value>showRequest showResponse </param-value>
    </init-param>
    <param-name>SequenceLength</param-name>
    <param-value>100</param-value>
    </init-param>
    </servlet>

In this example SequenceLength gets set to 100.

DAP2 Relational Database Server (DRDS) classname: opendap.servers.sql.drds

This OPeNDAP server serves data from a relational database to OPeNDAP clients.

The DRDS uses the JDBC interface to connect to the database. This means that to use this server you will need to locate and install JDBC drivers for your database system. (This requirement is for the server only, the OPeNDAP clients that use the server need know nothing about JDBC or SQL). Here are some links that should lead you to the JDBC support pages for some of the more common RDBM's:

Most modern database vendors usually provide JDBC drivers for their product. The glaring exception has been Microsoft, which isn't surprising as they have made no bones about wanting to kill Java. As of the release of MSSQL-Server 2000, Microsoft appears to be offering a JDBC driver for Win2000/XP systems. I have developed using MSSQL-Server for some time (still do actually.) and I have been using a purchased set of drivers from DataDirect Technologies (formerly known as Merant DataDirect). I am using their "SequeLink" product and it's been working great. Find it, and the Microsoft stuff, at the following links:

In this release the DRDS does not support SQL JOIN operations. Each database table must appear as a OPeNDAP Sequence data type in its own DDS file. If your data crosses multiple tables then you will need to make a "view" or a "virtual table" in the database in order to serve the data with the DRDS. This situation will improve in the next major revision. (I have an as yet un-implemented plan to allow the DRDS to support SQL JOIN operations.)

DRDS Datatype Translation

Since the DRDS is reading data from a relational database through a JDBC connection it is important to note that their are several layers of type translation happening in this:

Database -> JDBC -> Java -> OPeNDAP

The Database types are the native types for the particular database that is being read from. The translation from Database->JDBC is handled before we get to the data (most likely by the JDBC Drivers). Our mapping of JDBC type to OPeNDAP types (the intermediate Java types happen in the process) looks like this: 

        JDBC Type       OPeNDAP Type
        TINYINT             Byte
        SMALLINT            Int16
        INTEGER             Int32
        BIGINT              Int32 **NO SENSIBLE MAPPING (Need Int64)
        REAL                Float32
        FLOAT               Float64
        DOUBLE              Float64
        DECIMAL             Float64 **NO SENSIBLE MAPPING (Need Some Kind Monsterous Floating point value)
        NUMERIC             Float64 **NO SENSIBLE MAPPING (ibid)
        CHAR                String
        VARCHAR             String
		
        LONGVARCHAR         Implemented to be read into a String, 
		                       although it is a "BLOB" type and
                               might be better represented as an 
							   Array(of bytes).
							   
        BINARY              Array(of bytes)
        VARBINARY           Array(of bytes)
        LONGVARBINARY       Array(of bytes)
        TIME                String
        TIMESTAMP           String

And are handled in the read() method for each of the corresponding OPeNDAP data types.

 

DRDS Configuration

<init-param>'s unique to the DRDS:

        <init-param>
        <param-name>JDBCDriver</param-name>
        <param-value>com.merant.sequelink.jdbc.SequeLinkDriver</param-value>
        </init-param>

Default: This is a required <init-param>, there is no default value. 


        <init-param>
        <param-name>JDBCconnectionURL</param-name>
        <param-value>jdbc:sequelink://sugar.oce.orst.edu:19996</param-value>
        </init-param>

Default: This is a required <init-param>, there is no default value. 


        <init-param>
        <param-name>JDBCusername</param-name>
        <param-value>guest</param-value>
        </init-param>

Default: This is a required <init-param>, there is no default value. 


        <init-param>
        <param-name>JDBCpassword</param-name>
        <param-value>abracadabra</param-value>
        </init-param>

Default: This is a required <init-param>, there is no default value. 


        <init-param>
        <param-name>JDBCMaxResponseLength</param-name>
        <param-value>50000</param-value>
        </init-param>

Default: : If this parameter is not set (does not appear in as an <init-param>) then it is set to 100.

  

        Dataset {
        Sequence {
        Float64 battery;
        Float64 checksum;
        Float64 data_age;
        } Drifters;
        } EOSDB.DBO;

Thus the hack is invoked. It doesn't matter if the value of this init-param is empty (although if it's not you should set it to "true"), it simply needs to appear in the web.xml file.If you don't want to use this hack then DO NOT even included the init-param "UseDatasetName" in the web.xml entry for the DRDS.

Example: 

        <init-param>
        <param-name>JDBCDriver</param-name>
        <param-value>com.merant.sequelink.jdbc.SequeLinkDriver</param-value>
        </init-param>

Default: If this <init-param> does not appear in the configuration then the hack is not invoked..

Example of web.xml content:

<servlet>
    <servlet-name>
        drds
    </servlet-name>
	
    <servlet-class>
        opendap.servers.sql.drds
    </servlet-class>
	
    <init-param>
       <param-name>JDBCdriver</param-name>
       <param-value> com.merant.sequelink.jdbc.SequeLinkDriver</param-value>
    </init-param>
	
    <init-param>
        <param-name>JDBCconnectionURL</param-name>
        <param-value>jdbc:sequelink://sugar:19996</param-value>
    </init-param>
	
    <init-param>
        <param-name>JDBCusername</param-name>
        <param-value>guest</param-value>
    </init-param>
	
    <init-param>
        <param-name>JDBCpassword</param-name>
        <param-value></param-value>
    </init-param>
	
    <init-param>
        <param-name>JDBCMaxResponseLength</param-name>
        <param-value>300</param-value>
    </init-param>
	
    <init-param>
        <param-name>UseDatasetName</param-name>
        <param-value></param-value>
    </init-param>
	
    <init-param>
        <param-name>INFOcache</param-name>
        <param-value>/usr/Java-OPeNDAP/testsuites/sdds-testsuite/info/</param-value>
    </init-param>
	
    <init-param>
        <param-name>DDScache</param-name>
        <param-value>/usr/Java-OPeNDAP/testsuites/sdds-testsuite/dds/</param-value>
    </init-param>
	
    <init-param>
        <param-name>DAScache</param-name>
        <param-value>/usr/Java-OPeNDAP/testsuites/sdds-testsuite/das/</param-value>
    </init-param>
	
    <init-param>
        <param-name>DebugOn</param-name>
        <param-value>showRequest showResponse JDBC</param-value>
    </init-param>

</servlet>
Additional Information Files

The current implementation of the AbstractServlet provides a ".info" service in addition to the ".dds", ".das", and ".dods" services. This ".info" service returns an html document that renders human readable content in a browser. This document is a synthesis of the contents of the DDS and the DAS. There are provisions for adding additional information, and for overriding the default document. There are three types of files used by the ".info" service to achieve this. They are:

Examples of all of these files can be found in the default INFOcache directory of this servlet distribution.