Chapter 16
Administered Object Attribute Reference
This chapter provides reference information about the attributes of administered objects. It contains the following sections:
Destination Properties
Table 16-1 lists the attributes that configure destination administered objects.
Table 16-1 Destination Administered Object Attributes
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqDestinationDescription
|
A description for the destination objects.
|
string
|
None
|
|
imqDestinationName
|
The name of the physical destination.
|
string
|
Untitled_Destination_Object
|
Connection Factory Attributes
This section contains reference information on the attributes that configure connection factory administered objects. Attributes are categorized into the following sections:
Table 16-2 is an index to the connection factory administered object attributes. The first column alphabetically lists each attribute; the second column lists its category; and the third column is a cross-reference to the table in which the attribute is described.
Connection Handling
Table 16-2 lists the connection factory attributes for connection handling.
Table 16-2 Connection Factory Attributes: Connection Handling
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqAddressList
|
A comma-separated list of one or more message server addresses. There are several addressing schemes, which are specific to the connection service and port assignment method you want to use.
For information about how to specify the address list and examples that illustrate list entries, see Syntax for the imqAddressList Attribute Value.
|
string
|
An existing Message Queue 3.0 address if any, or if not, to the first entry in Table 16-3.
|
|
imqAddressListBehavior
|
A string specifying whether connection attempts are in the order of addresses in the imqAddressList attribute (PRIORITY) or in a random order (RANDOM). If many clients attempt a connection using the same connection factory, you can use a random order to prevent them from all connecting to the same address.
|
string
|
PRIORITY
|
|
imqAddressListIterations
|
The number of times the client runtime iterates through the imqAddressList in an effort to establish or re-establish a connection. A value of -1 indicates that the number of attempts is unlimited.
|
integer
|
5
|
|
imqPingInterval
|
The frequency, in seconds, with which the client runtime tests the connection between an application and broker.
A value of -1 or 0 (zero) disables the client runtime from periodically testing the connection.
|
integer
|
30
|
|
imqReconnectEnabled
|
A boolean value specifying whether the client runtime should attempt to reconnect to a message server (or the list of addresses in imqAddressList) when a connection is lost.
|
boolean
|
false
|
|
imqReconnectAttempts
|
The number of attempts to connect (or reconnect) for each address in the imqAddressList before the client runtime moves on to try the next address in the list. A value of -1 indicates that the number of reconnect attempts is unlimited (the client runtime will attempt to connect to the first address until it succeeds).
|
integer
|
0 (zero)
|
|
imqReconnectInterval
|
The interval between reconnect attempts, in milliseconds. This value applies for attempts on each address in the imqAddressList and for successive addresses in the list. If the value is too small, a broker has insufficient recovery time. If the value is too large, the reconnect might represent an unacceptable delay.
|
long
|
3000 (milliseconds)
|
|
imqSSLIsHostTrusted
|
A boolean value specifying whether the client can accept a broker’s self-signed certificate. To use signed certificates from a certificate authority, set this value to false.
|
boolean
|
true
|
Syntax for the imqAddressList Attribute Value
Each address in the imqbrokerlist value corresponds to a broker instance to which a client runtime can connect.
For each connection service, you specify the broker address differently. The syntax is generally as follows:
scheme://address_syntax
To add an address to the list, add a comma and another address. The list can have any number of entries, in the following format:
scheme://address_syntax,scheme://address_syntax...
The scheme variable specifies which of the following addressing types you are using, as described in Table 16-3: mq, mqtcp, mqssl, http, or https. The address_syntax variable represents the scheme-specific broker address. Table 16-3 lists the addressing schemes. The first column contains the name of an addressing scheme; the second column shows what connection service is associated with the name; the third column is a description; and the fourth column provides the syntax to use.
Table 16-3 Addressing Schemes for the imqAddressList Attribute
|
Scheme
|
Connection
Service
|
Description
|
Syntax
|
|
mq
|
ms
ssljms
|
Provides dynamic port assignment for use with the jms or ssljms services.
You specify the Port Mapper host and port. The Port Mapper dynamically assigns the port used for the connection.
|
[hostName][:port][/serviceName]
For the jms connection service, the following default values apply:
hostName = localhost
port = 7676
serviceName = jms
For the ssljms connection service, there are no default values. You must specify all variables.
|
|
mqtcp
|
jms
|
Specifies a port number and uses the jms connection service.
Message Queue client runtime makes a tcp connection to the specified host and port to establish a connection.
|
hostName:port/jms
|
|
mqssl
|
ssljms
|
Specifies a port number and uses the ssljms connection service.
Message Queue client runtime makes a secure ssl connection to the specified host and port to establish a connection.
|
port/ssljms
|
|
http
|
httpjms
|
Uses the httpjms connection service.
The client runtime makes an HTTP connection to a Message Queue tunnel servlet at the specified URL. The broker must be configured to access the HTTP tunnel servlet.
|
http://hostName:port/contextRoot/tunnel
If multiple broker instances use the same tunnel servlet, this is the syntax for connecting to a specific broker instance, rather than a randomly selected one:
http://hostName:port/contextRoot
/tunnel?ServerName=hostName:instanceName
|
|
https
|
httpsjms
|
Uses the httpsjms connection service.
Message Queue client runtime makes a secure HTTPS connection to the specified Message Queue tunnel servlet URL. The broker must be configured to access the HTTPS tunnel servlet.
|
https://hostName:port/contextRoot/tunnel
If multiple broker instances use the same tunnel servlet, this is the syntax for connecting to a specific broker instance, rather than a randomly selected one:
https://hostName:port/contextRoot/
tunnel?ServerName=hostName:instanceName
|
Table 16-4 contains examples of the addressing formats. The first column is the name of a connection service. The second column specifies whether the host in the example is the local host, an unspecified host, a specified host, or not applicable. The third column specifies whether the port in the example is specified, not specified, or not applicable, and the fourth column is an example.
Table 16-4 Message Server Address Examples
|
Connection Service
|
Broker Host
|
Port
|
Example Address
|
|
Not specified
|
Local host
|
Not specified
|
Default
(mq://localHost:7676/jms)
|
|
Not specified
|
Specified host
|
Not specified
|
myBkrHost
(mq://myBkrHost:7676/jms)
|
|
Not specified
|
Not specified
|
Portmapper port specified
|
1012
(mq://localHost:1012/jms)
|
|
ssljms
|
Local host
|
Portmapper port not specified
|
mq://localHost:7676/ssljms
|
|
ssljms
|
Specified host
|
Portmapper port
|
mq://myBkrHost:7676/ssljms
|
|
ssljms
|
Specified host
|
Portmapper port specified
|
mq://myBkrHost:1012/ssljms
|
|
jms
|
Local host
|
Service port specified
|
mqtcp://localhost:1032/jms
|
|
ssljms
|
Specified host
|
Service port specified
|
mqssl://myBkrHost:1034/ssljms
|
|
httpjms
|
Not applicable
|
Not applicable
|
http://websrvr1:8085/imq/tunnel
|
|
httpsjms
|
Not applicable
|
Not applicable
|
https://websrvr2:8090/imq/tunnel
|
Client Identification
Table 16-5 lists the connection factory attributes for client identification.
Table 16-5 Connection Factory Attributes: Client Identification
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqDefaultUsername
|
The default user name for authenticating with the broker.
|
string
|
guest
|
|
imqDefaultPassword
|
The default password for authenticating with the broker.
|
string
|
guest
|
|
imqConfiguredClientID
|
An administratively configured client ID.
|
string
|
null
|
|
imqDisableSetClientID
|
A boolean value specifying whether to prevent the client from changing the client ID using the setClientID() method in the JMS API.
|
boolean
|
false
|
Message Header Overrides
Table 16-6 lists the connection factory attributes for overriding JMS message header fields.
Table 16-6 Connection Factory Attributes: Message Header Overrides
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqOverrideJMSDeliveryMode
|
A boolean value specifying whether the client-set JMSDeliveryMode field can be overridden.
|
boolean
|
false
|
|
imqJMSDeliveryMode
|
The override value of JMSDeliveryMode. Values are 1 (non-persistent) and 2 (persistent).
|
integer
|
2
|
|
imqOverrideJMSExpiration
|
A boolean value specifying whether the client-set JMSExpiration field can be overridden.
|
boolean
|
false
|
|
imqJMSExpiration
|
The override value of JMSExpiration, in milliseconds.
|
long
|
0
(no expiration)
|
|
imqOverrideJMSPriority
|
A boolean value specifying whether the client-set JMSPriority field can be overridden.
|
boolean
|
false
|
|
imqJMSPriority
|
The override value of JMSPriority (an integer from 0 to 9).
|
integer
|
4 (normal)
|
|
imqOverrideJMSHeadersTo
TemporaryDestinations
|
A boolean value specifying whether overrides apply to temporary destinations.
|
boolean
|
false
|
Reliability and Flow Control
Table 16-7 lists the connection factory attributes that configure reliability and flow control.
Table 16-7 Connection Factory Attributes: Reliability and Flow Control
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqAckTimeout
|
The maximum time, in milliseconds, that the client runtime waits for a broker response before throwing an exception. A value of 0 means there is no time-out and the client runtime waits forever.
In some situations, this value can be too low and cause the client runtime to time out. For example, for each user that a broker authenticates using an LDAP user repository and a secure (SSL) connection, the first authentication can take more than 30 seconds.
|
string
|
0
|
|
imqAckOnProduce
|
A string specifying how the broker responds to messages from a producing client.
If this attribute is set to true, the broker responds to receipt of all JMS messages (persistent and non-persistent) from the producing client. The producing client thread blocks while waiting for those responses.
If this attribute is not specified, the broker responds to persistent messages only. The producing client thread blocks while waiting for those responses.
|
string
|
not
specified
|
|
imqConnectionFlowCount
|
The number of JMS messages in a metered batch. When this number of JMS messages is delivered to the client runtime, delivery is temporarily suspended, allowing any control messages that had been held up to be delivered. Payload message delivery is resumed upon notification by the client runtime, and continues until the count is again reached.
If the count is set to 0 then there is no restriction in the number of JMS messages in a metered batch. A non-zero setting allows the client runtime to meter message flow so that Message Queue control messages are not blocked by heavy JMS message delivery.
|
integer
|
100
|
|
imqConnectionFlowLimit
Enabled
|
A boolean value specifying whether to use the value of imqConnectionFlowLimit to limit message flow at the connection level.
|
boolean
|
false
|
|
imqConnectionFlowLimit
|
The maximum number of messages that can be delivered over a connection and buffered in the client runtime, waiting to be consumed. Note however, that unless imqConnectionFlowIsLimited is enabled, this limit is not checked.
When the number of JMS messages delivered to the client runtime (in accordance with the flow metering governed by imqConnectionFlowCount) exceeds this limit, message delivery stops. It is resumed only when the number of unconsumed messages drops below the value set with this attribute.
This limit prevents a consuming client that is taking a long time to process messages from being overwhelmed with pending messages that might cause it to run out of memory.
|
integer
|
1000
|
|
imqConsumerFlowLimit
|
The maximum number of messages per consumer that can be delivered over a connection and buffered in the client runtime, waiting to be consumed. This limit is used to improve load-balancing among consumers in multi-consumer queue delivery situations (no one consumer can be sent a disproportionate number of messages). This limit can be overridden by a lower value set on the broker side for the queue’s consumerFlowLimit attribute (see information on destination attributes in the Message Queue Administration Guide).
This limit also helps prevent any one consumer on a connection from starving other consumers on the connection.
When the number of JMS messages delivered to the client runtime exceeds this limit for any consumer, message delivery for that consumer stops. It is resumed only when the number of unconsumed messages for that consumer drops below the value set with imqConsumerFlowThreshold.
(Note that if the total number of messages buffered for all consumers on a connection exceeds the imqConnectionFlowLimit, delivery of messages through the connection will stop until that total drops below the connection limit.)
|
integer
|
100
|
|
imqConsumerFlow
Threshold
|
The number of messages per consumer buffered in the client runtime, as a percentage of imqConsumerFlowLimit, below which delivery of messages for a consumer will resume.
|
integer
|
50
|
Queue Browser Behavior and Server Session
Table 16-8 describes attributes that affect queue browsing for clients.
Table 16-8 Connection Factory Attributes: Queue Browser Behavior
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqQueueBrowserMax
MessagesPerRetrieve
|
The maximum number of messages that the client runtime will retrieve at one time when browsing the contents of a queue destination.
|
integer
|
1000
|
|
imqQueueBrowserRetrieveTimeou
t
|
The maximum time, in milliseconds, that the client runtime will wait to retrieve messages, when browsing the contents of a queue destination, before throwing an exception.
|
long
|
60000
|
|
imqLoadMaxToServerSession
|
For JMS application server facilities, a boolean value specifying whether a Message Queue connection consumer should load up to the maxMessages number of messages into a ServerSession's session. If false, the client will load only a single message at a time.
|
|
true
|
JMS-Defined Properties Support
JMS-defined properties are names reserved by JMS, and which a JMS provider can choose to support to enhance client programming capabilities. Table 16-9 describes the JMS-defined properties supported by Message Queue.
Table 16-9 Connection Factory Attributes: JMS-defined Properties Support
|
Property Name
|
Description
|
Type
|
Default
|
|
imqSetJMSXUserID
|
A boolean value specifying whether to set the JMS-defined property JMSXUserID (identity of user sending the message) on produced messages.
|
boolean
|
false
|
|
imqSetJMSXAppID
|
A boolean value specifying whether to set the JMS-defined property JMSXAppID (identity of application sending the message) on produced messages.
|
boolean
|
false
|
|
imqSetJMSXProducerTXID
|
A boolean value specifieying whether to set the JMS-defined property JMSXProducerTXID (transaction identifier of the transaction within which this message was produced) on produced messages.
|
boolean
|
false
|
|
imqSetJMSXConsumerTXID
|
A boolean value specifying whether to set the JMS-defined property JMSXConsumerTXID (transaction identifier of the transaction within which this message was consumed) on consumed messages.
|
boolean
|
false
|
|
imqSetJMSXRcvTimestamp
|
A boolean value specifying whether to set the JMS-defined property JMSXRcvTimestamp (the time the message is delivered to the consumer) on consumed messages.
|
boolean
|
false
|
SOAP Endpoint Attributes
Table 16-10 lists the attributes that configure endpoint URLs for applications that use SOAP. For information on applications that use SOAP, see the Message Queue Developer’s Guide for Java Clients.
Table 16-10 SOAP Endpoint Attributes
|
Attribute Name
|
Description
|
Type
|
Default
|
|
imqSOAPEndpointList
|
A list of one of more space-separated URLs representing SOAP endpoints to which to send messages.
If you specify more than one URL, messages are broadcast to all URLs in the list. Each URL should be associated with a servlet that can receive and process a SOAP message.
Example:
http://www.myServlet/ http://www.myServlet2/
|
string
|
|
|
imqEndpointName
|
The name of the SOAP endpoint.
Example: MyTopicEndpoint
|
string
|
Untitled_
Endpoint_
Object
|
|
imqEndpointDescription
|
A description of the SOAP endpoint.
Example:
"imqEndpointDescription=my endpoints for broadcast"
|
string
|
A
description
for the
endpoint
object
|
