README file on the installation CD. When you install JWAVE from the CD, you are presented with the following three installation options:
Installs PV-WAVE, which includes JWAVE components used for server-side development of JWAVE wrappers.
Installs components used for client Java application development (JWAVE class library, reference documents, and JWAVE Beans). See Figure 8-1.
Installs JWAVE server-side components required for deployment of JWAVE applications (JWAVE Manager, JWAVE Web Server, JWAVE Servlet, communication with JWAVE clients, and PV-WAVE). See Figure 8-2.
Figure 8-1 JWAVE client directory structure
Figure 8-2 JWAVE server directory structure, where VNI_DIR is the main Visual Numerics installation directory. Other directories may exist, depending on installation options.
JWAVE Client Development
A Java Development Kit (JDKTM) (Version 1.1.5 or later).
JWAVE Client Side (optional for using Beans) Beans Development Kit (BDK) (Version 1.0 July 98 or later), Swing (Version 1.1 or later).
JWAVE Server A Java Runtime Environment (JRE) (Version 1.1.5 or later).
For more detailed information on the JWAVE Manager, see Setting Up the JWAVE Server.
Starting the
Windows Users: If the JWAVE Service has been installed and configured (see Installing the JWAVE Service), open the Services window from the Control Panel, selectJWAVE Service, then clickStartto start the JWAVE Service).
cd VNI_DIR/jwave-3_0/binmanager start
cd VNI_DIR\jwave-3_0\binmanager startVNI_DIR is the main Visual Numerics installation directory.When it starts up, the JWAVE Manager writes information to the standard output. This information will vary depending on how the server is configured. Generally, the messages report all of the PV-WAVE sessions that are started and other status information.
Parsing persistent sessions: Session Pool is starting new session (1/1).... [Information on individual PV-WAVE sessions started on the server appears here...] Waiting for connection...
Testing to See If the
cd VNI_DIR/jwave-3_0/bin manager pingcd VNI_DIR\jwave-3_0\bin manager ping
VNI_DIR is the main Visual Numerics installation directory.If the test succeeds, the JWAVE Manager returns the following message:
PING was successful with SocketConnection(localhost:6500)
Configuring the JWAVE Manager for HTTP Connections
manager config
NOTE: When the configuration tool starts, a dialog appears that informs you that you cannot save server connection parameters when the JWAVE Manager is running. Dismiss this dialog box. For this exercise, you will only change client connection parameters.
Client Connection Info button to view the Client Connection Info panel.
JWave HTTP URL text field, enter the correct URL to the JWAVE server. By default, this URL is:
http://myhost:6580/JWave where
myhost is the name of the host where the JWAVE Manager is running.
Use Socket Connection checkbox. We are going to connect to the JWAVE Web server through an HTTP connection.
Use HTTP Connection checkbox.
Save Configuration button, and then select File=
Exit to exit the dialog box.
http://myhost:6580/JWave
http://myhost:6580/jwave_demos
Includes startup command options and stopping the JWAVE Manager.
Describes how to remake configuration files in which the JWAVE Manager and connection information for clients and servers is stored.
Explains the features of the JWAVE Manager Configuration Tool, which allows you to configure server and client connection parameters.
Describes the methods by which the JWAVE Server can communicate with clients. These methods include direct sockets, CGI, Web server, and servlet connections.
There are several methods by which client applications can communicate with the JWAVE Manager. These methods are described in JWAVE Server Options.
manager command.
NOTE: Client applications cannot contact the JWAVE server unless the JWAVE Manager is running.
cd VNI_DIR/jwave-3_0/bin manager
cd VNI_DIR\jwave-3_0\bin manager
VNI_DIR is the main Visual Numerics installation directory.The
manager command takes one argument and, in most cases, an optional parameter. Here is the list of arguments and parameters used with the manager command.Usage
Starts the JWAVE Manager daemon. Enter the path to the jwave.cfg file if it is not located in the same directory as the manager command. manager ping
Tests to see if the JWAVE Manager is running.
manager config [path_to_jwave.cfg]
Opens the JWAVE Manager Configuration tool. Enter the path to the jwave.cfg file if it is not located in the same directory as the manager command. Shuts down the JWAVE Manager.
Shutting Down the
Windows Users: If you started a JWAVE Service through the Service's dialog box, use the Service's dialog box to shut it down instead of using themanager shutdowncommand.
cd VNI_DIR/jwave-3_0/bin manager shutdown [password]
cd VNI_DIR\jwave-3_0\bin manager shutdown [password]
VNI_DIR is the main Visual Numerics installation directory and a password is required if a password was defined during server configuration (see page 129).
The window in which you typed the shutdown command displays the following message:
TIP: Since manager shutdown can be executed from any machine that has client access (even across the Web), it is recommended that a password be set for the JWAVE server. Assignment of a password for shutdown will prevent accidental shutdown of the JWAVE Manager by unauthorized users. (The instructions for assigning a password for shutdown are given in Using the JWAVE Configuration Tool).
With socket connections, the client connects to the JWAVE Manager either: a) through a direct socket connection, or b) through a CGI program that then hands a socket connection to the server.
With HTTP connections, the client connects to the JWAVE Manager either: a) through the JWAVE Server, or b:) through the JWAVE Servlet.
The Direct Socket Connection Option
Use Socket Connection option. Also, in this dialog box, set the Port and Host Name fields.
MANAGER_START_TCPIP to TRUE.
NOTE: To configure the JWAVE Manager to accept both socket/CGI and HTTP connections, set bothMANAGER_START_TCPIPandMANAGER_START_HTTPtoTRUE.
The CGI Connection Method
Use CGI Connection option. Also, in this dialog box, set the JWaveCGI URL field.
MANAGER_START_TCPIP to TRUE.
VNI_DIR/jwave-3_0/bin/bin.
arch/JWaveCGI[.exe] in your Web server's CGI area, where arch is the architecture of your system (such as solaris or i386nt), and [.exe] is a filename extension found on Windows systems only.
Using the JWAVE Web Server
Use HTTP Connection option.
MANAGER_START_HTTP to TRUE.
VNI_DIR/jwave-3_0/bin/jwave_http.cfgThis file is described in Appendix D, HTTP Configuration File.
Using the JWAVE Servlet
com.visualnumerics.jserver.JWaveServlet onto your Web server (such as JavaWebServer).
VNI_DIR parameter for the servlet to point to the Visual Numerics installation directory (VNI_DIR).
Use HTTP Connection option.
TIP: Once you have installed the JWAVE Servlet, you can test the URL by pointing your Web browser there. For example, type
http://myserver/servlet/JWave
NOTE: Do not use themanager shutdowncommand with the JWAVE Servlet. Instead, use the Web server's servlet administration tools to shut down the server.
Configuration Files
manager, is the JWAVE Manager startup script, which is discussed in the previous section. The other files are configuration files that contain information required for JWAVE to run properly.
VNI_DIR/jwave-3_0/bin/manager[.bat]
VNI_DIR/jwave-3_0/bin/
VNI_DIR/classes/JwaveConnectInfo.jar
VNI_DIR/jwave-3_0/bin/jwave_http.cfg
Remaking the
VNI_DIR) or the Java Runtime Environment (JRE) (JAVA_BIN_DIR), you must do the following:
cd VNI_DIR/jwave-3_0/binmanager shutdownmake_config VNI_DIR JAVA_BIN_DIRcd VNI_DIR\jwave-3_0\binmanager shutdownmake_config VNI_DIR JAVA_BIN_DIR
VNI_DIR is the main Visual Numerics installation directory and JAVA_BIN_DIR is the JRE directory.The
make_config script:
manager[.bat] and jwave.cfg files
manager[.bat] script that contains only the VNI_DIR and JAVA_BIN_DIR property definitions
jwave.cfg to their built-in default values
jwave.cfg file, you may copy those definitions from the jwave_cfg.bak file into the new jwave.cfg file, or use the JWAVE Configuration Tool to modify the new jwave.cfg file (described in Using the JWAVE Configuration Tool).
cd VNI_DIR/jwave-3_0/bin manager startcd VNI_DIR\jwave-3_0\bin manager start
VNI_DIR is the main Visual Numerics installation directory.
Windows Users: We recommend that you start and stop the JWAVE Manager using the JWAVE Service (page 115).
Starting the JWAVE Configuration Tool
cd VNI_DIR/jwave-3_0/bin manager shutdown manager config
cd VNI_DIR\jwave-3_0\bin manager shutdown manager config
VNI_DIR is the main Visual Numerics installation directory.
Manager Properties
Use the Manager Properties window in the JWAVE Configuration Tool (Figure 8-3) to:
Figure 8-3 Manager Properties in the JWAVE Configuration Tool
TIP: To get help for a specific parameter, select the parameter, then clickParameter Help. You can also refer to JWAVE Manager Configuration Properties for an description of each property.
This column may contain any of the following codes that describe the parameter's type:
R Read Only. Parameters with this type are displayed for information purposes only and their values cannot be changed in the JWAVE Configuration Tool.
D Indicates that the parameter's current value is the default value.
U Indicates a parameter defined by a user for passing environment variables to PV-WAVE sessions. This type of parameter is not used by JWAVE Manager.
$ Indicates that the parameter can be referenced by name in other parameters. More information on this type of parameter is available in Parameter Help...
This column lists the names of the parameters currently defined. = Value Column
This column lists the values of the parameters currently defined. These parameters are described in JWAVE Manager Configuration Properties.
Value Field
This field allows you to enter a value for any parameter that does not have the R type in the Type column. Displays the Define New Parameter dialog box for adding a new parameter (see Adding Properties).
Delete
Removes the selected user-defined parameter from the list of parameters. Sets the value of the selected parameter to its default value. Sets the value of the selected parameter to the value entered in the Value field. (Pressing the Enter key in the Value field is equivalent to clicking Set.) Displays the Help on Parameters dialog, which contains information about the selected parameter. Saves the configuration to the jwave.cfg file (path shown to the left of the button).
If the JWAVE Manager is running when you try to save the configuration by clicking Save Configuration, a message displays reminding you to shut down JWAVE Manager. Shut down the Manager and then click Save Configuration again. (See Shutting Down the JWAVE Manager.)
Modifying a Property
Manager Properties to display the list of configuration parameters.
Value field.
Set or press Enter. The new value for the parameter appears in the = Value list.
Save Configuration to save your changes. The changes are saved in the jwave.cfg file.
Resetting a Single Property to Its Default
Manager Properties to display the list of configuration parameters.
Set to Default. A letter D appears next to the parameter in the Type list. The default value for the parameter appears in the = Value list
Save Configuration to save your changes. The changes are saved in the jwave.cfg file.
Adding Properties
jwave.cfg file:
Manager Properties to display the list of configuration parameters.
New Parameter. The Define New Parameter dialog box appears.
Name field. For example: mydata
Value field. For example: /user/data/mydata
Set. The new parameter appears in the Parameter list of the Manager Properties window. U appears next to the parameter in the Type list.
Save Configuration to save your changes. The changes are saved in the jwave.cfg file.
JWAVE Manager Configuration
NOTE: Some properties (usually directories) can be referenced by name in other properties. For example, the default for the propertyWRAPPER_PATHis$JWAVE_DIR/lib/userand the propertyJWAVE_DIRis an "expandable" property. Such properties are marked with a $ in the descriptions that follow.
For security, you can specify a list of regular expressions to limit the wrapper functions that the PV-WAVE session will execute. Leave this field blank (empty string) to allow any valid JWAVE function. Separate multiple expressions with a comma (,). (Default: [null])
HTTP_CONFIG
Specifies the HTTP configuration file. (Default: VNI_DIR/jwave/bin/jwave_http.cfg) Specifies the port number used by the JWAVE Web server. (Default: 6580).
NOTE: The normal default for Web servers is port 80; however, you must be an administrator or super user to start a server on port numbers less than 1024.
Read-only. Specifies the directory where JWAVE is installed. (Default: VNI_DIR/jwave-3_0)
JWAVE_SHUTDOWN Specifies the shutdown procedure for the PV-WAVE session. You can use this procedure to do site-specific shutdown after every PV-WAVE session. (Default: JWAVE_SHUTDOWN)
JWAVE_STARTUP Specifies the startup procedure for the PV-WAVE session. You can use this procedure to do site-specific initialization for every PV-WAVE session. (Default: JWAVE_START)
MANAGER_LOG $ Specifies the JWAVE Manager log file location, filename, and file continuation instructions. Leave this field blank (empty string) to discard logging. Use TERMINAL to have the logs go to the JWAVE Manager's terminal (stdout). Prefix the file with a "+" to append to the log when the manager is restarted (otherwise a new file will be created). (Default: TERMINAL)
manager start
MANAGER_START_TCPIP
If set to TRUE, the command:
manager start
MAX_SESSIONS
Specifies the maximum number of simultaneous PV-WAVE sessions the JWAVE Manager will allow. Note that the session limit is also controlled by licensing, but this parameter may be useful for server performance tuning. (Default: 100)
PASSWORD Specifies the server password for remote access to configuration information and JWAVE Manager shutdown. (Default: [null])
PERSISTENT_SESSION_IDS
Specifies a list of PV-WAVE session ID numbers (positive numbers). The specified sessions do not time out as do regular sessions. After a PV-WAVE session is started, the JWAVE Manager attempts to contact (ping) it. This property specifies the number of ping attempts that will be made before the session is considered dead (and an error exception is returned to the client). (Default: 5)
PING_INTERVAL Specifies the delay (in milliseconds) between PING_ATTEMPTS. (Default: 500)
PORT $ Specifies the socket port number where the JWAVE Manager listens for client connections. Usually just a number, but may also be specified as hostname:port_number if you have multiple network addresses and want the JWAVE Manager to listen on only one. (Default: 6500)
NOTE: The port number must be1024 for JWAVE Manager to be contacted via CGI (the Web).
Specifies the log file location, filename, and file continuation instructions for ERROR output from individual PV-WAVE sessions. A "#" character in the parameter will be replaced by a session ID number. If there is no "#", all sessions log to the same file. Leave this field blank (empty string) to discard logging. Use TERMINAL to have the logs go to the JWAVE Manager's terminal (stdout). (Default: $MANAGER_LOG)
SESSION_IDLE_CHECK_INTERVAL Specifies how often (in minutes) to check for idle (unused) PV-WAVE sessions. (Default: 1)
SESSION_IDLE_TIMEOUT Specifies how long (in minutes) idle (unused) PV-WAVE sessions will remain alive. After this time, idle sessions are closed. If a session is timed out, it is no longer available to its client. (Default: 5)
SESSION_OUT_LOG Specifies the log file location, filename, and file continuation instructions for output from individual PV-WAVE sessions. A "#" character in the parameter will be replaced by a session ID number. If there is no "#", all sessions log to the same file. Leave this field blank (empty string) to discard logging. Use TERMINAL to have the logs go to the JWAVE Manager's terminal (stdout). (Default: $MANAGER_LOG)
SESSION_POOL_SIZE Sets the number of PV-WAVE sessions to pre-start. If there is a PV-WAVE session in the pool, a client's first contact becomes faster because it will not have to wait for the PV-WAVE process to start up. These are only used for auto-assigned sessions.
SESSION_START_TIMEOUT Specifies the maximum time (in seconds) to wait for a PV-WAVE session to start. Sessions that take longer will be killed and an error exception will be returned to the client. You may wish to increase this value on slow or heavily loaded servers. (Default: 15)
SOCKET_BACKLOG Specifies the maximum queue length (number of concurrent connections) for incoming connection requests (used by the ServerSocket class). If a connection request arrives when the queue is full, the connection is refused. (Default: 50)
SYSTEMROOT $ Windows NT only. Required for servers running on Windows NT. Set this property to your Windows NT directory. (Default: C:\Windows or the value of SYSTEMROOT at install time)
VERBOSE Specifies logging level. Valid values are 0 (silent) to 3 (verbose). (Default: 2)
VNI_DIR $ Read-only. Required. The value is set by the manager[.bat] script.
WAVE_DIR $ Read-only. Specifies the directory where PV-WAVE is installed. (Default: $VNI_DIR/wave)
WRAPPER_PATH Specifies directories that contain your custom JWAVE wrapper functions (.cpr files). You can separate multiple directories on Windows NT with a ; (semi-colon) character, on UNIX with a : (colon) character. The standard PV-WAVE and JWAVE lib directories are automatically included. (Default: $JWAVE_DIR/lib/user)
Client Connection Info
Figure 8-4 Client Connection Info in the JWAVE Configuration Tool
Port or Host Name (it is preferred that both fields be filled in).
Use Socket Connection, Use HTTP Connection, Use CGI Connection (or any combination of the three).
Use CGI Connection is selected, JWaveCGI URL must be filled in.
HTTP Connection is selected, Jwave HTTP URL must be filled in.
Specifies the port number where the JWAVE Manager is running. (See also the PORT parameter in the Manager Properties list of the JWAVE Configuration Tool and its description in JWAVE Manager Configuration Properties).
Host Name Specifies the name of the machine where the JWAVE Manager is running. If this field is blank or set to localhost, clients will only be able to connect (via sockets) when running on the same machine where the JWAVE Manager is running.
JWave HTTP URL Specifies the URL to the Web server or JWAVE Servlet that is associated with the JWAVE Manager. It can be an http or https protocol URL.
JWaveCGI URL Specifies the URL to the CGI program that is associated with the JWAVE Manager. It can be an http or https protocol URL. If you want clients using CGI to contact a different JWAVE Manager than the one defined in the Port and Host Name fields, append a question mark and that information to the end of the URL. For example:
http://webhost/cgi-bin/JWaveCGI?manager_host:6501
http://SERVER-NAME/cgi-bin/JWaveCGI[.exe])
NOTE: The https protocol uses the Secure Socket Layer (SSL) to connect to the server. If you specifyhttps, both the client and server must supporthttps. Most browsers and Web servers do supporthttps; however, the Java Development Kit (JDK) does not. Therefore, if you save the client configuration with anhttpsprotocol, you will always receive a message that says "unable to test https".
When checked, specifies that clients will be able to contact the JWAVE Manager using direct Socket connections.
Use HTTP Connection When checked, specifies that clients will be able to contact the JWAVE Manager as a Web server or servlet.
Use CGI Connection When checked, specifies that clients will be able to contact the JWAVE Manager using the JWaveCGI URL.
Use Compression When checked, specifies that the data stream be compressed. Use compression if you intend to send very large datasets. Compression saves network time in transmission of the data, but costs some CPU time for compression and decompression on the client and server.
TIP: The client checks the selections Use Socket Connection, Use HTTP Connection, and Use CGI Connection in the order they are listed: 1) Socket, 2) HTTP, 3) CGI. Normally, we recommend that you only choose one method. The client-side getConnection method is optimized to be faster for the initial connection if only one method is checked.
If you wish to establish a connection order other than the one that is available in the dialog box (Socket, HTTP, CGI), then you need to edit the file:
VNI_DIR/classes/JWaveConnectInfo.jar
Installing the JWAVE Service
VNI_DIR\jwave-3_0\bin\bin.i386nt\jwaveservice -install
VNI_DIR is the main Visual Numerics installation directory.
Configuring the JWAVE Service
Services icon. The Services window appears (see Figure 8-5).
Figure 8-5 Windows NT Services window listing the JWAVE Service
JWAVE Service.
Startup... The Service window appears (see Figure 8-6).
Figure 8-6 Windows NT Service window for configuring the JWAVE Service
Startup Type to Automatic. This causes the JWAVE Manager to run as a background process and keep running even when there are no interactively logged-in users.
OK in the Service window to close it and accept your changes.
Start in the Services window to start up the JWAVE Manager in the background.
Stopping the JWAVE Service
jwave.cfg file, if a password has been defined.To shut down JWAVE Manager running as a Service:
Services icon. The Services window appears (see Figure 8-5).
JWAVE Service.
Stop.
Close.
Monitoring the JWAVE Service
SrvMgr.exe) supplied with both the Windows NT Server and the Windows NT Workstation Resource Kit.
Starting and Stopping the JWAVE Service from the Command Line
net command after installing and configuring the Service as described above. To start the JWAVE Service from the command line:
net start jwaveservice
net stop jwaveservice
Removing the JWAVE Service
To remove the JWAVE Service from your Windows NT server:
VNI_DIR\jwave-3_0\bin\bin.i386nt\jwaveservice -remove
VNI_DIR is the main Visual Numerics installation directory.
VNI_DIR/classes/jwave_demos/tests
VNI_DIR\classes\jwave_demos\tests
VNI_DIR is the main Visual Numerics installation directory. To run the following tests:
VNI_DIR/classes/JWaveConnectInfo.jarVNI_DIR/JWave.jar classes/jwave_demos/tests
VNI_DIR\classes\JWaveConnectInfo.jarVNI_DIR\JWave.jar VNI_DIR\classes\jwave_demos\tests
VNI_DIR is the main Visual Numerics installation directory.
Plot, Surface, and Close Session buttons.
Figure 8-7 The View Test window showing the 2D plot.
Plot a PV-WAVE session starts and a 2D plot displays.
Surface The same PV-WAVE session makes a surface and displays it.
Plot again The 2D plot displays again.
Close Session This should close the PV-WAVE session on the JWAVE server.
README files in the subdirectories of:
VNI_DIR/classes/jwave_demos VNI_DIR\classes\jwave_demos VNI_DIR is the main Visual Numerics installation directory.
CLASSPATH environment variable. Set the CLASSPATH on a JWAVE client to include (at least):
VNI_DIR/classes/JWave.jarVNI_DIR\classes\JWave.jarVNI_DIR is the main Visual Numerics installation directory.The JWAVE Client documentation is referenced with:
VNI_DIR/classes/docs/api/packages.html.VNI_DIR\classes\docs\api\packages.html.
VNI_DIR/classes/jwave_demos VNI_DIR\classes\jwave_demos
swing.jar or swingall.jar)
JWaveBeans.jar into BDK 1.0_mar98 or an IDE like JavaStudioCLASSPATH does not include any JWAVE JAR files or classes. (JWAVE applets can only communicate with the JWAVE Manager if the applets are served by that serverhaving these classes in CLASSPATH causes a security error.)
NOTE: You must have access to the JWAVE server for JWAVE client applications to work properly.
JWaveConnectInfo.jar in your CLASSPATH.
README file in the subdirectories of VNI_DIR/classes/jwave_demos for other hints on setting up your environment.
