Table 12 lists the properties that can be assigned to topics and queues. The following sections describe each property.
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:
where name is the name of a channel, as defined in the
channels.conf file.
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.
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:
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.
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:
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. However, 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.
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:
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.
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.
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.
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.
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:
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:
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:
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.
where value is the number of bytes. For example:
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 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.
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 the queue size to below these limits.
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:
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.
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:
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.
If wildcards are used in the .conf file the inheritance of the
overflowPolicy policy from multiple parents works as follows:
●
|
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.
|
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.
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.
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.)
To discard messages on myQueue when the number of queued messages exceeds 1000, enter:
To reject all new messages published to myTopic when the memory used by undelivered messages for any of the topic subscribers exceeds 100KB, enter:
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:
where value is one of the values in
Table 13.
|
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 replayed 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.
|
●
|
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.
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).
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.
When a destination inherits the prefetch property from parent destination with matching names, these behaviors are possible:
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:
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.
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:
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.
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:
If the sender_name property is also set on the destination, this property overrides the
sender_name property.
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:
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:
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.
The trace property specifies that tracing should be enabled for this destination.
You can set trace using the form:
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.