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 Data Sources section of this documentation for system requirements and setup specific to your data source.

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

Option	Description
display_timeout	Amount of time, in seconds, that a display can be kept in memory after the Display Servlet has stopped requesting it. Default is 60 seconds (to allow faster load time when switching between displays).
imageformat	Specify image format: jpg or png. If imageformat is not specified, the Display Server will automatically select the image that results in the fewer number of bytes for each display. By default the png format will be selected for most displays, but the jpg format is preferred for: a background image in the main display background images in graphs or labels images with color gradients (especially those with lower imagequality values).
imagequality	A value between 0 and 100 which controls the quality of the generated images. If the value is 100, the Display Server outputs the highest quality image with the lowest compression. If the value is 0, the Display Server outputs the lowest quality image using the highest compression. Default is 75.
history_config	To preload a display, making data immediately available. Preloaded displays are not unloaded unless the Display Server is restarted or the display cache is cleared via JMX. This option may be used multiple times to specify multiple displays to preload: history_config rtvFileName substitution Substitutions are optional and must use the following syntax: $subname:subvalue $subname2:subvalue2 If a substitution value contains a single quote, it must be escaped using a / : $filter:Plant=/'Dallas/' If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes: $subname:subvalue $subname2:'sub value 2' A substitution string cannot contain the following: : | . tab space , ; = < > ' " & / \ { } [ ] ( )
max_displays	Number of displays kept in memory. Default is 20 (to optimize memory used by the Display Server).
passclientlogin	If true, pass Enterprise RTView login information into all data sources that have the Use Client Credentials option enabled. NOTE: Some data sources do not support this feature. For information on Application Options for your data source, refer to the Data Sources section of this documentation.
port	Port that the Display Server uses to communicate with the Display Servlet. Default is 3279.  NOTE: If you will be running multiple Display Server applications on the same application server, you must specify a unique port for each application.

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

display_timeout 60
imagequality 75
history_config trend1.rtv
max_displays 20
port 3279
passclientlogin false

User Name: admin
Password: admin

To use this security feature, do the following:
1. Define the users that can access Enterprise 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 Enterprise 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 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 Enterprise RTView login into these database connections.

Running Display Server

You can run the Display Server as an application or in the background as a Windows Service.

To run the Display Server as an application: open an initialized command 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.

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.

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.

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 Enterprise 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 Enterprise RTView.

Display Servlet Configuration
The Display Servlet reads rtvdisplay.properties to get configuration information. An rtvdisplay.properties file with the default settings is in servlets\rtvdisplay. If you do not want to use the default settings, copy this file to your project directory and modify it. 

Set the following options in rtvdisplay.properties:

Option	Description
DisplayServerBackup	The name of the host and port for designated backup servers. Designation of backup servers is optional; multiple backup servers should be separated by a comma.
DisplayServerHost	The name of the host on which the Display Server is running. Default is localhost. NOTE: Default localhost assumes the Display Server and Display Servlet are running on the same application server.
DisplayServerPort	Port for communicating with the Display Server. Default is 3279. This must be the same port specified in your DISPLAYSERVER.ini file. NOTE: If you will be running multiple Display Server applications on the same application server, you must specify a unique port for each application.
DisplayServerTimeout	Amount of time (in seconds) the Display Servlet waits for replies from the Display Server. Default is 15 seconds.
DefaultRefreshInterval	Rate (in seconds) at which displays are refreshed. Default is 15 seconds. Set this interval to 0 if you do not want displays automatically refreshed. NOTE: The refresh rate specified in the rtvRefreshInterval property or the URL or DIV tag used to open a display will override this value.
LoginEnabled	Set to true to enable role management security. If enabled, a login dialog will appear when the client browses to the URL for the Display Servlet, unless single sign-on is configured. The default is false.
VirtualThreshold	Set the cell count of a table at which point Virtual Mode is used. Default is 500.  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.

Example of the rtvdisplay.properties file:

DisplayServerHost=localhost
DisplayServerPort=3279
DisplayServerTimeout=15
DefaultRefreshInterval =15
LoginEnabled=true
VirtualThreshold=500
DisplayServerBackup=host:3238

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

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 your rtvdisplay.properties file 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 Enterprise 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 Enterprise 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, 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 Enterprise 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 Enterprise 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.

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 thesse 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:
 

http://host:8080/rtvdisplay/index.html

Where host and port are correct for the application server hosting the Display Servlet.

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.

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.

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.
• 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:

• Multiple rows can only be selected using Ctrl+Left click.
• A mouse click must be used to select columns.
• A right-click does not select a row under the mouse pointer
• Once a table is displayed, changes to the value of the multiSelectFlag property are ignored.
• 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.

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 Enterprise 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 have the following limitations:

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

The Fx graph objects have the following limitations:

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

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:

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

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):
 

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