Browser Deployment

Rich Client Versus Thin Client Browser Deployment

Technologies for providing high performance, feature rich and interactive graphics in a browser environment are constantly evolving. The definition of the terms rich client and thin client are also continually changing as the technologies advance. In a very general definition, rich client means that the client is more intelligent and can assist in some of the processing. Thin client means that the client is less intelligent and the majority of the processing is done on a server. Currently, with Java based implementations, rich client solutions involve the use of Java applet technology and thin client solutions involve HTML, DHTML, Java Script, JSP, Java Struts, Java Server Faces or most recently AJAX technologies.

RTView provides the option of shifting seamlessly between the Rich Client Browser or Thin Client Browser deployment. SL also continually evaluates the most efficient technologies available for either deployment and provides the best solution available with complete upward compatibility for all deployed RTView displays. Therefore you are shielded from the risks and costs of implementing these solutions via in-house programming efforts and potentially choosing a soon to be obsolete technology. Currently RTView uses AJAX technologies for its Thin Client Browser solution which provides the optimal solution for dynamic and real-time dashboard solutions.

There are many factors described in the table below which need to be evaluated in order to choose the optimal browser deployment. However, in most cases this decision would be made by weighing the costs of deploying and maintaining the Java plug-in for the Rich Client Browser applet against any degradation in usability or performance with the Thin Client Browser option.

The pros and cons of the two browser options, Rich Client Browser and Thin Client Browser, are described below.

Pros and Cons

Rich Client Browser Deployment

The Rich Client Browser deployment requires that a Java plug-in is installed on each client machine. The Display Viewer Applet is then hosted on an application server to provide visualization to client browsers. This solution can be used either from a standard browser or from a portal environment (see Figure 8).

Figure 8: Rich Client Browser Deployment Overview

Choose “Rich Client Browser Deployment” 

Thin Client Browser Deployment

The Thin Client Browser deployment involves no installation on the clients. Only a standard browser is necessary on each client. The Display Server must be installed on a server and an application server with a JSP Servlet Container is required to provide visualization to the clients. This solution can be used either from a standard browser or from a portal environment (see Figure 9).

Figure 9: Thin Client Browser Deployment Overview

Choose “Thin Client Browser Deployment” 

Rich Client Browser Deployment

This section includes:

§        “Served Data Versus Direct Data Connection” on page 900

§        “Rich Client Browser with Served Data” on page 901

§        “Rich Client Browser with Direct Data Connection” on page 901

§        “Rich Client Browser with Served Data - Manual Deployment Process” on page 902

§        “Rich Client Browser with Served Data - Manual Set up” on page 903

§        “Rich Client Browser with Direct Data Connection - Manual Deployment Process” on page 909

§        “Rich Client Browser with Direct Data Connection - Manual Setup” on page 910

§        “Display Viewer Applet” on page 911

Served Data Versus Direct Data Connection

With most Rich Client Browser deployments it is better to use the Data Server rather than a Direct Data Connection. The Data Server uses EII and XML technologies to gather, federate and distribute information from disparate data sources based on information currently in demand. It also caches the data so that multiple demands are delivered to any number of clients - without need of subsequent data queries. These important factors greatly enhance processing speed.

Because the Data Server can exist behind firewalls, it also greatly simplifies and strengthens the secured delivery of information to clients beyond the firewall. In small scale deployments or prototyping situations there may be a case where it is desired not to provide the Data Server because of the costs of a dedicated machine or server software. However, the setup and security issues involved with the Direct Data Connection often outweigh any cost benefits.

Note: Refer to the “RTView Data Sources” section of this documentation to see if deployment with a Direct Data Connection is supported by your data source.

The pros and cons of the two scenarios, Served Data and Direct Data Connection, are described below.

Pros and Cons

Rich Client Browser with Served Data

With this solution, the Data Server is typically installed on a dedicated server and gathers, federates and caches the data which is supplied via a socket to a Data Servlet installed on the application server. The clients can then access the RTView displays via the Display Viewer Applet (see Figure 10).

Deployment with the Data Server has several benefits. Access to your data sources is restricted to a single machine, the Data Server, instead of multiple applet clients connecting to your data sources. This lends to better performance and higher security. This scenario also entails a simple client setup, fewer applet requirements, easy applet setup, and no modifications to your firewall. When you deploy RTView as a Rich Client Browser with Served Data, depending on the command, commands are executed either on the server or the client. See command descriptions for information on where commands are executed.

Figure 10: Rich Client Browser with Served Data Deployment Overview

Choose “Rich Client Browser with Served Data”

Rich Client Browser with Direct Data Connection

The Direct Data Connection option does not require the Data Server and only requires an application server and the installation of a Java plug-in on the clients. This option, however, involves a complex client setup and potential firewall modifications.

Each individual client must be configured so that it can have direct access to data sources. This may involve the installation of additional software such as database drivers or middleware components depending on the data source types used (see Figure 11).

Note: Refer to the “RTView Data Sources” section of this documentation to see if deployment with a Direct Data Connection is supported by your data source.

Figure 11: Rich Client Browser with Direct Data Connection Deployment Overview

Choose “Rich Client Browser with Direct Data Connection”

Rich Client Browser with Served Data - Manual Deployment Process

The following is an overview of how to manually deploy the Rich Client Browser with Served Data option of RTView. Alternatively, you can use the “Deployment Wizard” to guide you through this process.

Note: These instructions are intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

Process Summary

“Step 1: Set up Data Server” 

“A: Verify System Requirements”

“B: Install and Set up RTView” 

“C: Register”

“D: Configure Data Server”

“Step 2: Set up Data Servlet on Application Server” 

“A: Verify System Requirements” 

“B: Install and Set up Data Servlet” 

“Step 3: Set up Report Servlet on Application Server” 

“Step 4: Set up RTVAgent Servlet on Application Server (Optional*)” 

“Step 5: Set up Applet on Application Server” 

“A: Verify System Requirements”

“B: Configure Applet”

“C: Install Applet”

“D: Register” 

“Step 6: Start / Run Data Server”

“Step 7: Test Data Servlet” 

“Step 8: Test Client”

Rich Client Browser with Served Data - Manual Set up

This section provides step-by-step instructions on how to manually deploy RTView. Refer to “Rich Client Browser with Served Data - Manual Deployment Process” for a summary of these instructions. Alternatively, you can use the “Deployment Wizard” to guide you through this process.

Note: These instructions are intended for users with standard working knowledge of servlet deployment, HTML code and application server administration. If you do not have a full understanding of these, you will need assistance from your system administrator.

An Apache Tomcat application server (see “RTView Demo Server”) is included with your RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with RTView.

Step 1: Set up Data Server

Install RTView on the system where you will run the Data Server. If you are using multiple or high availability Data Servers, you will need to repeat the following steps on each system where you will run Data Server(s). See “Data Server Tab” and “Data Server” for more information.

A: Verify System Requirements

•        Java 1.5.0_01+

•        Accessible over the network to the Data Servlet.

•        Basic “System Requirements”

•        In addition to basic system requirements, refer to the “RTView Data Sources” section of this documentation for system requirements and setup specific to your data source.

Note: The Data Servlet must have permission to access the Data Server on the port specified for the socket in the DATASERVER.ini file. This process will be explained in Step D: Configure Data Server.

B: Install and Set up RTView 

At this point you have verified your system requirements.

1.     Install RTView. See “Installation” for more information.

2.     Set up RTView. See “Setup” for more information.

C: Register

At this point you have installed and setup RTView.

Register for a license for the Data Server. See “Registration” for more information.

D: Configure Data Server 

At this point you have installed, setup and registered your RTView installation.

1.     Create a project directory to store Data Server configuration files.

2.     Copy the following files into the directory you just created from the project directory where you developed your RTView application:

•        OPTIONS.ini file

•        Refer to “Deployment”in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

•        All display (.rtv) files you want to preload (optional)

Note: If you are using multiple or high availability Data Servers, each Data Server needs to run on a different host and/or port. Be sure that the DATASERVER.ini file, the OPTIONS.ini file, and any related data source initialization files are all correct for this instance of the Data Server. See “Data Server Tab” and “Data Server” for more information.

3.     If you already created a DATASERVER.ini that is configured to run the Data Server in socket mode on the correct port, copy the DATASERVER.ini to the project directory you just created. Then go to Step 2: Set up Data Servlet on Application Server.

If you have not created a DATASERVER.ini, go to next step.

4.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the project directory you created in Step D1 and type:

run_dataserver -socket

5.     Set up the Data Server configuration. See “Configuration Tab” for more information.

Note: The Data Server must be configured to run on a socket. The port specified for the socket must match the ServicePort specified for the Data Servlet in Step 2B.

6.     Click the Save Configuration button to save DATASERVER.ini and exit the Data Server.

Step 1 is completed. Go to Step 2: Set up Data Servlet on Application Server.

Step 2: Set up Data Servlet on Application Server

At this point you have completed the RTView installation and setup, and configured the Data Server.

A: Verify System Requirements 

•        Application server with a JSP servlet container, such as Apache Tomcat

•        Must have permission to access the Data Server on the port specified for the socket in   DATASERVER.ini (see Step 1D)

B: Install and Set up Data Servlet

The Data Server uses a Data Servlet that runs on your application server. The Data Servlet communicates with the Data Server via a socket and communicates with the clients via HTTP or HTTPS. The servlets\rtvdata directory contains all of the files necessary to configure and install the Data Servlet.

If you are using multiple Data Servers, you must configure and install a Data Servlet for each Data Server. If you want to install multiple Data Servlets on the same application server, each must have a unique name.

At this point you have verified your system requirements.

1.     Configure Data Servlet Options

The Data Servlet reads servlet.properties to get configuration information. If you have not installed the Data Servlet, modify the servlet.properties files in the servlets\rtvdata directory and it will be installed as part of the next step. If you have already installed the Data Servlet on your application server, you can edit this properties file in your application server. You may need to restart your application server after making changes to this file.

You can set the following options in servlet.properties:

The following is an example of the servlet.properties file:

ServiceHost=localhost

ServicePort=3278

ServiceTimeout=15

2.     Install the Data Servlet

•        In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the servlets\rtvdata directory and type:

•        Your RTView installation includes an Apache Tomcat application server, so that you can prototype and test your deployment before moving it to your production server. If you will be using this application server, type the following to install the Data Servlet:

•        If you will be using your own Apache Tomcat application server, type the following to install the Data Servlet:

•        If you will be using an application server other than Apache Tomcat, install the files in the rtvdata.war file to your application server according to the documentation for that product.

Step 2 is completed. Go to Step 3: Set up Report Servlet on Application Server.

Step 3: Set up Report Servlet on Application Server

At this point you have completed the RTView installation and setup, configured the Data Server and setup the Data Servlet.

Your RTView installation includes an Apache Tomcat application server you can use to prototype and test your deployment before moving it to your production server. If you will be using this application server, the Report Servlet is already installed so you can skip to Step 4.

Follow the instruction in Report Servlet to setup and install the Report Servlet on your application server. See “Hosting the Applet” for more information.

Step 3 is completed. Go to Step 4: Set up RTVAgent Servlet on Application Server.

Step 4: Set up RTVAgent Servlet on Application Server (Optional*)

*This step is only required if you are setting up the Data Server to accept RTVAgent data via HTTP or HTTPS.

At this point you have installed and setup RTView and configured the Data Server, setup the Data Servlet and Report Servlet.

1.     Verify System Requirements

•        Application server with a JSP servlet container, such as Apache Tomcat.

2.     Install and Set up RTVAgent Servlet

 The Data Server uses the RTVAgent Servlet that runs on your application server to access data sent from an RTVAgent application that is sending data via HTTP. The servlets\rtvagent directory contains all of the files necessary to configure and install the RTVAgent Servlet.

If you are using multiple Data Servers that are gathering RTVAgent data, you must configure and install a RTVAgent Servlet for each Data Server.

a. Configure RTVAgent Servlet Options

The RTVAgent Servlet reads the servlet.properties properties file to get configuration information. If you have not installed the RTVAgent Servlet, modify servlet.properties (in the servlets\rtvagent directory) and install. (Step 4-2b - Install the RTVAgent Servlet). If you have already installed the RTVAgent Servlet on your application server, you can edit your properties file in the application server. Note: You may need to restart your application server after making changes to your properties file.

You can set the following options in servlet.properties:

The following is an example of the servlet.properties file:

ServiceHost=localhost

ServicePort=5665

ServiceTimeout=15

b. Install the RTVAgent Servlet:

•        In an initialized command window, go to the servlets\rtvagent directory and type:

make_war 

This script creates a web archive (.war) named rtvagent.war that includes all of the files necessary to run the RTVAgent Servlet.

•        Install the files in the rtvagent.war file to your application server according to the documentation for that product.

Step 4 is completed. Go to Step 5: Set up Applet on Application Server.

Step 5: Set up Applet on Application Server

At this point you have installed and setup RTView, configured the Data Server, setup the Data Servlet, Report Servlet and RTVAgent Servlet.

A: Verify System Requirements

•        Application server

Note: This must be the same application server where you installed the Data Servlet in Step 2.  

B: Configure Applet

In this section you create an HTML page that instances the Display Viewer Applet. All of the jars necessary to run the Display Viewer Applet can be found under your installation directory located in the lib directory.

Note: The jars in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed_jars.zip. The certificate in these jars will expire in December of 2011.

See Applet “Configuration” for instructions on configuring the Display Viewer applet. Since you are using the Data Server, you do not need to follow any instructions for configuring data sources.

C: Install Applet

At this point, you have created an HTML file that instances the Display Viewer Applet. Follow the instruction in “Hosting the Applet” to install the applet to your application server.

D: Register 

The Display Viewer Applet requires a separate license key from the RTView applications to run on an application server. Without a key, the Display Viewer Applet will run for 20 minutes to facilitate testing. No key is required to run locally.

Register Display Viewer Applet

Step 5 is completed. Go to Step 6: Start / Run Data Server.

Step 6: Start / Run Data Server

At this point you have installed and setup RTView, setup the Data Servlet, Report Servlet, RTVAgent Servlet and the Display Viewer Applet. If you are using multiple Data Servers, you will need to repeat the following steps on each system where you will run Data Server(s). See “Data Server Tab” for more information.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the directory you created in Step 1D and type:

run_dataserver

2.     Click the Start Serving Data button.

Note: You may also run the Data Server as a daemon process. See “Running the Data Server”for more information and additional options.

Note: The Data Server is instrumented with JMX to allow you to manage and monitor the clients and application settings. See “Managing the Data Server Using JMX” for more information.

Step 6 is completed. Go to Step 7: Test Data Servlet.

Step 7: Test Data Servlet

At this point you have installed and setup RTView, setup the Data Servlet, Report Servlet, RTVAgent servlet, Display Viewer Applet and started the Data Server.

1.     Open a browser and navigate to the test.jsp file included in the rtvdata.war:

2.     Verify that the Data Servlet is running. The browser should display text similar to the following:

GmsServlet: running

POSTs: 0

Service:

host: localhost

port: 3278

connected: false

Service should reflect the configuration that is entered in servlet.properties and connected should be true if the Data Servlet is connected to the Data Server.

Step 7 is completed. Go to Step 8: Test Client.

Step 8: Test Client

At this point you have installed and setup RTView, setup the Data Servlet, Report Servlet, RTVAgent servlet, and Display Viewer Applet, started the Data Server and tested the Data Servlet.

Follow the instructions in “Browser Client” to test your deployment.

For troubleshooting information, see Display Viewer Applet “Display Viewer Applet Troubleshooting”.

Congratulations! RTView deployment is completed.

Rich Client Browser with Direct Data Connection - Manual Deployment Process

The following is an overview of how to manually deploy the Rich Client Browser with Direct Data Connection option of RTView. Alternatively, you can use the “Deployment Wizard” to guide you through this process.

Note: These instructions are intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

Process Summary

“Step 1: Setup Applet on Application Server” 

“A: Verify System Requirements”

“B: Configure Applet”

“C: Install Applet”

“D: Register”

“Step 2: Setup Report Servlet on Application Server”

“Step 3: Setup Client”

“Step 4: Test Client” 

Rich Client Browser with Direct Data Connection - Manual Setup

This section provides step-by-step instructions on how to manually deploy RTView. Refer to “Rich Client Browser with Direct Data Connection - Manual Deployment Process” for a summary of these instructions. Alternatively, you can use the “Deployment Wizard” to guide you through this process.

Note: These instructions are intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

An Apache Tomcat application server is included with your RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with RTView.

Step 1: Setup Applet on Application Server

A: Verify System Requirements 

Verify the following system requirements:

•        Application server.

•        Basic “System Requirements”

•        In addition to basic system requirements, refer to the “RTView Data Sources” section of this documentation for system requirements and setup specific to your data source.

When finished, proceed to Part B: Configure Applet.

B: Configure Applet 

At this point you have verified your system requirements.

In this section, you will create an HTML page that instances the Display Viewer Applet. All of the jars necessary to run the Display Viewer Applet can be found under your installation directory located in the lib directory. The jars in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed-jars.zip. The certificate in these jars will expire in May of 2018.

See “Display Viewer Applet” for instructions on configuring the Display Viewer applet. Since you are not using the Data Server, you need to follow all instructions for configuring data sources.

C: Install Applet

At this point you have verified system requirements and configured the applet. Follow the instruction in “Hosting the Applet” to install the applet to your application server.

D: Register 

At this point you have verified system requirements, configured and installed the applet.

Display Viewer Applet requires a separate license key from the RTView application to run on a application server. Without a key, the Display Viewer Applet will run for 20 minutes to facilitate testing. No key is required to run locally.

Register Display Viewer Applet. See “Display Viewer Applet Registration” for more information.

Step 1 is completed. Go to Step 2: Setup Report Servlet on Application Server.

Step 2: Setup Report Servlet on Application Server

At this point you have setup the applet on the application server.

Your RTView installation includes an Apache Tomcat application server you can use to prototype and test your deployment before moving it to your production server. If you will be using this application server, the Report Servlet is already installed so you can skip to Step 3.  

Follow the instruction in “Hosting the Applet” to setup and install the Report Servlet on your application server.

Step 2   is completed. Go to Step 3: Setup Client.

Step 3: Setup Client

At this point you have setup the applet and the Report Servlet on the application server.

Follow the instructions in “Browser Client” to setup your client.

When finished return to Step 4: Test Client.

Step 4: Test Client

At this point you have setup the Display Viewer Applet and the Report Servlet on the application server, and setup the client.

Follow the instructions in “Browser Client” to test your deployment.

For troubleshooting information, see “Display Viewer Applet Troubleshooting”.

Congratulations! RTView deployment is completed.

Display Viewer Applet

The Rich Browser Client deployments are implemented using the Display Viewer Applet, which is a Java applet. The Display Viewer Applet can either connect directly to your data source(s) or it can connect to the Data Server. For step-by-step instructions on deploying the Display Viewer Applet, see “Rich Client Browser with Served Data - Manual Set up” or “Rich Client Browser with Direct Data Connection - Manual Setup”.

This section describes how to configure (“Configuration”), host (“Hosting the Applet”), and run (“Browser Client”) the Display Viewer Applet and “Report Servlet”.

Configuration

The Display Viewer Applet must be instanced in an HTML page as described below. All of the jars necessary to run the Display Viewer Applet can be found under your installation directory located in the lib directory. The jars in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed-jars.zip. The certificate in these jars will expire in May of 2018.

Create an HTML page that instances the Display Viewer Applet. This procedure has two Parts:

§        “Part i: Required Applet Parameters”

§        “Part ii: Optional Applet Parameters”

Note: The Display Viewer Applet also supports several JavaScript methods. See “Display Viewer Applet JavaScript” for more information.

Display Viewer Applet Example

A sample HTML page, mydisplay.html, contains the Display Viewer Applet and can be found in your installation directory under demos. The minimum HTML code required to run the Display Viewer Applet are as follows:

<html>

<body>

<object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"  

            WIDTH = "725" HEIGHT = "585" ALIGN = TOP  

           codebase="http://java.sun.com/update/1.5.0/jinstall-1_5_0-windows-i586.cab#Version=1,5,0,0">

           <param NAME = CODE VALUE = "com.sl.gmsjrtview.GmsJRtView.class" >

           <param NAME = ARCHIVE VALUE = "gmsjrtview.jar,gmsjmodels.jar,gmsjrtvreport.jar,iText.jar,J2PrinterWorks.jar" >

          <param NAME="type" VALUE="application/x-java-applet;version=1.5">

          <COMMENT><embed type="application/x-java-applet;version=1.5"

                             code = "com.sl.gmsjrtview.GmsJRtView.class"  

                             ARCHIVE = "gmsjrtview.jar,gmsjmodels.jar,gmsjrtvreport.jar,iText.jar,J2PrinterWorks.jar"  

                             WIDTH="725" HEIGHT="585" ALIGN=TOP rtv_filename="mydisplay.rtv"  

                            pluginspage="http://java.sun.com/j2se/1.5.0/download.html">

          <noembed></COMMENT>

          <param NAME="rtv_filename" VALUE="mydisplay.rtv">

          </noembed>

          </embed>

</object>

</body>

</html>

Part i: Required Applet Parameters

To host the Display Viewer Applet you must specify the following in your HMTL file:

§        basic required applet parameters;

§        applet parameters for data sources - this is only needed if you are not using the Data Server

Basic Required Applet Parameters

Applet Parameters Required for Data Sources

If you are using more than one Data Server connection, use the dataserver applet parameter for the first Data Server listed in the applet HTML file, and use the dataserverN applet parameter to specify additional Data Server connections. See “Part i: Required Applet Parameters” and “Part ii: Optional Applet Parameters” for more information.

If you are using one or more Data Server connections, by default you do not need to specify any data source information.    

In configurations where the applet is not connecting to any Data Servers but retrieves data directly from the data sources, you must specify the data sources in the HTML applet parameters. The applet parameters for the Alert and Cache data sources are listed below. If you are using additional data sources, refer to Deployment in the Data Sources section of this documentation for required applet parameters specific to your data source. If you are using history data you must include the SQL data source in your applet.

Note: To specify multiple data sources for the value of the ds parameter, separate them with a semicolon (;).

When finished, go to“Part ii: Optional Applet Parameters”.   

Applet Parameters Required for Alert Data Source

These parameters are only required if you are using the Alert data source.

Note: Setup is also required for any data sources you used to input data to your alerts.

Include the Alert data source in your applet:

1.     Add the following to your ARCHIVE parameter (found under your installation directory in lib):

gmsjalertds.jar

2.     Add the following applet parameter:

name = ds

value = com.sl.gmsjalertds.GmsRtViewAlertDs

Applet Parameters Required for Cache Data Source

These parameters are only required if you are using the Cache data source.

Note: Setup is also required for any data sources you used to input data to your caches.

Include the Cache data source in your applet:

1.     Add the following to your ARCHIVE parameter (found under your installation directory in lib):

gmsjcacheds.jar 

2.     Add the following applet parameter:

name = ds

value = com.sl.gmsjcacheds.GmsRtViewCacheDs

Part ii: Optional Applet Parameters

Basic optional applet parameters can be specified either in your HTML file or from a configuration file (OPTIONS.ini).

•        To create in an initialization file, see “Application Options”.

•        To use an initialization file in your applet, include it in the directory containing the HTML file.

Note: Applet parameters you specify in you HTML file will override settings in configuration (.ini) files.

The following can be specified in the applet parameters of your HTML file:

•        basic optional applet parameters;

•        data source optional applet parameters - this is only needed if you are not using the Data Server

Basic Optional Applet Parameters

Optional Applet Parameters for Data Sources

If you are using more than one Data Server connection, use the dataserver applet parameter for the first Data Server listed in the applet HTML file, and use the dataserverN applet parameter to specify additional Data Server connections. See “Part i: Required Applet Parameters” and “Part ii: Optional Applet Parameters” for more information.

If you are using one or more Data Server connections, by default you do not need to specify any data source information.   

The applet parameters for the Alert and Cache data sources are listed below. If you are using additional data sources, refer to “Deployment” in the Data Sources section of this documentation for optional applet parameters specific to your data source.   

Optional Applet Parameters for Alert Data Source

The following parameters can be specified in your HTML file, otherwise they will be read from ALERTOPTIONS.ini.

Hosting the Applet   

System Requirements 

The system where you host the Display Viewer Applet must meet the following requirements:

•        Application server.

•        Basic “System Requirements”

•        If you are not using the Data Server, in addition to basic system requirements, refer to the “RTView Data Sources” section of this documentation for system requirements and setup specific to your data source.

Installing the Applet 

1.     Create a project directory to store all files needed by the Display Viewer Applet.

2.     Copy the following files into the directory you just created:

•        HTML file containing an instance of the “Display Viewer Applet”

•        From the lib directory of your RTView installation:

–      all .jar files added to the ARCHIVE parameter in your HTML file

•        From the project directory of your RTView installation:

–      OPTIONS.ini. See “Application Options” for more information.

–      COLORS.ini (only required if Custom Colors have been defined). See “Custom Colors Tab” for more information.

–      .jar file containing custom classes (optional)

–      Panel configuration file (optional). See “Multiple Display Panels” for more information.

–      All display (.rtv) files

–      Style sheet (.rts) files (optional)

–      Refer to “Deployment” in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

–      Security configuration files (optional). See “Configuration” for more information.

•        KEYS (see “Registration”, next)

The .jar files in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed-jars.zip. The certificate in these jars will expire in May of 2018.

3.     Install this directory to your application server according to documentation for that product.

Registration 

At this point you have verified system requirements, configured and installed the applet.

Display Viewer Applet requires a separate license key from the RTView application to run on a application server. Without a key, the Display Viewer Applet will run for 20 minutes to facilitate testing. No key is required to run locally.

“Display Viewer Applet Registration”

Report Servlet   

The Display Viewer Applet uses a Report Servlet to support exporting PDF reports. If you do not want to generate reports, you can skip this setup. Your RTView installation includes an Apache Tomcat application server you can use to prototype and test your deployment before moving it to your production server. If you will be using this application server, the Report Servlet is already installed so you can skip this setup. See “Reporting” for more information.

System Requirements 

•        Application server with a JSP servlet container, such as Apache Tomcat

Install and Setup Report Servlet 

 The servlets\rtvreport directory contains all of the files necessary to install the Report Servlet.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the servlets\rtvreport directory and type:

make_war - This script creates a web archive (.war) named rtvreport.war that includes all of the files necessary to run the Report Servlet.

2.     If you will be using your own Apache Tomcat application server, type the following to install the Report Servlet:

install_to_tomcat rtvreport - This script installs the web archive rtvreport.war to your Apache Tomcat server.

Note: This script will shutdown and restart Apache Tomcat and requires administrative permissions.

•        If you will be using an application server other than Apache Tomcat, install the files in the rtvreport.war file to your application server according to the documentation for that product.

Browser Client

System Requirements

Each client must meet all of the following requirements:

•        Java Plugin 1.5.0_01+

•        Browser: IE4.0+ (other browsers also work)

•        In addition to basic “System Requirements”, if you are not using the Data Server, refer to the Data Sources section of this documentation for system requirements specific to your data source.

•        To enable copying tables to the clipboard, the client must have the following permission on their Java security settings:

permission java.awt.AWTPermission "accessClipboard";

•        In order to use the Send Email system command (see “Define System Command”), you must modify the Java security settings on each client to include the following permissions. Where SMTPHostName is the name of the SMTP server, SMTPHostIP is the IP address of the SMTP server and <> in the FilePermission is the name of the file to be attached to the email.

permission java.net.SocketPermission "SMTPHostName", "resolve";

permission java.net.SocketPermission "SMTPHostIP", "accept, connect, listen, resolve";

permission java.util.PropertyPermission "user.name", "read"; };

permission java.io.FilePermission "<>", "read";

•        The Send SNMP Trap command requires outgoing access to UDP port 162 (or a different port as specified in your command). See “Command Types” for more information.

•        In order to use the Topmost Window Mode on drill down windows, depending on your Security Manager, you may need to modify the Java security settings on each client to include the following permission:

permission java.awt.AWTPermission "setWindowAlwaysOnTop”;

Setup Client for Additional Data Sources

If you are using additional data sources and you are not using the Data Server, refer to “Deployment” in the Data Sources section of this documentation for information on client setup specific to your data source.

Note: If you are using history data you must complete SQL setup.   

Accessing the Project 

1.     Open a browser and navigate to the URL for the applet. Note: Multiple applets running in the same VM will share a single Custom Color tab.

2.     “Login” to the Display Viewer Applet. By default, the Display Viewer Applet does not require a login. Login can be enabled at setup to support “Role-based Security”. The default user name and password are:

User Name: admin

Password: admin

Note: It is possible that your system administrator may have configured another user name and password. In this case, you may also need to select a role. See “Role-based Security” for more inforamation.

For troubleshooting information, see “Display Viewer Applet Troubleshooting”.

Display Viewer Applet Registration

The Display Viewer Applet requires a separate PIN and license key than the RTView applications to run on a web server. Without a key, the Display Viewer Applet will run for 20 minutes to facilitate testing. No key is required to run locally.

In order to request a license key, you will need to retrieve a PIN specific to the web server where you are hosting your applet(s). To retrieve the PIN, locate the files gmsjregister.jar and GmsRegister.html in the lib directory (found in your installation directory) and copy those files into the document root directory of your web server. Open the file GmsRegister.html through your web server and note the PIN.

To request a key, contact SL Corporation at 800.548.6881 or 415.927.8400, or send an email to keys@sl.com and provide your PIN.

Type the key you receive into an ASCII file and name that file KEYS. Put the KEYS file into the document root directory of your web server. If you do not want to put the KEYS file in the document root of your web server, you can put it in the directory containing the Display Viewer Applet. You can also put the KEYS file in any directory under your document root directory and include a KeyLocation parameter in all of the .html files containing the Display Viewer Applet. The KeyLocation parameter must be set to the directory containing the KEYS file. For example, if the KEYS file is located in a subdirectory named registration in the web server's document root directory, you would add a KeyLocation parameter as follows to all of the .html files that contain the Display Viewer Applet:

PARAM NAME="KeyLocation" PARAM VALUE="registration"

Display Viewer Applet Troubleshooting

Served Data and Direct Data Connection Deployments 

Problem 

Console Error:

ERROR: cannot open <rtv_filename.rtv>.

Solution 

The specified rtv file is not in the directory containing the HTML file.

Problem 

Console Error:

load: class com.sl.gmsjrtview.GmsJRtView.class not found

Solution

The gmsjrtview.jar is not specified in the ARCHIVE parameter or it is not in the directory containing the HTML file. If you specified a relative path for gmsjrtview.jar in the ARCHIVE parameter, it was not found.

Direct Data Connection Deployments 

Errors/solutions vary depending on which RTView data sources are included in your applet. Refer to “Deployment” in the Data Sources section of this documentation for troubleshooting specific to your data source.

Display Viewer Applet JavaScript

If you are using JavaScript within your HTML file, the Display Viewer Applet supports the following methods:

Timezone ID Values

Thin Client Browser Deployment

The Thin Client Browser deployment option requires the installation of the Display Server which is typically installed on a dedicated platform. The Display Server then communicates via a socket to an application server where the Display Servlet is installed. No configuration of the client is necessary other than access to a standard browser.

This section includes:

§        “Served Data Versus Direct Data Connection” on page 929

§        “Pros and Cons” on page 929

§        “Thin Client Browser with Served Data” on page 930

§        “Thin Client Browser with Direct Data Connection” on page 930

§        “Thin Client Browser with Served Data - Manual Deployment Process” on page 931

§        “Thin Client Browser with Served Data - Manual Setup” on page 932

§        “Thin Client Browser with Direct Data - Manual Deployment Process” on page 939

§        “Thin Client Browser with Direct Data - Manual Setup” on page 940

§        “Display Server” on page 945

Served Data Versus Direct Data Connection

In some cases, the Display Server can act as your Data Server to support connections to necessary data sources, handle all defined data calculations, provide cache storage, and maintain the alert rules engine. However, there are situations where this is not possible or desirable.

Data Access/Centralization

 Depending on where the Data Server will reside in the network, it may not be desirable to have direct TCP connections to each necessary data source. For example, data sources may reside in a sub-network where it is not possible to open multiple connections to the Display Server. In this case, the Data Server could act as a proxy so that one TCP or HTTP connection to the Data Server could be used to deliver data across the network.

Data Reduction/Aggregation

 Sometimes the data exists in a network configuration where bandwidth is very sensitive. Data Servers could be used to maintain data aggregations, data caches and alert information that  would only be accessed on demand by the Display Server. This will allow for significant optimization of network bandwidth.

Scalability

 If large amounts of data are cached, many data calculations are performed, or large alert rule bases are activated, it may be beneficial to distribute this processing load across one or multiple Data Servers.

The pros and cons of the two scenarios, Served Data and Direct Data Connection, are described below.

Pros and Cons

Thin Client Browser with Served Data

The Thin Client Browser with Served Data deployment involves deploying one Display Server and one or more Data Servers. Each Data Server will have its own configuration files which describe data connections, cache definitions, function definitions, and alert definitions. The Display Server will have one connection to each deployed Data Server and gather the necessary data on demand when users are viewing applicable dashboards.

How It Works

Choose “Thin Client Browser with Served Data”

Thin Client Browser with Direct Data Connection

The Thin Client Browser with Direct Data Connection deployment involves deploying only one Display Server. The Display Server will have a direct connection to all required data sources and will be responsible for serving dashboards, performing data calculations, caching data and processing alerts.

How It Works

Choose “Thin Client Browser with Direct Data Connection”

Thin Client Browser with Served Data - Manual Deployment Process

The following is an overview of how to manually deploy the Thin Client Browser with Served Data option of RTView. The steps need to be followed in the order given. Alternatively, you can use the“Deployment Wizard” to help you deploy your project.

See “How It Works” for a Thin Client Browser with Served Data system overview and sequence of usage.

Note: This documentation is intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

Process Summary

“Step 1: Install and Configure Display Server” 

“A: Verify System Requirements”

“B: Install Display Server” 

“C: Register” 

“D: Configure Display Server”

“Step 2: Configure and Install Display Servlet”

“A: Create Display Servlet HTML or JSP Files”

“B: Configure Display Servlet Options”

“C: Install Display Servlet” 

“Step 3: Configure and Install Display Server Portlet (Optional)”

Configure Display Server Portlet Options

Install Display Server Portlet

Instance the Display Server Portlet in Your Portal

“Step 4: Install and Configure Data Server”

“A: Verify System Requirements” 

“B: Install and Setup RTView”

“C: Register”

“D: Configure Data Server”

“E: Set up RTVAgent Servlet on Application Server (Optional)”

“Step 5: Run Display Server”

“Step 6: Start / Run Data Server” 

“Step 7: Test Client”

Thin Client Browser with Served Data - Manual Setup

This section provides step-by-step instructions on how to manually deploy RTView. The steps must be done in the order given. Refer to “Thin Client Browser with Served Data - Manual Deployment Process” for a summary of these instructions. Alternatively, you can use the “Deployment Wizard” to help you deploy your project.

This section is intended for users with standard working knowledge of HTML, JSP, and servlet deployment on an application server.

An Apache Tomcat application server is included with your RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with RTView.

Step 1: Install and Configure Display Server

Install RTView on the system where you will run the Display Server. If you are using “High Availability Display Servers”, you will need to repeat the following steps on each system where you will run a Display Server.

A: Verify System Requirements

•        Java 1.5.0_01+

•        Basic “System Requirements”

B: Install Display Server

At this point you have verified your system requirements.

1.     Install RTView. See “Installation” for more information.

2.     Setup RTView. See “Setup” for more information.

C: Register 

At this point you have verified your system requirements and installed the Display Server.

Register for a license to run the Display Server. See “Registration” for more information.

D: Configure Display Server 

At this point you have verified your system requirements, and installed and registered RTView.

1.     Create a project directory to store Display Server configuration files.

2.     Copy the following files into this directory from the project directory where you developed your RTView application:

•        All display (*.rtv) files

•        Style sheet (.rts) files (optional)

•        OPTIONS.ini. See “Application Options” for more information.

•        COLORS.ini (only required if Custom Colors have been defined). See “Custom Colors Tab” for more information.

•        Refer to “Deployment” in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

•        Panel configuration file (optional). See “Multiple Display Panels” for more information.

•        Security Configuration files (optional). See “Configuration” for more information.

•        DISPLAYSERVER.ini

Note: If you have no DISPLAYSERVER.ini file, create one now by configuring your Display Server application options. Otherwise, go to Step 2: Configure and Install Display Servlet.

3.     Configure your Display Server application options. See “Display Server Configuration” for information on how to specify your options. All configuration files should be saved in the directory you just created.

Step 1 is completed. Go to Step 2: Configure and Install Display Servlet.

Step 2: Configure and Install Display Servlet

At this point you have completed the RTView installation and setup.

About Display Servlet 

The Display Server uses the Display Servlet, a JSP servlet that runs on your application server. Clients communicate with the Display Servlet using HTTP. The Display Servlet communicates with the Display Server via socket to request HTML for display in the browser. The servlets\rtvdisplay directory contains files (JSP, HTML, classes, properties) necessary to install the Display Servlet.

A: Create Display Servlet HTML or JSP Files 

The Display Servlet comes with a few HTML files for testing. You can use these to deploy, or you can create your own HTML or JSP files which make calls to the Display Servlet to show your displays.

Skip this step and go to “B: Configure Display Servlet Options” if both of the following are true:   

•        You will only be deploying one Display Server application on your application server   

•        You want to deploy using only the test HTML files that come with the Display Servlet

Note: If you skip this step, use servlets\rtvdisplay as your project directory referenced in Steps B and C, and use rtvdisplay for the appname argument for all of the scripts.

Otherwise, proceed with the following steps.

1.     Create a project directory to store your Display Servlet files.

2.     Copy rtvdisplay.properties into this directory from servlets\rtvdisplay.

3.     Create the HTML files or JSP files for your Display Server application. See “Creating Display Servlet HTML Files” and “Creating Display Servlet JSP Files” for more information.

4.     Copy these HTML or JSP files and any referenced files (e.g., images referenced in the HTML files) to this directory.

5.     Copy sample_make_war.bat (for Windows) or sample_make_war.sh (for UNIX) into this directory from servlets\rtvdisplay and rename it to make_war (with the appropriate extension).

6.     This script takes a name for the web archive, without the .war extension, and builds a web archive file that includes all of the necessary RTView Display Servlet files along with all .html, .js, .gif, and .jpg files from the current directory. If there are other files you would like to include in your web archive, add them to the following line in your make_war script:

jar uf %1.war *.html *.jpg *.gif *.js *.jsp WEB-INF

Note: You may receive an error message if the script does not find at least one of each of the file types specified (.html, .jpg, etc). Disregard this error message.

B: Configure Display Servlet Options 

The Display Servlet reads rtvdisplay.properties to get configuration information. If you have not installed the Display Servlet, modify the rtvdisplay.properties files in your project directory and it will be installed as part of the next step. If you have already installed the Display Servlet on your application server, you can edit this properties file in your application server. You may need to restart your application server after making changes to this file.

Use servlets\rtvdisplay as your project directory if you skipped “A: Create Display Servlet HTML or JSP Files”.

Set your options in rtvdisplay.properties as specified in “Display Servlet Configuration”.

C: Install Display Servlet

At this point you have completed Display Servlet setup.

If you skipped “A: Create Display Servlet HTML or JSP Files”, use servlets\rtvdisplay as your project directory and rtvdisplay as your appname in this step.

Otherwise, use the project directory that you setup in Step A and your web archive file name for appname.

Note: If you will be running multiple Display Server applications on the same application server, each application must have a unique name.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to your project directory and type:

make_war appname - This script creates a web archive (.war) that includes all of the files necessary to run the Display Servlet.

2.     Your RTView installation includes an Apache Tomcat application server, so that you can prototype and test your deployment before moving it to your production server. If you will be using this application server, run the following script to install the Display Servlet:

install_to_demoserver appname - This script installs the web archive to the Apache Tomcat server included in your RTView installation.

Note: This script will shutdown and restart Apache Tomcat and requires administrative permissions.

3.     If you will be using your own Apache Tomcat application server, run the following script to install the Display Servlet:

install_to_tomcat appname - This script installs the web archive to your Apache Tomcat server.

Note: This script will shutdown and restart Apache Tomcat and requires administrative permissions.

4.     If you will be using an application server other than Apache Tomcat, install the files in the web archive to your application server according to the documentation for that product.

Step 2 is completed. Go to Step 3: Configure and Install Display Server Portlet (Optional).

Step 3: Configure and Install Display Server Portlet (Optional)

At this point you have setup the Display Server and the Display Servlet.

The Display Server can optionally be deployed as a portlet. The portlet is tested in Liferay and contains configuration files specific to Liferay, but should work with any JSR-168 compliant portal. If you want to deploy the Display Server as a servlet, skip this step and go to “Step 5: Run Display Server”.

Configure install and instance the Display Server Portlet as described in “Configure and Install Display Server Portlet (Optional)”.

Step 3 is completed. Go to Step 4: Install and Configure Data Server.

Step 4: Install and Configure Data Server

At this point you have setup the Display Server, Display Servlet and (optionally) the Display Server Portlet.

Install RTView on the system where you will run the Data Server(s). If you are using multiple or high availability Data Servers, you will need to repeat the following steps on each system where you will run Data Server(s). See “Data Server Tab” and “High Availability” for more information. If you want to run the Data Server from the RTView installation in Step 1, skip steps B and C.

A: Verify System Requirements 

•        Basic “System Requirements”

•        In addition to basic system requirements, refer to the “RTView Data Sources” section of this documentation for system requirements and setup specific to your data source.

•        Data Server must be accessible via network to all clients.

Note: All clients must have permission to access the Data Server on the port specified for the socket in the DATASERVER.ini file (see Step D).

B: Install and Setup RTView

At this point you have verified your system requirements.

1.     Install RTView (see “Installation”)

2.     Setup RTView (see “Setup”)

C: Register

At this point you have installed and setup RTView.

Register for a license (see “Registration”) for the Data Server.

D: Configure Data Server 

At this point you have installed, setup and registered your RTView installation.

1.     Create a project directory to store Data Server configuration files.

2.     Copy the following files into the directory you just created from the project directory where you developed your RTView application:

•        OPTIONS.ini

•        Refer to Deployment in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

•        All display (.rtv) files you want to preload (optional)

Note: If you are using multiple or high availability Data Servers, each Data Server needs to run on a different host and/or port. Be sure that the DATASERVER.ini file, the OPTIONS.ini file, and any related data source initialization files are all correct for this instance of the Data Server. See “Data Server Tab” and “High Availability” for more information.

3.     If you already created a DATASERVER.ini that is configured to run the Data Server in socket mode on the correct port, copy the DATASERVER.ini to the project directory you just created. Then go to Step 2: Setup File Server.

If you have not created a DATASERVER.ini, go to next step.

4.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the project directory you created and type:

run_dataserver -socket

5.     Setup the Data Server configuration. See “Configuration Tab” for more information.

Note: The Data Server must be configured to run on a socket. The port specified for the socket must match the port specified for the Data Server in Step 2B-5.

6.     Click the Save Configuration button to save DATASERVER.ini and exit the Data Server.

E: Set up RTVAgent Servlet on Application Server (Optional)

Note: This step is only required if you are setting up the Data Server to accept RTVAgent data via HTTP or HTTPS.

At this point you have setup the Display Server, Display Servlet, (optionally) the Display Server Portlet, and configured the Data Server.

1.     Verify System Requirements

•        Application server with a JSP servlet container, such as Apache Tomcat.

2.     Install and Setup RTVAgent Servlet

The Data Server uses the RTVAgent Servlet that runs on your application server to access data sent from an RTVAgent application that is sending data via HTTP. The servlets\rtvagent directory contains all of the files necessary to configure and install the RTVAgent Servlet.

If you are using multiple Data Servers that are gathering RTVAgent data, you must configure and install a RTVAgent Servlet for each Data Server.

a. Configure RTVAgent Servlet Options

 The RTVAgent Servlet reads the servlet.properties properties file to get configuration information. If you have not installed the RTVAgent Servlet, modify servlet.properties (in the servlets\rtvagent directory) and install. (Step 4E-2b - Install the RTVAgent Servlet). If you have already installed the RTVAgent Servlet on your application server, you can edit your properties file in the application server. Note: You may need to restart your application server after making changes to your properties file.

You can set the following options in servlet.properties:

The following is an example of the servlet.properties file:

ServiceHost=localhost

ServicePort=5665

ServiceTimeout=15

b. Install the RTVAgent Servlet:

In an initialized command window, go to the servlets\rtvagent directory and type:

make_war 

This script creates a web archive (.war) named rtvagent.war that includes all of the files necessary to run the RTVAgent Servlet.

Install the files in the rtvagent.war file to your application server according to the documentation for that product.

Step 4 is completed. Go to Step 5: Run Display Server.

Step 5: Run Display Server

At this point you have setup the Display Server, Display Servlet, (optionally) the Display Server Portlet, configured the Data Server and (optionally) setup the RTVAgent Servlet.

A: Start Display Server 

1.     Start the Display Server. Open an initialized command window (see “Initializing a Command Prompt or Terminal Window”) and go to the directory created in Step 1 and type:

run_displayserver -dataserver:remote://ipaddress:3278

Java options specified in “RTV_JAVAOPTS” are used by the run_displayserver scripts.

See “Command Line” for available command line options.

Note: The Display Server is instrumented with JMX to allow you to manage and monitor the display cache and application settings. See “Managing the Display Server Using JMX” for more information.

Step 5 is completed. Go to Step 6: Start/Run Data Server.

Step 6: Start / Run Data Server

At this point you have setup the Display Server, Display Servlet, (optionally) the Display Server Portlet, configured the Data Server, (optionally) setup the RTVAgent Servlet and run the Display Server. If you are using multiple or high availability Data Servers, you will need to repeat the following steps on each system where you will run Data Server(s). See “Data Server Tab” and “High Availability” for more information.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the directory you created in Step 1 and type:

run_dataserver

2.     Click Start Serving Data.

Note: You may also run the Data Server as a daemon process. See “Running the Data Server” for more information and additional options.

Note: The Data Server is instrumented with JMX to allow you to manage and monitor the clients and application settings. See “Managing the Display Server Using JMX” for more information.

You have finished Step 6. Go to Step 7: Test Client.

Step 7: Test Client

At this point you have setup the Display Server, Display Servlet, (optionally) the Display Server Portlet, configured the Data Server, (optionally) setup the RTVAgent Servlet and run the Display Server and Data Server.

1.     Open a browser and navigate to the URL for the Display Servlet you set up in Step 2. For example:

2.     Login to the Display Server. By default, the Display Server does not require a login. “Login” can be enabled in the Display Servlet to support “Role-based Security”, If login is enabled, the default user name and password are:

User Name: admin

Password: admin   

Note: It is possible that your system administrator may have configured another user name and password. In this case, you may also need to select a role. See “Role-based Security” for more information.

Problem: An error message appears in the browser.

Solution: Check the command window where you started the Display Server as well as the Display Servlet log file on your application server.

See the “Browser Client” and “Limitations” for more information.

Congratulations! RTView deployment is completed.

Thin Client Browser with Direct Data - Manual Deployment Process

The following is an overview of how to manually deploy the Thin Client Browser with Direct Data option of RTView. The steps need to be followed in the order given. Alternatively, you can use the “Deployment Wizard” to help you deploy your project.

See “How It Works” for a Thin Client Browser with Direct Data system overview and sequence of usage.

Note: This documentation is intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

Process Summary

“Step 1: Install and Configure Display Server” 

“A: Verify System Requirements”

“B: Install Display Server” 

“C: Register” 

“D: Configure Display Server” 

“Step 2: Configure and Install Display Servlet” 

“A: Create Display Servlet HTML or JSP Files”

“B: Configure Display Servlet Options”

“C: Install Display Servlet”

“Step 3: Configure and Install Display Server Portlet (Optional)”

Configure Display Server Portlet Options

Install Display Server Portlet

Instance the Display Server Portlet in Your Portal

“Step 4: Run Display Server”

“A: Start Display Server”

“Step 5: Test Client”

Thin Client Browser with Direct Data - Manual Setup

This section provides step-by-step instructions on how to manually deploy RTView. The steps must be done in the order given. Refer to “Thin Client Browser with Direct Data - Manual Deployment Process” for a summary of these instructions. Alternatively, you can use the “Deployment Wizard” to help you deploy your project.

This section is intended for users with standard working knowledge of HTML, JSP and servlet deployment on an application server.

An Apache Tomcat application server is included with your RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with RTView.

Step 1: Install and Configure Display Server

Install RTView on the system where you will run the Display Server.

A: Verify System Requirements

•        Java 1.5.0_01+

•        Basic system requirements

•        In addition to basic system requirements, refer to the Data Sources section of this documentation for system requirements and setup specific to your data source.

B: Install Display Server

At this point you have verified your system requirements.

1.     Install RTView (see “Installation”)

2.     Setup RTView (see “Setup”)

C: Register 

At this point you have verified your system requirements and installed the Display Server.

Register for a license (see “Registration”) to run the Display Server.

D: Configure Display Server 

At this point you have verified your system requirements, and installed and registered RTView.

1.     Create a project directory to store Display Server configuration files.

2.     Copy the following files into this directory from the project directory where you developed your RTView application:

•        All display (*.rtv) files

•        Style sheet (.rts) files (optional)

•       OPTIONS.ini. See “Application Options” for more information.

•        COLORS.ini (only required if Custom Colors have been defined). See “Custom Colors Tab” for more information.

•        Refer to Deployment in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

•        Panel configuration file (optional). See “Multiple Display Panels” for more information.

•        Security Configuration files (optional). See “Configuration” for more information.

•       DISPLAYSERVER.ini

Note: If you have no DISPLAYSERVER.ini file, create one now by configuring your Display Server application options. Otherwise, go to “Step 2: Configure and Install Display Servlet”.

3.     Configure your Display Server application options. See “Display Server Configuration” for information on how to specify your options. All configuration files should be saved in the directory you just created.

Step 1 is completed. Go to Step 2: Configure and Install Display Servlet.

Step 2: Configure and Install Display Servlet

At this point you have completed the RTView installation and setup.

About Display Servlet

The Display Server uses the Display Servlet, a JSP servlet that runs on your application server. Clients communicate with the Display Servlet using HTTP. The Display Servlet communicates with the Display Server via socket to request HTML for display in the browser. The servlets\rtvdisplay directory contains files (JSP, HTML, classes, properties) necessary to install the Display Servlet.

A: Create Display Servlet HTML or JSP Files 

The Display Servlet comes with a few HTML files for testing. You can use these to deploy, or you can create your own HTML or JSP files which make calls to the Display Servlet to show your displays. See “Creating Display Servlet HTML Files” and “Creating Display Servlet JSP Files” for more information.

Skip this step and go to Step B: Configure Display Servlet Options if both of the following are true:    

§        You will only be deploying one Display Server application on your application server    

§        You want to deploy using only the test HTML files that come with the Display Servlet

Note: If you skip this step, use servlets\rtvdisplay as your project directory referenced in Steps B and C, and use rtvdisplay for the appname argument for all of the scripts.

Otherwise, proceed with the following steps.

1.     1. Create a project directory to store your Display Servlet files.

2.     Copy rtvdisplay.properties into this directory from servlets\rtvdisplay.

3.     Create the HTML files or JSP files for your Display Server application.

4.     Copy these HTML or JSP files and any referenced files (e.g., images referenced in the HTML files) to this directory.

5.     Copy sample_make_war.bat (for Windows) or sample_make_war.sh (for UNIX) into this directory from servlets\rtvdisplay and rename it to make_war (with the appropriate extension).

6.     This script takes a name for the web archive, without the .war extension, and builds a web archive file that includes all of the necessary RTView Display Servlet files along with all .html, .js, .gif, and .jpg files from the current directory. If there are other files you would like to include in your web archive, add them to the following line in your make_war script:

jar uf %1.war *.html *.jpg *.gif *.js *.jsp WEB-INF

Note: You may receive an error message if the script does not find at least one of each of the file types specified (.html, .jpg, etc). Disregard this error message.

B: Configure Display Servlet Options 

The Display Servlet reads rtvdisplay.properties to get configuration information. If you have not installed the Display Servlet, modify the rtvdisplay.properties files in your project directory and it will be installed as part of the next step. If you have already installed the Display Servlet on your application server, you can edit this properties file in your application server. You may need to restart your application server after making changes to this file.

Use servlets\rtvdisplay as your project directory if you skipped Step A: Create Display Servlet HTML Files.

Set the your options in rtvdisplay.properties as specified in “Display Servlet Configuration”.

C: Install Display Servlet 

At this point you have completed Display Servlet setup.

If you skipped Step A: Create Display Servlet HTML Files, use servlets\rtvdisplay as your project directory and rtvdisplay as your appname in this step.

Otherwise, use the project directory that you setup in Step A and your web archive file name for appname.

Note: If you will be running multiple Display Server applications on the same application server, each application must have a unique name.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to your project directory and type:

2.     Your RTView installation includes an Apache Tomcat application server so that you can prototype and test your deployment before moving it to your production server. If you will be using this application server, run the following script to install the Display Servlet:

3.     If you will be using your own Apache Tomcat application server, run the following script to install the Display Servlet:

4.     If you will be using an application server other than Apache Tomcat, install the files in the web archive to your application server according to the documentation for that product.

Step 2 is completed. Go to Step 3: Configure and Install Display Server Portlet (Optional).

Step 3: Configure and Install Display Server Portlet (Optional)

At this point you have setup the Display Server and the Display Servlet.

The Display Server can optionally be deployed as a portlet. The portlet is tested in Liferay and contains configuration files specific to Liferay, but should work with any JSR-168 compliant portal. If you want to deploy the Display Server as a servlet, skip this step and go to Step 4: Run Display Server.

Configure install and instance the Display Server Portlet as described in “Configure and Install Display Server Portlet (Optional)”.

Step 3 is completed. Go to Step 4: Run Display Server.

Step 4: Run Display Server

At this point you have setup the Display Server and the Display Servlet, and (optionally) setup the Display Server Portlet.

A: Start Display Server

1.     Start the Display Server. Open an initialized command window (see “Initializing a Command Prompt or Terminal Window”) and go to the directory created in Step 1 and type:

run_displayserver

Java options specified in “RTV_JAVAOPTS” are used by the run_displayserver scripts.

See “Command Line” for available command line options.

Note: The Display Server is instrumented with JMX to allow you to manage and monitor the display cache and application settings. See “Managing the Display Server Using JMX” for more information.

Step 4 is completed. Go to Step 5: Test Client.

Step 5: Test Client

At this point you have setup and started the Display Server, and setup and installed the Display Servlet.

1.     Open a browser and navigate to the URL for the Display Servlet you set up in Step 2. For example:

2.     Login to the Display Server. By default, the Display Server does not require a login. Login can be enabled in the Display Servlet to support “Role-based Security”. If login is enabled, the default user name and password are:

User Name: admin

Password: admin   

Note: It is possible that your system administrator may have configured another user name and password. In this case, you may also need to select a role. See “Role-based Security” for more information.

Problem: An error message appears in the browser.

Solution: Check the command window where you started the Display Server as well as the Display Servlet log file on your application server.

See “Browser Client” and “Limitations” for more information.

Congratulations! RTView deployment is completed.

Display Server

The Thin Client deployment is implemented using the Display Server. The Display Server consists of two parts, the Display Server application and the Display Servlet. The Display Server application is generally installed on a dedicated platform. It runs the RTView engine which loads displays, and gathers data which it passes on to the Display Servlet via a socket. The Display Server can either access data directly or it can connect to the Data Server for data. The Display Servlet is a JSP servlet that runs on an application server. Clients communicate with the Display Servlet using HTTP, so the only system requirement for a the client is a standard browser.

This document describes the system requirements, configuration, installation and runtime information for the “Display Server Application”, “Display Servlet”, and the “Browser Client”. Some objects and interactions behave differently in the Display Server than they do in the other RTView deployments. See the “Runtime Functionality” and “Limitations” sections below for more information.

Display Server Application

System Requirements

The system where you will run the Display Server application must meet the following system requirements:

•        Java 1.5.0_01+

•        Basic “System Requirements”

•        In addition to basic system requirements, if you will not be using the Data Server, refer to the “RTView Data Sources” section of this documentation for system requirements and setup specific to your data source.

Display Server Configuration

Create DISPLAYSERVER.ini in your project directory with the following options:

Example of the above options set in the DISPLAYSERVER.ini file:

cellsperpage 10000

cellsperexport 30000

cellsperreport 5000

clearsubs false

display_timeout 60

imagequality 75

history_config trend1.rtv

max_displays 20

port 3279

passclientlogin false

shared_display navtop.rtv

shared_display summary.rtv $region:East

RTView offers role based security that allows you to limit access to displays based on the user's role. User and role definitions also support substitutions. When role based security is enabled, users are prompted to login. The default user name and password are:

User Name: admin

Password: admin

Note: To use this feature, you must also enable it in the Display Servlet by specifying LoginEnabled in rtvdisplay.properties.

To use this security feature, do the following:

1.     Define the users that can access RTView, assign each user a password and one or more associated roles. If your user definitions are in an XML file, copy this file to your project directory.

2.     Set “Role Definitions” to specify which displays users can access. If your role definitions are in an XML file, copy this file to your project directory.

3.     Enable the Use Client Credentials option if you want to pass RTView login user name and password to database connections. Note: Some data sources do not support this feature. For information on Application Options for your data source, refer to the “RTView Data Sources” section of this documentation.

Use the -passclientlogin command line option or the -passclientlogin option (see Step 1D-3) in the DISPLAYSERVER.ini configuration file to pass RTView login into these database connections. See “Command Line Options: Display Server” for more information.

See “Login”, “Roles and Displays”, and “Configuration” for more information.

Running the Display Server

You can run the Display Server as an application or in the background as a Windows Service. See “Running as a Windows Service” for more information.

To run the Display Server as an application: open an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to your project directory, and type:

run_displayserver 

Several command line options are supported for the Display Server. Java options specified in “RTV_JAVAOPTS” are used by the run_displayserver scripts. See “Command Line Options: Display Server” for more information.

Note: The Display Server is instrumented with JMX to allow you to manage and monitor the display cache and application settings. See “Managing the Display Server Using JMX” for more information.

High Availability Display Servers

It is possible to designate one or more backup Display Servers to take over during a failover event when the Display Servlet discovers that the current Display Server is no longer accessible. Backup servers may be run in hot standby mode (default) or warm standby mode (designated as a command line option). In hot standby mode all global variable definitions, as well as cache and alert definitions, are loaded and activated at start up. In warm standby mode none of these actions are performed, thereby avoiding the overhead of maintaining Alert and Cache data sources until the backup server has become the primary. See “Command Line Options: Display Server” for more information.

You can specify a primary Display Server, as well as one or more backup Display Servers, in the rtvdisplay.properties file.

At startup, the Display Servlet will connect to the primary server if available, otherwise it will connect to the backup server. If neither is available, the Display Servlet will periodically retry connecting to both. If the Display Servlet connects to either the primary or the backup, and later the connection is lost, it will then try to connect to the other server. If a Display Servlet connects to a backup server and later the primary server becomes available, the Display Servlet will not switch to the primary unless the connection to the backup server is lost. See “Display Servlet Configuration” for more information.

If the Display Server is using the Data Server to connect to data, primary and backup Data Servers can also be specified. Refer to “Running the Data Server” for more information.

Display Servlet

The Display Server uses the Display Servlet, a JSP servlet that runs on your application server. Clients communicate with the Display Servlet using HTTP. The Display Servlet communicates with the Display Server via socket to request HTML for display in the browser. The servlets\rtvdisplay directory contains files (JSP, HTML, classes, properties) necessary to install the Display Servlet.

This section is intended for users with standard working knowledge of HTML, JSP and servlet deployment on an application server.

System Requirements

Display Servlet requires an application server with a servlet container such as Apache Tomcat. An Apache Tomcat application server is included with your RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with RTView. See

Display Servlet Configuration 

The Display Servlet reads rtvdisplay.properties and rtvdisplay_strings.properties to get configuration information. See “Localize Display Server” for more information.

Note: The rtvdisplay_strings.properties file provides the ability to localize messages that appear in the browser.

The rtvdisplay.properties file is located in servlets\rtvdisplay with the default settings. If you do not want to use the default settings, copy this file to your project directory and modify.

Set the following options in rtvdisplay.properties:

Example of the rtvdisplay.properties file:

DisplayServerHost=localhost

DisplayServerConnectionPool=10

DisplayServerPort=3279

DisplayServerTimeout=15

DefaultRefreshInterval  =15

LoginEnabled=true  

MaxSharedDisplays=10

SharedDisplayRefreshInterval=15

VirtualThreshold=500

DisplayServerBackup=host:3238

DisplayServerConnectionFailback=true

Localize Display Server

 The rtvdisplay_strings.properties file contains settings for text displayed by the thin client (i.e. popup menus, login window, status window, error messages, etc.). This file is located in the WEB-INF/classes/gmsjsp directory of the rtvdisplay.war file. For localization, extract this file from rtvdisplay.war and modify. Make a copy of this file with the desired locale suffix (e.g. rtvdisplay_strings_ja.properties for Japanese) and pack into rtvdisplay.war, in WEB-INF/classes/gmsjsp.

The locale setting of the application server (e.g. tomcat) will determine which .properties file to load. If the app server does not have the desired locale setting for the thin client, then edit the original file (rtvdisplay_strings.properties) instead.

Create Custom Servlet Files 

The Display Servlet comes with a few HTML files for testing. You can use these to deploy, or you can create your own HTML files or JSP files that make calls to the Display Servlet to show your displays. All custom HTML or JSP files should be saved in your project directory or a subdirectory. See “Creating Display Servlet HTML Files”, “Creating Display Servlet JSP Files”, and “Test Displays” for more information.

Create War File 

If you will not be using the Deployment Wizard to generate your deployment, you will need to create a .war file that contains rtvdisplay.properties, rtvdisplay_strings.properties and any custom servlet files:

1.     Copy sample_make_war.bat (for Windows) or sample_make_war.sh (for UNIX) into this directory from servlets\rtvdisplay and rename it to make_war (with the appropriate extension).

2.     This script takes a name for the web archive, without the .war extension, and builds a web archive file that includes all of the necessary RTView Display Servlet files along with all .html, .js, .gif and .jpg files from the current directory. If there are other files you would like to include in your web archive, add them to the following line in your make_war script:

jar uf %1.war *.html *.jpg *.gif *.js *.jsp WEB-INF

Note: You may receive an error message if the script does not find at least one of each of the file types specified (.html, .jpg, etc). Disregard this error message.

3.     Type make_war warName where warName is the name of the war file to create.

Deploying War Files 

Once you have created a war file for the Display Servlet, you will need to install it to your application server. An Apache Tomcat application server is included with your RTView installation for prototyping and testing your deployment before going into the production environment. You can either use this application server or your own.   

If did not create a war file, use servlets\rtvdisplay as your project directory and rtvdisplay as your appname in the steps below.

Otherwise, use your project directory and your web archive file name for appname.

Note: If you will be running multiple Display Server applications on the same application server, each Display Servlet war file must have a unique name.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to your project directory and type:

2.     Your RTView installation includes an Apache Tomcat application server, so that you can prototype and test your deployment before moving it to your production server. If you will be using this application server, run the following script to install the Display Servlet:

3.     If you will be using your own Apache Tomcat application server, run the following script to install the Display Servlet:

4.     If you will be using an application server other than Apache Tomcat, install the files in the web archive to your application server according to the documentation for that product.

Configure and Install Display Server Portlet (Optional) 

The Display Server can optionally be deployed as a portlet. The portlet is tested in Liferay and contains configuration files specific to Liferay, but should work with any JSR-168 compliant portal. If you want to deploy the Display Server as a servlet, skip this step.

Configure Display Server Portlet Options

The servlets\rtvportlet directory contains all of the files necessary to install the Display Server portlet. It includes a web.xml and several other configuration files necessary for use in a Liferay portal. Make any necessary changes to these files, or if you are using another JSR-168 compliant portal, copy any required configuration files to this directory. The Display Server portlet requires the Display Servlet to run and will access it at http://host:port/rtvdisplay, where host and port are the host and port where the portlet is running. If this is not the case, modify the value for the rtvServletUrl parameter in portlet.xml to point to the correct location of the Display Servlet. Rebuild the rtvportlet.war file using the make_war.bat script.

Install Display Server Portlet 

Install servlets\rtvportlet\rtvporlet.war to your portal according to the documentation for that product.

Instance the Display Server Portlet in Your Portal

Once the Display Server portlet is installed to your portal, you can instance it according to the documentation for that product. The Display Server portlet supports edit mode and view mode. In edit mode, you can specify the display, refresh rate, window name, width and height for the portlet.

Browser Client

System Requirements 

The client requires a standard browser.

Accessing the Project   

1.     Open a browser and navigate to the URL for the Display Servlet. For example:

2.     Login to the Display Server. By default, the Display Server does not require a login. Login can be enabled in the Display Servlet to support “Role-based Security”, If login is enabled, the default user name and password are:

User Name: admin

Password: admin   

Note: It is possible that your system administrator may have configured another user name and password. In this case, you may also need to select a role. See “Role-based Security” for more information.

Problem: An error message appears in the browser.

Solution: Check the command window where you started the Display Server as well as the Display Servlet log file on your application server.

Runtime Functionality

Limitations

§        “Threshold Commands” are not supported in the Display Server, as well as the following “Commands”:

–      Beep

–      Play Audio File

–      Run DOS Command or UNIX Shell

§        The commandCloseWindowOnSuccess property is not supported in the Display Server.

§        The Display Server does not support command failure notification on the client. Notification only appears as a console message on the server.

§        Drill down displays have the following limitations: ◦The Topmost Window Mode has no effect in the Display Server, it is equivalent to the Normal setting.

–      If the user clicks outside of a display from which a drill down in Modal Window Mode was opened, but still within the same browser instance (i.e.: in another frame or iframe), the modal drill down may be obscured. When the mouse is moved across or clicked in the parent display, the modal drill down will return to the top.

–      In Modal Window Mode the user can close the main browser window without first closing the drill down window.

–      If the Window Position specified is completely off-screen, the coordinates will be adjusted so that the window is partially on-screen.

–      If the Window Position is set to Center of Screen or Center of Parent the window open slightly lower than expected.

–      In Firefox, when drill down window is closed the next mouse click in the parent window may be ignored.

Table Objects

§        The Display Server generates JavaScript to display table objects (obj_table02). The JavaScript table has the following limitations: ◦The scrollbarMode, tabIndex, and editDataEnabledFlag properties are ignored. The default values are used.

–      The minimum requirements for viewing in a web browser are Internet Explorer 5.5, Netscape 7.1 and Firefox 1.0.

–      For smooth scrolling, data is preloaded into tables with less than 500 cells. For tables with more than 500 cells, Virtual Mode is used in which data is paged into the tables to speed processing time for displaying, refreshing and sorting. However, the table may blink while scrolling in this mode. To modify, use the VirtualThreshold property in rtvdisplay.properties. See “Display Servlet Configuration” for information.

–      If a sort column is configured in the table object in the Display Builder, the sort icon does not appear in the column header when viewed in the Display Server. The sort icon appears if the sort column is selected at the time the Display Server is started.

§        Table object (obj_table02) has the following limitations:

–      When the multiSelectFlag property is enabled:

a. Multiple rows can only be selected using Ctrl+Left click.

b. A mouse click must be used to select columns.

c. A right-click does not select a row under the mouse pointer

d. Once a table is displayed, changes to the value of the multiSelectFlag property are ignored.

e. In Firefox, a double right-click must be used to open popup menus.

–      When the indexColumns property is enabled it is ignored. Also, a selection made in the table gets cleared if the number of rows in the table changes after a data update.

–      The columnResizeEnabledFlag cannot be toggled.

–      The rowHeaderEnabledFlag cannot be toggled.

Graph Objects

§        The scrollbarSize property is ignored. The system default value is used.

Object Grid

§        The scrollbarSize property is ignored. The system default value is used.

Control Objects

§        Since Firefox does not support multi-line tool tips, any returns (i.e. \n) found in mouseOverText entries will be replaced with spaces.

§        Invalid numeric characters that are copied and pasted into text entry fields are not rejected.

Slider Control 

§        The Slider Control (obj_c1scale) is drawn as a scrollbar rather than a slider.

§        The updateWhileAdjustingFlag, bgColor, and objHeight properties are not supported.

§        The enabledFlag property is not supported in Firefox.

Button Control

§        In Firefox, the defaultButtonFlag is ignored unless a control object in the display has focus.

Combo Box Control

•The textEditEnabledFlag property is not supported.

Date Chooser Control

§        Uses the Datejs date library for parsing and formatting dates and times. The Datejs library subclasses the standard javascript Date object. If you embed a display with the Date Chooser control object inside your javascript application, it may pickup the Datejs date class instead of the standard date class. The Datejs library is distributed under the MIT License and can be downloaded at http://www.datejs.com.

§        The month and day names can be localized by replacing the date.js file in the Display Servlet with a localized version. To do this, go to servlets\rtvdisplay in your RTView installation directory. Extract the appropriate date*.js file for your language from datejs_loc.zip. Rename this file to date.js in the servlets\rtvdisplay directory and rebuild the Display Servlet .war file. Note: The default date.js is a copy of date-en-US.js from the datejs_loc.zip file.

§        The following dateFormat specifiers are not supported:

G, w, W, D, F, E, k, K, S, z, Z

§        No validation against specified dateFormat for date entered in text entry field.

Generated HTML Controls

§        Control objects are generated with your browser's default font and color settings. The bgColor and valueTextFont properties are ignored.

§        In older browsers that do not support CSS, HTML control objects may not be positioned correctly and appear outside the image.

§        Control objects are reset to their initial values when a Drill Down is executed. To display the current value, attach the selectedValue property to a variable or Get Substitution function for the substitution set.

Fx Graph Objects

§        The Fx graph objects can be resource intensive during display loading and updating. This should be kept in mind when designing displays. A display containing several Fx graph objects may load slowly.

§        If the context menu is opened near an Fx graph object, the menu will be partially hidden by the Fx graph.

§        A right-click inside an Fx graph object will open the Flash Player menu, not the Thin Client's context menu.

iPad Safari 

§        In the iPad settings for Safari, JavaScript must be ON and Block Pop-ups should be OFF. As of this writing, the Thin Client has been tested only on iOS 4.3.5 in Safari.

§        The iPad does not support Adobe Flash, so the Fx graph objects (obj_fxtrend, obj_fxpie, obj_fxbar) are unavailable. The Thin Client automatically replaces the Fx graph objects with the equivalent non-Fx object (obj_trendgraph02, obj_pie, obj_bargraph). Note that the replacement objects behave the same as the Fx objects in most cases but not in all. In particular, obj_trendgraph02 does not support the sliding cursor object nor the legendPosition property. Custom Fx objects are not supported on the iPad.

§        The Thin Client implements scrollbars for table objects and graph objects. However, unlike the scrollbars used on desktop browsers, the scrollbars used on the iPad do not have arrow buttons at each end. This can make it difficult to scroll precisely (for example, row by row) on objects with a large scrolling range.

§        At full size, users may find it difficult to touch the intended display object without accidentally touching nearby objects and performing an unwanted drill-down, sort, scroll, and so forth. This is particularly true of table objects that support drill-down and also scrolling, and also in panel layouts that the tree navigation control. In those cases, the user may want to zoom the iPad screen before interacting with the Thin Client.

§        If the iPad sleeps or auto-locks while a Thin Client display is open in Safari, or if the Safari application is minimized by clicking on the iPad's home button, the display is not updated until the iPad is awakened and Safari is reopened. In some cases it may be necessary to refresh the page from Safari's navigation bar.

Because the iPad uses a touch interface there are differences in the Thin Client appearance and behavior in iOS Safari as compared to the conventional desktop browsers that use a cursor (mouse) interface, such as Firefox and Internet Explorer. These are described below.

§        Popup browser windows: An RTView object's drill-down target can be configured to open a display in a new window. In a desktop browser, when the RTView object is clicked the drill-down display is opened in a popup browser window. But in iOS Safari 4.3.5, only one page is visible at a time, so when the RTView object is touched a new page containing the drill-down display opens and fills the screen. The Safari navigation bar can be used to toggle between the currently open pages or close them.

§        Mouseover text: When mouseover text and drill-down are both enabled on an RTView object (for example, a bar graph), in iOS Safari the first touch on an element in the object (for example, a bar) displays the mouseover text for that element and the second touch on the same element performs the drill-down.

§        Resize Mode and Layout: By default, the Display Server runs with resizeMode set to crop. In crop mode, if a display is larger than the panel that contains it only a portion of the display is visible. In a desktop browser, scrollbars become available to allow the user to scroll to view the entire display. In iOS Safari, scrollbars do not appear but the display can be scrolled by dragging two fingers inside the display. (Dragging one finger scrolls the entire page, not the display).

If the Display Server is run with resizeMode set to scale or layout, the display is resized to fit into the panel that contains it. If a desktop browser is resized after a display is opened, the display is resized accordingly. On the iPad, the Safari browser can only be resized by reorienting the iPad itself, between portrait mode and landscape mode.

The panel layout feature is supported in the Thin Client. However, unlike a desktop browser which resizes to match the layout size, the size of Safari is fixed. So if the Display Server is run with resizeMode set to crop or scale mode, there may be unused space at the edges of the display(s) or, in crop mode, the panels and displays may be cropped.

This means that layout mode should be used for best results on the iPad. For layout mode to be most effective, displays should use the anchor and dock object properties. Please see RTView documentation for more information.

§        Scrolling: The Thin Client implements scrollbars for table objects and graph objects. The scrollbars are activated by dragging with one finger.

If an RTView display is viewed in crop mode and is too large to be displayed entirely in Safari, scrollbars do not appear (as they would in a desktop browser) but the display can be scrolled by dragging with two fingers inside the display.

Scrollbars do not ever appear in a text area control. If the text area contains more text than is visible, use the two finger drag in the text area to scroll the text.

Regardless of the size of a listbox control, it can only display a single item (typically, the selected item). When the listbox is touched, the list of items appear in a popup list. In other words, on iOS Safari the listbox control and the combobox control behave identically.

On the default Thin Client page (opened as http://hostname/rtvdisplay), the panels cannot be resized by dragging the border between the left and right frame, as they can in a desktop browser. The list of displays in the left hand panel can be scrolled by dragging with two fingers inside the panel.

§        Context menu: The Thin Client context menu is opened by a right mouse button click in a desktop browser. It is opened in iOS Safari by touching any location on a display and holding that touch for 2 seconds. The menu appears in the top left corner of the display, regardless of where the display is touched. The items Export Table to Excel, Drill Down, and Execute Command are not included on the context menu in Safari. All other items are available. The Export Table to HTML item is enabled if a table object is touched (unless the table object's drillDownTarget is configured to open another display). After and Export to PDF/HTML is performed, the exported content opens on another page in Safari. From there, the content can either be opened by another application (for example, the iBooks application opens PDF) and emailed, or it can be copied ands pasted into an email.

Test Displays 

Two HTML files are included in the rtvdisplay.war for testing. You can also open a display by entering the JSP directly in the URL.

1.     Open index.html (e.g., http://host:port/rtvdisplay/index.html).

In the left frame of index.html is a list of display (.rtv) files available in the directory where you started the Display Server. The main frame should show the selected display.

2.     Open panels.html (e.g., http://host:port/rtvdisplay/panels.html).

The panels.html file arranges multiple display panels in frames according to your panel configuration file. If the panel configuration file is not found in the project directory where you are running the Display Server, the Display Server searches under lib in your installation directory. See the “Multiple Display Panels” section for information on creating panel configuration files.

Note: The CardPanel and GridPanel are not currently not supported in the Display Server.

3.     Specify the panel configuration file name and the border width (in pixels) in the URL:

http://host:port/rtvdisplay/panels.jsp?file=mypanelconfig&border=1

4.     To specify a display to open in the URL:

http://host:port/rtvdisplay/getdisplay.jsp?display=MyDisplay 

5.     Specify substitutions to apply to your display and a refresh rate (in seconds) which overrides the DefaultRefreshRate in rtvdisplay.properties (specified in Step 2A):

http://host:8080/rtvdisplay/getdisplay.jsp?display=MyDisplay&refresh=30&subs=$sub1:Hello+$sub2:'value+2 

Note: To specify multiple substitutions, separate them with a + (plus). If a substitution value contains a single quote, escape it with a / (forward slash). If a substitution value contains a space, enclose it in single quotes (do not escape these quotes) and replace the space with a +.

Creating Display Servlet HTML Files

The Display Servlet comes with a few HTML files for testing. You can use these to deploy, or you can create your own HTML files which reference getdisplay.jsp to show the specified display (.rtv) file. getdisplay.jsp supports three parameters:

getdisplay.jsp Parameters

For example:

getdisplay.jsp?display=MyDisplay&refresh=30&subs=$sub1:Hello+$sub2:'value+2&rtvsign=8I559A5NA8A5864J6J924N0B2

The HTML returned by getdisplay.jsp is only suitable to be displayed as an entire page, in a window, frame or iframe, so it can be used only in the href tag for links, or the src tag for frames and iframes:

<A HREF="getdisplay.jsp?display=MyDisplay"> View My Display </A>

<FRAME SRC="getdisplay.jsp?display=MyDisplay">

<IFRAME SRC="getdisplay.jsp?display=MyDisplay">

The demos\esphere example shows how to setup a navigation frame on the left that uses getdisplay.jsp to load displays into the main frame. To show multiple displays on the same page, use frames or iframes to display the HTML from getdisplay.jsp. If the name of the frame or iframe corresponds to the window name specified in a drill down target, drill downs on that object update the named frame.

As an alternative, refer to the “Multiple Display Panels” section for information on how you can use RTView to generate a navigation frame for your display. Once you've created a navigation tree definition as described, reference it from an iframe in your .html file as follows:

<iframe name="navtree" id="navtree" src="navtree.xml"scrolling="yes"></iframe>

See demos\dstututorial\displayserver\index.html or servlets\ocmonitor\index.html for an example.

Note: If you are referencing getdisplay.jsp from multiple HTML files in a frameset, and login is enabled, a login screen will appear for each HTML file. To bypass this, go to login.jsp to login and redirect to your page (where display1.html is the name of your page):

<script> location.href = "login.jsp?destPath=display1.html"; </script>

Creating Display Servlet JSP Files

You can create your own JSP files using the RTView tag library to show any number of display (.rtv) files. The RTView tag library defines two tags:

Requirements

There are THREE requirements for JSP pages using the RTView tag library:

1.     Tag library definition

The tag library must be defined at the top of the JSP page. For example:

<%@ taglib prefix="rtv" uri="rtv.tld" %>

Note: The file rtv.tld is contained in rtvdisplay.war.

2.     RTView mouse and key events

For proper operation of the RTView menu, the onmousedown and onkeydown event handler of the page's BODY must be defined. For example:

<BODY onmousedown="rtvBodyMouseDown(event)" onkeydown="rtvBodyKeyDown(event)">

If other functions are already assigned to these event handlers, then those functions must call rtvBodyMouseDown and rtvBodyKeyDown.

3.     RTView menu

Each JSP page must include the RTView menu. For example:

<jsp:include page="rtvmenu.html"/>

This is typically added near the end of the page's BODY, and should not be enclosed in any elements other than <BODY>.

Example

The following is a simple JSP page using the RTView tag library.

<%@ page contentType="text/html;charset=UTF-8"%>

<%@ taglib prefix="rtv" uri="rtv.tld" %>

<HTML>

<BODY topmargin='0' leftmargin='0'

onmousedown="rtvBodyMouseDown(event)"

onkeydown="rtvBodyKeyDown(event)">

<rtv:setup/>

<rtv:display id="d1" displayname="MyDisplay" refresh="0"/>

<rtv:display id="d2" displayname="AnotherDisplay" refresh="30"/>

<jsp:include page="rtvmenu.html"/>

</BODY>

</HTML>

Limitations

A separate timer is used for each <rtv:display/> tag that has a nonzero refresh rate. If all of the display tags on a page use the same refresh rate, they may still be refreshed at slightly different times. A display's timer is restarted when a drill down is performed in the display, which may offset its refresh timer from other refresh timers on the page.

Managing the Display Server Using JMX

The Display Server is instrumented with JMX to allow you to manage and monitor the display cache and application settings. To enable JMX, you must run the Display Server using the -jmxport command line option (see “Command Line Options: Display Server” for more information):

-jmxport:(port number)

The JMX Monitor demo, located in demos\jmxmonitor in your RTView installation, shows how to use RTView to monitor the Display Server using JMX.

Note: Java 1.5.0_06+ is required.

The Display Server contains one MBean named RTViewDisplayServer:name=Manager with the following methods:

The RTViewDisplayServer:name=Manager MBean also supports the following commands:

See “Display Server Configuration” for more information.

Display Server Single Sign-On

In addition to supporting the single sign-on method that utilizes the rtvuser, rtvpass, rtvsign, and rtvrole parameters in getdisplay.jsp, the Display Server also supports two other types of single sign-on:

§        “Login from a Servlet Container”

§        “Login from Custom JavaScript”

Login from a Servlet Container 

User authentication is a general feature of servlet containers (Tomcat, WebLogic, etc). The web.xml servlet file can be configured to require user login before the web server allows access to the servlet. A sample web.xml file included with RTView and located in rtvdisplay\web.xml.auth_example, shows how user authentication can be configured for the Display Servlet. It requires the user to login to the servlet container in order to open any Display Servlet URL, then grants authenticated users access to all Display Servlet URLs.

The sample web.xml specifies DIGEST authentication mode, which tells the browser to prompt for a user name and password, then encrypt the password before sending it to the web server. Most modern browsers and servlet containers support DIGEST mode. Other authentication modes are also defined, but support for those is determined by your servlet container and browser, not by RTView.

To configure the Display Servlet to accept user names authenticated by the servlet container as the login user name for the Display Server:

1.     Set web.xml to require user login before the web server allows access to the servlet.

2.     Modify the LoginEnabled property in the rtvdisplay.properties file as follows:

LoginEnabled=AUTH

To enable single sign-on to the servlet container and the Display Server, the servlet container login name must match the user name defined in the user configuration file. It is not necessary for the passwords to match unless passclientlogin is set to true, since it is assumed that the user name has already been authenticated by the servlet container.

For example, the user database for Tomcat is defined in the file <tomcat_home>/conf/tomcat-users.xml. By default, a user named admin is defined. The default user configuration file for RTView also defines a user named admin. If the Display Servlet files web.xml and rtvdisplay.properties are configured as described above, a user could login to Tomcat as admin and the Display Servlet would then automatically login the admin user to the Display Server, without prompting again for a user name and password. See “Configuration” for more information.

Login from Custom JavaScript 

The Display Servlet also supports login from custom JavaScript by calling the following JavaScript function:

rtvLogin(username, password, role)

This function returns the string "ok" if the login is successful and returns a string with an error message if it fails. The role argument is optional. The password is encrypted before it is sent to the server. To call the rtvLogin function from a custom web page, the page must be included in the Display Servlet web archive file and must import the rtv1.js and rtvx.js script files. An rtvLogout function is also available:

rtvLogout() 

These functions use the XMLHttpRequest object that is included with most modern browsers. In Internet Explorer, if scripting of ActiveX objects is disabled, these functions will fail.

For example, the following HTML file presents the user with a combo box containing the user names admin and guest, and a text box for entering a password. When the user clicks OK, the rtvLogin function is called. If the login information is validated by the Display Server, the displays.html file is opened in the browser. Otherwise an error dialog appears.

Example:

<html>

<script src="rtv1.js"></script>

<script src="rtvx.js"></script>

<script>

function doLogin ()

{

                   var user = document.getElementById("usercombo").value;

                   var pwd = document.getElementById("password").value;

                   var msg = rtvLogin(user, pwd);

                   if (msg != "ok")

                                     alert(msg);

                   else

                                     document.location = "displays.html";

}

</script>

<body>

<div>Please log in</div>

<table border="0" cellpadding="2" cellspacing="0">

                 <tr><td align="right" nowrap>Username:</td>

                 <td align="right">

                                   <select id="usercombo" style="width:120px">

                                                     <option value="admin">admin</option>

                                                     <option value="guest">guest</option>

                                   </select>

                  </td></tr>

                  <tr><td align="right" nowrap>Password:</td>

                  <td align="right"><input type="password" id="password"

                                     style="width:120px"

                                    value="" onkeypress="if (isEnterKey(event)) doLogin()">

                   </td></tr>

                   <tr><td colspan="2" align="right">

                                    <button onclick="doLogin()">OK

                   </td></tr>

</table>

</body>

</html>