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

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

 

Option

Description

cellsperexport

Specify to limit the number of table cells included in HTML/Excel exports requested by the Thin Client. This option avoids out-of-memory exceptions and timeouts when exporting tables with many rows. This option is typically used in conjunction with the cellsperpage option, and has the following behavior:

• If the cellsperexport option is not specified, or if a value of less than a 1000 is specified, the Display Server attempts to export all rows for all tables, regardless of the table size.
• If a table contains fewer cells than the cellsperexport setting, the Display Server exports all rows for that table.
• The exported HTM/Excel table starts with the same first row (or near it) that is visible in the Thin Client. That is, if you scroll to row 900 in the Thin Client and perform an HTML/Excel export, the exported table will begin near line 900.
• If the rows included in an export to HTML/Excel are limited by the cellsperexport option, the first row in the exported file is the same as the first row currently visible in the Thin Client.

 
• An export to HTML/Excel requires less CPU and memory than an export to PDF (see cellsperreport), therefore the value of the cellsperexport option is typically larger than the value of the cellsperreport option. For example, if an export to HTML/Excel was performed on a table with 5 columns and 100,000 rows, and the option cellsperexport 30000 was specified when the Display Server was launched, 6000 rows (30000/5) would be included in an exported HTML/Excel file for that table. If the cellsperreport 5000 option was specified, an export to PDF would include 1000 rows from the table.

Note: This option is not recognized by the Builder or the Viewer.

Example:

cellsperpage 10000

cellsperexport 30000

cellsperpage

Specify server-side table paging and sorting mode, also referred to as paging mode, for the Thin Client. Paging mode improves the performance of displays containing table objects (obj_table02) with many rows. In paging mode, the Display Server sends a specified maximum number of table data rows at a time to the Thin Client, rather than sending all table data rows at once. This option avoids out-of-memory exceptions, timeouts and sluggish performance that can otherwise occur from processing and transmitting all of the rows at once. This option is typically used in conjunction with the cellsperexport and cellsperreport options, and can also be specified on the command line. See Command Line Options: Display Server for more information.

The page of rows sent from the Display Server to the Thin Client includes all of the rows currently visible in the Thin Client plus additional rows above and/or below the visible rows. If the user scrolls beyond the rows contained in the current page or clicks on a column header to change the sorting order, the Display Server sends another page of rows in response.

To specify in the DISPLAYSERVER.ini file:

cellsperpage NNNN

where NNNN specifies the number of table cells the Display Server includes per page. Typical values for cellsperpage are 10000 to 30000.

 

The number of cells in a table is equal to the number of rows multiplied by the number of columns. For example, if cellsperpage = 10000, and the display contains a table with 5 columns, the Display Server uses a page size of 2000 rows for the table. This means the Display Server sends a maximum of 2000 table rows to the Thin Client at a time. If the table contains 40,000 rows the Display Server sends rows 1 through 2000 to the Thin Client when a user opens the display. If the user then scrolls to the bottom of the table, the Display Server sends rows 38,001 through 40,000 to the Thin Client. Similarly, if the user clicks on a column header to sort by that column, the Display Server sorts the table and sends the first 2000 sorted rows to the Thin Client. After the user scrolls or sorts a table in paging mode, the Thin Client displays '...' in each cell and an hourglass cursor appears over the table while it waits to receive the new page from the Display Server. The cellsperpage option also has the following behavior:

 
• A smaller value for cellsperpage reduces the memory requirements for processing large tables in the Display Server, Application Server, and browser. A larger value smooths scrolling in the Thin Client because it increases the number of rows through which the Thin Client can scroll before it needs to request another page from the Display Server.
• If the cellsperpage option is not specified, or if a value less than a 1000 is specified, paging mode is disabled and the Display Server sends all data rows to the Thin Client for all tables regardless of the table size.
• If a table contains fewer cells than the cellsperpage setting, the Display Server sends all rows for that table.
• Paging mode only affects the behavior of obj_table02 objects, and only in the Thin Client.
• The maxNumberOfHistoryRows property on obj_table02 still limits the maximum number of rows that are shown in the table, regardless of the cellsperpage setting.
• After scrolling to a new page, if the user immediately drags the scrollbar again, the table may not react. The user may need to nudge the scrollbar knob or click on the scroll up/down arrows to make the table react.

 
• The Thin Client Export Table to Excel/HTML/PDF feature is not affected by paging mode. Attempts to export a table with many rows may result in timeouts or out-of-memory exceptions in the Display Server or in the Display Servlet. To avoid those errors, see the cellsperexport and cellsperreport Display Server options.
• After the user clicks a column to sort a table, the table vertical scrollbar is reset to the top position.
• The Thin Client ignores the scrollToSelectionFlag property on a table that is in paging mode.
• A table row selection is cleared when a different page of rows is received from the Display Server. If a table is in paging mode, only rows that are on the current page can be selected, even if the table multiSelectFlag property is checked.

cellsperreport

Specify to limit the number of table cells included in PDF exports requested by the Thin Client. This option avoids out-of-memory exceptions and timeouts when exporting tables with many rows. This option is typically used in conjunction with the cellsperpage option, and has the following behavior:

• If the cellsperexport option is not specified, or if a value of less than a 1000 is specified, the Display Server attempts to export all rows for all tables, regardless of the table size.
• If a table contains fewer cells than the cellsperreport setting, the Display Server exports all rows for that table.
• In an exported PDF file, the scroll position of the Thin Client has no effect on the starting row in the PDF file, nor any effect on the rows that are included in the PDF report.
• An export to PDF requires more CPU and memory than an export to HTML/Excel (see cellsperexport), therefore the value of the cellsperreport option is typically smaller than the value of the cellsperexport option. For example, if an export to HTML/Excel was performed on a table with 5 columns and 100,000 rows, and the option cellsperexport 30000 was specified when the Display Server was launched, 6000 rows (30000/5) would be included in an exported HTML/Excel file for that table. If the cellsperreport 5000 option was specified, an export to PDF would include 1000 rows from the table.

Note: This option is not recognized by the Builder or the Viewer.

Example:

cellsperpage 10000

cellsperreport 5000

clearsubs

Set to false to preserve the value of local variables, for which the Use as Substitution option is selected, when navigating to different displays in the same panel. This behavior is consistent with that of the Display Viewer.

By default (or if set to true), the Display Server will reset all local variables to their initial values when navigating to a new display regardless of the variable's value in the current display.

Note: Global variables are not affected by this option.

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

Specify a value between 0 and 100 to control the quality of .jpg images. If the value is 100, the Display Server will output the highest quality image with the lowest compression. If the value is 0, the Display Server will output the lowest quality image using the highest compression. Default is 75.

If the -verbose option is specified at startup, image creation time/size for each display refresh will be shown in the Display Server console output.

Note: The Display Server chooses an image format (.jpg or .png) for each display, depending on which format produces the smallest image size (in bytes). The size of .png images is controlled by the pngcompress option.

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 (see Managing the Display Server Using 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 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.

permitpanel

Specifies the panel layout files that the server will read.

A panel layout for the thin client is requested from the display server with a URL parameter as follows:

panels.jsp?file=X

where X is the name of the panel layout file that the server should read. By default, the display server will attempt to read any filename on the server that is specified by the URL parameter.

The permitpanel option allows you to specify the file(s) that the display server will read in response to a panels.jsp request. Requests from panels.jsp for any other files are rejected with a Permission denied error shown in the browser, regardless of whether the file exists or not, and the server will not attempt to read such files. The option may be specified multiple times to allow access to multiple panel files.

Command-line example:

run_displayserver -permitpanel:PANELS.ini -permitpanel:layout.xml

 

DISPLAYSERVER.ini example:

permitpanel PANELS.ini

permitpanel layout.xml

permitfile

This option prevents attempts to load remote files, as follows:

-permitfile:LOCAL_ONLY

 

If this option is specified, any rtv or image files that are referenced by URL will not be read and the server will log a message similar to the following:

non-local file read permission denied: http://host/somefile

pngcompress

Specify a value between 1 and 9 to control the quality of .png images. If the value is 1, the Display Server will output the highest quality image with the lowest compression. If the value is 9, the Display Server will output the lowest quality image using the highest compression. Default is 9. A value of 3 is a good compromise between speed and quality.

If the -verbose option is specified at startup, image creation time/size for each display refresh will be shown in the Display Server console output.

Note: The Display Server chooses an image format (.jpg or .png) for each display, depending on which format produces the smallest image size (in bytes). The size of .jpg images is controlled by the imagequality option.

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.

shared_display

Enables Display Sharing for a display. Add the name of the display (.rtv) file and the substitutions, if any, to be applied when the display is opened:

shared_display <filename> [substitutions]

Where:

<filename> is the name of a display (.rtv) file to share.

[substitutions] is an optional list of substitution string:value pairs, separated by spaces. If a substitution value contains spaces it must be enclosed in single quotes.

Example:

shared_display navtop.rtv

shared_display summary.rtv $region:East

See Overview - Display Sharing for more information.

 

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:

 

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.

DisplayServerConnectionFailback

When set to true, the rtvdisplay servlet attempts to reconnect to its primary Display Server, approximately every 30 seconds, while connected to its backup Display Server. When the connection to the primary server is restored the servlet disconnects from the backup server and resumes using the primary server. By default, this option is false. To enable this behavior add DisplayServerConnectionFailback=true, then rebuild and deploy the rtvdisplay.war file.

DisplayServerConnectionPool

Specifies the maximum number of simultaneous connections the Display Servlet makes to the Display Server, and, consequently determines the maximum number of display requests the Display Server processes simultaneously. The default value is 10.

This option improves response times on multi-CPU systems by enabling the Display Servlet to manage a pool of threaded requests to the Display Server. By default, the Display Servlet opens to 10 simultaneous connections to the Display Server, allowing it to process up to 10 display requests simultaneously.

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. See Background Properties, Creating Display Servlet HTML Files , and Creating Display Servlet JSP Files for more information.

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.

MaxSharedDisplays

Used to configure Display Sharing, specifies the maximum number of shared displays for which the Display Servlet stores content. The default is 10. (This property does not need to be included in the rtvdisplay.properties file if the default setting is used). See Overview - Display Sharing for more information.

Note: Best practices dictate that the MaxSharedDisplays property be set to a value at least as large as the number of shared_display entries in DISPLAYSERVER.ini.

MenuItemsToHide

Allows you to remove items from the thin client context menu by specifying the names of the items in rtvdisplay.properties. Multiple names are separated by commas. For example, the following will remove the "Export Table To HTML", "Export Table to Excel", "Export PDF", and "Status" items from the menu:

MenuItemsToHide=PDF,ExcelTable,HtmlTable,Stat

After adding this property, the corresponding .war file must be rebuilt and redeployed.

Here are the names of all of the menu items, with the English label string of the menu item in quotes if it differs from the item name:

Refresh

Back

Next

Command "Execute Command"

Drill "Drill Down"

ExcelTable "Export Table to Excel"

HtmlTable "Export Table to HTML"

PDF "Export PDF"

CopyCell "Copy Cell Value"

Stat "Status"

Logoff "Log Off"

Use the menu item name when configuring MenuItemsToHide, not the label string.

SharedDisplayRefreshInterval

Used to configure Display Sharing, specifies the time interval at which the Display Servlet updates the content it uses for a shared display. The default is 15 seconds. See Overview - Display Sharing for more information.

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

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

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:

 

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.

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:

 

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

 

Option

Description

Command Execution

Depending on the command, it executes either on the Display Server or the client. See Define/Execute Command for further information. Some commands are not supported on the Display Server. See Display Server Limitations (below) for information.

Control Objects

HTML control objects are generated for the following:

• Combo Box
• Check Box
• Text Entry
• List Box
• Push Button
• Slider

Display Refresh

Right-click in the page and select Refresh to refresh the display.

Note: The web browser's Refresh button resets the display to its original state if you have updated variables or substitutions using an object in the display.

Drill Down

Drill down functionality is supported using hyperlinks. Single-click to activate a drill down display.

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 Display Server Single Sign-On is configured. The default is false.

Popup Menu Interaction

Right-click in the page to open a Display Server popup menu.

Hold down the <Shift> key while you right-click to bring up the web browser's popup menu.

Logout by right-clicking and selecting Log Off before closing the web browser. Some web browsers may not logout the user after the browser window has been closed.

Resize Mode

To globally specify a Window Resize Mode, select Tools>Options>General Tab or set -resizemode on the command line. It is also possible to set a specific Resize Mode for each particular display (.rtv) file using the Background Properties dialog.

The default Resize Mode for the Thin Client is Crop. Runtime behavior in the Thin Client differs in the following cases:

• When the initial display is opened, the browser frame is not resized to match the display size as it is in the Display Viewer. Instead, in the default Crop mode, the display will appear in its full size. Additionally if the browser frame is larger than the display, then unused space will appear below and to the right of the display. If the browser frame is smaller than the display, then scrollbars will appear. In Layout and Scale modes, the display will briefly appear at its default size and will then resize to fit the browser frame size. This may also occur if another tab is opened in the browser, the browser is resized, and then the browser tab that contains the Thin Client is reselected.

 
• In Layout and Scale modes, after resizing the browser frame, table objects will revert to their original states. For example if you clicked on a column header in a table to sort the column, after resize the table would revert to its default sort. Likewise if you scrolled in a table or resized the legend, after resize the scrollbars and legend will revert to their initial position and size.
• In Scale mode, there will be unused space in the browser frame. This is due to the fact that, to ensure equal scaling in both dimensions, the display will only use the largest 4"x3" rectangular area of the frame. The unused area will have the same color as the display background, but will not have a gradient fill.

Status

From the Display Server popup menu, select Status to access the following information:

• Name of the current RTView display
• Time the display was last refreshed
• URL and connection status for the rtvdisplay servlet
• Hostname and port used by the servlet to connect to the Display Server

Table Objects

The Display Server generates JavaScript to display table objects (obj_table02). The JavaScript table allows scrolling, sorting and column resizing.

Right-click on a table and select Export to Excel to open Excel in a web browser, or Export to HTML to export to an HTML file with the data from the selected table.

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.

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

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

 

Parameter

Description

display

The name of the display (.rtv) file to show.

refresh

The refresh rate (in seconds) at which the display inside this URL should be refreshed. Set to 0 if you do not want displays periodically refreshed.

Note: This refresh rate overrides the rtvRefreshInterval property. If no refresh rate is specified, the interval defined in the rtvdisplay.properties file will be used unless you have set a value for rtvRefreshInterval. This parameter is optional. See Background Properties and Display Server Configuration for more information.

rtvpass

If Login is enabled, specify the password in plain text to use for the login. This parameter must be used in conjunction with rtvuser and will bypass the login dialog. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used. Use the rtvsign parameter instead to specify an encoded user name and password. Any non-alphanumeric characters in the parameter value must be URL encoded as %xx, where xx is the hexadecimal value of the ASCII character.

Note: If the user name or password specified is not valid, the login dialog will appear.

rtvrole

If Login is enabled, specify the role to use for the login. This parameter must be used with rtvsign or rtvuser and rtvpass. If this parameter is not specified for a user with multiple roles, the first role will be used. Any non-alphanumeric characters in the parameter value must be URL encoded as %xx, where xx is the hexadecimal value of the ASCII character.

Note: It may be necessary to URL-encode the username, password, or role, depending on the characters they contain.

rtvsign

If Login is enabled, specify an encoded user name and password to use for the login, and bypass the login dialog. Contact SL Technical Support at support@sl.com to request a copy of the utility to create the encoded strings. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used.

Note: If the user name or password specified is not valid, the login dialog will appear.

rtvuser

If Login is enabled, specify the user name in plain text to use for the login. This parameter must be used in conjunction with rtvpass and will bypass the login dialog. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used. Use the rtvsign parameter instead to specify an encoded user name and password. Any non-alphanumeric characters in the parameter value must be URL encoded as %xx, where xx is the hexadecimal value of the ASCII character.

Note: If the user name or password specified is not valid, the login dialog will appear.

subs

The substitution(s) to apply to the display. 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 +. Any non-alphanumeric characters in the parameter value must be URL encoded as %xx, where xx is the hexadecimal value of the ASCII character. This parameter is optional.

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:

 

setup

This tag must be included once on each JSP page that uses the RTView tag library. It will insert references to Javascript files and CSS files required by the Display Server. The setup tag must be included in the JSP page before the first display tag. This tag has no attributes.

Example:

<rtv:setup/>

display

This tag inserts an HTML DIV tag containing an RTView display. The display tag has the following attributes:

Attribute

Description

id

Required. The ID for this tag. This must be unique on the JSP page. An id must start with a letter and may contain only letters and digits.

displayname

Required. The string specifying an RTView display (.rtv) file name. This should correspond to the name of a display (.rtv) file accessible by the Display Server.

refresh

Optional. A positive number defining the rate, in seconds, at which the display inside this DIV should be refreshed. If zero, the DIV is not periodically refreshed.

Note: This refresh rate overrides the rtvRefreshInterval property. If no refresh rate is specified, the interval defined in the rtvdisplay.properties file will be used unless you have set a value for rtvRefreshInterval. See Background Properties and Display Server Configuration for more information.

style

Optional. The CSS style to be used for this DIV.

Example:

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

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

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

 

Method/Attribute

Type

Description

DisplayData

TabularData

One row for each cached display containing:

Display Name - The name of the .rtv file for the display.

Display Number - The display number. These values always range from 1 to N, where N is the number of displays currently in the cache. This number is not tied to a particular display (i.e. display name + substitutions), and can change as displays are automatically removed from the cache.

Last Reference Time - The amount of time that has elapsed since the display was last requested by a client. When this time exceeds the Display Timeout, the display is eligible for automatic removal from the cache.

Substitutions - The substitution string for the display.

DisplayTimeout

int

The current display timeout setting.

ImageQuality

float

The current image quality setting.

MaximumDisplayCount

int

The current maximum display count setting.

NumberOfDisplays

int

The number of cached displays.

Sessions

TabularData

One row for each active client session. Typically, there is one client session for each browser instance that is currently viewing a Thin Client display. The Sessions table contains the following columns:

Session ID - A unique ID for the client session. The Session ID is also a column in the mbean's DisplayData table, which contains one row for each display that is currently open in a Thin Client. The Session ID is a unique string assigned to a session by RTView and is not the same value as the session identifier assigned by the webapp manager (e.g. Tomcat).

Client Address - The IP address of the client. The Client Address will be in IPv4 (e.g. x.x.x.x) or IPv6 (x:x:x:x:x:x:x:x) notation, depending on which protocol the client browser used to connect to the rtvdisplay servlet. For example, if the client is on localhost then the client address could be shown as 127.0.0.1 for IPv4, or 0:0:0:0:0:0:0:1 for IPv6.

Duration - The elapsed time since this client session was created. The Duration column and the Last Reference Time column show elapsed time as "d hh:mm:ss" where d = days, hh = hours, mm = minutes and ss = seconds. By default, a session expires and is removed from the table after about 10 or 11 minutes of inactivity (that is, when the elapsed time shown in the Last Ref Time column is "0 00:11:00" or more). If the Display Server's display_timeout property has been set, then the session expiration is 10 times the display_timeout value. (The default display_timeout is 60 seconds).

Last Reference Time - The elapsed time since this client opened or refreshed a display.

User - The login user name. The User and Role columns will be blank if the login feature of the rtvdisplay servlet is disabled.

Role - The login user role. The User and Role columns will be blank if the login feature of the rtvdisplay servlet is disabled.

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

Method/Attribute

Description

clearDisplayCache

Clears the cached displays as well as preloaded displays.

setDisplayTimeout

Set the display timeout.

setImageQuality

Set the image quality.

setMaximumDisplayCount

Set the maximum display count.

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 script file. An rtvLogout function is also available:

rtvLogout()

These functions use the XMLHttpRequest object that is included with most modern browsers.

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.

Note: The following example custom file would need to be named login.jsp and should replace the original login.jsp in the servlet.

Example:

<html>

<script src="rtv1.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

var homePage = "displays.html";

if (window.frameElement && window.parent) {

window.parent.location = homePage;

} else {

document.location = homePage;

}

}

</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>