JMS Data Source

The Java Message Service (JMS) defines the standard for reliable enterprise messaging. Enterprise messaging, often referred to as Messaging Oriented Middleware (MOM), is universally recognized as an essential tool for building enterprise applications. By combining Java™ technology with enterprise messaging, the JMS API provides a powerful tool for solving enterprise computing problems.

With RTView, the JMS data source is designed to take advantage of this standard and therefore can be used with any JMS implementation. SL tests for compatibility against these commercial JMS offerings: IBM WebSphere® MQ, TIBCO Enterprise Message Service™, Progress SonicMQ® and Sun SeeBeyond™.

With RTView you can subscribe to JMS topics, browse JMS queues, or send JMS messages and then build sophisticated monitoring and management applications that allow you to:

•        present real-time business content included in JMS messages;

•        archive business metrics in the RTView Historian for trend analysis;

•        provide a look at application health and troubleshooting by analyzing message content; and/or

•        instigate interactive measures by sending JMS messages to applications.

This section includes:

§        “JMS System Requirements and Setup” on page 523

§        “Attach to JMS Data” on page 524

§        “Define JMS Command Window” on page 532

§        “JMS Data Source Substitutions” on page 535

§        “Application Options -- JMS” on page 535

§        “JMS Handler” on page 542

§        “RTView Deployment - JMS” on page 544

§        “JMS Demos” on page 545

§        “Quick Start Tutorial: JMS” on page 547

§        “JMS Data Simulator” on page 552

§        “JMS Data Source Command Line Options” on page 558

JMS System Requirements and Setup

System Requirements

In addition to basic “System Requirements”, the JMS data source is only available if you include your JMS provider's JMS jars in “RTV_USERPATH”. See the README_sysreq.txt file in your installation’s home directory for details.

Setup

In addition to general environment variables (see “Setup”), you must include the JMS jars for your provider in “RTV_USERPATH”:

Attach to JMS Data

Note: The JMS data source may not be licensed in your RTView installation.

From the Object Properties window you can access the Attach to JMS Data dialog, which is used to register an RTView object as a listener for a JMS message topic or queue browser. In the Attach to JMS Data dialog, enter the name of a message topic or queue and specify which message field should be used to update an object property. RTView supports attaching to the following message types:

•        MapMessage

•        TextMessage

•        BytesMessage - This message type requires a “JMS Handler”.

•        ObjectMessage - This message type requires a “JMS Handler”.

Once an object property has been attached to a message, it receives continuous updates. For topics, it updates whenever a new message is received. For queue browsing, the current contents of the queue are polled every update period, but not more often than once every six seconds. For example, if your update period is two seconds, the queue will only be polled once every third update period. It is also possible to set up a filter based on a particular field in the message.

Note: IBM WebSphere MQ does not allow you to browse queues, subscribe to topics or send messages on the same connection. Only one of these can be performed on each connection. Therefore, you have to define a separate connection for each one.

For example, a message with the topic orders.STATUS.London has two possible message fields: PERCENTCOMPLETED and PLANT. The first field, PERCENTCOMPLETED, tracks the status of an order. The second field, PLANT, indicates which London plant (L1 or L2) the message is describing.

Setting the Message Field to PERCENTCOMPLETED will set the attached object to indicate the real-time status of an order. Without a filter, the attached object would receive simultaneous updates from both London plants. To receive updates for a specific plant, you would set up a filter for the PLANT field and enter a Filter Field Value of either L1 or L2 to indicate which London plant will update the attached object.

In the JMSALIAS.ini file, you may create an alias for (top level or nested) messages, message fields and XML data embedded in messages (see “Create JMS Message Alias” for more information). Once JMSALIAS.ini is saved and RTView is restarted, you will be able to access these aliases from the Topic Name drop down menu:

To bring up the Attach to JMS Data dialog, right-click on the Property Name from the Object Properties window and select Attach to Data>JMS. The Attach to JMS Data dialog provides several drop down menus that allow you to specify information regarding a message. If the drop down menu does not contain the item you require, type your selection into the text field.

Attach to JMS Data Dialog

Drop down menus populate based on message topics added from the Application Options dialog or those typed directly into the Attach to JMS Data dialog. Message topics will not be added to drop down menus until at least one JMS message with that topic has been received by RTView.

When an object property has been attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing values from the Object Properties window is no longer possible. To remove the data attachment and resume editing capabilities in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.

Validation Colors

Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid. Information is validated against the message topic added from Application Options dialog, or those typed directly into the Attach to JMS Data dialog. Message topics will not be validated until at least one JMS message with that topic has been received by RTView.

Note: Some topics using wild card characters are not validated at this time.

The following describes the significance of the validation colors:

Substitutions

The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. A generic Message Topic such as $topic is used instead of a specific message. Later when the display is running, this generic value is defined by the actual name of a specific message, such as orders.STATUS.London. In this way, a single display can be reused to show data from a number of different sources. For more information on creating displays using substitution values, see “Substitutions”.

Special Values

The following special values can be entered for message and filter fields:

Select Message Fields (Tables Only)

From the Attach to Data dialog you can specify which message fields to display as columns in a table and in what order they will appear. In order to populate the listing of available message fields, you must first select a valid topic.

To bring up the Select Columns dialog, click on the  button in the Message Field field (or right-click in the Message Field field and click Select Columns). The dialog should contain a list of Available Columns that you can add to your table.

To add a field, select an item from the Available Columns list and click on the Add button. If the item you require is not listed, type your selection into the Enter Column Name field. Click the Remove button to delete an item previously added to the Selected Columns list. You can control the order of fields in a table by arranging the items in the Selected Columns list with the Move Up and Move Down buttons.

Validation colors indicate whether selected message fields are valid. However, if even one field selected is invalid the Message Field field in the Attach to JMS Data dialog will register as an invalid entry.

If no data is available for a table row within a selected column, the table cell will display one of the following values: N/A, false, 0, or 0.0.

The following describes Attach to JMS Data dialog commands:

Create JMS Message Alias

Note: The JMS data source may not be licensed in your RTView installation.

In the JMSALIAS.ini file, you can create aliases for (top level or nested) messages, message fields and XML data embedded in JMS messages. Once JMSALIAS.ini is saved and RTView is restarted, you will be able to access these aliases from the Message Topic drop down menu in the “Attach to JMS Data” dialog.

It is possible to specify a directory for your initialization files. If no directory has been specified for initialization files and JMSALIAS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information.

To define an alias in JMSALIAS.ini use the following syntax:

aliasName connection topic partialUpdatesOK fieldNameList

Nested MapMessage Field Aliases

In the alias defined below named allOrders, a message with the topic orders.STATUS.* contains the customer_info MapMessage field, which is nested within the sales MapMessage field.

Note: Not all JMS providers support nested MapMessages.

allOrders myConnection orders.STATUS.* sales::customer_info

A table attached to allOrders will contain a column for each field in the customer_info message field.

It is also possible to create an alias for a specific field in the customer_info message field.

allNames myConnection orders.STATUS.* sales::customer_info::NAME

A table attached to allNames would contain one column for the NAME field.

Embedded XML Data Aliases

To display XML data embedded within a JMS message, add the $xml: prefix to the field name that contains the XML data. In the alias defined below named OrderInfo, the OrderData message field (containing XML data) is nested within the Production MapMessage field:

OrderInfo myConnection orders.STATUS.* Production::$xml:OrderData

It is also possible to display XML from a TextMessage:

OrderInfo myConnection orders.STATUS.* $xml:<TEXT>

There are several ways that the following XML values and attributes (contained in the message field named OrderData) can be defined in an alias.

       <Orders>

               <Order Date="March 1, 2004" Time="12:00:00">

                       <OID>12345</OID>

                       <Customer>

                               <Name>John Smith</Name>

                               <CID>6789</CID>

                       </Customer>

               </Order>

              <Order Date="March 1, 2004" Time="12:00:00">

                       <OID>67891</OID>

                       <Customer>

                               <Name>Alice Chen</Name>

                               <CID>1001</CID>

                       </Customer>

               </Order>

       </Orders>

Displaying XML Values

To display all XML values contained within Order tags of the OrderData MapMessage field, you would use the following alias.

Note: Hierarchical XML tags are converted to column names using the _ symbol (e.g.: Customer_Name, Customer_CID, etc.).

OrderInfo myConnection orders.STATUS.* $xml:OrderData::Orders::Order

To display the same data from a TextMessage:

$xml:<TEXT>::Orders::Order

You can display specific information contained within Customer tags of the OrderData message field using the following alias:

CustomerInfo myConnection orders.STATUS.* $xml:OrderData::Orders::Order::Customer

To display the same data from a TextMessage:

$xml:<TEXT>::Orders::Order::Customer 

Displaying XML Values and Attributes

To display all XML values and attributes contained within Order tags of the OrderData message field, you would use the following alias.

Note: Hierarchical XML tags are converted to column names using the _ symbol (e.g.: Customer_Name, Customer_CID, etc.).

OrderInfoAllValuesAndAttribs myConnection orders.STATUS.* $xml:OrderData::Orders::Order:$attrib=**

To display the same data from a TextMessage:

$xml:<TEXT>::Orders:Order:$attrib=** 

Displaying XML Attributes Only

You can display all of the XML attributes contained within Order tags of the OrderData message field using the following alias:

OrderInfoAllAttribs myConnection orders.STATUS.* $xml:OrderData::Orders::Order:$attrib=*

To display the same data from a TextMessage:

$xml:<TEXT>::Orders::Order:$attrib=*

It is also possible to display only a particular attribute (Date) contained within the Order tags.

OrderInfoDate myConnection orders.STATUS.* $xml:OrderData::Orders::Order:$attrib=Date

To display the same data from a TextMessage:

$xml:<TEXT>::Orders::Order:$attrib=Date

Define JMS Command Window

Note: The JMS data source may not be licensed in your RTView installation.

You can access the Define JMS Command window from the Object Properties window. The Define JMS Command window is used to assign a JMS message to an object's command property, giving you the ability to send messages from within an RTView display. If you execute a JMS command from a Thin Client with Direct Data Connection or any Served Data deployment, the command will execute on the server.

Note: IBM WebSphere MQ does not let you send a command on a connection that you receive messages on. Therefore, you need to define separate connections for executing commands and attaching to data.

To open the Define JMS Command window, right-click on the appropriate command property in the Object Properties window and select Define Command>JMS. The information supplied assigns a message to the command property. See the “Define/Execute Command” section for information on how to execute a command.

Drop down menus populate based on message topics added from the Application Options window or those typed directly into the Attach to Data window. Message topics will not be added to drop down menus until at least one JMS message with that topic has been received by RTView.

Substitutions

The Substitutions feature allows you to build open-ended displays in which commands depend on values defined at the time the display is run. A generic topic such as $topic is used instead of a specific topic. Later when the display is running, this generic value is defined by the actual name of a specific topic, such as orders.STATUS.London. In this way, a single display can be reused to send a number of different messages. Substitutions can be used in any field in this dialog. For more information on creating displays using substitution values, see “Substitutions”.

Special Values

The following describes Define JMS Command window commands:

JMS Data Source Substitutions

 In addition to standard built-in substitutions, this data source also sets the following drill down substitutions:

See “Drill Down Substitutions” for more information.

Application Options -- JMS

To access the Application Options dialog, in the Display Builder select Tools>Options.

Options specified in JMS tabs can be saved in an initialization file (JMSOPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server and Historian to set initial values. If no directory has been specified for your initialization files and JMSOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information

Note: Options specified using command line arguments will override values set in initialization files. See “Weather Data” for more information.

There are three Application Options tabs for JMS: “JMS Options Tab”, “JMS Messages Tab”, and the “JMS JNDI Connections Tab”.

JMS Options Tab

JMS Messages Tab

Message topics listed on the JMS Messages tab are used to populate drop down menus in the “Attach to JMS Data” dialog. RTView starts listening for new topics added to the Topics list after you click OK, Apply, or Save.

JMS Connections Tab

This tab allows you to add or remove connections and set your default connection.

When you add a JMS connection to the list it will be highlighted in yellow indicating that RTView has not connected to it. To attempt to connect to a JMS connection, click OK, Apply, or Save. If the background remains yellow, then RTView was unable make a connection. Check that your JMS connection was setup correctly and that the JMS message server is running.

Note: Regardless of which tab you are currently working from in the Application Options dialog, RTView will attempt to connect to all unconnected connections each time you click OK, Apply, or Save.

Note: Additional setup is required to connect to your JMS Server using SSL. This is only supported for JMS connections to TIBCO EMS. See “JMS SSL Parameters” for more information.

Field Name	Description
Default Connection	Name of connection used as the default for data attachments. Select from drop down menu to change default setting.
Add Connection	Click to open the Add Connection dialog. To edit, select a connection from the list and double-click. Connections that are updating objects in a current display or that are listening for topics defined on the “JMS Messages Tab” cannot be renamed.
	Connection Name -- Name to use when referencing this JMS connection in your data attachments.
	Factory Class Name -- The fully qualified name of the topic connection factory class to use when creating this connection. The path to this class must be included in the RTV_USERPATH environment variable. Refer to your JMS provider documentation if you do not know the name of this class. To use IBM Websphere MQ as a JMS Connection, select either a Topic connection which can be used to subscribe to topics, or a Queue connection which can be used to browse queues. For a Topic connection select:  com.ibm.mq.jms.MQTopicConnectionFactory  For a Queue connection select:  com.ibm.mq.jms.MQQueueConnectionFactory Then specify the Host Name, Port and Queue Manager used by IBM Websphere MQ.
	Server URL -- Complete URL for your JMS message server. This parameter is optional.
	User Name -- User name to use when creating this connection. This parameter is optional.
	Password -- Password to use when creating this connection. This parameter is optional. If you need to provide an encrypted password (rather than expose server password names in a clear text file, use the encode_string command line option with the following syntax: encode_string type mypassword where type is the key for the data source and mypassword is your plain text password.  Note: The type argument is only required when you encrypt a string for a data source.
	For example, enter the following in an initialized command window: encode_string jms mypassword and you will receive an encrypted password: encrypted value: 013430135501346013310134901353013450134801334 Copy the encrypted value, paste it into the password field, and click Save to save this value to the initialization (*.ini) file. Or, if necessary, manually edit the (*.ini) file to include the encrypted value. Note: If you need to manually edit a configuration (*.ini) file, contact SL Technical Support at support@sl.com for information about supported syntax.
	Client ID --Client identifier to set on this connection. This parameter is optional.
	Host Name -- For IBM WebSphere MQ only. Name of the host to use for this connection.
	Port -- For IBM WebSphere MQ only. Name of the port to use for this connection.
	Queue Manager -- For IBM WebSphere MQ only. Name of the queue manager to use for this connection.
Remove Connection	Select a connection from the list and click Remove Connection to delete. Connections that are updating objects in a current display or that are listening for topics defined on the “JMS Messages Tab” cannot be removed.

Note: IBM WebSphere MQ does not let you send a command on a connection that you receive messages on. Therefore, you need to define separate connections for executing commands and attaching to data.

JMS SSL Parameters

This section assumes you have a working knowledge of writing, compiling and deploying Java classes.

Note: This is only supported for JMS connections to TIBCO EMS.

To use SSL with JMS, you will need to create a Java class named MyJmsDsSSLHandler that extends the com.sl.gmsjjmsds.GmsRtViewJmsDsSSLHandler class.

In MyJmsDsSSLHandler, define the following method:

public Map getSSLParams (String serverUrl)

This method will get called to retrieve the list of SSL parameters to pass in when RTView creates each JMS Connection. See the TIBCO EMS documentation for information on creating a map of SSL parameters suitable to pass into the JMS Connection.

Add gmsjjmsds.jar, located in the lib directory (found in your installation directory), to your classpath when you compile MyJmsDsSSLHandler. The compiled MyJmsDsSSLHandler class must be included in the RTView classpath by adding it to the definition for the RTV_USERPATH environment variable.

The following is an example of MyJmsDsSSLHandler:

import java.util.*;

import com.tibco.tibjms.TibjmsSSL;

import com.sl.gmsjjmsds.GmsRtViewJmsDsSSLHandler;

public class MyJmsDsSSLHandler extends GmsRtViewJmsDsSSLHandler

{

public Map getSSLParams (String serverUrl)

{

       System.out.println("==> MyJmsDsSSLHandler.getSSLParams");

        return null;

}

}

JMS JNDI Connections Tab

This tab allows you to add or remove JNDI connections and set your default connection. JNDI connections are only supported for BEA Weblogic 9.2+. Other JNDI JMS vendors may work, but are not guaranteed.

When you add a JNDI connection to the list it will be highlighted in yellow indicating that RTView has not connected to it. To attempt to connect to a JNDI connection, click OK, Apply, or Save. If the background remains yellow, then RTView was unable make a connection. Check that your connection was setup correctly and that the JMS message server is running.

Note: Regardless of which tab you are currently working from in the Application Options dialog, RTView will attempt to connect to all unconnected connections each time you click OK, Apply, or Save.

Field Name	Description
Default Connection	Name of connection used as the default for data attachments. Select from drop down menu to change default setting.
Add JNDI Connection	Click to open the Add JNDI Connection dialog. To edit, select a connection from the list and double-click. Connections that are updating objects in a current display or that are listening for topics defined on the “JMS Messages Tab” cannot be renamed.
	Connection Name -- Name to use when referencing this JNDI connection in your data attachments.
	Initial Context Factory -- The fully qualified name of the Initial Context Factory class to use when creating this JNDI connection. Note: The path to this class must be included in the “RTV_USERPATH” environment variable.
	Provider URL -- Complete URL for your JNDI server.
	Connection Factory -- JNDI name of the JMS connection factory to use when creating this connection
	Security Principal -- Security principal to use when creating this connection. This parameter is optional.
	Security Credentials -- Security credentials to use when creating this connection. This parameter is optional.
	Additional Properties -- This parameter is optional.
	Property Name -- Specify property name to add to the list.
	Property Value -- Specify property value to add to the list.
Remove Connection	Select a connection from the list and click Remove Connection to delete. Connections that are updating objects in a current display or that are listening for topics defined on the “JMS Messages Tab” cannot be removed.

JMS Handler

The JMS data source supports a custom JMS handler to parse BytesMessage and ObjectMessage content. To get the content from BytesMessage or ObjectMessage, create a subclass of com.sl.gmsjjmsds.GmsJRtViewCustomJmsHandler and add it to RTV_USERPATH. By default, RTView looks for a class named MyJmsHandler. To specify an alternate name, use the -jms_customhandlername:className command line option. Include gmsjrtview.jar and gmsjjmsds.jar (in the lib directory of your RTView installation) and the jms.jar from your JMS vendor in the classpath when building this subclass.

The GmsJRtViewCustomCommandHandler has three methods you may override in your subclass:

§        public void initialize() - This method is called once, after the class is instanced, in case the subclass needs to perform an initialization.

§        public String getBytesMessageStringContent (BytesMessage bytesMsg) - This method is called every time a BytesMessage is received. Subclasses should override this method to return a String representation of the byte[] from the message body.

§        public GmsTabularData getObjectMessageTableContent (ObjectMessage objectMsg) - This method is called every time an ObjectMessage is received. Subclasses should override this method to return a GmsTabularData representation of the Object in the message body.

For example:

import com.sl.gmsjjmsds.*;

import javax.jms.*;

import javax.jms.*;

import com.sl.gmsjrt.*;

public class MyJmsHandler extends GmsRtViewCustomJmsHandler

{

public void initialize ()

{

}

public String getBytesMessageStringContent (BytesMessage bytesMsg)

{

try {

byte[] bytes = new byte[(int)bytesMsg.getBodyLength()];

bytesMsg.readBytes(bytes);

return new String(bytes);

} catch (Exception e) {

System.out.println("ERROR: Can't parse BytesMessage &lt; " +

bytesMsg + "&gt;. Caught exception: " + e);

}

return null;

}

public GmsTabularData getObjectMessageTableContent (ObjectMessage objMsg)

{

try {

Object obj = objMsg.getObject();

if (obj == null)

return null;

if (obj instanceof Vector)

return processVector((Vector)obj);

else

return processString(String.valueOf(obj));

} catch (Exception e) {

System.out.println("ERROR: Can't parse Object &lt; " +

objMsg + "&gt;. Caught exception: " + e);

}

return null;

}

private GmsTabularData processVector (Vector&lt;String[]&gt; v)

{

GmsTabularData data = new GmsTabularData();

data.addColumn("Plant", GmsTabularData.STRING);

data.addColumn("Status", GmsTabularData.STRING);

data.addColumn("Units Completed", GmsTabularData.STRING);

String[] plants = v.elementAt(0);

String[] statuses = v.elementAt(1);

String[] units = v.elementAt(2);

if (plants == null || statuses == null || units == null)

return data;

for (int i = 0; i &lt; plants.length; i++) {

data.addRow("");

data.setCellValue(plants[i], i, 0);

data.setCellValue(statuses[i], i, 1);

data.setCellValue(units[i], i, 2);

}

return data;

}

private GmsTabularData processString (String s)

{

if (s == null)

s = "";

GmsTabularData data = new GmsTabularData();

data.addColumn("Value", GmsTabularData.STRING);

data.addRow("");

data.setCellValue(s, 0, 0);

return data;

}

}

§        XML data embedded in both BytesMessage content and ObjectMessage content can be used to define a JMS alias. To show all XML content of a bytes message add the following to your JMSALIAS.ini file:

OrderInfo myConnection orders.STATUS.* $xml:&lt;TEXT&gt;   

§        To show the data from a specific XML tag in the bytes message content, add something similar to the following:

$xml:&lt;TEXT&gt;::Orders::Order

Where Orders::Order specifies the path to the XML element to display.

§        Since the ObjectMessage callback returns a GmsTabularData, use the column name of the field containing the XML data:

OrderInfo myConnection orders.STATUS.* Production::$xml:OrderData 

Where OrderData is the name of the column containing the XML data. Note that only the value from the cell in the first row is used.

§        To show the data from a specific XML tag of an ObjectMessage table, add something similar to the following:

CustomerInfo myConnection orders.STATUS.* $xml:OrderData::Orders::Order::Customer 

Where Orders::Order::Customer defines the path to the XML element to display.

RTView Deployment - JMS

This section contains details about the deployment process that are specific to your data source. Please go to the Deployment section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.

System Requirements and Setup

The JMS data source has additional “JMS System Requirements and Setup”.

Data Source Configuration File

RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “Application Options”, “Application Options -- JMS”, and “RTV_JAVAOPTS” for more information.

Include the following initialization files when you deploy RTView with this data source:

Note: Options specified using command line and applet parameters override values set in initialization files.

Rich Client Browser Deployment Setup for Direct Data Connection

Required Applet Parameters

In addition to basic applet parameters (see “Rich Client Browser Deployment Setup for Direct Data Connection” for more information), you must specify the following in your HTML file to host the Display Viewer Applet:

Include the JMS data source in your applet:

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

 gmsjjmsds.jar 

2.     Add the following applet parameter:

name = ds 

value = com.sl.gmsjjmsds.GmsRtViewJmsDs 

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

3.     Include the jar(s) containing your JMS provider classes in the ARCHIVE parameter:

•        TIBCO EMS:

tibjms.jar

jms.jar

If you are using SSL, also include:  

jnet.jar

jsse.jar

•        SonicMQ:

sonic_Client.jar 

•       BEA Weblogic:

weblogic.jar

•        Other:

See JMS provider documentation.

Optional Applet Parameters

The following options are read from JMSOPTIONS.ini if not included in the applet parameters of your HTML file.

Setup Client

No additional client setup is required for this data source.

JMS Demos

Note: Demos that utilize the JMS data source will not work with IBM WebSphere MQ.

Except where noted, all demos can be run in three ways, as an application, or via rich or thin client in a browser.

Before You Begin

Start the Demo Server 

Rich Client and Thin Client Demos only. 

There are rich and thin client demos already installed on the “RTView Demo Server”.

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”):

Type run_startup_demoserver 

Data Source Demo

The Data Source Demo is designed to illustrate each data source.

1.     Start the Simulators

Start the simulators for each data source you will be using. To run the “JMS Data Simulator”:

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory and type:

run_jmssimdata

2.     Run Demos - Application, Rich Client Browser, or Thin Client Browser

Application Demo 

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. To view the demo, type:

run_viewer 

3. To edit the demo, type:

run_builder 

Rich Client Browser Demo

“Start the Demo Server” if it is not running.

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. Start the Data Server by typing:

run_dataserver -socket 

3. In the Data Server dialog, select:

Start Serving Data

4. Open a browser and navigate to http://localhost:8068/dstutorial_applet.

Thin Client Browser Demo 

“Start the Demo Server” if it is not running.

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. Start the Display Server by typing:

run_displayserver

3. Open a browser and navigate to http://localhost:8068/dstutorial.

Quick Start Tutorial: JMS

This Quick Start Tutorial provides you with the fundamentals on how to use RTView with a JMS data source. Once completed, you can swiftly apply this knowledge to building your own real-time dashboard displays for visual access to your JMS data.

Learn to:

§        Animate graphic objects with JMS data

§        Create a drill down display with JMS data

Note: The JMS data source may not be licensed in your RTView installation.

Get Started

 This tutorial requires the following:

§        Register for a license key. If you have not, you must do so before continuing. See “Registration” for more information.

§        “Quick Start Tutorial” - This tutorial requires that you have a working knowledge of RTView. We recommend that you complete the Quick Start Tutorial before continuing.

§        Setup your “RTV_USERPATH” to include your JMS provider's JMS jars.

§        Your JMS message server must be running.

Note: This tutorial will not work with IBM WebSphere MQ, which does not support the way wildcard characters are used in topic names in this example.

Start the JMS Simulator

In this exercise you start the “JMS Data Simulator” which is the data source used in this tutorial. The data simulator sends JMS messages that are used to animate objects in your display

1.     In an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”), type:

On Windows: start run_jmssimdata

On UNIX: run_jmssimdata & 

The JMS simulator runs as a background process and is ready when dots appear across the screen.

Note: Note: You must follow this initialization process for each new terminal window you open. See the “Setup” section for more details about setting up your environment.

Start the Display Builder

If you are already logged onto the Display Builder, skip this section and go to the Create a Display section, below.

1.     In an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”):

type run_builder 

2.     Login to the Display Builder. By default, the Display Builder 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.

You are now ready to create a display using the data source.

Create a Display

At this point you have:

§        Registered for a license key. See “Registration” for more information.

§        Logged on to the Display Builder

§        Setup your “RTV_USERPATH” to include your JMS provider's JMS jars

§        Started your JMS message server

§        Completed the “Quick Start Tutorial” 

In this tutorial you use the JMS simulator as your data source to create an animated pie graph that displays, as seen below.

As you saw in the Quick Start Tutorial, the data structure of tables and graphs (tabular data) enables RTView to automatically create several data source specific, built-in Substitutions for you. You will see these built-in Substitutions used in the target display when you create the drill down. For more information on Substitutions, see Substitutions.

In this exercise, you create a drill down using the previously created display, jms_dd_qs.rtv, as the target display. First you will set the pie graph to display units completed per plant. Then you will create a drill down that will open a bar graph that shows more detailed data for each plant.

Add a JMS Connection to List of Available Connections

Adding the JMS connection to the list of available connections makes it available for animating graphic objects in your display.

1.     In the Display Builder, select Tools>Options to open the Application Options dialog. See “Application Options -- JMS” for more information.

2.     Select the JMS Connections tab and click on Add Connection to open the Add Connection dialog.

3.     In the Add Connection dialog:

Connection Name - Enter My Connection 

Factory Class Name - If you are a TIBCO EMS user, select com.tibco.tibjms.TibjmsTopicConnectionFactory from the drop down menu. If not, enter the name of your JMS provider's connection factory class. The path to this class must be included in the “RTV_USERPATH” environment variable. Refer to your JMS provider documentation if you do not know the name of this class.

Server URL - The complete URL for your JMS message server if it is not running on localhost.

User Name - The user name to use when creating this connection. This parameter is optional.

Password - The password to use when creating this connection. This parameter is optional.

If you need to provide an encrypted password (rather than expose server password names in a clear text file, use the encode_string command line option with the following syntax:

encode_string type mypassword

where type is the key for the data source and mypassword is your plain text password.

Note: The type argument is only required when you encrypt a string for a data source.

For example, enter the following in an initialized command window (see “Initializing a Command Prompt or Terminal Window”):

encode_string jms mypassword

and you will receive an encrypted password:

encrypted value: 013430135501346013310134901353013450134801334

Copy the encrypted value, paste it into the password field and click Save to save this value to the initialization (*.ini) file. Or, if necessary, manually edit the (*.ini) file to include the encrypted value.

Note: If you need to manually edit a configuration (*.ini) file, contact SL Technical Support at support@sl.com for information about supported syntax.

Client ID - The client identifier to set on this connection. This parameter is optional.

4.     Click Apply and OK.

5.     Select the JMS Messages tab:

Connection - Select My Connection.

Topic Name - Enter orders.STATUS.*

6.     Click Add.

All of the messages contained in My Connection with topic names that begin with orders.STATUS. are generated by the JMS data simulator.

7.     Click OK to apply and close the Application Options dialog.

The connection and message topics are now available for animating graphic objects in your display.

Display Data in a Pie Graph

In this exercise you add a pie graph and then display the message topic in the pie graph by  attaching it to the data source.

1.     Click the button and click again in the Working Area to place the pie graph.

2.     In the Object Properties dialog:

label (category: Label) - Change the name of the label to Units Completed (by Plant).

legendWidthPercent (category: Legend) - Increase to 50 to widen the legend.

valueTable (category: Data) - Right-click on the  button and select Attach to Data>JMS.

3.     In the Attach to JMS Data dialog:

Connection - Select My Connection.

Destination Type - Topic should already be selected.

Topic Name - Enter orders.STATUS.* 

Message Field - Select the button to open the Select Columns dialog.

4.     In the Select Columns dialog:

Select PLANT in the Available Columns list and click Add.

Select UNITSCOMPLETED in the Available Columns list and click Add.

5.     Click OK to close the Select Columns dialog.

6.     In the Attach to JMS Data dialog:

Filter - Click to select the check box.

Filter Field Name - Select PLANT.

Filter Field Value - * should already be selected.

7.     Click OK to apply these values and close the Attach to JMS Data dialog.

The pie graph is now animated by the JMS data. Since the values in the Units Completed column are numeric, this data is graphed in the pie. Since the values in the Plant column contain text, they are shown in the legend.

You are now ready to create the drill down.

Create a Drill Down Target in the Pie Graph

In this exercise, you create a drill down in the pie graph using the previously created display,  jms_dd_qs.rtv, as the target.

1.     In the Object Properties window:

drillDownTarget (category: Interaction) - Double-click in the Property Name field to bring up the “Drill Down Properties” dialog.

2.     In the “Drill Down Properties” dialog:

Apply Drill Down To - Select Named Window from the drop down menu. This option lets you re-use the window when you drill down multiple times.

Window Name - Enter jms. This name should be unique unless the display is to open in an existing window.

Drill Down Display Name - Select dstutorial\jms_dd_qs.rtv from the drop down menu.

3.     Click OK to attach the drill down target and close the Drill Down Properties dialog.

View the Drill Down Display

 In this exercise, you drill down to the target display.

1.     Double-click on any wedge in the pie graph to drill down to detailed data. The target display opens.

Note: You must select the top of a wedge for the drill down to open.

2.     Double-click on another wedge in the pie and the same display is used to show different data based on the wedge you select.

3.     Close the drill down window.

4.     In the Display Builder select File>Save.

JMS Data Simulator

A JMS data simulator allows customers to work with RTView without setting up their own messages. The simulator creates, updates, and sends out messages with the following topics:

MapMessages: 

§        orders.STATUS.Belfast

§        orders.STATUS.Chicago

§        orders.STATUS.Denver

§        orders.STATUS.Hong Kong

§        orders.STATUS.London

§        orders.STATUS.Madrid

§        orders.STATUS.Mazatlan

§        orders.STATUS.Moscow

§        orders.STATUS.Palo Alto

§        orders.STATUS.Seattle

§        orders.STATUS.Tokyo

§        WEATHER.REGIONAL.WEST

§        WEATHER.REGIONAL.EAST

TextMessages: 

§        orderStatus.simple

§        WEATHER.XML.WEST

§        WEATHER.XML.EAST

Note: IBM WebSphere MQ does not support spaces in topic names. When the simulator is run with the IBM WebSphere MQ connection factory, spaces in topic names will be replaced with underbar  (_) symbols.

Running the Simulator

From an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”), type:

run_jmssimdata

Your JMS server must be running before you start the JMS data simulator.

Note: You must run the JMS data simulator from a command prompt or terminal window to use command line parameters.

Command line parameters for the simulator include:

The data simulator MapMessages for topic orders.STATUS.* contain the following fields and properties.

Note: IBM WebSphere MQ does not support spaces in field or property names. When the simulator is run with the IBM WebSphere MQ connection factory, spaces in field and property names will be replaced with underbar (_) symbols.

The data simulator MapMessages for topic WEATHER.REGIONAL.* contain the following fields and properties:

The data simulator TextMessages for topic orderStatus.simple contains the following properties. The body of the message toggles between WORKING, BROKEN, and COMPLETED.

The data simulator TextMessages for topic WEATHER.XML.* contains the following properties. The body of the message contains an XML string containing “Weather Data”.

Weather Data

<?xml version="1.0" ?>

<xmldata xmlns="www.sl.com">

  <weatherUpdate>

     <timeStamp>2/23/2005 04:10:45</timeStamp>

     <state MeasurementMethod="every 6 hours" Observations="Upper Air">

       <name>CA</name>

       <numberRegionsReporting>2</numberRegionsReporting>

       <regions>

          <region>

             <name>coast northern</name>

             <reportingIDNum>831</reportingIDNum>

             <currentWeatherConditions>

                <tempHigh>16</tempHigh>

                <tempLow>-16</tempLow>

                <wind>

                   <direction>North</direction>

                   <speed>30</speed>

                </wind>

                <rainfall>0.0</rainfall>

                <snowPack>6.7</snowPack>

             </currentWeatherConditions>

             <toDateTotals>

                 <rainfall>0.0</rainfall>

                 <snowPack>6.7</snowPack>

                 <tempHigh>16</tempHigh>

                 <tempLow>-16</tempLow>

              </toDateTotals>

           </region>

           <region>

              <name>inland northern</name>

              <reportingIDNum>95</reportingIDNum>

              <currentWeatherConditions>

                 <tempHigh>17</tempHigh>

                 <tempLow>2</tempLow>

                 <wind>

                   <direction>East</direction>

                   <speed>24</speed>

                </wind>

                <rainfall>4.0</rainfall>

                <snowPack>1.5</snowPack>

             </currentWeatherConditions>

             <toDateTotals>

                <rainfall>4.0</rainfall>

                <snowPack>1.5</snowPack>

                <tempHigh>17</tempHigh>

                <tempLow>2</tempLow>

             </toDateTotals>

          </region>

       </regions>

       <currentStateTotals>

          <currentMaxRainfall>4.0</currentMaxRainfall>

          <currentMaxSnowfall>6.7</currentMaxSnowfall>

          <currentHighTemp>17</currentHighTemp>

          <currentLowTemp>-16</currentLowTemp>

       </currentStateTotals>

       <todateStateTotals>

          <toDateTotalRainfall>28.0</toDateTotalRainfall>

          <toDateTotalSnowfall>6.7</toDateTotalSnowfall>

          <todateHighTemp>17</todateHighTemp>

          <todateLowTemp>-16</todateLowTemp>

       </todateStateTotals>

    </state>

    <state MeasurementMethod="daily" Observations="Satellite">

       <name>OR</name>

       <numberRegionsReporting>2</numberRegionsReporting>

       <regions>

         <region>

            <name>central eastern</name>

            <reportingIDNum>848</reportingIDNum>

            <currentWeatherConditions>

               <tempHigh>64</tempHigh>

               <tempLow>5</tempLow>

               <wind>

                  <direction>South East</direction>

                  <speed>42</speed>

               </wind>

               <rainfall>0.0</rainfall>

               <snowPack>4.0</snowPack>

            </currentWeatherConditions>

            <toDateTotals>

               <rainfall>0.0</rainfall>

               <snowPack>4.0</snowPack>

               <tempHigh>64</tempHigh>

               <tempLow>5</tempLow>

            </toDateTotals>

         </region>

         <region>

            <name>southern</name>

            <reportingIDNum>54</reportingIDNum>

            <currentWeatherConditions>

               <tempHigh>49</tempHigh>

               <tempLow>39</tempLow>

               <wind>

                  <direction>South</direction>

                  <speed>10</speed>

               </wind>

               <rainfall>0.0</rainfall>

               <snowPack>0.0</snowPack>

            </currentWeatherConditions>

            <toDateTotals>

               <rainfall>0.0</rainfall>

               <snowPack>0.0</snowPack>

               <tempHigh>49</tempHigh>

               <tempLow>39</tempLow>

            </toDateTotals>

         </region>

      </regions>

      <currentStateTotals>

         <currentMaxRainfall>0.0</currentMaxRainfall>

         <currentMaxSnowfall>4.0</currentMaxSnowfall>

         <currentHighTemp>64</currentHighTemp>

         <currentLowTemp>5</currentLowTemp>

      </currentStateTotals>

      <todateStateTotals>

         <toDateTotalRainfall>15.0</toDateTotalRainfall>

         <toDateTotalSnowfall>4.0</toDateTotalSnowfall>

         <todateHighTemp>64</todateHighTemp>

         <todateLowTemp>5</todateLowTemp>

      </todateStateTotals>

   </state>

   <state MeasurementMethod="twice a day" Observations="Buoy Reports">

      <name>WA</name>

      <numberRegionsReporting>2</numberRegionsReporting>

      <regions>

         <region>

            <name>north west</name>

            <reportingIDNum>225</reportingIDNum>

            <currentWeatherConditions>

               <tempHigh>44</tempHigh>

               <tempLow>-18</tempLow>

               <wind>

                  <direction>North</direction>

                  <speed>3</speed>

               </wind>

               <rainfall>2.0</rainfall>

               <snowPack>4.5</snowPack>

            </currentWeatherConditions>

            <toDateTotals>

               <rainfall>2.0</rainfall>

               <snowPack>4.5</snowPack>

               <tempHigh>44</tempHigh>

               <tempLow>-18</tempLow>

            </toDateTotals>

         </region>

         <region>

            <name>central</name>

            <reportingIDNum>135</reportingIDNum>

            <currentWeatherConditions>

               <tempHigh>59</tempHigh>

               <tempLow>41</tempLow>

               <wind>

                  <direction>North East</direction>

                  <speed>7</speed>

               </wind>

               <rainfall>2.0</rainfall>

               <snowPack>0.0</snowPack>

            </currentWeatherConditions>

            <toDateTotals>

               <rainfall>2.0</rainfall>

               <snowPack>0.0</snowPack>

               <tempHigh>59</tempHigh>

               <tempLow>41</tempLow>

            </toDateTotals>

         </region>

      </regions>

      <currentStateTotals>

          <currentMaxRainfall>2.0</currentMaxRainfall>

          <currentMaxSnowfall>4.5</currentMaxSnowfall>

          <currentHighTemp>59</currentHighTemp>

          <currentLowTemp>-18</currentLowTemp>

       </currentStateTotals>

       <todateStateTotals>

          <toDateTotalRainfall>32.0</toDateTotalRainfall>

          <toDateTotalSnowfall>4.5</toDateTotalSnowfall>

          <todateHighTemp>59</todateHighTemp>

          <todateLowTemp>-18</todateLowTemp>

       </todateStateTotals>

    </state>

 </weatherUpdate>

</xmldata>

JMS Data Source Command Line Options

In addition to General Options, the following command line arguments are enabled with the JMS data source when you run RTView applications from a Windows Command Prompt or UNIX terminal window. See “Command Line Options: Display Builder and Display Viewer” for more information

Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").