Installation & Configuration

In the sample directory listing above, /usr/local/dnav_root is the portal's base directory. This directory must be accessible and read/write-able from the servlet container -- otherwise DataNav Server will not have access to it either! -- but it should NOT be within the container's own directory tree. Be sure that this directory exists before you install and run Server. When it starts for the first time, it will look for the base directory and create the necessary files and subdirectories to represent an initially "empty" portal. The subdirectory vault is the backing store for the portal's archive vault. The structure and content of this directory is detailed on the Backing Store page. The file authorized.json maintains the login names and passwords (in encrypted form) of all users authorized to administer or modify the portal. It also includes optional contact information (full name, job title, phone number and email address) for each registered user.

The archive state information file, stateinfo,json, contains portal modification information and meta-data on each archive currently mounted in the portal's archive vault. The JSON-formatted file contains a single JSON object with the following fields:

• • "version" (int32) : The file version number, for migration purposes. Current version = 2.

  • "modstamp" (int32) : The portal's current modification stamp. This stamp is incremented each time a client request alters portal contents. The stamp value is included in server responses so that clients can detect when their cached portal content is stale.

  • "lastmod" (int64) : The portal's last-modified time (system time in milliseconds since midnight GMT, January 1, 1970).

  • "archives" (JSON array) : Archive state records. Each element in the array is a JSON array listing meta-data for an archive mounted on the portal -- [uid, mount, stamp, lastUpd, owner, collaborators, checkout]. Here uid is the archive's unique ID (int32), stamp is the archive's current modification stamp (int32), mount and lastUpd are the system times when the archive was originally mounted and when it was last updated (int64), and owner is the login name of the archive's owner (string). The element collaborators is itself a JSON array listing the login names of any portal users that have been designated as collaborators on the archive. If there are no such collaborators, the array will be empty. Finally, the checkout element is another JSON array describing the archive's checkout state. If the archive is NOT currently checked out, the array is empty. Otherwise it is a mixed-content array containing 3 elements: the UID assigned to the internal copy of the archive to which all revisions are applied while the archive is checked out; the system time when checkout occurred; and the login name of the portal user that holds the checkout lock.

The DataNav Server WAR file

DataNav Server will eventually be available for download as a Web application archive, or WAR. A WAR file is simply a Java application archive (JAR) file with specific content and directory structure conforming to the needs of a web application that is deployed within a web server + Java servlets container like Tomcat. The sample file listing below shows the directory structure for the DataNav Server web application:

portalhome.html

assets/

META-INF/

WEB-INF/

      web.xml

      classes/

      lib/

The top-level directory in the WAR is the web application's document root. All static web content and client-side resources associated with the application -- HTML files, Javascript files, image files, and the like -- are stored in this directory or a subdirectory thereof. When the application is deployed and running in the Tomcat container, these web resources will be accessible by entering their URL. In fact, the general public can explore an online DataNav portal by pointing a web browser to the "entry point" page for the DataNav Viewer web client: portalhome.html. Suppose Tomcat is configured to accept HTTP requests on port 8118 (the standard HTTP port is usually 80) and is running on a server with web address www.mylab.edu, and that Server has been deployed within this Tomcat container under the application root dnportal. Then, to browse the online portal managed by this installation, you would enter this URL in a web browser's address bar: http://www.mylab.edu:8118/dnportal/portalhome.html. As it loads this page, the web browser will automatically retrieve and execute the various Javascript files that implement the DataNav Viewer client; the Javascript code will render the web page initially and update it in place as the user interacts with it. All Javascript files and a supporting icon sprites image file are located in the assets subdirectory.

All server-side resources of the DataNav portal -- i.e., DataNav Server -- are stored in the WEB-INF subdirectory. Even though this directory is under the web application's document root, it cannot be accessed from a web browser; it is essentially hidden by the web container. As indicated in the directory listing above, the Java class files and supporting libraries that implement the DataNav Server application are located here, as well as the application's deployment descriptor, web.xml. This XML file contains configuration information for the application's two servlets  -- the builder servlet mediating authenticated read-write access to the portal over HTTPS, and the viewer servlet controlling read-only anonymous client access over HTTP. It also sets the full file system path for the portal's base directory in a context parameter called portalRoot. Here's an excerpt from web.xml showing how the base directory is specified:

<!-- THE PORTAL ROOT DIRECTORY. THIS MUST BE AN ABSOLUTE PATH ACCESSIBLE FROM SERVLET CONTAINER'S HOST. -->

<context-param>

    <param-name>portalRoot</param-name>

    <param-value>/usr/local/dnav_root</param-value>

</context-param>

We recommend that you use /usr/local/dnav_root for your portal's base directory. If you do so, then you should be able to deploy the DataNav Server WAR file without modification. If not, you will need to unpackage the WAR file, edit the portalRoot parameter in web.xml accordingly, then repackage the WAR. Do not change anything else in web.xml -- unless you have to provide additional information for your chosen servlet container. In that case, be sure not to alter the configuration parameters for the two servlet classes.

To install DataNav Server, simply download the WAR file (once it becomes available) and use Tomcat's manager application to deploy and start it. The WAR file is called dnportal.war -- so the application root name (part of the URL) will be dnportal. Should a problem occur that disables the portal, use the manager app to stop the application. You can then examine the backing files under the portal base directory and hopefully fix the issue, then use the manager app once again to restart the portal.