Understanding the Event Transmitter

Event Transmitter Startup

When a StarTeam Server configuration starts, it determines if it is an MPX-enabled configuration by locating a configuration-specific Event Transmitter XML file. The server attempts to load this file, identify the server default profile, and load the Event Transmitter with that profile. All startup messages and errors for the server configuration and the Event Transmitter are recorded in the configuration’s server log file.

On most systems, the server’s log file is located in the root folder of the server configuration’s repository. See “Server Log Entries” for examples of typical startup messages.

If the configuration-specific XML file loads successfully, the Event Transmitter establishes a connection with the Message Broker identified in the server default profile.

The Name property in the <Handler> section indicates what type of messaging will be used with this configuration. ActiveMQ MPX Transmitter designates the use of ActiveMQ MPX messaging and brokers.

If the Event Transmitter fails to connect with a Message Broker, the StarTeam Server terminates the Event Transmitter and starts the server configuration in non-MPX mode.

When a client opens a project on a server configuration, it determines whether or not the server configuration is MPX-enabled. If the configuration is MPX-enabled, the server sends the client the encryption key needed to decrypt messages from the Event Transmitter. It also sends the client the connection profiles defined in the configuration-specific Event Transmitter XML file.

Some clients have settings that allow the server’s default connection profile to be overridden. It the user can select a specific profile and has done so, the client uses the profile set by the user. Otherwise, the client uses the profile marked as the client default profile.

If the client is unable to connect to the designated Message Broker, it displays an error dialog and proceeds to open the project in non-MPX mode.

Back to top

Event Transmitter XML File Format

The general format of the Event Transmitter XML file is as follows: 

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> 
<StExternHandlerModule version="2.0">
  <Handler>
    <Name>ActiveMQ MPX Transmitter</Name>
    <Description>...</Description>
    <Properties>
      <ClientDefault>...</Client default>
      <ServerDefault>...</Server default>
    </Properties>
    <Profiles>
      <Profile>
        ...profile #1 information...
      </Profile>
      <Profile>
        ...profile #2 information...
      </Profile>
      ...more profiles, if any...
    </Profiles>
  </Handler>
  </StExternHandlerModule>

Note that in this example, the ellipses (…) denote information where some details have been left out. Some XML parameters in the Event Transmitter XML file are used to identify the Event Transmitter library to the server configuration; the presence and order of these parameters should not be modified.

The following table lists the parameters that can be modified to tailor the connection profiles within the XML file. The parameters are listed in the order in which they appear in the XML file.

Unless otherwise stated, all integer parameters have very large positive ranges. For example, all time values have a range of 1 to 2,147,483,647. In most cases, you should consider the default value the minimum setting. Use a practical upper limit based on common sense.

Table 1: Event Transmitter Parameters

Parameter Description
ServerDefault

Defines the server default profile. Its value must match the name of a Profile within the Profile Set group in this XML file. The server default profile is used by the Event Transmitter and File Transmitter to establish a Message Broker connection. For configuration-specific XML files, you can use the Server Administration to set a profile as the server default.

ClientDefault

Defines the client default profile. Its value must match the name of a Profile within the XML file. The client default profile is used by clients as the default definition to establish a Message Broker connection. For configuration-specific XML files, you can use the Server Administration to set a profile as the client default.

Profile

Can be repeated. It is both a group for parameters and a member of the Profiles group.

Each profile has a name, a brief textual description, and a set of properties.

The initial profiles in the Event Transmitter XML file are specified during the transmitter’s installation. In most cases, the default values are sufficient and do not need to be changed. However, if you need to add, move, or remove Message Brokers, or if you want to customize any connection profile settings, you can edit the XML file.

Name Defines the name of the profile. The name should provide a useful tip as to the purpose of the profile (such as “West-coast on-site”). If the profile is a server or client default profile, whose value should match the value of the corresponding ServerDefault or ClientDefault parameter.
Description Provides a short textual message describing the profile. It should contain a value that helps users and administrators understand when to use the parameter (such as “A unicast/Message Broker profile for users residing in the west coast office LAN”). Along with the profile name, the profile description appears in both the client and Server Administration connection profile dialogs.
Properties

This is a group inside the Profile group. Its inner parameters define the connection details of the profile.

The parameters within this group specify the connection details of the profile. The most common options that can be used within the Properties group and their usage are described below.

In special cases, some other options which are not described below can also be used. However, these options should only be used under the advice of our technical developer support services (https://www.microfocus.com/support).

The parameters in the Properties group are listed in the next table.

Table 2: Parameters for the Properties Group Inside the Profile Group

Parameter Description
server_names

Designates the protocol, address, and port number of one or more Message Brokers. The general syntax for this parameter is: 

tcp:servername:endpoint

where

servername The TCP/IP address or computer name of the computer running a Message Broker.
endpoint The port number on which the Message Broker accepts connections. The default endpoint for a Message Broker connection is 61616.

Examples:

For a Message Broker running on a computer with the TCP/IP address of 12.34.56.78 and port number 5320, the <server_names> value would be: 

<server_names>tcp:12.34.56.78:5320</server_names>

Any process using the profile communicates with a single Message Broker. However, you can list multiple Message Brokers (each separated by a comma) to provide alternatives: 

<server_names>tcp:HostA:61616,tcp:HostB:61616</server_names>

The Event Transmitter and any clients using a connection profile with this <server_names> value will first attempt to connect to the Message Broker on the computer named HostA, using port 61616. If a connection to that Message Broker is unsuccessful, the process will attempt to connect to the Message Broker on HostB using port number 61616.

_random

The _random option is used with <server_names>. If multiple Message Brokers are available, the Event Transmitter can be instructed to randomly choose from the available Message Broker pool. This is done by adding the keyword _random, followed by a comma, before the list of pooled Message Brokers.

For example: 

_random, tcp:HostA:61616,tcp:HostB:61616,tcp:HostC:61616

The benefit of this option is not realized by the Event Transmitter, since it creates a single TCP/IP connection to a single Message Broker. Rather, the benefit comes when the MPX profile is used by many StarTeam clients.

Consequently, as StarTeam clients connect and execute the same <server_names> value using the _random option, their Message Broker connections will be distributed among the available Message Brokers, causing automatic load balancing to take place. Note that when the _random option is used, if a selected Message Broker is unavailable, another Message Broker is randomly selected, until an available Message Broker is found.

project

Specifies a publish/subscribe “universe” name. The default value is Starbase and should not be changed.

timeToLive

Specifies the expiration time for mpx messages(in seconds) starting from when it was dispatched.

The default value is 60.
enable_control_msgs

The default is echo.

Specifies the types of control messages that the ActiveMQ MPX process (and application clients) will honor. Only the echo control message should normally be enabled, so this value defaults to echo and normally should not be modified.

server_keep_alive_timeout

integer; number of seconds. The default is 30.

Both the Event Transmitter and application clients send an occasional “keep alive” message (analogous to a ping) to the Message Broker to ensure that it is still responding. This parameter specifies the time (in seconds) during which the keep alive response must be received. If the keep alive response is not received within the specified amount of time, the Message Broker connection is severed, and a reconnect sequence is initiated.

Minimum value is zero, which disables the feature.

server_read_timeout

integer; number of seconds. The default is 30.

Specifies the time (in seconds) that the Event Transmitter or client using this profile will wait for a response when performing a read operation. If no data is received from the Message Broker within the specified amount of time, a timeout occurs, and a keep alive operation is performed.

Minimum value is zero, which disables the feature.

Note: The client_read_timeout option in the STMessageBroker68.ini file should be set higher than the server_read_timeout option in all profiles in the MPXEventTransmitter.xml file. The client_read_timeout option by default is 45 seconds. This causes the clients to drive keep-alive logic, freeing-up processing from the Message Brokers.

server_write_timeout

integer; number of seconds. The default is 30.

Specifies the time (in seconds) that the Event Transmitter or client will wait on a write operation. If a write request is not accepted by the Message Broker within the specified amount of time, a write timeout occurs. Unlike read timeouts, which trigger a keep alive sequence, write timeouts cause the Message Broker connection to be immediately severed, followed by a reconnect sequence.

Minimum value is zero, which disables the feature.

server_start_max_tries

Integer. The default is 1.

Specifies how many times the Event Transmitter or application client will traverse the server_names list during a connect sequence, before giving up and deciding that no messaging service is available.

Minimum value is zero, which disables the feature.

server_start_delay

Integer; number of seconds. The default is 10.

Specifies how long (in seconds) to wait between traversals of the server_names list. If an attempt to reconnect to a Message Broker fails, the Event Transmitter or application client will wait for up to the specified number of seconds before attempting the reconnect again.

Minimum value is zero, which disables the feature.

Here is an example unicast profile: 

<Profile>
  <Name>Unicast Off-site</Name>
  <Description>The Message Broker profile for clients using unicast off-site. </Description>
  <Properties>
     <server_write_timeout>30</server_write_timeout>
     <server_names>tcp:123.45.6.78:61616</server_names>
     <socket_connect_timeout>10</socket_connect_timeout> 
     <server_start_delay>10</server_start_delay>
     <enable_control_msgs>echo</enable_control_msgs>
     <server_max_reconnect_delay>10</server_max_reconnect_delay>
     <project>Starbase</project>
     <server_start_max_tries>1</server_start_max_tries>
     <server_keep_alive_timeout>30</server_keep_alive_timeout>
  </Properties>
</Profile>

If you manually edit an Event Transmitter configuration-specific XML file, the changes will take effect after you save the updated file and restart the corresponding configuration. If you use the Server Administration, changes go into effect immediately for all new client connections.

If you edit an Event Transmitter template XML file, you can only edit it manually. The updated file will be used for new configurations that you create using the Server Administration.

Back to top