DODS Java Software

Servlet Configuration And General Information


Servlets

This document should help you get started configuring your DODS 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-DODS software can be found below:

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

for instructions on how to perform this customization.

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


Requirements

You will need a servlet engine. I developed This release of Java-DODS using " Tomcat".


Tomcat: First you will need to install a web server which supports servlets (aka a servlet engine). The current "reference standard" for this release is jakarta-tomcat-4.1.18 from Apache. Go get it from:
http://jakarta.apache.org/tomcat/. Follow the instructions and get it installed.


Installation

The easiest way to install the distibuted servlets is to get the "dods.war" file with the latest distribution ($Name: v_1_1_7 $).

Put the "dods.war" file in appropriate directory of your servlet engine. For tomacat-4.1.18 you would place it in $TOMCATHOME/webapps.

Restart the servlet engine (Tomcat), this will unpack the "dods.war" file into the directory $TOMCATHOME/webapps/dods. (Recently I have had problems with this method. If the WAR file doesn't unpack when Tomcat is restarted, create the directory $TOMCATHOME/webapps/dods manually. Using a terminal window change directory to the one you just created. run the command "jar -xf ../dods.war" then restart Tomcat. This should work.)

Once it's unpacked you will need to configure the servlets. With the "web.xml" file whipped into shape, restart the
servlet engine (tomcat) again. You should be up and running!

If things aren't working for you, try turning on the Debug flags showRequest and showResponse.

If you get stuck contact support@unidata.ucar.edu. If they can't help you, they will find me (Nathan Potter), and I will help you get it working.


Servlet Configuration

The DODS 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/dods/WEB-INF (Obviously if the dods directory gets renamed then things change accordingly.)

Each instance of a servlet running in the DODS 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 dods.servers.sql.drds

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

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

This servlet could then be accessed as:

http://hostname/dods/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/dods/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 DODS servlets use <init-param> elements inside of each <servlet> element to get specific configuration information.

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

 


DODS Test Server (DTS) classname: dods.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>
		dods.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.


DODS Relational Database Server (DRDS) classname: dods.servers.sql.drds

This DODS server serves data from a relational database to DODS 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 DODS 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 DODS 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 -> DODS

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 DODS types (the intermediate Java types happen in the process) looks like this:

JDBC Type        DODS 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 a 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 DODS 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>
		dods.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-DODS/sdds-testsuite/info/</param-value>
	</init-param>
	<init-param>
		<param-name>DDScache</param-name>
	<param-value>/usr/Java-DODS/sdds-testsuite/dds/</param-value>
	</init-param>
	<init-param>
		<param-name>DAScache</param-name>
		<param-value>/usr/Java-DODS/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 DODSServlet 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.