Destination Properties


This section contains a description of properties for topics and queues. Table 4 lists the properties that can be assigned to topics and queues. The following sections describe each property.

Table 4 Destination properties (Sheet 1 of 2)
Property
Described on Page
Topic
Queue
35
Yes
Yes
36
Yes
Yes
36
Yes
Yes
37
No
Yes
37
No
Yes
37
Yes
Yes
sender_name
37
Yes
Yes
sender_name_enforced
38
Yes
Yes
flowControl
38
Yes
Yes
trace
39
Yes
Yes
import
39
Yes
Yes
export
39
Yes
No
maxRedelivery
40
No
Yes
40
No
Yes
40
No
Yes
42
Yes
Yes
Deprecated Properties

The following properties are available for backward-compatibility with previous versions. The functionality of these properties is replaced with the import and export properties.

tibrv_import
Yes
Yes
tibrvcm_import
Yes
Yes
tibrv_export
Yes
No
tibrvcm_export
Yes
No

failsafe

TIBCO Enterprise Message Service provides two modes for persisting topic/queue messages in external storage. These two modes are:

Normal mode writes all messages into the file on disk in asynchronous mode. In this mode, the data may remain in system buffers for a short time before it is written to disk.

Asynchronous mode storage includes a small probability that, in case of software or hardware failure, some data may be lost without the possibility of recovery. In many applications, when a rare loss of a few messages is acceptable, this mode provides the best combination of performance and reliability.

For situations in which any loss of data is not acceptable, the administrator should set the failsafe property for the topic or the queue. In failsafe mode, all data for that queue or topic are written into external storage in synchronous mode. In synchronous mode, a write operation is not complete until the data is physically recorded on the external device.

The failsafe property ensures that no messages are ever lost in case of server failure. Although failsafe mode guarantees no messages are lost, it also significantly affects the performance.

secure

When the secure property is enabled for a destination, it instructs the server to check user permissions whenever a user attempts to perform an operation on that destination. When the secure property is disabled for a destination, the server does not check permissions for that destination—any authenticated user can perform any operations on that topic or queue.

The secure property is independent of SSL—it controls basic authentication and permission verification within the server. To configure secure communication between clients and server, see Using the SSL Protocol.

The server authorization property acts as a master switch for checking permissions. That is, the server checks user permissions on secure destinations only when the authorization property is enabled. To enforce permissions, you must both enable the authorization configuration parameter, and set the secure property on each affected destination.

See Chapter 9, Authentication and Permissions for more information on permissions and the secure property.

maxbytes

Topics and queues can specify the maxbytes property in the form: maxbytes=b where b is the number of bytes.

For queues, maxbytes defines the maximum size (in bytes) that the queue can store, summed over all messages in the queue. When adding a message would exceed this limit, the server does not accept the message into storage, and the message producer’s send call returns an error (but see also overflowPolicy). For example, if a receiver is off-line for a long time, then the queue size could reach this limit, which would prevent further memory allocation for additional messages.

If maxbytes is zero, or is not set, the server does not limit the memory allocation for the queue.

You can set both maxmsgs and maxbytes properties on the same queue. Exceeding either limit causes the server to reject new messages until consumers reduce the the queue size to below these limits.

For topics, maxbytes limits the maximum size (in bytes) that the topic can store for delivery to each durable subscriber on that topic. That is, the limit applies separately to each durable subscriber on the topic. For example, if a durable subscriber is off-line for a long time, pending messages accumulate until they exceed maxbytes; when the subscriber consumes messages (freeing storage) the topic can accept additional messages for the subscriber.

When a destination inherits different values of this property from several parent destinations, it inherits the smallest value.

maxmsgs

Queues can specify the maxmsgs property in the form: maxmsgs=m where m is the number of messages.

maxmsgs defines the maximum number of messages that can be waiting in a queue. When adding a message would exceed this limit, the server does not accept the message into storage, and the message producer’s send call returns an error (but see also overflowPolicy).

If maxmsgs is zero, or is not set, the server does not limit the number of messages in the queue.

You can set both maxmsgs and maxbytes properties on the same queue. Exceeding either limit causes the server to reject new messages until consumers reduce the the queue size to below these limits.

overflowPolicy

Queues can specify the overflowPolicy property to change the effect of exceeding queue limits (either maxbytes or maxmsgs).

When overflowPolicy=discardOld, exceeding queue limits causes the server to discard the oldest messages in the queue to free space for new messages from producers.

When overflowPolicy is not set, the server refuses new messages for the queue, and the producer send call indicates an error.

global

Messages destined for a topic or queue with the global property set are routed to the other servers that are participating in routing with this server. For further information on routing between servers, see Chapter 14, Working With Routes.

sender_name

The sender_name property specifies that the server may include the sender’s username for messages sent to this destination. When this property is enabled, the server takes the user name supplied by the message producer when the connection is established and places that user name into the JMS_TIBCO_SENDER property in the message.

The message producer can override this behavior by specifying a property on a message. If a message producer sets the JMS_TIBCO_DISABLE_SENDER property to true for a message, the server overrides the sender_name property and does not add the sender name to the message.

If authentication for the server is turned off, the server places whatever user name the message producer supplied when the message producer created a connection to the server. If authentication for the server is enabled, the server authenticates the user name supplied by the connection and the user name placed in the message property will be an authenticated user. If SSL is used, the SSL connection protocol guarantees the client is authenticated using the client’s digital certificate.

sender_name_enforced

The sender_name_enforced property specifies that messages sent to this destination must include the sender’s user name. The server retrieves the user name of the message producer using the same procedure described in the sender_name property above. However, unlike, the sender_name property, there is no way for message producers to override this property.

If the sender_name property is also set on the destination, this property overrides the sender_name property.

In some business situations, clients may not be willing to disclose the username of their message producers. If this is the case, these clients may wish to avoid sending messages to destinations that have the sender_name or sender_name_enforced properties enabled.
In these situations, the operator of the EMS server should develop a policy for disclosing a list of destinations that have these properties enabled. This will allow clients to avoid sending messages to destinations that would cause their message producer usernames to be exposed.

flowControl

The flowControl property specifies the target maximum size the server can use to store pending messages for the destination. This is useful when message producers send messages much more quickly than message consumers can consume them. Using this property can prevent the pending messages from consuming too many machine resources.

The value specified for this property is in bytes, unless you specify the units for the amount of storage using KB, MB, or GB. For example, flowControl=60MB specifies the target maximum storage for pending messages of the destination is 60 Megabytes. You can specify the flowControl property without a value to set it to the default of 256KB.

Flow control must be enabled for the server before the value in this property is enforced by the server. See Flow Control for more information about flow control.

trace

Specifies that tracing should be enabled for this destination. This property can be specified as either trace or trace=body. Specifying trace (without =body), generates trace messages that include only the message sequence and message ID. Specifying trace=body generates trace messages that include the message body. See Message Tracing for more information about message tracing.

import

The import property allows messages published by an external system to be received by a TIBCO Enterprise Message Service destination (a topic or a queue), as long as the transport to the external system is configured. Currently you can configure transports for TIBCO Rendezvous reliable and certified messaging protocols. You can specify the name of one or more transports of the same type in the import property.

You must purchase, install, and configure the external system (for example, Rendezvous) before configuring topics with the import property. Also, you must configure the communication parameters to the external system by creating a named transport in the transports.conf file.

For complete details about external message services, see these chapters:

export

The export property allows messages published by a client to a topic to be exported to the external systems with configured transports. Currently you can configure transports for Rendezvous reliable and certified messaging protocols. You can specify the name of one or more transports of the same type in the export property.

You must purchase, install, and configure the external system (for example, Rendezvous) before configuring topics with the export property. Also, you must configure the communication parameters to the external system by creating a named transport in the transports.conf file.

For complete details about external message services, see these chapters:

maxRedelivery

The maxRedelivery property specifies the number of attempts the server should make to redeliver a message sent to a queue. The value of this parameter can be set to an integer between 2 and 255. Once the server has attempted to deliver the message the specified number of times, the message is either destroyed or it is placed on the undelivered queue, if the JMS_TIBCO_PRESERVE_UNDELIVERED property on the message is set to true.

For messages that have been redelivered, the JMSRedelivered header property is set to true and the JMSXDeliveryCount property is set to the number of times the message has been delivered to the queue. If the server restarts, the current number of delivery attempts in the JMSXDeliveryCount property is not retained.

For more information about undelivered messages, see Undelivered Message Queue.

exclusive

The exclusive property is available for queues only (not for topics). When exclusive is set to true, the server sends all messages (on that queue) to one consumer. Any other consumers do not receive any messages from the queue. Instead, these additional consumers act in a standby role; if the primary consumer fails, the server selects one of the standby consumers as the new primary, and begins delivering messages to it.

Non-Exclusive Queues & Round-Robin Delivery

With non-exclusive queues (exclusive set to false) the server distributes messages in a round-robin—one to each receiver that is ready. If any receivers are still ready to accept additional messages, the server distributes another round of messages—one to each receiver that is still ready. When none of the receivers are ready to receive more messages, the server waits until a queue receiver reports that it can accept a message.

This arrangement prevents a large buildup of messages at one receiver and balances the load of incoming messages across a set of queue receivers.

prefetch

The prefetch property applies only to queues.

Background

Delivering messages from the server to a client program involves two independent phases—fetch and accept:

The receive call embraces both of these phases. It initiates fetch when needed, and it accepts a message from the MessageConsumer object.

To reduce waiting time for client programs, the MessageConsumer can prefetch messages—that is, fetch a batch of messages from the server, and hold them for client code to accept, one by one.

Values

The MessageConsumer and the server cooperate to regulate fetching according to the queue’s prefetch property. Table 5 presents the range of values.

Table 5 Prefetch 
Value
Description
2 or more
The MessageConsumer automatically fetches messages from the server. The MessageConsumer never stores more than this maximum number of messages.
1
The MessageConsumer automatically fetches messages from the server—initiating fetch only when it does not currently hold a message.
none
Disables automatic fetch. That is, the MessageConsumer initiates fetch only when the client calls receive—either an explicit synchronous call, or an implicit call (in an asynchronous receiver).
0
The queue inherits the prefetch value. If it has no parent, or no queue in the parent chain sets a value for prefetch, then the default value is 5.
When a queue does not set any value for prefetch, then the default value is 0 (that is, inherit the prefetch value).

Automatic Fetch Enabled

To enable automatic fetch, set prefetch to a positive integer. Automatic fetch ensures that a message is always waiting when client code is ready to accept one. It can improve performance by decreasing or eliminating client idle time while the server transfers a message.

However, when a MessageConsumer prefetches a group of messages, the server does not deliver them to other consumers (unless the first consumer’s connection to the server is broken).

Automatic Fetch Disabled

To disable automatic fetch, set prefetch=none.

Even when prefetch=none, a MessageConsumer object can still hold a message. For example, a receive call initiates fetch, but its timeout elapses before the server finishes transferring the message. This situation leaves a fetched message waiting in the MessageConsumer. A second receive call does not fetch another message; instead, it accepts the message that is already waiting. A third receive call initiates another fetch.

Notice that a waiting message still belongs to the MessageConsumer, and the server does not deliver it to another consumer (unless the first consumer’s connection to the server is broken). To prevent messages from waiting in this state for long periods of time, code programs either to call receive with no timeout, or to call it (with timeout) repeatedly and shorten the interval between calls.

Inheritance

When a queue inherits the prefetch property from parent queues with matching names, these behaviors are possible:



expiration

The server’s expiration property overrides expiration values set by message producers (in client programs). You can set this property for any queue and any topic.

If this property is set for a destination, then when the server delivers a message to that destination, the server replaces the producer’s expiration value with this value.

Specify this value as an integer with units. Legal units are msec, sec, min, hour and day (for example, expiration=10min). When units are absent, the default unit is seconds.

Zero is a special value, which indicates that messages to the destination never expire.

Whenever a client application uses non-zero values for message expiration, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest message expiration time.


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