The Generic JWAVE Applet

This chapter explains how you can get started almost immediately using JWAVE to publish PV-WAVE graphics on a Web page. With the generic JWAVE applet provided by Visual Numerics, you can execute a JWAVE wrapper function on the server and display output from the server in a Web browser.

The generic JWAVE applet lets you do this with very little programming. All you need to write is the JWAVE wrapper function (in PV-WAVE) and some simple HTML code. The generic applet takes care of the rest of the work, such as contacting the server, opening a connection to the server, and retrieving data and graphics from the server.

Later, you will see how you can use HTML forms and JavaScript to create a user interface for the generic applet. This interface can be used to modify the appearance of graphics returned from the server, to generate different types of plots, to send client data to the server, and many other possible functions.

Simple Applet Example

Let's look now at a very simple implementation of the generic applet. This applet asks PV-WAVE to generate and return a 2D plot, which the applet displays. The resulting plot is shown in Figure 2-1.

This section discusses the HTML code used to display the applet and the JWAVE wrapper function that is executed by PV-WAVE on the server.

Example 2-1 shows the simple HTML file in which this sample JWAVE applet is embedded.

---

TIP: You can find examples similar to this one in the directory:

---

(UNIX)VNI_DIR/classes/jwave_demos/JWaveApplet

(Windows)VNI_DIR\classes\jwave_demos\JWaveApplet

where VNI_DIR is your main Visual Numerics installation directory.

HTML
HEAD
TITLEJWaveApplet Example 1/TITLE
/HEAD
BODY
APPLET CODE="com.visualnumerics.jwave.JWaveApplet"
        CODEBASE="../../classes"
        ARCHIVE="JWave.jar, JWaveConnectInfo.jar"
        WIDTH=450
        HEIGHT=500
  PARAM NAME="FUNCTION"            VALUE="TESTPLOT"
  PARAM NAME="TRANSIENT_SESSIONS"  VALUE="YES"
/APPLET
/BODY
/HTML

The CODE, CODEBASE, ARCHIVE, WIDTH, and HEIGHT parameters are standard applet parameters used to call any applet. The CODE parameter gives the class name of the applet. This class was installed on the server when you installed JWAVE. The CODEBASE parameter tells the applet where to find the root of the Java class tree. The ARCHIVE parameter specifies Java Archive (JAR) files that contain the JWAVE Java class files that are required by the applet. The JAR file called JWave.jar is shipped with JWAVE and contains all of the class files you need to develop JWAVE client applications, including the JWaveApplet class file. The JAR file JWaveConnectInfo.jar describes how to connect to the server. The WIDTH and HEIGHT parameters simply specify the size of the applet display area.

---

TIP: The generic JWAVE applet accepts a number of PARAM tags, many more than are used in this example. Refer to the Javadoc reference on the JWaveApplet class for detailed information on all of the generic applet's PARAM tags. For information on Javadoc, see Using the JWAVE Javadoc Reference.

---

The FUNCTION parameter takes one argument, TESTPLOT, which is the name of the JWAVE wrapper function on the server. This is the PV-WAVE function that is executed on the server. This function will be described later. It creates a plot and sends it back to the client.

By setting the TRANSIENT_SESSIONS parameter to YES, we are asking the JWAVE Manager on the server to shut down the PV-WAVE session as soon as the client-server transaction is completed. This request makes sense because all we want is to get back a single picture from PV-WAVE. No further processing is required. Therefore, it is best to shut down the PV-WAVE session. If TRANSIENT_SESSIONS were set to NO (the default), the PV-WAVE session would remain active on the server until explicitly terminated (when the applet is unloaded, which occurs when you move to a new HTML page in your browser).

A JWAVE wrapper function is a PV-WAVE function that can communicate with a JWAVE client. This particular wrapper function doesn't do much. It simply creates a plot and returns it to the client. In this case, no parameters were passed from the client to the server.

Example 2-2 A minimal JWAVE wrapper function

FUNCTION TESTPLOT, client_data 
      PLOT, FINDGEN(10), Linestyle=0, PSym=6 
      RETURN, 0 
END 

When RETURN is called, the wrapper automatically returns the plot to the client applet, where it is displayed.

In the next example, we'll add some JavaScript^TM functions to the client HTML file. These functions will enable the client to control the appearance of the graphic generated by PV-WAVE on the server.

In this example, we described a very simple scenario where a client applet executes a function on the JWAVE server, and the server sends a picture back to the client. In that case, no parameters or data were passed from the client to the server. The server simply generated some data, created a plot, and sent it back to the client.

The next section discusses how to pass parameters and data from client to server using JavaScript.

Using JavaScript to Control the Applet

If you do not wish to program Java applications, you can use JavaScript^TM to provide a wide range of client-side control for the generic JWAVE applet. JavaScript is a scripting language that allows you to create a user interface for HTML pages.

http://developer.netscape.com/docs/manuals

Example 2-3 demonstrates how you can add JavaScript controls to an HTML page for passing parameters and data between the generic applet and the server.

For instance, JavaScript can be used to create client-side Web pages with a graphical user interface. The GUI can be used with the generic JWAVE applet, for example, to change plot characteristics such as line color, axis range, plot symbols, and so on. When used with the generic JWAVE applet, JavaScript can be used to create complex client-side applications rapidly and efficiently.

---

TIP: Visual Numerics has provided several applet demonstrations, including the one used in this example, with your JWAVE installation. For information on running the demonstration applets, see Running the Applet Demonstrations.

---

In this section, we discuss:

• The HTML file with JavaScript

• The JWAVE wrapper function

• Demonstration applets

There are a few differences between this example HTML file and the one shown in Example 2-1. The biggest difference is that this HTML file contains JavaScript commands. JavaScript is an object-based scripting language that can be embedded into HTML files.

In this example, we use JavaScript to call methods that are defined in the JWAVE generic applet.

---

TIP: For detailed information on the generic applet methods that can be used with JavaScript, refer to the Javadoc page on JWaveApplet (in the jwave package). For information on Javadoc, see Using the JWAVE Javadoc Reference.

---

Example 2-3 HTML file with JavaScript calls

HTML
HEAD
TITLEJWaveApplet Example 2/TITLE
/HEAD

SCRIPT LANGUAGE=JavaScript 
// Update the plot
  function updatePlot() {
        if (! document.JWavePlot.isStarted()) {
      // Wait for applet to start before trying to updatePlot
      setTimeout("updatePlot()", 250); 
      return;
    }
        // Must get a session before we can set anything
    document.JWavePlot.openSession();
    // Set background and data line colors
    document.JWavePlot.setNamedColor('BACKGROUND', 'LightGray');
    document.JWavePlot.setNamedColor('LINE', 'Blue');
    // Set line style (dashed)
    document.JWavePlot.setParam('LINESTYLE', 2);
    // Turn off plot symbols
    document.JWavePlot.setParam('SYMBOL', 0);
    // Update the plot (and close the transient session)
    document.JWavePlot.execute();
  }

BODY onLoad="updatePlot()"

H1JWaveApplet Example 2/H1

APPLET NAME="JWavePlot"
          CODE="com.visualnumerics.jwave.JWaveApplet"
          CODEBASE="../../"
          ARCHIVE="JWave.jar, JWaveConnectInfo.jar"
WIDTH=450
        HEIGHT=500
  PARAM NAME="FUNCTION"           VALUE="TESTPLOT"
  PARAM NAME="EXECUTE_ON_START"   VALUE="NO"
  PARAM NAME="TRANSIENT_SESSIONS" VALUE="YES"
/APPLET

/BODY
/HTML

Let's look at the JavaScript function, updatePlot, that is embedded in the HTML file.

First, the "if" clause with the setTimout function ensures that the plot does not update until the applet is ready.

The next call in this function is:

document.JWavePlot.openSession();

This call follows the JavaScript object convention, where document is the object name referring to the browser window itself. JWavePlot is the name by which JavaScript recognizes the applet (specified with the applet's NAME tag), and openSession is a method defined in the generic JWAVE applet, JWaveApplet (specified with the CODE tag).

We need to call openSession to open a connection with the JWAVE Manager on the server. Normally, the applet connects and executes immediately upon startup. But we want to delay the execution until the parameters are set. That is, we want to open a session, set the parameters, and then execute the JWAVE wrapper.

The next few JavaScript calls set color values and parameters to be sent to the JWAVE wrapper function on the server.

document.JWavePlot.setNamedColor('BACKGROUND', 'LightGray');
document.JWavePlot.setNamedColor('LINE', 'Blue');
document.JWavePlot.setParam('LINESTYLE', 2);
document.JWavePlot.setParam('SYMBOL', 0);

The function setNamedColor sets a parameter name and a color value. In the JWAVE wrapper function on the server, these parameters are interpreted by corresponding GETPARAM functions, and their values are retrieved. Once retrieved, those parameter values can be plugged directly into PV-WAVE functions. In this case, TESTPLOT is going to plug the parameters set in the HTML file into the PV-WAVE PLOT command.

The final call in our JavaScript function is:

document.JWavePlot.execute();

The execute method sends parameters to the server and executes the JWAVE wrapper function. This in turn generates a plot, which is sent back to the client and displayed.

Finally, we use a couple of PARAM tags to prevent the applet from executing the JWAVE wrapper immediately when the applet starts. First, we need to set the EXECUTE_ON_START parameter to NO. This parameter prevents the JWaveApplet from executing when the applet starts. Then, having told the applet what not to do, we need to tell the applet what to do when it is loaded. This is the purpose of the onLoad parameter that is set in the applet's BODY tag. The onLoad parameter tells the applet to execute the JavaScript function updatePlot when the HTML page loads. And, to reiterate, this JavaScript function does the following:

• Opens a connection to the JWAVE server.

• Sets four different parameters that are used to send values to PV-WAVE.

• Executes the JWAVE wrapper on the server.

---

TIP: Because JavaScript supports form objects, you can use JavaScript to create interactive GUIs for your client applets without any Java programming. For information about more complex JavaScript demonstrations created by Visual Numerics, see Running the Applet Demonstrations.

---

The JWAVE Wrapper

To take the actions requested by the client, the JWAVE wrapper must retrieve and "unpack" the parameters and data sent from the client.

The functions used to unpack data sent from the client are: GET_NAMED_COLOR and GETPARAM. PLOT commands are then constructed using the unpacked values.

You can find the following JWAVE wrapper in:

(UNIX)VNI_DIR/jwave-3_0/lib/user/testplot.pro

(Windows)VNI_DIR\jwave-3_0\lib\user\testplot.pro

where VNI_DIR is the main Visual Numerics installation directory.

Example 2-4 JWAVE wrapper function, TESTPLOT

FUNCTION TESTPLOT, client_data
 
   ; get colors
   black = '000000'xL
   white = 'FFFFFF'xL
 
   back_color = GET_NAMED_COLOR("BACKGROUND", Default = black)
   axis_color = GET_NAMED_COLOR("AXES", Default = white)
   line_color = GET_NAMED_COLOR("LINE", Default = white)
 
   psym_colors = GET_NAMED_COLOR("SYMBOLS", Default = [white], 
/Color_Set)
 
   ; get data
   data = GETPARAM(client_data, 'DATA', /Value, Default = 
FINDGEN(10))
 
   ; get plot attributes
   linestyle = GETPARAM(client_data, 'LINESTYLE', /Value, Default = 
1)
   psym = GETPARAM(client_data, 'SYMBOL', /Value, Default = 6)

   ; Plot axes
   PLOT, data, /NoData, Background = back_color, Color = axis_color
   ; plot lines
   IF linestyle GE 0 THEN $
     OPLOT, data, Linestyle = linestyle, Color = line_color
   ; plot symbols
   IF psym NE 0 THEN $
     OPLOT, data, PSym = ABS(psym), Color = psym_colors
RETURN, 0
END

The GETPARAM Function

GETPARAM (a JWAVE-specific PV-WAVE function) is designed to retrieve non-color related parameters and values. In Example 2-4, the first GETPARAM call retrieves data values to plot. The next two GETPARAM calls are used to set the linestyle and symbol style for the plot.

The Value keyword is used to specify that an actual value be returned by GETPARAM, and the Default keyword specifies a default value to use in case no value is received from the client. Therefore, the GETPARAM call:

data = GETPARAM(client_data, 'DATA', /Value, Default = FINDGEN(10))

returns the actual data values to be plotted, which can be used in a PLOT command, such as:

PLOT, data, ...

---

NOTE: Detailed information on the parameters and keywords of the GETPARAM and GET_NAMED_COLOR functions are available in the PV-WAVE online help system and in Appendix A, JWAVE Wrapper API.

---

The GET_NAMED_COLOR Function

If a color is specified by the client with the generic applet's setNamedColor method, that color can be retrieved by PV-WAVE with the GET_NAMED_COLOR function.

The GET_NAMED_COLOR function converts a named color specified on the client into a color index that PV-WAVE can understand. For instance, the returned value from GET_NAMED_COLOR can be used with the PLOT command's Background keyword.

For example, GET_NAMED_COLOR might return a color index for the background color of a 2D plot.

back_color = GET_NAMED_COLOR("BACKGROUND", Default = black)
data = GETPARAM(client_data, 'DATA', /Value, Default = FINDGEN(10))
PLOT, data, Background = back_color 

Visual Numerics has provided a set of demonstration HTML files that use JavaScript controls.

---

NOTE: To run these applets, you must have a working installation of JWAVE and the JWAVE Manager must be running on the server. To run these demonstrations, you must also have a browser that supports JDK 1.1.

---

You can find these demonstration files in:

(UNIX)$VNI_DIR/classes/jwave_demos/JWaveApplet

(Windows)VNI_DIR\classes\jwave_demos/JWaveApplet

You are free to copy any of the form and JavaScript functions in these demonstration applets for your own use. The examples include:

• applet_demo1.html This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. All plot parameters (and data) are set/generated by the JWAVE wrapper function. This applet is similar to Example 2-1.

• applet_demo2.html This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. There is some simple JavaScript in this page that initializes some parameters (colors and linestyle) used by the JWAVE wrapper function. The wrapper function generates its own data. This applet is identical to Example 2-3.

• applet_demo3.html This HTML page contains a single JWaveApplet that calls JWAVE to make a plot. There is some JavaScript in this page that sets parameters used by the JWAVE wrapper function. The parameters set by JavaScript are controlled by HTML FORM tags. There are some JavaScript helper functions provided in this page to help the FORM tags interact with JWAVE. The wrapper function still generates its own data.

• applet_demo4.html There are two JWAVE applets running in this HTML page. They share a connection to a single PV-WAVE session, and thus can share data on the server side. One applet is invisible, and uses the JWaveExecute class to create some data on the server. The resulting data stays on the server. It is stored by the Data Manager. The second applet uses the JWaveView class to make a plot of the data created by the first applet.

• applet_demo5.html There are two JWAVE applets running in this HTML page. They share a connection to a single PV-WAVE session, and thus can share data on the server side. One applet is invisible, and uses the JWaveExecute class to create some data. The resulting data stays on the server (stored by the Data Manager). The second applet uses the JWaveView class to make a plot of the data created by the first applet, using one of two wrapper functions that each create a particular type of plot.

Summary

In this chapter we explained how the generic JWAVE applet, JWaveApplet, can be used to create client applications that use PV-WAVE as a numerics and graphics server. The generic applet allows you to use JavaScript functions to control the applet and pass data and parameters between the client and server. Visual Numerics has provided several sample applets that you can run and examine on your own. Feel free to reuse these applets and their helper functions for your own applications.