## Data Explorer
for the Web

Data Explorer is a general-purpose software package for data visualization and analysis. It employs a data-flow driven client-server execution model and provides a visual program editor (VPE) that allows the user to create a visualization using a point and click interface.

### Example Web Based Visualizations

1990 Census Data | Home Ownership Trends | Mapping Colorado
--- | --- | ---
Valuing a Perpetuity | Wind Veloctiy | MRI of the Brain

###### Click and drag on the images to view at different angles.

### Interacting with Images

Java Explorer provides interaction modes similar to those in Data Explorer: Rotate, Pan, Zoom, and Pick. A new interaction mode available in Java Explorer is called Orbit mode. Each of the preceeding images corresponds to a sample visualization available thru a link in this page. Click and drag inside an image to sample orbit mode.

- Java Explorer's Pick mode reflects the design of Data Explorer. Select an Image then choose Pick mode. Place a pick by clicking with the left mouse button on something in the image. The original net must contain a Pick tool with appropriate wiring.
- Rotate mode provides a gnomon for rotating in the x and y planes using the left mouse button. Ctrl+mouse button rotates in the z plane.
- Zoom mode provides a 2d area of interest in response the mouse button. Ctrl+mouse button zooms out.
- Pan mode provides a single pan cursor which moves the screen in response to a mouse button drag.
- The Execution control panel provides a 'Reset Camera' button which works the same way Data Explorer's Reset menu bar option works.

### Creating Web Pages from Visual Programs

Starting with a visualization and assuming it's called myprog.net...

- Extend DXMACROS:

      $ setenv DXMACROS "${DXMARCROS}:installDir/java/server/dxmacros"

      or

      $ setenv DXMACROS installDir/java/server/dxmacros

- Start the new copy of dxui:

      $ dx -ui installDir/java/server/bin_arch/dxui \
          -mdf installDir/java/server/mdf/ui.mdf &

- Load myprog.net
- Choose 'Edit/Java/Add Tools' from the VPE menubar.
- Save the visual program.
- Choose 'Edit/Java/Save As Web Page'.
- Edit myprog.make.
- $ make -f myprog.make
- $ make -f myprog.make install

Tech Notes:

- The actual .net file which runs under control of Java Explorer is the same .net file you use when you run with the Data Explorer user interface. The 'Add Tools' step makes minor modifications to the visualization which don't interfere with using the Image window as you normally do.
- Java Explorer will not work with visual programs containing Display tools. You must manually change your nets so that you use Image tools rather than Display tools for all your images.
- Java Explorer will provide camera interaction modes and possibly pick mode for any image whose Image window in the .net file was assigned a name using the 'Options/Change Image Name' menubar option. If you're converting Display tools to Image tools, then you'll probably want to assign a name to the the original Image tools and leave the Display tools unnamed.
- 'Edit/Java/Remove Tools' reverses the affect of 'Edit/Java/Add Tools'. You can add and remove java tools as often as you like without changing the meaning of the visual program. After you add tools, you'll need to choose 'Edit/Java/Net to Applet' and build and install the resulting java code.
- After you've chosen the 'Add Tools' menubar option in the VPE, the visual program will execute more slowly under control of the Data Explorer user interface.
- The 'Save as Web Page' option will reset dxexec and start an execution in order to produce the first batch of images for your web page. This batch of images allows the web page to be complete at initial browser contact. This differs conceptually from the way Data Explorer works. When you run a visualization under control of Data Explorer you must execute once before you can see any images. If you choose the 'Save as Web Page' option when the Data Explorer user interface is not connected to dxexec, then a complete web page will be written however the images will not be saved to your disk. Of course that's perfectly reasonable if you've already saved these images.

#### The generated files

Data Explorer will write the following files:

- myprog.html
- myprog.make
- myprog.java
- For each Image tool which executes myprog%d_0_0.[gif | wrl] Note that if dxexec is executing in a different directory than the Data Explorer user interface, you might have to go searching for the .gif or .wrl files.

#### The generated makefile

myprog.make contains values which you can insert using you favorite editor. A new alternative is to set app-defaults.

>     JARFILE=installDir/java/htmlpages
>     JDKFILE=/usr/jdk_base/lib/classes.zip
>     DXSERVER=installDir/java/server

DXSERVER_DIR can be set to any directory as long as that directory is included in installDir/java/server/class/dxserver.paths.

### Installing Java Explorer

There is no formal installation process for Java Explorer as there is with most software products including Data Explorer. These instructions assume some familiarity with UNIX and pc file systems, http servers, and browsers.

installDir refers to the location in which you've installed OpenDX.

1. Install the full version of OpenDX with Java Explorer compiled.

2. Add installDir/java/server/bin to your path

- For csh
  `$ set path = ($path installDir/java/server/bin)`
- For bash
  `$ PATH=$PATH:installDir/java/server/bin`

1. For PC users... Edit startserver.bat.
2. Install a Web Server (optional)
3. Install J2SE (the Java Runtime Environment).

### Running the Java Explorer 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.

After you've extended your path, you can control the DXServer using the startserver and stopserver scripts.

### Scripts for Controlling the Java Explorer Server

These are located in installDir/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)

### Running the Java Explorer Server on a PC

A batch file is provided in installDir/java/server/bin/startserver.bat to start the pc version of DXServer. Using an editor such as vi or NotePad on your pc, edit in real values for DXROOT, JDKPATH, and JXVSPATH in this script. If you edit this file and then find that it won't run, then reinstall from the original zip file and re-edit the file using a different editor. You may have saved unprintable characters in the file.

### Configuration Files

DXServer reads the following files from its current working directory (which will be installDir/java/server/class):

- dxserver.paths contains directories which are searched for visual program files. DXServer locates the .net file prior to instructing Data Explorer to load the visual program.
- dxserver.hosts contains host names. DXServer will schedule Data Explorer 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:
  - $ setenv DXDATA installDir/java/server/userdata
  - $ setenv DXMACROS $DXROOT/samples/macros:installDir/java/server/dxmacros:installDir/java/server/usermacros
  - $ setenv DXINCLUDES $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 '/'.

Lines beginning with // and empty lines are ignored. DXServer rereads these files as they are updated, so it isn't necessary to restart.

### Changes in This Release

- Instead of the standard GridBagLayout, a lot of the internal layout of control panel components is using the customized AWT TableLayout. This should provide a tighter appearance on controls and make it significantly easier to develop other controls.
- Updated all the code to the Java 1.1 event model. This removes the compilation warnings about deprecated 1.0 functionality and should help performance.
- Changed the multiple page control panel to use a new tabbed window to improve functionality and appearance.
- Now possible to pass data into the network from the html using a DXLInput tool. Extremely useful if html is generated on the fly and the data file for the visualization is not static.
- Correction for FileSelector Interactor, quotes will now be included.
- Corrected the html generator to output a more correct Applet tag and added some new comments.
- Updated the WebOptions macro to make it more clear what the inputs are.
- Changed the way that execution of a network is presented to the user. A green (execution color) line stating "Running. Please Wait.." is presented at the bottom of the control panel.

Changes in earlier releases.

### Java Interfaces

    package dx.net;

    public interface DXLinkHandler {
        public void outputHandler(String key, String msg, Object data);
        public boolean hasHandler(String key);
    };

outputHandler() will be called once each time a value is received from Data Explorer for the corresponding DXLOutput tool. The name of the tool will be in key.

hasHandler() will be called by Java Explorer to determine if the applet intends to handle messages produced the the DXLOutput tool named in key.

### References

> Richard Brealy and Stewart Myers 1981. Principles of Corporate Finance. McGraw-Hill Book Company

### Bugs/Issues

You should expect to have to find workarounds for things in the 'Issues' list and software fixes in Java Explorer for things in the 'Bugs' list.

#### Bugs

- Please see the buglist at http://www.opendx.org/bugs/

[ Java Explorer | OpenDX home page | Help ]