JWAVE lets you create Java client applications that communicate directly with PV-WAVE running on a remote server. On the server side, PV-WAVE code is used to analyze data and generate graphics. On the client side, a Java applet (or application) lets users interact with the PV-WAVE session and display the graphics returned from PV-WAVE.
JWAVE offers four separate client/server connection models:
Figure 1-2 shows a JWAVE client that is connected to the server via a direct socket connection.
Figure 1-3 shows a JWAVE client that is connected to the JWAVE Web server via an HTTP connection. The JWAVE Web is bundled with JWAVE. It handles client connections and manages JWAVE sessions on the server.
Figure 1-4 shows a JWAVE client that is connected to the server via the JWAVE Servlet. The JWAVE Servlet plugs into any Web server that accepts servlets.
NOTE: HTTP and socket connection methods can be used simultaneously by multiple JWAVE client applications; the JWAVE server can respond to several client applications at the same time.
TIP: In general, you must be a Java developer to develop client-side JWAVE applications or applets. If your Java experience is limited, you can still create useful JWAVE applications using the generic JWAVE applet described in Chapter 2, The Generic JWAVE Applet.
Figure 1-1 JWAVE client-serverconfiguration. Java applets (or applications) communicate with a JWAVE server through HTTP connections. In this model, the client contacts a CGI program running on a Web server. The CGI then starts the JWAVE Manager. You can use this type of connection simultaneously with a direct socket connection, shown in Figure 1-2.
Figure 1-2 JWAVE client-serverconfiguration. Java applets (or applications) communicate with a JWAVE server via direct socket connections. You can use this type of connection simultaneously with an HTTP connection, shown in Figure 1-1.
Figure 1-3 Java applets (or applications) communicate directly with the JWAVE Web server. The JWAVE Web Server includes the JWAVE Manager, therefore, the client can connect to the JWAVE Manager directly with a URL address.
Figure 1-4 Java applets (or applications) communicate with aWeb server using the JWAVE Servlet. The JWAVE Servlet plugs into any Web server that accepts servlets. Once the JWAVE Servlet is configured properly, clients can connect to the JWAVE Manager directly with a URL address.
NOTE: A Java applet is run within another application, usually a Web browser. A Java application runs on its own, without the need for another controlling program. The distinction is usually irrelevant for JWAVE (with the exception of applet security restrictions), as the applet/application decision depends on how the users access the program, rather than on what the program does.
JWAVE allows client applications to remain thin, because all of the data analysis can be done on the server. Typical client applications allow users to run remote PV-WAVE applications on the server and then retrieve only the desired results (such as plots and/or analysis results).
Figure 1-5 shows a basic client configuration, where the client happens to be an applet running in a browser.
Figure 1-5 JWAVE client applet. A JWAVE applet requires JWAVE Java classes (in the JAR file) and configuration information. The browser uses an HTML page to load the applet.
where
VNI_DIR is the main Visual Numerics installation directory. These classes provide the means for Java applications to:
JWave.jar file. This file provides information necessary (for example, a server socket ID) for the applet to contact the remote JWAVE server.
TIP: If you want to use an IDE for JavaBeans application development, see Chapter 7, Using JWAVE Beans.
Figure 1-6 shows the basic configuration of the JWAVE server components.
Figure 1-6 The server side of a JWAVE system. The JWAVE Manager application listens for client connections and takes appropriate actions, such as starting a PV-WAVE session.
The JWAVE Manager can manage multiple PV-WAVE sessions, or a client application can make several sequential requests using the same PV-WAVE session. This allows faster updates (as new sessions are not started for each request). This also allows data to remain with the session (in memory) for use by subsequent requests (rather than making round trips back to the client).
manager (manager.bat on Windows) is used to control and configure the JWAVE Manager. This script is described in detail in Chapter 8, JWAVE Server Configuration.
As shown in Figure 1-7, the JWAVE Manager uses configuration information from the file jwave.cfg. (By default, output is sent to the terminal.) For information on using the manager command and changing server configuration, see Setting Up the JWAVE Server.
Figure 1-7 JWAVE Manager handles activity on the JWAVE server
The individual PV-WAVE sessions log their output, by default, to the terminal. You can change this default (send information to a log file) using the Configuration Tool. For more information, see Setting Up the JWAVE Server.
TIP: These functions are called "wrappers" because they "wrap" a PV-WAVE application with JWAVE-specific routines (such as GETPARAM).
NOTE: The regular PV-WAVE functions that JWAVE wrappers cannot use mainly include the user interface features, such as WAVE Widgets and VDA Tools.
We've kept this example simple to demonstrate the fundamental building blocks of a JWAVE application: creating a connection, passing parameters and data to from the client to the server, and retrieving results from the server. Later, we will discuss more complex, and practical, scenarios.
Example 1-1 shows the Java client application. This client simply sends a number to the JWAVE server, and then prints out a result that is returned from the server. In this case, PV-WAVE executes a function that returns the square root of the number sent from the client.
TIP: You can find the code for this function in:
Example 1-1 Client-side Java code, simple.java
// (1) Import JWAVE classes import com.visualnumerics.jwave.JWaveExecute; public class Simple { public static void main(String[] args) { JWaveExecute command = null; try { // (2) Auto-connect to a new PV-WAVE Session // Set a command object to use the Wrapper function named "SIMPLE" command = new JWaveExecute("SIMPLE"); // (3) Set a parameter named "NUMBER" to the value 2 // (NUMBER is expected by the SIMPLE wrapper function) command.setParam("NUMBER", 2); // Execute the command: // Pass parameters, Run the Wrapper, get returned parameters command.execute(); // (4) Get the returned data, named "DATA" Double answer = (Double) command.getReturnData("DATA"); // (5) Print the result System.out.println("The answer is: " + answer); } catch (Exception e) { // Report any problems System.out.println(e.toString()); } finally { // Shut down the PV-WAVE session (it would eventually // time out and shut itself down if we did not do this) try { if (command != null) command.getConnection().shutdown(); } catch (Exception ignore) { } } } }
1. Any required Java and JWAVE class packages must be imported into the Java application. The JWAVE classes reside in:
where
VNI_DIR is the main Visual Numerics installation directory. 2. A connection must be established between the Java client and the JWAVE server. This is accomplished by instantiating the
JWaveExecute object. 3. The name of the JWAVE wrapper function is specified in the
JWaveExecute constructor. The JWaveExecute object contains the methods needed to "pack" parameters and data to be sent to the server. In this case, a parameter named NUMBER with a value of 2 is set. The execute method sends the parameter and data to the server and "executes" the JWAVE wrapper function (called SIMPLE) 4. The
getReturnData method is used to retrieve the result from the JWAVE server. The result, in this case, is named DATA. 5. The result received from the server is printed on the client.
SIMPLE, demonstrates the basic form of the JWAVE wrapper. Example 1-2 can be found in:
where
VNI_DIR is the main Visual Numerics installation directory.As shown in Example 1-2, JWAVE wrapper functions take a single input parameter, usually called
client_data. This parameter is automatically passed to the JWAVE wrapper from the Java application (when the execute method is called). The JWAVE wrapper receives parameter names and data through this parameter. The function GETPARAM, which is a JWAVE-specific PV-WAVE function, unpacks the parameters and data so that the wrapper can use them.
Example 1-2 JWAVE wrapper function, simple.pro
FUNCTION SIMPLE, client_data
value = GETPARAM(client_data, 'NUMBER', /Value, Default=1)
mydata = SQRT(value) ; Return the result to the client (the default parameter ; name is DATA) RETURN, mydata END
SIMPLE function receives a parameter called NUMBER from the Java client. The Value keyword specifies that the actual value of the parameter be returned to the JWAVE wrapper. The types of Java variables (and their corresponding PV-WAVE types) that can be passed between the client and server are listed in the following table.
| JAVA Data Types | Corresponding PV-WAVE Data Types |
|---|---|
| Byte | BYTE |
| Short | INTEGER |
| Integer | LONG |
| Float | FLOAT |
| Double | DOUBLE |
| String | STRING |
NOTE: You can use either numeric objects or primitives (for example,java.lang.Shortorshort).
Figure 1-8 further illustrates the flow of parameters and data between the JWAVE client and server.
Figure 1-8 Parameters and data are passed between the Java client and the JWAVE wrapper. Java methods and special PV-WAVE functions are used to package and extract the data and parameters.
NOTE: To run this application, the following items must be included in yourCLASSPATH:
If you do not want to write original Java programs, you can create useful JWAVE applications using the generic JWAVE applet. This applet, discussed in the next chapter, allows you to run PV-WAVE applications on the server and display results in a Web browser with little or no client-side programming. If you wish, you can use JavaScript and HTML forms to create a user interface for your applet.
