Java 2 Standard Edition (J2SE)
Minimum: Java 1.2
Recommended: Java 1.4.1 or newer.
This software was developed and tested against the 1.4.1 release of the J2SE
Minimum: Optional (Only required if you lan on working on the parsers.)
Recommended: 2.1 or higher. (Warning!)
Javacc takes a grammar file and produces a Java source code file from it. All of these resulting Java source files are checked into the CVS tree, so unless you anticipate working on the grammar files themselves you will not need to get Javacc. Most of the OPeNDAP parsers rely on the JavaCC tool to build. The parsers are built from a grammar file with a .jj extension. The grammars contain the rules for both the scanner and the parser (and thus encapsulate both the functionalities of lex and yacc). The Javacc tool appears to be a red headed step child of the Java development community. Originally it was written by someone at Sun Microsystems ( possibly Bill Joy?). Eventually it was farmed off to small company called WebGain. It now appears that WebGain went under in the Dot Com bust and now Sun has it in an Open Source project under the BSD license. I think it survives because it does something important, we can't live without it, and there is nothing else like it out there. If you are going to work on the parsers you should :
Minimum: 4.1.18
Recommended: 4.1.27
Note: This code has not been tested against version 5 of Tomcat!
The servlets were developed and tested using Jakarta/Tomcat 4.1.18. In particular, the code was linked against the servlet.jar bundled with this particular version of Tomcat. This is not (to the best of my knowledge) a library that is included with the standard Java distributions.
Minimum: 1.5.2 (Warning!)
Recommended: 1.6 or higher
This software now builds entirely with ANT. If you haven't already got ANT, then go get it: You need it. There is a master build file in the top level directory, Java-OPeNDAP/build.xml which relies on the numerous build files located in the Java-OPeNDAP/buildfiles directory. The master build file contains only a few simple targets. The serious developer will want to read and understand the collection of build files in the buildfiles directory.
Compiling the source: This should be straight forward. Just go to the top level directory and type "ant compile". For more detailed instructions you should read the master build file, Java-OPeNDAP/build.xml, and the core build files in Java-OPeNDAP/buildfiles.
Compiling the parsers: First let me point out that unless you are actively involved in parser development for OPeNDAP you shouldn't bother with this. The parsers are built using JavaCC, which takes grammar files (.jj) and makes Java code from them. This Java code is checked into the OPeNDAP CVS tree and thus does not need to be rebuilt unless the underlying grammar (.jj) files have been changed, which is strongly discouraged unless you are a OPeNDAP core programmer. I suggest you turn back now. Still here? I warned you...
The parsers target in the opendap.xml build file uses the <javacc> task build the parsers. The javacc task requires that the local installation of JavaCC be identified as an attribute. In order to build the parser you will need to create a separate properties file (that is not checked into CVS). This file must be called javacc-config and it must live in the Java-OPeNDAP/buildfiles directory. The content of the javacc-config file must be the property JavaCC.home and its value should be set to the top level directory of the JavaCC distribution on your development system.
Here is an example of the content of the javacc-config file:
JavaCC.home=/usr/local/javaccOnce you have created the javacc-config then the parsers target in Java-OPeNDAP/buildfiles/opendap.xml should work, at least within the constraints of the Warning.
Using the deployment targets: There is a separate ANT build file called catalina-targets.xml in Java-OPeNDAP/buildfiles which contains a number of targets (webapp-deploy, webapp-remove, webapp-redeploy) that allow the developer to build the software and deploy it into a running Jakarta-Tomcat (aka Catalina) server, and one target (webapp-list) to check on the running servlets in Tomcat. Also, for the sake of rapid development and conservation of effort, the opendap.xml build file contains two targets (deploy, and quick-deploy) that will compile the project (with and without the JavaDoc's respectively) and put it into a running Tomcat server.
All of these targets require that you modify your local installation of ANT (see below) and that you create an ANT properties file to configure the ANT tasks to talk to and authenticate with Tomcat.
The properties file must called catalina-config and it must be located in Java-OPeNDAP/buildfiles. The catalina-config file must contain three property definitions: Catalina.url, Catalina.username, and Catalina.password.
Here is an example of the content of the catalina-config file:
Catalina.url=http://localhost:8080/manager Catalina.username=admin Catalina.password=secretstuff
Where the username and password pair will authenticate as a Tomcat manager (see below)
Additionally you will need to configure ANT as described below in this excerpt from the Tomcat 4 online documentation:
In addition to the ability to execute Manager commands via HTTP requests Tomcat 4 includes a convenient set of Task definitions for the Ant (version 1.4 or later) build tool. In order to use these commands, you must perform the following setup operations: * Download the binary distribution of Ant from http://jakarta.apache.org/ant. You must use version 1.4 or later. * Install the Ant distribution in a convenient directory (called ANT_HOME in the remainder of these instructions). * Copy the file server/lib/catalina-ant.jar from your Tomcat 4 installation into Ant's library directory ($ANT_HOME/lib). * Add the $ANT_HOME/bin directory to your PATH environment variable. * Configure at least one username/password combination in your Tomcat user database that includes the manager role.
You may wish to read more about the configuration issues for Tomcat. Check out the online documentation in your running version. Assuming that you have tomcat running on port 8080, then at: http://yourhost:8080 You should find the additional information you need.
Warning: There exists a version conflict between some versions of ANT and some versions of JavaCC. If you have JavaCC 2.1 or 2.0 then the parsers should compile fine, no matter what version of ANT you have. However, if you are using JavaCC 3.0 or newer (released after the JavaCC project migrated from WebGain to Java.Net) older versions of ANT will fail to correctly identify the JavaCC libraries. The mail and bug archives indicate that the problem was fixed as of 5/26/2003, but the patch won't migrate into a release until version 1.6. You can grab a nightly build of Ant release 1.6beta as work around until 1.6 hits the street. Good luck.
Additional Libraries:
The core software depends on several third part libraries. All of these are included with the distribution, and these (should) be the ones that the code was compiled against for development and testing purposes. It is possibly (in fact likely) that newer versions of these libraries are available from the various development teams that create these products. Replace them at your own risk.
The JDOM package, version Beta 9, available from jdom.org
The gnu regexp package, version 1.1.4, available
from gnu.org
The gnu getopt package, version 1.0.6, available form gnu.org
The Apache SOAP package, version 2.3.1, available from apache.org
Building the Java-OPeNDAP software should be very simple.
This will compile all of the distributed software, but nothing more. Each sub project in Java-OPeNDAP has it's own build file with targets that are unique to it. For more detailed information you should read (and try to understand) the ANT files in Java-OPeNDAP/buildfiles. For those of you using an IDE you will have to follow your own "path" to get this going.