Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Destinations : Destination Properties

Destination Properties
This section contains a description of properties for topics and queues.
You can set the properties directly in the topics.conf or queues.conf file or by means of the setprop topic or setprop queue command in the EMS Administration Tool.
Table 12 lists the properties that can be assigned to topics and queues. The following sections describe each property.
channel
The channel property determines the multicast channel over which messages sent to this topic are broadcast. By including the channel property, the associated topic is enabled for multicast.
Set the channel property using this form:
   channel=name
where name is the name of a channel, as defined in the channels.conf file.
For example, this will broadcast all messages sent to the topic topic.foo over the channel named mycast:
   topic.foo channel=mycast
Only one channel is allowed for each topic. For this reason, overlapping wildcard topics are incompatible with channel properties. The creation of a wildcard topic with a channel property that overlaps with another wildcard topic with a channel property will fail. See Overlapping Wildcards and Disjoint Properties for more information.
exclusive
The exclusive property is available for queues only (not for topics), and cannot be used with global queues.
When exclusive is set for a queue, the server sends all messages on that queue to one consumer. No other consumers can receive 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.
You can set exclusive using the form:
   exclusive
Non-Exclusive Queues & Round-Robin Delivery
By default, exclusive is not set for queues and 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.
expiration
If an expiration property is set for a destination, the server honors the overridden expiration period and retains the message for the length of time specified by the expiration property.
However, the server overrides the JMSExpiration value set by the producer in the message header with the value 0 and therefore the consuming client does not expire the message.
You can set the expiration property for any queue and any topic using the form:
   expiration=time[msec|sec|min|hour|day]
where time is the number of seconds. Zero is a special value that indicates messages to the destination never expire.
You can optionally include time units, such as msec, sec, min, hour or day to describe the time value as being in milliseconds, seconds, minutes, hours, or days, respectively. For example:
   expiration=10min
Means 10 minutes.
When a message expires it is either destroyed or, if the JMS_TIBCO_PRESERVE_UNDELIVERED property on the message is set to true, the message is placed on the undelivered queue so it can be handled by a special consumer. See Undelivered Message Queue for details.
In EMS version 4.4 and later, clients automatically synchronize their clocks with the server when a connection is created. However, for long-lasting connections, Network Time Protocol (NTP) is the most reliable method for ensuring continuing synchronization between server and client. Additionally, if your EMS server or client application are based on a version of EMS prior to 4.4, you must ensure that clocks are synchronized among all the host computers that send and receive messages, if your pre-4.4 client application uses non-zero values for message expiration. Synchronize clocks to a tolerance that is a very small fraction of the smallest message expiration time.
export
The export property allows messages published by a client to a topic to be exported to the external systems with configured transports.
You can set export using the form:
   export="list"
where list is one or more transport names, as specified by the [transport_name] ids in the transports.conf file. Multiple transport names in the list are separated by commas.
For example:
   export="RV1,RV2"
Currently you can configure transports for SmartSockets or 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:
flowControl
The flowControl property specifies the target maximum size the server can use to store pending messages for the destination. Should the number of messages exceed the maximum, the server will slow down the producers to the rate required by the message consumers. This is useful when message producers send messages much more quickly than message consumers can consume them. Unlike the behavior established by the overflowPolicy property, flowControl never discards messages or generates errors back to producer.
You can set flowControl using the form:
   flowControl=size[KB|MB|GB]
where size is the maximum number of bytes of storage for pending messages of the destination. If you specify the flowControl property without a value, the target maximum is set to 256KB.
You can optionally include a KB, MB or GB after the number to specify kilobytes, megabytes, or gigabytes, respectively. For example:
   flowControl=1000KB
Means 1000 kilobytes.
The flow_control parameter in tibemsd.conf file must be set to enabled before the value in this property is enforced by the server. See Flow Control for more information about flow control.
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.
You can set global using the form:
   global
For further information on routing between servers, see Chapter 20, Working With Routes.
import
The import property allows messages published by an external system to be received by a EMS destination (a topic or a queue), as long as the transport to the external system is configured.
You can set import using the form:
   import="list"
where list is one or more transport names, as specified by the [NAME] ids in the transports.conf file. Multiple transport names in the list are separated by commas. For example:
   import="RV1,RV2"
Currently you can configure transports for TIBCO SmartSockets or 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:
maxbytes
Topics and queues can specify the maxbytes property in the form:
   maxbytes=value[KB|MB|GB]
where value is the number of bytes. For example:
   maxbytes=1000
Means 1000 bytes.
You can optionally include a KB, MB or GB after the number to specify kilobytes, megabytes, or gigabytes, respectively. For example:
   maxbytes=1000KB
Means 1000 kilobytes.
For queues, maxbytes defines the maximum size (in bytes) that the queue can store, summed over all messages in the queue. Should this limit be exceeded, messages will be rejected by the server and the message producer send calls will return an error (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 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 or non-durable online subscriber on that topic. That is, the limit applies separately to each 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. For a non-durable subscriber, maxbytes limits the number of pending messages that can accumulate while the subscriber is online.
Under certain conditions, because of the pipelined nature of message processing or the requirements of transactional messaging, the maxbytes limit can be slightly exceeded. You may see message totals that are marginally larger than the set limit.
When a destination inherits different values of this property from several parent destinations, it inherits the smallest value.
maxmsgs
Topics and queues can specify the maxmsgs property in the form:
   maxmsgs=value
where value 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 queue size to below these limits.
Under certain conditions, because of the pipelined nature of message processing or the requirements of transactional messaging, the maxmsgs limit can be slightly exceeded. You may see message totals that are marginally larger than the set limit.
maxRedelivery
The maxRedelivery property specifies the number of attempts the server should make to deliver a message sent to a queue. Set maxRedelivery using the form:
   maxRedelivery=count
where count is an integer between 2 and 255 that specifies the maximum number of times a message can be delivered to receivers. A value of zero disables maxRedelivery, so there is no maximum.
Once the server has attempted to deliver the message the specified number of times, the message is either destroyed or, if the JMS_TIBCO_PRESERVE_UNDELIVERED property on the message is set to true, the message is placed on the undelivered queue so it can be handled by a special consumer. See Undelivered Message Queue for details.
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.
 
In the event of an abrupt exit by the client, the maxRedelivery count can be mistakenly incremented. An abrupt exit prevents the client from communicating with the server; for example, when the client exits without closing the connection or when the client application crashes. If a client application exits abruptly, the EMS server counts all messages sent to the client as delivered, even if they were not presented to the application.
For more information, see Undelivered Message Queue.
overflowPolicy
Topics and queues can specify the overflowPolicy property to change the effect of exceeding the message capacity established by either maxbytes or maxmsgs.
Set the overflowPolicy using the form:
   overflowPolicy=default|discardOld|rejectIncoming
If overflowPolicy is not set, then the policy is default.
The effect of overflowPolicy differs depending on whether you set it on a topic or a queue, so the impact of each overflowPolicy value is described separately for topics and queues.
When overflowPolicy is set on multicast-enabled topics, it is honored in the multicast daemon. That is, the multicast daemon will discard messages based on the backlog in the daemon rather than the backlog in the server.
For topics and consumers that are not multicast-enabled, the response to the overflowPolicy occurs in the EMS server.
If wildcards are used in the .conf file the inheritance of the overflowPolicy policy from multiple parents works as follows:
If a child destination has a non-default overflowPolicy policy set, then that policy is used and it does not inherit any conflicting policy from a parent.
If a parent has OVERFLOW_REJECT_INCOMING set, then it is inherited by the child destination over any other policy.
If no parent has OVERFLOW_REJECT_INCOMING set and a parent has OVERFLOW_DISCARD_OLD policy set, then that policy is inherited by the child destination.
If no parent has the OVERFLOW_REJECT_INCOMING or OVERFLOW_DISCARD_OLD set, then the default policy is used by the child destination.
default
For topics, default specifies that messages are sent to each subscriber in turn. If the maxbytes or maxmsgs setting has been reached for a subscriber, that subscriber does not receive the message. No error is returned to the message producer.
For queues, default specifies that new messages are rejected by the server and an error is returned to the producer if the established maxbytes or maxmsgs value has been exceeded.
Note that this is the same default behavior for topics and queues as in EMS 4.3.
discardOld
For topics, discardOld specifies that, if any of the subscribers have an outstanding number of undelivered messages on the server that are over the message limit, the oldest messages are discarded before they are delivered to the subscriber.
The discardOld setting impacts subscribers individually. For example, you might have three subscribers to a topic, but only one subscriber exceeds the message limit. In this case, only the oldest messages for the one subscriber are discarded, while the other two subscribers continue to receive all of their messages.
When messages are discarded for topic subscribers, no error is returned to the producer because messages could be delivered to some subscribers and discarded for others.
For queues, discardOld specifies that, if messages on the queue have exceeded the maxbytes or maxmsgs value, the oldest messages are discarded from the queue and an error is returned to the message producer.
rejectIncoming
For topics, rejectIncoming specifies that, if any of the subscribers have an outstanding number of undelivered messages on the server that are over the message limit, all new messages are rejected and an error is returned to the producer.
For queues, rejectIncoming specifies that, if messages on the queue have exceeded the maxbytes or maxmsgs value, all new messages are rejected and an error is returned to the producer. (This is the same as the default behavior.)
Examples
To discard messages on myQueue when the number of queued messages exceeds 1000, enter:
setprop queue myQueue maxmsgs=1000,overflowPolicy=discardOld
To reject all new messages published to myTopic when the memory used by undelivered messages for any of the topic subscribers exceeds 100KB, enter:
setprop topic myTopic maxbytes=100KB,overflowPolicy=rejectIncoming
prefetch
The message consumer portion of a client and the server cooperate to regulate fetching according to the prefetch property. The prefetch property applies to both topics and queues.
You can set prefetch using the form:
   prefetch=value
where value is one of the values in Table 13.
Table 13 Prefetch 
2 or more
The message consumer automatically fetches messages from the server. The message consumer never fetches more than the number of messages specified by value.
The message consumer automatically fetches messages from the server—initiating fetch only when it does not currently hold a message.
Disables automatic fetch. That is, the message consumer initiates fetch only when the client calls receive—either an explicit synchronous call, or an implicit call (in an asynchronous consumer).
The destination inherits the prefetch value from a parent destination with a matching name. If it has no parent, or no destination in the parent chain sets a value for prefetch, then the default value is 5 queues and 64 for topics.
When a destination does not set any value for prefetch, then the default value is 0 (zero; that is, inherit the prefetch value).
See Inheritance for details.
 
If both prefetch and maxRedelivery are set to a non-zero value, then there is a potential to lose prefetched messages if one of the messages exceeds the maxRedelivery limit. For example, prefetch=5 and maxRedelivery=4. The first message is redelivered 4 times, hits the maxRedelivery limit and is sent to the undelivered queue (as expected). However, the other 4 pre-fetched messages are also sent to the undelivered queue and are not processed by the receiving application. The work around is to set prefetch=none, but this can have performance implications on large volume interfaces.
Background
Delivering messages from the server destination to a message consumer involves two independent phases—fetch and accept:
The fetch phase is a two-step interaction between a message consumer and the server.
In the accept phase, client code takes a message from the message consumer.
The receive call embraces both of these phases. It initiates fetch when needed and it accepts a message from the message consumer.
To reduce waiting time for client programs, the message consumer can prefetch messages—that is, fetch a batch of messages from the server, and hold them for client code to accept, one by one.
Automatic Fetch Enabled
To enable automatic fetch, set prefetch to a positive integer. Automatic fetch ensures that if a message is available, then it is 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 queue consumer prefetches a group of messages, the server does not deliver them to other queue consumers (unless the first queue consumer’s connection to the server is broken).
Automatic Fetch Disabled
To disable automatic fetch, set prefetch=none.
Even when prefetch=none, a queue consumer 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 message consumer. 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 queue consumer, and the server does not deliver it to another queue consumer (unless the first queue 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 destination inherits the prefetch property from parent destination with matching names, these behaviors are possible:
When all parent destinations set the value none, then the child destination inherits the value none.
When any parent destination sets a non-zero numeric value, then the child destination inherits the largest value from among the entire parent chain.
When none of the parent destinations sets any non-zero numeric value, then the child destination uses the default value (which is 5).
redeliverydelay
When redeliverydelay is set, the EMS server waits the specified interval before returning an unacknowledged message to the queue. When a previously delivered message did not receive a successful acknowledgement, the EMS server waits the specified redelivery delay before making the message available again in the queue. This is most likely to occur in the event of a transaction rollback, session or message recovery, session or connection close, or the abrupt exit of a client application. However, note that the delay time is not exact, and in most situations will exceed the specified redeliverydelay.
The value can be specified in seconds, minutes, or hours. The value may be in the range of 15 seconds and 8 hours.
You can set redeliverydelay using the form:
   redeliverydelay=time[sec|min|hour]
where time is the number of seconds. Zero is a special value that indicates no redelivery delay.
You can optionally include time units, such as sec, min, or hour describe the time value as being in seconds, minutes, or hours, respectively. For example:
   redeliverydelay=30min
specifies a redelivery delay of 30 minutes.
During the delay interval, messages are placed in the $sys.redelivery.delay queue. This queue can be browsed, but it cannot be consumed from or purged. However, purging the queue from which the delayed message came, or removing the message using its message ID, immediately removes that message from $sys.redelivery.delay.
While a message is on the $sys.redelivery.delay queue, it is not on the queue from which it came and so it is not included in statistical message counts. This includes maxmsgs, maxbytes, flowControl, and so on.
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.
You can set secure using the form:
   secure
If the secure property is not set for a destination, the server does not check permissions for that destination and any authenticated user can perform any operation 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 8, Authentication and Permissions for more information on permissions and the secure property.
sender_name
The sender_name property specifies that the server may include the sender’s username for messages sent to this destination.
You can set sender_name using the form:
   sender_name
When the sender_name 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.
You can set sender_name_enforced using the form:
   sender_name_enforced
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.
store
The store property determines where messages sent to this destination are stored. Messages may be stored in a file, or in a database. See Store Messages in Multiple Stores for more information on using and configuring multiple stores.
Before using the setprop or addprop commands to change the store settings for a topic or queue, you must stop the flow of incoming messages on the destination.
Set the store property using this form:
   store=name
where name is the name of a store, as defined in the stores.conf file.
For example, this will send all messages sent to the destination giants.games to the store named baseball; messages sent to all other destinations will be stored in everythingelse:
   > store=everythingelse
   giants.games store=baseball
Only one store is allowed for each destination. If there is a conflict, for example if overlapping wildcards cause a topic to inherit multiple store properties, the topic creation will fail.
 
This parameter cannot be used without first enabling this feature in the tibemsd.conf file. The stores.conf file must also exist, but can be left empty if the only store names that are associated with destinations are the default store files.
trace
The trace property specifies that tracing should be enabled for this destination.
You can set trace using the form:
   trace = [body]
Specifying trace (without =body), generates trace messages that include the message sequence, message ID, and message size. Specifying trace=body generates trace messages that include the message body. See Message Tracing for more information about message tracing.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved