Apama 10.15.0 | Connecting Apama Applications to External Components | Correlator-Integrated Support for the Java Message Service (JMS) | Using the Java Message Service (JMS) | JMS configuration reference | XML configuration bean reference
 
XML configuration bean reference
 
Advanced configuration bean properties
This topic lists the various configuration objects (beans) and the supported properties for each bean.
See also Using custom EL mapping extensions.
jms:connection
This bean defines the information needed to establish a JMS Connection to a single JMS broker instance. Its required properties are: connectionFactory or connectionFactory.jndiName, and (if JNDI is used to locate the connection factory), jndiContext.
Example:
<jms:connection id="MyConnection">
<property name="staticReceiverList"
value="${staticReceiverList.MyConnection}" />

<property name="defaultReceiverReliability"
value="${defaultReceiverReliability.MyConnection}"/>
<property name="defaultSenderReliability"
value="${defaultSenderReliability.MyConnection}"/>

<property name="connectionFactory.jndiName"
value="${connectionFactory.jndiName.MyConnection}" />

<property name="jndiContext.environment">
<value>
${jndiContext.environment.MyConnection}
</value>
</property>

<property name="connectionAuthentication.username"
value="${connectionAuthentication.username.MyConnection}" />
<property name="connectionAuthentication.password"
value="${connectionAuthentication.password.MyConnection}" />

</jms:connection>
Supported properties:
*connectionFactory.jndiName - the JNDI lookup name for the ConnectionFactory object that should be used for this jms:connection.
*connectionFactory - a JMS provider bean that implements the JMS ConnectionFactory interface, if the ConnectionFactory is to be instantiated directory by the Spring framework (rather than using JNDI to lookup the ConnectionFactory). The bean value that is provided will usually required properties and/or constructor arguments to be specified in order to fully initialize it.
*connectionAuthentication.username - the name of the user/principal to be used for the JMS connection (note that this is often different from the username/password needed to login to the JNDI server, which is part of the JNDI environment configuration). Default value is "".
*connectionAuthentication.password - the password/credentials to be used for the JMS connection.
*jndiContext.environment - the set of properties that specify the environment for initializing access to the JNDI store. Typically includes some standard JNDI keys such as java.naming.factory.initial, java.naming.provider.url, java.naming.security.principal and java.naming.security.credentials, and maybe also some provider-specific keys. The usual way to specify a properties map value is key=value entries delimited by newlines and surrounded by the <value> element, for example, <property name="jndiContext.environment"><value>...</value><</property>.
*clientId - the JMS client ID which uniquely identifies each connected JMS client to the broker. Default value is "" although some JMS providers may require this to be set, especially when using durable topics.
*defaultReceiverReliability - the Apama reliability mode to use for all this connection's receivers unless overridden on a per-receiver basis; valid values are BEST_EFFORT, AT_LEAST_ONCE, EXACTLY_ONCE, APP_CONTROLLED. Default value is BEST_EFFORT.
*defaultSenderReliability - the Apama reliability mode to use for all this connection's senders unless overridden on a per-sender basis; valid values are BEST_EFFORT, AT_LEAST_ONCE, EXACTLY_ONCE. Default value is BEST_EFFORT.
*staticReceiverList - a list of destinations to receive from, delimited by semi-colons. Each destination must begin with "queue:", "topic:" or "jndi:". This property provides a simple way to add static receivers when the more advanced configuration options provided by the staticReceivers property are not needed. staticReceiverList receivers are always added in addition to any receivers specified by staticReceivers. The staticReceiverList property cannot contain duplicate destination entries (see the staticReceivers property if this is required). Default value is "".
*staticReceivers - a list of jms:receiver beans specifying JMS receivers to create for this connection. The jms:receiver elements are wrapped in a <list> element, for example, <property name="staticReceivers"><list>...</list></property>. Default value is an empty list.
*staticSenders - a list of sender beans specifying JMS senders to create for this connection. The jms:sender elements are wrapped in a <list> element, for example, <property name="staticSenders"><list>...</list></property>. Default value is a single sender called "default".
*defaultReceiverSettings (advanced users only) - a reference to a JmsReceiverSettings bean, which provides access to advanced settings that are usually shared across all configured receivers for this connection. Default value is a reference to the JmsReceiverSettings bean instance defined in the jms-global-spring.xml file (this uses Spring's byType auto-wiring; if multiple top-level JmsReceiverSettings beans exist in the configuration then the reference must be specified explicitly in each jms:connection).
*defaultSenderSettings (advanced users only) - a reference to a JmsSenderSettings bean, which provides access to advanced settings that are usually shared across all configured senders for this connection. Default value is a reference to the JmsSenderSettings bean instance defined in the jms-global-spring.xml file (this uses Spring's byType auto-wiring; if multiple top-level JmsSenderSettings beans exist in the configuration then the reference must be specified explicitly in each jms:connection).
*reliableReceiveDatabase (advanced users only) - a reference to a ReliableReceiveDatabase bean, which is required for implementing the AT_LEAST_ONCE or EXACTLY_ONCE reliability modes for any receivers added to this jms:connection. Default value is a reference to the single DefaultReliableReceiveDatabase bean instance defined in the jms-global-spring.xml file (this uses Spring's byType auto-wiring; if multiple top-level DefaultReliableReceiveDatabase beans exist in the configuration then the reference must be specified explicitly in each jms:connection). The only reason for changing this property would be to use separate databases or different JMS connections which could in some advanced cases provide a performance advanced, depending on the application architecture and the configuration of the jms:connection and disk hardware.
*connectionRetryIntervalMillis - Specifies how long to wait between attempts to establish the JMS connection. Default value is 1000 ms.
*receiverMapper - points to a custom mapper. Typically you use a ref="beanid" attribute to do this. If this property is not specified, the default is that the connection uses the Apama-provided mapper, assuming it is the only mapper defined in the configuration.
*senderMapper - points to a custom mapper. Typically you use a ref="beanid" attribute to do this. If this property is not specified, the default is that the connection uses the Apama-provided mapper, assuming it is the only mapper defined in the configuration.
jms:receiver
This bean defines a single-threaded context for receiving events from a single JMS destination. Its only required property is "destination".
Example:
<jms:receiver id="myReceiver">
<property name="destination" value="topic:SampleT1"/>
</jms:receiver>
Supported properties:
*destination - the JMS queue or topic to receive from. Must begin with the prefix "queue:", "topic:" or "jndi:". A JMS queue or topic name can be specified with the "queue:" or "topic:" prefixes, or if the queue or topic should be looked up using a JNDI name then the "jndi:" prefix should be used instead.
*receiverReliability - the Apama reliability mode to use when JMS messages are received; valid values are BEST_EFFORT, AT_LEAST_ONCE, EXACTLY_ONCE, APP_CONTROLLED. Default value is provided by the parent jms:connection's defaultReceiverReliability setting.
*durableTopicSubscriptionName - if specified, a durable topic subscriber will be created (instead of a queue/topic consumer), and registered with the specified subscription name. Default value is "", which means do not create a durable topic subscription. Note that some providers will require the connection's clientId property to be specified when using durable topics.
*messageSelector - a JMS message selector string that will be used by the JMS provider to filter the messages pulled from the queue or topic by this receiver, based on the header and/or property values of the messages. Default value is "" which means that no selector is in operation and all messages will be received. Message selectors can be used to partition the messages received by multiple receivers on the same queue or durable topic. The JMS API documentation describes the syntax of message selectors in detail; a simple example selector is "JMSType = 'car' AND color = 'blue' AND weight > 2500".
*noLocal - an advanced JMS consumer parameter that prevents a connection's receivers from seeing messages that were sent on the same (local) JMS connection. Default value is false.
*dupDetectionDomainId - an advanced Apama setting for overriding the way receivers are grouped together for duplicate detection purposes when using EXACTLY_ONCE receive mode. Set this to the same string value for a set of receivers to request detection of duplicate uniqueMessageIds across all the messages from those receivers. Default value is "<connectionId>:<destination>" (that is, look for duplicates across all receivers for the same queue/topic only within the same jms:connection).
*receiverSettings - a reference to a JmsReceiverSettings bean, which provides access to advanced settings that are usually shared across all configured receivers. Default value is provided by the parent connection's defaultReceiverSettings property (which is usually a reference to the JmsReceiverSettings bean instance defined in the jms-global-spring.xml file).
jms:sender
This bean defines a single-threaded context for sending events to a JMS destination, and results in the creation of a correlator output channel called jms:senderId. It has no required properties.
Example:
<jms:sender id="mySender">
<property name="senderReliability" value="BEST_EFFORT"/>
<property name="messageDeliveryMode" value="PERSISTENT"/>
<property name="senderSettings" ref="globalSenderSettings"/>
</jms:sender>
Supported properties:
*senderReliability - the Apama reliability mode to use when events are sent to JMS. Valid values are BEST_EFFORT, AT_LEAST_ONCE, EXACTLY_ONCE. Default value is provided by the parent jms:connection's defaultSenderReliability setting.
*messageDeliveryMode - this property applies to a sender that is using the BEST_EFFORT reliability mode to deliver messages to a JMS broker. The default is the JMS NON_PERSISTENT delivery mode. You can change the value of this property to PERSISTENT mode. While PERSISTENT mode is slower, it causes the JMS broker to write messages to disk to protect against crashes of the JMS broker node. The only possible values for the messageDeliveryMode property are PERSISTENT and NON_PERSISTENT. This property is ignored for other reliable senders.
*senderSettings - a reference to a JmsSenderSettings bean, which provides access to advanced settings that are usually shared across all configured senders. Default value is provided by the parent connection's defaultSenderSettings property (which is usually a reference to the JmsSenderSettings bean instance defined in the jms-global-spring.xml file).
ReliableReceiveDatabase
This bean defines a database used by Apama to implement reliable receiving. It has no required properties. Typically all connections in a correlator will share the same receive database; if the correlator is not started with the -P (persistence enabled) flag, this bean will be ignored.
Example:
<bean id="myReliableReceiveDatabase"
class="com.apama.correlator.jms.config.DefaultReliableReceiveDatabase">
<property name="storePath" value="jms/my-receive.db"/>
<!-- either absolute path, or path relative to correlator store location -->
</bean>
Supported property:
*storePath - the path where the message store database should be created. Default value is jms-receive-persistence.db. Use an absolute path, or a path relative to the store location specified for use by the correlator state persistence store on the correlator command line.
To protect the security of personal data, see Protecting Personal Data in Apama Applications.
JmsSenderSettings
This bean defines advanced settings for message senders. It has no required properties. Typically all senders in all connections will share the same JmsSenderSettings bean, but it is also possible to use different settings for individual senders.
Example:
<bean id="globalSenderSettings"
class="com.apama.correlator.jms.config.JmsSenderSettings">
<property name="logJmsMessages" value="false"/>
<property name="logJmsMessageBodies" value="false"/>
<property name="logProductMessages" value="false"/>
</bean>
Supported properties:
*logJmsMessages - if true, log information about all JMS messages that are sent (but not the entire body) at INFO level. Default value is false.
*logJmsMessageBodies - if true, log information about all JMS messages that are sent, including the entire message body at INFO level. Default value is false.
*logProductMessages - if true, log information about all Apama events that are sent at INFO level. Default value is false.
*logDetailedStatus - Enables logging of a dedicated INFO status line for each sender and a summary line for each parent connection. The default value is false (detailed logging is disabled), which results in a single summary line covering all senders and connections.
*logPerformanceBreakdown - Enables periodic logging of a detailed breakdown of how much time is being taken by the different stages of mapping, sending, and disk operations for each sender. By default, the messages are logged every minute at the INFO level. The interval can be changed if desired. The default is false, and Apama recommends disabling this setting in production environments to prevent the gathering of the performance information from reducing performance.
*logPerformanceBreakdownIntervalSecs - Specifies the interval in seconds over which performance throughput and timings information will be gathered and logged. Default is 60.
*sessionRetryIntervalMillis - Specifies how long to wait between attempts to create a valid JMS session and producer for this sender either after a serious error while using the previous session or after a previous failed attempt to create the session. However, if the underlying JMS connection has failed the connectionRetryIntervalMillis is used instead. Default value is 1000 ms.
JmsReceiverSettings
This bean defines advanced settings for message receivers. it has no required properties. Typically all receivers in all connections will share the same JmsReceiverSettings bean, but it is also possible to use different settings for individual receivers.
Example:
<bean id="globalReceiverSettings"
class="com.apama.correlator.jms.config.JmsReceiverSettings">
<property name="dupDetectionPerSourceExpiryWindowSize" value="2000"/>
<property name="dupDetectionExpiryTimeSecs" value="120"/>

<property name="logJmsMessages" value="false"/>
<property name="logJmsMessageBodies" value="false"/>
<property name="logProductMessages" value="false"/>
</bean>
Supported properties:
*logJmsMessages - if true, log information about all JMS messages that are received (but not the entire body) at INFO level. Default value is false.
*logJmsMessageBodies - if true, log information about all JMS messages that are received, including the entire message body at INFO level. Default value is false.
*logProductMessages - if true, log information about all Apama events that are received at INFO level. Default value is false.
*logDetailedStatus - Enables logging of a dedicated INFO status line for each receiver and a summary line for each parent connection. The default value is false (detailed logging is disabled), which results in a single summary line covering all receivers and connections.
*logPerformanceBreakdown - Enables periodic logging of a detailed breakdown of how much time is being taken by the different stages of mapping, receiving, and disk operations for each receiver. By default, the messages are logged every minute at the INFO level. The interval can be changed if desired. The default is false, and Apama recommends disabling this setting in production environments to prevent the gathering of the performance information from reducing performance.
*logPerformanceBreakdownIntervalSecs - Specifies the interval in seconds over which performance throughput and timings information will be gathered and logged. Default is 60.
*dupDetectionPerSourceExpiryWindowSize - used for EXACTLY_ONCE receiving, and specifies the number of messages that will be kept in each duplicate detection domain per messageSourceId (if messageSourceId is set on each message by the upstream system - messages without a messageSourceId will all be grouped together into one window for the entire dupDetectionDomainId). Default value is "2000". It can be set to 0 to disable the fixed-size per-sender expiry window.
*dupDetectionExpiryTimeSecs - used for EXACTLY_ONCE receiving, and specifies the time for which uniqueMessageIds will be remembered before they expire. Default value is "120". It can be set to 0 to disable the time-based expiry window.
*maxExtraMappingThreads - Specifies the number of additional (non-receiver) threads to use for mapping received JMS messages to Apama events. The default value is 0. Using a value of 1 means all mapping is performed on a separate thread to the thread receiving messages from the bus; a value greater than 1 provides additional mapping parallelism. This setting cannot be used if maxBatchSize has been set to 1. Using multiple separate threads for mapping may improve performance in situations where mapping of an individual message is a heavyweight operation (for example, for complex XML messages) and where adding separate receivers is not desired (because they involve the overhead of additional JMS sessions and reduced ordering guarantees). Note that strictly speaking JMS providers do not have to support multi-threaded construction of JMS messages (since all JMS objects associated with a receiver's Session are meant to be dedicated to a single thread), so although in practice it is likely to be safe, it is important to verify that this setting does not trigger any unexpected errors in the JMS provider being used.
The order in which mapped events are added to the correlator input queue (of each public context) is not changed by the use of extra mapping threads, as messages from all mapping threads on a given receiver are put back into the original receive order at the end of processing each receive batch.
*sessionRetryIntervalMillis - Specifies how long to wait between attempts to create a valid JMS session and consumer for this receiver either after a serious error while using the previous session, or after a previous failed attempt to create the session. However, if the underlying JMS connection has failed the connectionRetryIntervalMillis is used instead). Default value is 1000 ms.
*receiverFlowControl - Specifies whether application-controlled flow is enabled for each receiver. When set to true, application-controlled flow control is enabled for each receiver, by listening for the com.apama.correlator.jms.JMSReceiverFlowControlMarker event and responding by calling the updateFlowControlWindow() action as appropriate. Default value is false.