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.
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.
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 destinationany authenticated user can perform any operations on that topic or queue.
![]() |
The
secure property is independent of SSLit 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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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:
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.
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.
With non-exclusive queues (exclusive
set to false) the server distributes messages in a round-robinone to each receiver that is ready. If any receivers are still ready to accept additional messages, the server distributes another round of messagesone 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.
The prefetch
property applies only to queues.
Delivering messages from the server to a client program involves two independent phasesfetch 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 messagesthat is, fetch a batch of messages from the server, and hold them for client code to accept, one by one.
The MessageConsumer
and the server cooperate to regulate fetching according to the queue’s prefetch
property. Table 5 presents the range of values.
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).
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.
When a queue inherits the prefetch
property from parent queues with matching names, these behaviors are possible:
none
, then the child queue inherits the value none
.
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 |