Configuring Transports for SmartSockets


Transports mediate the flow of messages between TIBCO Enterprise Message Service and TIBCO SmartSockets.

timemsd connects to SmartSockets RTservers in the same way as any other SmartSockets client. Transport definitions (in the file transports.conf) configure the behavior of these connections. You must properly configure these transports.

Transport Definitions

transports.conf contains zero or more transport definitions. Each definition begins with the name of a transport, surrounded by square brackets. Subsequent lines set the parameters of the transport.

Table 14 SmartSockets: Transport Parameters (Sheet 1 of 4)
Parameter
Description
type
Required. For SmartSockets transports, the value must be tibss.
SmartSockets Parameters
The syntax and semantics of these parameters are identical to the corresponding parameters in SmartSockets clients. For full details, see the SmartSockets documentation set.
server_names
The value is a comma-separated list specifying connections to one or more SmartSockets RTservers.
Each item in the list has the form protocol:hostname:port. You may omit any of the three parts. The default hostname is the local host computer. The default protocols and ports vary with hardware and operating system platforms; on Windows platforms, the default protocol is tcp and the default port is 5101.
A list of several servers specifies fault tolerance—timemsd attempts to connect to them in the order listed.
When this parameter is absent, the default instructs the EMS server to attempt to connect to an RTserver on the local host computer (the same computer as the EMS server), using default protocols and ports.
username
password
timemsd uses these two parameters to authenticate itself to the SmartSockets servers.
project
SmartSockets uses projects to maintain orthogonal subject name-spaces.
When absent, the default project is rtworks.
delivery_mode
This parameter determines the quality of service with which delivers messages to the SmartSockets server over this transport:
 best_effort | gmd_all | gmd_some | ordered
When absent, the default is best_effort.
lb_mode
SmartSockets servers balance the message load by distributing messages among several clients. This parameter determines the load balancing regimen for messages that this transport exports to the SmartSockets server.
 none | round_robin | weighted | sorted
When absent, the default is none.
override_lb_mode
enable instructs the RTserver to deliver all messages on this client connection—even if other clients participate in load balancing. For example, even though many order-processing clients might share the load of order messages, a message logging facility would require all order messages, rather than a subset.
disable informs the RTserver that this client (that is, the EMS server) participates in load balancing (for example, sharing the load with other EMS servers).
When absent, the default is enable.
gmd_file_delete
SmartSockets clients keep data for guaranteed message delivery (GMD) in a store file.
disable instructs tibemsd to open the existing GMD store file.
enable instructs tibemsd to delete the GMD store file and create a new one when creating this transport.
When absent, the default is disable.
EMS Parameters
topic_import_dm
queue_import_dm
EMS sending clients can set the JMSDeliveryMode header field for each message. However, SmartSockets clients cannot set this header. Instead, these two parameters determine the delivery modes for all topic messages and queue messages that tibemsd imports on this transport.
 TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE
When absent, the default is TIBEMS_NON_PERSISTENT.
export_headers
When true, tibemsd includes JMS header fields in exported messages.
When false, tibemsd suppresses JMS header fields in exported messages.
When absent, the default value is true.
export_properties
When true, tibemsd includes JMS properties in exported messages.
When false, tibemsd suppresses JMS properties in exported messages.
When absent, the default value is true.
import_ss_headers
This parameter governs the import of SmartSockets message headers to EMS properties.
The value can be none, type_num, or all. For complete details, see SmartSockets Message Properties.
When absent, the default value is none.
subscribe_mode
  • When subscriptions do not collide, specify exact, for best performance.
  • When subscriptions collide, specify all, for correct semantics.
When absent, the default is exact.
For a definition of wildcard collision, and complete details about the operation of these two modes, see Subscribe Mode.
preserve_gmd
This parameter determines the behavior of the EMS server when it has exported a GMD message to SmartSockets, and SmartSockets cannot deliver that message. When SmartSockets returns the undelivered message, EMS can either preserve it in the EMS undelivered message queue, or discard it.
  • always instructs EMS to preserve all undelivered GMD messages in the EMS undelivered message queue.
  • receivers instructs EMS to preserve only those undelivered GMD messages that SmartSockets could not deliver despite the existence of one or more GMD receivers. That is, if SmartSockets cannot deliver a message because no GMD receivers exist, then EMS does not preserve the undelivered message.
  • never instructs EMS to discard all undelivered SmartSockets GMD messages.
When absent, the default value is never.
This parameter applies only when the transport’s delivery_mode parameter is either gmd_all or gmd_some.
When the EMS server preserves a GMD message, it follows these rules to convert the returned SmartSockets message to an EMS message:

Example

These examples from transports.conf illustrate the syntax of transport definitions.

[SS01] 
   type = tibss 
   server_names = rtHost1 
   username = emsServer6 
   password = myPasswd 
   project = sales_order_entry 
 
[SS02] 
   type = tibss 
   server_names = tcp:rtHost2A:5555, ssl:rtHost2B:5571 
   username = emsServer6 
   password = myPasswd 
   project = mfg_process_control 
   override_lb_mode = enable 
   delivery_mode = gmd_some 

Subscribe Mode

Both EMS and SmartSockets allow wildcard subscriptions to collide (for example, in EMS syntax, foo.* collides with foo.bar; and foo.* collides with *.bar).
The transport parameter subscribe_mode governs SmartSockets message filtering when EMS wildcard subscriptions collide. This section describes the mechanisms of subscription, and the results when import subscriptions collide.

exact

exact instructs tibemsd to pass subscriptions to the RTserver exactly as the EMS subscribers specify. As a result, subject filtering occurs on the RTserver. Consequently, the RTserver delivers each SmartSockets message with subject /foo/bar to this client (tibemsd) twice—once for the subscription to foo.*, and once for the subscription to foo.bar. However, tibemsd does not recognize these duplicates as redundant, and delivers two copies to each subscriber. It is illegal to configure exact when EMS subscriptions collide.

all

all instructs tibemsd to pass the subscription /... to the RTserver. As a result, the RTserver delivers all messages to this client (only once)—letting tibemsd filter the messages. tibemsd delivers messages to each subscriber as appropriate, so EMS subscribers do not receive duplicate messages. Because tibemsd requests all messages from SmartSockets, an all connection carries more data than an exact connection.

Destination Name—Syntax and Semantics

Slash & Dot Separators

This aspect of the mapping between EMS destination names and SmartSockets subjects is straightforward, one-to-one, and bidirectional.

EMS destination names consist of tokens separated by the dot (.) character. SmartSockets subjects consists of tokens preceded by the slash (/) character (like UNIX directory pathnames).

For example, the EMS name foo.bar.baz corresponds to the SmartSockets name /foo/bar/baz. (Remember that SmartSockets names must begin with a leading slash, but EMS names need not begin with a leading dot. A leading dot indicates an empty element preceding it.)

The slash and dot characters have complementary roles in EMS and SmartSockets. In EMS slash is an ordinary character, while dot is a separator. In SmartSockets slash is a separator, while dot is an ordinary character. To translate names between EMS and SmartSockets, substitute these characters one for another. For example, the EMS name foo/bar.baz corresponds to the SmartSockets name /foo.bar/baz. However, to avoid confusion, we discourage using either slash or dot as ordinary characters.

Wildcard Star

Although both EMS and SmartSockets both interpret the star (*) character as a wildcard, they differ in its semantics. In this aspect, the mapping is not one-to-one.

In EMS, star can match any whole token of a name, but not part of a token. In SmartSockets, star can match part of an token—for example, /foo/b*/baz matches /foo/bar/baz and /foo/box/baz.

If you are familiar with SmartSockets wildcards but not EMS wildcards, see Wildcards.

Trailing Wildcard

In EMS the greater-than (>) character is a wildcard that matches any number of trailing tokens. In SmartSockets a string of three dots (...) signifies identical semantics.


TIBCO Enterprise Message Service™ User’s Guide
Software Release 4.3, February 2006
Copyright © TIBCO Software Inc. All rights reserved
www.tibco.com