User's Guide - The Java Explorer Server

11.7 The Java Explorer Server

The Java Explorer server is a java application that manages (via DXLink) DX executives that run DX networks for web clients. The Java Explorer server will run multiple clients per executive and will round-robin executives on a list of servers. This provides a measure of scalability.

Running the Server

You run one DXServer process on a machine and it serves all requests from all browsers pointed at the machine.

The web pages generated using Java Explorer use applets which detect the ip address of the machine from which they were loaded and attempt to contact a DXServer using that ip address.

If you are browsing web pages using a URL beginning with file:/, then the applets will be able to use only a DXServer running on the same machine as your browser.

Scripts for Controlling the Server

For UN*X, two scripts are installed for controlling the Java Explorer server. See their description below. Add the Java Explorer server's bin directory to the path environment variable to use these directly. The default Java Explorer server bin directory is /usr/local/dx/java/server/bin.

Format: startserver [ -webpage htmlfile | [ -outdir dir -outurl url ]] \
		[ -help ] [ -debug ] [ -verbose ] [ -memory Mbytes ] \
		[ -dxroot dir ] [ -user user ]
    -webpage.......complete path of a Java Explorer web page
    -outdir........directory into which new images should be written
    -outurl........url of the -outdir argument relative to the document base
    -help..........this message
    -debug.........print message traffic
    -verbose.......print cmd line args passed to DXServer
    -version.......the software version number of this script
    -foreground....run in the foreground in order to satisfy init
    -memory........set the amount of memory dxexec uses. 
    -dxroot........use dir as DXROOT
    -user..........run the script under a different user id
    -sessions......max number of simultaneous Data Explorer sessions (default: 1)
    -morehelp......examples

stopserver [ host ]
     host..........the host machine of the DXServer (default is localhost)

Configuration Files

In the following notes, installDir is the installation directory of the Java Explorer server - in OpenDX this is typically /usr/local/dx/java.

The Java Explorer server reads the following files from the class working directory (which will be installDir/java/server/class):

dxserver.paths contains directories which are searched for visual program files. The Java Explorer server locates the .net file prior to instructing Data Explorer to load the visual program.
dxserver.hosts contains host names. The Java Explorer server will schedule Data Exlporer sessions on the hosts in dxserver.hosts in round-robin fashion. Before using this mechanism you will want to modify the following environment variables which are normally set by the startserver script:
- DXDATA - Location to the user data files; typically installDir/java/server/userdata
- DXMACROS - Location to the macros directories, typically set up as $DXROOT/samples/macros:installDir/java/server/dxmacros:installDir/java/server/usermacros, note how more directories can be added by concatenating them onto the list separated by a colon.
- DXINCLUDES - Location of the directory which the executive will search for included scripts. typically $DXMACROS.
The startserver script modifies these for use on localhost. However, settings which work on localhost won't work on a remote machine. You must also modify dxserver.paths so that it contains a pathname beginning with a '/'.

Within these files, lines beginning with // and empty lines are ignored. The Java Explorer server re-reads these files as they are updated, so it isn't necessary to restart.

The Java Explorer server also reads the DX application defaults file from the invoker's home directory on startup. Several settings can be added to this file to change the behavior of the server so all command line options do not have to be specified upon launch.

DX*htmlDir - should be changed so that it does not include the htmlpages directory. For example:
```
DX*htmlDir: /usr/http/java
```
DX*userHtmlDir and DX*userJarFile. The default settings are user and user.jar respectively. Consequently, dxui will generate makefiles which compile applets into user.jar and install user.jar into htmlDir/userHtmlDir. By default, all web pages generated by dxui will not be installed into installDir/java/htmlpages. Instead they'll be installed into a directory beside htmlpages.

Configuration Notes

In order to use Java Explorer, dx must be in the invoker's path and started with "startserver" from the installDir/server/bin/ directory. If no httpd web server is running or has yet to be configured, start a browser locally and point it at file:///$DROOT/java/htmlpages/Status.html, where $DXROOT is the DX installation directory--typically /usr/local/dx.

httpd should point to the directory structure such that "htmlpages" and "output" are accessible via the same prefixed url (e.g.for a given whatever, whatever/htmlpages and whatever/output should work). various additions for mime.types and or httpd.conf may be required. For example, to add the text/html mime type for .htm files, the line should read:

text/html html htm

If Java Explorer is going to create vrml that httpd serves, mime.types should have an entry

x-world/x-vrml wrl

Variations exist, and sometimes this is in httpd.conf or srm.conf (depending upon your httpd) using the "AddTypes" directive, as in

AddType x-world/x-application .wrl

[ OpenDX Home at IBM | OpenDX.org ]