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.
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.
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.
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:
<init-param> <param-name>DebugOn</param-name> <param-value>showRequest showResponse</param-value> </init-param>Default: If this parameter is not set, or the value field is empty then debugging instrumentation is not turned on.
<init-param> <param-name>DDScache</param-name> <param-value>/usr/DODS/sdds-testsuite/dds/</param-value> </init-param>Default: If this parameter is not set (does not appear in as an <init-param>) then it is set to $TOMCATHOME/webapps/dods/datasets/servlet-name/dds (where servlet-name is the same as the name specified in the <servlet-name> element of the servlet configuration)
<init-param> <param-name>DAScache</param-name> <param-value>/usr/DODS/sdds-testsuite/das/</param-value> </init-param>Default: If this parameter is not set (does not appear in as an <init-param>) then it is set to $TOMCATHOME/webapps/dods/datasets/servlet-name/das (where servlet-name is the same as the name specified in the <servlet-name> element of the servlet configuration) .
<init-param> <param-name>INFOcache</param-name> <param-value>/usr/DODS/sdds-testsuite/info/</param-value> </init-param>Default: If this parameter is not set (does not appear in as an <init-param>) then it is set to $TOMCATHOME/webapps/dods/datasets/servlet-name/info (where servlet-name is the same as the name specified in the <servlet-name> element of the servlet configuration)
DTS Configuration
<init-param>'s unique to the DTS:
<init-param> <param-name>SequenceLength</param-name> <param-value>100</param-value> </init-param>Default: Is set to 5 if this parameter is not set (does not appear in as an <init-param>).
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>
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.