Chapter 11. Java Explorer

Partial Table-of-Contents

11.1 About Java Explorer

Java Explorer is a network based server and a set of Java applets that allow Data Explorer networks to run from within a web browser. In an authoring step, the visualization expert selects to add the required Java Explorer modules; thus, activating the option to then generate an appropriate html page and applet code that corresponds to the network's user interface Control Panels and Images. Once the Java Explorer modules are added, the network can be executed from either the standard DX user interface or a web browser via the Java Explorer server, eliminating dual-source problems. The Image macro when running in the Java Explorer environment outputs image formatted files for the web server to send. Results of a visualization can be sent as Images (single or multiple), or geometry (as VRML), determined by the visualization programmer or the end-user's settings. Direct user interactions (e.g. rotate, pick, etc.) are implemented by the client or the server depending upon the presentation mode.

In order to view a network with a web browser, the network is first converted to a web page, installed into the Java Explorer server's specified web page directory and then the server must be started. If Java Explorer is to be used to allow users via the Internet to run specified visualizations, then a web server must also be running and set up in conjunction with Java Explorer.

If Java Explorer is to produce images to send to a web browser, it is required that ImageMagick be included within the DX framework.

11.2 Creating Web Pages

Once a visualization is ready to be shared via Java Explorer, the network must be converted to a web page. The following steps show how to perform this transformation:

Figure 95. Java Explorer Tools Options

1. Load network - Start by loading the appropriate network into the Visual Programming Environment.
2. Choose Add Tools - Once loaded, choose the Java->Add Tools option of the Edit menu of the VPE menu bar. This will add a page to the network named "java tools" and set up the control panels and Image modules to work with the Java applets.
3. Save the visual program - The visual program can still be used as before within the DX user interface. No need to save a second copy.
4. Choose Save As Web Page - Once the network is saved, the Java->Save As Web Page option from the Edit menu is made available. This will save a minimum of four new files within the same directory as the network.
5. Compile the Java files - Of the files created, one is myprog.java and another is myprog.make, where myprog is the name of your network. The .java file must be compiled to create a .jar file that can be used with the Java Explorer server. Data Explorer helps by providing a make file. make is a command line utility to compile programs. Invoke the make file by issuing the following command:

   make -f myprog.make

6. Install the Java files - The files must be put into the Java Explorer server's specified web page directory. Again the make file helps since it has some notion of where these files should be stored. To install using the make file, issue the following command:
   

   make -f myprog.make install

Technical 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 is assigned a name using the 'Options/Change Image Name' menu bar option. If you're converting Display tools to Image tools, then you'll probably want to assign a name to 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' menu bar 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.
• It is possible to pass information into the network from java parameters within the html. To do this, set a parameter with the name DXLInput, for example <param name=DXLInput value='filename="cloudwater.dx";'>. This will replace the DXLInput named filename with the value "cloudwater.dx". Multiple parameters can be sent in by using compound assignments, for example <param name=DXLInput value='filename, length = "cloudwater.dx", 1.23 ;'>.

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.

Generated Makefile

myprog.make contains values which you can change using you favorite text editor, such as where files should be installed if you do not want them installed into the default location or where files are installed if DX is not installed in its default directory. Some of the relevant variables are:

• JARFILE - Location of dx.jar file.
• JDKFILE - Classpath needed to compile Java programs.
• DXSERVER - Directory where the Java Explorer server resides.
• DXSERVER_DIR - Directory where the .net file is installed.
• JAVADIR - Directory where web files are stored.

Java Explorer Macros

In order for Java Explorer to work, several macros were created to extend the Image Module. The macros are listed below:

• DXExport
• ImageExport
• VRMLExport
• WebOptions

11.3 Interacting with Images

Java Explorer provides interaction modes similar to those within Data Explorer: Rotate, Pan, Zoom, and Pick. A new interaction mode available in Java Explorer is called Orbit mode. Orbit mode produces an applet with a group of images that allows the users to feel as if they can minimally rotate the object quickly.

• 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.

11.4 Displaying Captions: The CaptionLabels Applet

Java Explorer sends information to the end-user's browser via an imageWindow applet as discussed in Interacting with Images. In addition to displaying text in the Image window, you can also display captions and other labels by sending strings to DXLOutput modules within a network.

• A web page generated by the VPE will contain a CaptionLabels applet for each DXLOutput module. Modify the generated applet tags as desired to set the size, font, and colors.
• See the AutoInsurance demo for an example.

11.5 Displaying HTML: The HTMLDisplay Applet

Java Explorer can also display HTML generated by your network. (E.g., to provide even more formatting for labels, include icons, links, etc.)

• As with CaptionLabels, send the HTML to a DXLOutput module.
• In the generated html page, you must change the class name in the applet tag from "CaptionLabels.class" to "HTMLDisplay.class"
• Optionally, add a PARAM to the applet, setting NAME to "Content-type" and VALUE to "text/html".
• HTMLDisplay will also render plain text (use content type "text/plain") and rich text format (use "text/rtf").
• Scrollbars are added automatically if the rendered document is larger than the applet's size.
• Full support for rendering HTML 3.2. Links work. Forms and buttons do not.

11.6 Linking to Other Web Pages: The HTMLDisplay Applet

Java Explorer can cause the user's browser to open a desired web page (e.g., to link an object in your scene to an external resource).

• Send a string containing the URL and a target window name to a DXLOutput. (Example: send the string "http://www.opendx.org Foo" to open the OpenDX home page in window Foo.) Standard HTML target names (e.g., "_self") apply.
• Change the applet's class to HTMLDisplay.class.
• Add a PARAM with NAME="Content-type" and VALUE="text/url".
• The applet itself simply displays the URLs you send it. You can make the applet size 1x1 pixel if you don't want to see it.