Simple Example

PV-WAVE Advantage > JWAVE User Guide > JWAVE System Introduction > Simple Example

Simple Example

This example shows a simple JWAVE application that processes a transaction between client and server. The Java client sends a number to PV‑WAVE, and PV‑WAVE returns the square root of that number back to the client.

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.

This example includes:

Java client application code

JWAVE wrapper code

Sample output

Client Java Application

A Java application (or applet) resides on the client side of a JWAVE system. Typically, the Java client provides an interface to a PV‑WAVE application running on a remote server. The Java client can send information, including data, to the server for processing. How the processed data is handled is up to the JWAVE programmer. Typically, the client displays graphically the data returned from the server.

Client-side Java code, simple.java 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.

note	You can find the code for this function in:

(UNIX) RW_DIR/classes/jwave_demos/doc_examples/
Simple.java

(WIN) RW_DIR\classes\jwave_demos\doc_examples\
Simple.java

where RW_DIR is the main Rogue Wave installation directory.

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) { }

Here is a breakdown of the main parts of this program.

1. Any required Java and JWAVE class packages must be imported into the Java application. The JWAVE classes reside in:

(UNIX) RW_DIR/classes/JWave.jar

(WIN) RW_DIR\classes\JWave.jar

where RW_DIR is the main Rogue Wave 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” the 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.

The JWAVE Wrapper Function

A JWAVE wrapper function is a PV‑WAVE routine that contains JWAVE-specific function calls. These JWAVE calls typically include the function GETPARAM, which retrieves parameter information and data directly from a Java client application. The following function, SIMPLE, demonstrates the basic form of the JWAVE wrapper.

JWAVE wrapper function, simple.pro can be found in:

(UNIX) RW_DIR/jwave-3_6/lib/user/simple.pro

(WIN) RW_DIR\jwave-3_6\lib\user\simple.pro

where RW_DIR is the main Rogue Wave installation directory.

As shown in JWAVE wrapper function, simple.pro, 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.

JWAVE wrapper function, simple.pro

FUNCTION SIMPLE, client_data

; Retrieve the parameter and data from the Java client.

value = GETPARAM(client_data, ’NUMBER’, /Value, Default=1)

; Process the data.

mydata = SQRT(value)

; Return the result to the client (the default parameter

; name is DATA)

RETURN, mydata

END

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

Byte—BYTE

Short—INT

32-bit Integer—INT32

64-bit Integer—LONG

Float—FLOAT

Double—DOUBLE

String—STRING

You can also pass arrays of these basic data types of up to eight dimensions. Note that the Java Short maps to PV‑WAVE INT, and that Java Integer maps to PV‑WAVE LONG. This is because of differences in the internal data representations of these integers.

note	You can use either numeric objects or primitives (for example, java.lang.Short or short).

The PV‑WAVE RETURN statement sends the results back to the Java client. “get” methods in the Java client are then used to extract the returned parameters and data.

Figure 1-8: Passing Data between Client and Wrapper further illustrates the flow of parameters and data between the JWAVE client and server.

Figure 1-8: Passing Data between Client and Wrapper

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.

Running the Application

To run the simple application:

1. Start the JWAVE Manager. For instructions, see "Starting the JWAVE Manager" on page 127.

2. Move to the following directory:

(UNIX) RW_DIR/classes/jwave_demos/doc_examples

(WIN) RW_DIR\classes\jwave_demos/doc_example

3. Run the program by typing the following command:

java Simple

note	To run this application, the following items must be included in your CLASSPATH:

RW_DIR/classes/JWaveConnectInfo.jar

RW_DIR/classes/JWave.jar

. (the current directory)

where RW_DIR is the main Rogue Wave installation directory.

Sample Output

Here is the output from this simple JWAVE application:

The answer is: 1.4142135623730951