Configuring JMS endpoints
Overview
The Java Message Service (JMS) is a messaging standard that allows application components based on the Java Platform Enterprise Edition (Java EE) to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.
As per FIXEdge Java, JMS endpoints allow you to establish a connection with JMS message providers and receive/send data from/to them. JMS endpoints can work with queues and topics. Each endpoint has a unique name. Each JMS endpoint routes messages only in one way: it can be either a Producer or a Consumer.
During FIXEdge Java server start-up, it initiates endpoints that are defined in the jms-adaptor.properties configuration file.
The list of active endpoints is defined by the jms.adaptor.ClientNames property. If the jms.adaptor.ClientNames property is specified with an empty value, then none of the clients are active.
To add a new JMS endpoint, the following steps should be taken:
- In the jms-adaptor.properties configuration define the JMS endpoint configuration and specify its name in the jms.adaptor.ClientNames property.
- In the jms-adaptor.properties configuration file define the JMS connection configuration. JMS connection properties have the jms.adaptor.Connection.[ConnectionName] prefix, where the [ConnectionName] is a unique identifier/name of this connection. Each JMS connection has a set of available configuration properties but it can be extended with custom ones.
Configuration properties
It is possible to use environment variables in configuration.
For example, jms.adaptor.Connection.[ConnectionName].Password = ${CONNECTION_PASSWORD}, where CONNECTION_PASSWORD is the name of the environment variable.
The JMS adaptor should be configured using the following properties:
Property Name | Description | Required | Default Value |
|---|---|---|---|
Adapter parameters | |||
jms.adaptor.ClientNames | This property defines the comma-delimited list of JMS endpoints. Each listed client should be configured in a separate section. | Y | - |
jms.adaptor.ConnectionNames | This property defines the comma-delimited list of JMS TA connections. Each listed connection should be configured in a separate section. | Y | - |
Connection parameters | |||
jms.adaptor.Connection.[ConnectionName].ProviderURI | This property defines the URI of the JMS provider to connect to and the protocol to use, e.g. TCP/IP. Also, the configuration information can be encoded in the URI. | Y | - |
jms.adaptor.Connection.[ConnectionName].User | This property defines the name of the user. | Y | - |
jms.adaptor.Connection.[ConnectionName].Password | This property defines the passport of the user. | Y | - |
jms.adaptor.Connection.[ConnectionName].Reconnect | This property enables/disables the reconnection procedure for JMS brokers that don't support the failover mechanism. Valid values: true | false | N | false |
jms.adaptor.Connection.[ConnectionName].ReconnectTries | This property defines the number of reconnect tries. Valid values: int | -1 for an infinite number of attempts | N | 3 |
jms.adaptor.Connection.[ConnectionName].ReconnectInterval | This property defines the fixed interval in milliseconds between reconnection attempts. Valid values: int | N | 2000 |
jms.adaptor.Connection.[ConnectionName].InitialContextFactory | This property is used for JNDI and defines the fully qualified class name of the factory that will create the initial context. An initial context is the starting point for naming operations. | Y (if the JNDI mechanism is used) | - |
jms.adaptor.Connection.[ConnectionName].ConnectionFactory | This property defines the connection factory object name in the JNDI objects store. | Y (if the JNDI mechanism is used) | - |
Client parameters | |||
jms.adaptor.Client.[ClientName].ConnectionName | This property defines the name of the primary connection used by the client. The specified connection must be registered in the jms.adaptor.ConnectionNames property and all its required parameters must be specified. | Y | - |
jms.adaptor.Client.[ClientName].StorageDir | This property defines the path to the directory where the persistence file is stored in case of connection problems. | Y (if the Persist delivery mode is selected) | - |
jms.adaptor.Client.[ClientName].SessionType | This property defines the session role. Valid values: Producer | Consumer | Y | - |
jms.adaptor.Client.[ClientName].MessagingMode | This property defines the session messaging mode. Valid values: Queue | Topic When the 'Queue' value is specified then each message is addressed/sent to a specific queue, and consuming clients extract them from the queue(s). Queues retain messages until they are consumed or expired. When the 'Topic' value is specified then each message is addressed/sent to a topic. Publishers and subscribers are generally anonymous and can dynamically publish or subscribe to the content hierarchy. The system distributes messages arriving from a topic to its subscribers. Topics retain messages until they are distributed to current subscribers. | Y | - |
jms.adaptor.Client.[ClientName].DestinationURI | This property specifies the URI of the session destination - the name of the queue or topic. Valid values: string | Y | - |
jms.adaptor.Client.[ClientName].DeliveryMode
| This property defines whether sent messages will be lost in case of JMS provider failure. Used for Producers only. Valid values: Persist | NoPersist When the 'Persist' value is specified each sent message is logged to a safe and stable storage to recover in case of JMS provider failure. When the 'NoPersist' value is specified each sent message is not logged so it may be lost in case of JMS provider failure. | Y | - |
jms.adaptor.JMSTA.Client.[ClientName].TimeToLive | This property defines message expiration time in milliseconds. The time of message expiration is defined by the sum of the jms.adaptor.JMSTA.Client.[ClientName].TimeToLive property value and the GMT timestamp of message sending. Valid values: int | 0 for an infinite TTL | Y | 3000 |
jms.adaptor.JMSTA.Client.[ClientName].SessionAckMode | This property defines a mode in which the JMS session will acknowledge the receiving and sending messages. Valid values: Auto | Client | DupsOk When the 'Auto' value is specified the session automatically acknowledges the receipt of the message when the session has successfully returned from a call to receive or when the message listener's call to process the message successfully returns. When the 'Client' value is specified the client acknowledges the receipt of the message by calling the message's acknowledge method. When the 'Client' acknowledgment mode is used the client may accumulate a large number of unacknowledged messages while attempting to process them. When the 'DupsOk' value is specified the session 'lazily' acknowledges the receipt of the message which leads to duplicate delivery in case of JMS provider failure. This mode must be used only by Consumer sessions which can tolerate duplicated messages. | Y | - |
jms.adaptor.JMSTA.Client.[ClientName].MessageType
| This property defines the JMS message type for the session. Valid values: Bytes | Text | Custom When the 'Bytes' value is specified the session operates by the messages in the form of interpreted bytes. This message type is used for encoding the message body in order to match the existing format. When the 'Text' value is specified the session operates by messages in a String. This message type is used for handling more complex character data, such as XML documents. When the 'Custom' value is specified the session operates by messages with the custom message type. Custom message types may be used to adapt to already existing systems. If the custom message type is used the jms.adaptor.Client.[ClientName].CustomMessageType property is required. | Y | - |
jms.adaptor.Client.[ClientName].CustomMessageType
| This property defines the class of a custom message type implementation. Implementation of one of the following interfaces is valid:
| Y (if message type is Custom) | - |
jms.adaptor.Client.[ClientName].Transacted
| This property enables/disables sending or receiving session messages in transacted mode. Valid values: true | false | N | false |
jms.adaptor.Client.[ClientName].TransactionBatchSize | This property defines the maximum number of messages per transaction. An available number of messages less than the TransactionBatchSize value will be sent/received from the incoming/outgoing queue. Used only when Transacted mode is enabled. Valid values: int | N | 20 |
jms.adaptor.Client.[ClientName].QueueSize | This property defines the maximum number of messages in the outgoing queue. Used for Producers only. Valid values: int | N | 100 |
jms.adaptor.Client.[ClientName].QueuePersistent
| This property defines whether messages will be stored in the file until they are committed. This approach allows restoring and sending messages after an unexpected application shutdown. Valid values: true | false When the 'true' value is specified messages will be saved in the file storage (persistent queue) with parallel saving in memory. When the 'false' value is specified messages will be saved in the in-memory queue. This approach is faster but less safe since some messages may be lost after restart. 'QueuePersistent = true' is used to save queued messages only in file storage, without parallel storing in memory since the JMS TA 1.3.10 version. | N | true |
jms.adaptor.Client.[ClientName].QueueNormalFileSize | This property defines the normal persistent file size in MBytes. After reaching the specified queue size, the endpoint waits until the queue is empty to truncate the file. Used only when Persistent queue is enabled. Valid values: int | N | 10 |
jms.adaptor.Client.[ClientName].QueueMaxFileSize
| This property defines the maximum persistent file size in MBytes. After reaching the specified queue size, the endpoint truncates the file and overwrites the messages that are queued. Used only when Persistent queue is enabled. Valid values: int | N | 50 |
jms.adaptor.Client.[ClientName].StorageFlushMode | This property defines whether the forced flush must be performed after each write operation. Used for Producers only. Valid values: Force | Auto | N | Auto |
jms.adaptor.Client.[ClientName].PublishTimeout | This property defines a timeout interval in milliseconds to put the message in the outgoing queue if it is full. Used for Producers only. If publishing to the queue fails after PublishTimeout milliseconds (the queue is still full) the exception will be thrown and the message won't be added to the queue. Valid values: int | -1 for automated publishing | N | 2000 |
jms.adaptor.Client.[ClientName].DurableSubscription
| This property enables durable topic subscriptions which allow receiving messages published while the subscriber is not active. Used for Consumers only. Durable subscriptions offer the reliability of queues to publish/subscribe to the message domain. Valid values: true | false | N | false |
jms.adaptor.Client.[ClientName].DurableSubscriptionName | This property defines the name/identifier of the durable subscription. Valid values: string | Y (if durable subscription is enabled) | - |
jms.adaptor.Client.[ClientName].ConnectionsCount | This property defines the number of connections to the JMS server that will be opened by JMS. The selected session will be able to send messages simultaneously. If the number of connections is greater than 1, there is no guarantee that messages will be delivered to JMS in the same order as they were sent by the JMS adapter. Valid values: int | N | 1 |
jms.adaptor.Client.[ClientName].ThreadsPerConnection | This property defines the number of threads per JMS connection. The endpoint will open a given amount of JMS sessions for each connection to send messages simultaneously. If the number of threads per connection is greater than 1, there is no guarantee that messages will be delivered to JMS in the same order as they were sent by the JMS adapter. Valid values: int | N | 1 |
jms.adaptor.Client.[ClientName].maskPasswordsInStorages | This property provides the ability to enable/disable user password obfuscating. When the 'true' value is specified the Password(554) value in the Logon(35=A) message will be masked with "*****". Valid values: true | false | N | true |
jms.adaptor.Client.[ClientName].AllowRejectMessages | This property defines whether unsent messages will be sent back to a user's application on the JMS Producer disconnect. Used for Producers only. When the 'true' value is specified JMS rejects messages if unable to send to the MQ or an error occured. Valid values: true | false | N | false |
jms.adaptor.Client.[ClientName].AllowMeasureIncomingTimestamp | This property defines whether incoming timestamps will be recorded to calculate the processing latency of the JMS client displayed on FIXICC H2 WebUI. Used for Comsumers only. Valid values: true | false | N | true |
jms.adaptor.Client.[ClientName].startOnload | Since FIXEdge Java 1.8.0 version all configured JMS endpoints will be started automatically during the FIXEdge Java server initialization if there is a defined schedule for them. The schedule may be defined by the startTime and stopTime properties or within the Scheduler configuration. This property defines whether the JMS endpoint will be started during FIXEdge Java server initialization. Valid values: true | false | N | true |
jms.adaptor.Client.[ClientName].startTime | This property defines the JMS endpoint start time. Valid values: CRON expressions | N | NULL |
jms.adaptor.Client.[ClientName].stopTime | This property defines the JMS endpoint stop time. Valid values: CRON expressions | N | NULL |
jms.adaptor.Client.[ClientName].scheduleTimeZone | This property defines the timezone for the startTime and stopTime. | N | NULL |
All changes in the jms-adaptor.properties configuration file will be applied only after the FIXEdge Java server restart.
Sample Configuration
ActiveMQ Connection
The particular activemq-client.jar file must be present in the /lib directory.
General JMS Consumer endpoint parameters in the jms-adaptor.properties configuration file:
jms.adaptor.ConnectionNames =LocalActiveMQConnection jms.adaptor.ClientNames = ActiveMQProducer, ActiveMQConsumer # ActiveMQ Connection definition jms.adaptor.Connection.LocalActiveMQConnection.InitialContextFactory = org.apache.activemq.jndi.ActiveMQInitialContextFactory jms.adaptor.Connection.LocalActiveMQConnection.ProviderURI = tcp://localhost:61616 jms.adaptor.Connection.LocalActiveMQConnection.User = jms.adaptor.Connection.LocalActiveMQConnection.Password = jms.adaptor.Connection.LocalActiveMQConnection.ConnectionFactory = queueConnectionFactory jms.adaptor.Connection.LocalActiveMQConnection.Reconnect = true jms.adaptor.Connection.LocalActiveMQConnection.ReconnectTries = 3 jms.adaptor.Connection.LocalActiveMQConnection.ReconnectInterval = 500 # ActiveMQ Producer definition jms.adaptor.Client.ActiveMQProducer.ConnectionName = LocalActiveMQConnection jms.adaptor.Client.ActiveMQProducer.StorageDir = ./logs jms.adaptor.Client.ActiveMQProducer.SessionType = Producer jms.adaptor.Client.ActiveMQProducer.MessagingMode = Queue jms.adaptor.Client.ActiveMQProducer.DestinationURI = MyQueue jms.adaptor.Client.ActiveMQProducer.DeliveryMode = NoPersist jms.adaptor.Client.ActiveMQProducer.TimeToLive = 100000 jms.adaptor.Client.ActiveMQProducer.SessionAckMode = Auto jms.adaptor.Client.ActiveMQProducer.MessageType = Text jms.adaptor.Client.ActiveMQProducer.Transacted = true jms.adaptor.Client.ActiveMQProducer.DurableSubscription = false jms.adaptor.Client.ActiveMQProducer.DurableSubscriptionName = DurableTest # ActiveMQ Consumer definition jms.adaptor.Client.ActiveMQConsumer.ConnectionName = LocalActiveMQConnection jms.adaptor.Client.ActiveMQConsumer.StorageDir = ./logs jms.adaptor.Client.ActiveMQConsumer.SessionType = Consumer jms.adaptor.Client.ActiveMQConsumer.MessagingMode = Queue jms.adaptor.Client.ActiveMQConsumer.DestinationURI = MyQueue jms.adaptor.Client.ActiveMQConsumer.DeliveryMode = NoPersist jms.adaptor.Client.ActiveMQConsumer.TimeToLive = 100000 jms.adaptor.Client.ActiveMQConsumer.SessionAckMode = Auto jms.adaptor.Client.ActiveMQConsumer.MessageType = Text jms.adaptor.Client.ActiveMQConsumer.Transacted = false jms.adaptor.Client.ActiveMQConsumer.DurableSubscription = false jms.adaptor.Client.ActiveMQConsumer.DurableSubscriptionName = DurableTest
The jms.adaptor.Connection.LocalActiveMQConnection.ProviderURI property must be set to the 'tcp://localhost:61616' which is the host:port of Apache ActiveMQ Message Broker.
TIBCO EMS Connection
The particular tibjms.jar TIBCO JMS client library must be copied from the TIBCO EMS installation /lib directory.
General JMS Consumer endpoint parameters in the jms-adaptor.properties configuration file:
jms.adaptor.ConnectionNames =TibcoJMSConnection jms.adaptor.ClientNames = TibcoConsumer # JMS Connection definition jms.adaptor.Connection.TibcoJMSConnection.InitialContextFactory = com.tibco.tibjms.naming.TibjmsInitialContextFactory jms.adaptor.Connection.TibcoJMSConnection.ProviderURI = tcp://localhost:7222 jms.adaptor.Connection.TibcoJMSConnection.User =dev jms.adaptor.Connection.TibcoJMSConnection.Password =dev jms.adaptor.Connection.TibcoJMSConnection.ConnectionFactory = TopicConnectionFactory jms.adaptor.Connection.TibcoJMSConnection.ReconnectTries = 2000000 jms.adaptor.Connection.TibcoJMSConnection.ReconnectInterval = 2000 jms.adaptor.Connection.TibcoJMSConnection.Reconnect = true # Topic Consumer client jms.adaptor.Client.TibcoConsumer.ConnectionName = TibcoJMSConnection jms.adaptor.Client.TibcoConsumer.SessionType = Consumer jms.adaptor.Client.TibcoConsumer.MessagingMode = Topic jms.adaptor.Client.TibcoConsumer.DestinationURI = fixedge.deals jms.adaptor.Client.TibcoConsumer.DeliveryMode = NoPersist jms.adaptor.Client.TibcoConsumer.TimeToLive = 100000 jms.adaptor.Client.TibcoConsumer.SessionAckMode = Auto jms.adaptor.Client.TibcoConsumer.MessageType = Text jms.adaptor.Client.TibcoConsumer.StorageDir = ./logs jms.adaptor.Client.TibcoConsumer.DurableSubscription = true jms.adaptor.Client.TibcoConsumer.DurableSubscriptionName = fixedge.deals
RedHat AMQ Connection
The particular RHEL JMS Client library must be copied to the /lib directory.
General JMS Consumer endpoint parameters in the jms-adaptor.properties configuration file:
#JMS Connection definition jms.adaptor.ConnectionNames = Connection1 jms.adaptor.Connection.Connection1.InitialContextFactory = org.apache.qpid.jms.jndi.JmsInitialContextFactory jms.adaptor.Connection.Connection1.ConnectionFactory = myFactoryLookup jms.adaptor.Connection.Connection1.ConnectionFactory.myFactoryLookup = amqp://localhost:5672 jms.adaptor.Connection.Connection1.User = centos jms.adaptor.Connection.Connection1.Password = centos jms.adaptor.ClientNames = ProducerSession, ConsumerSession # Poducer client jms.adaptor.Client.ProducerSession.ConnectionName = Connection1 jms.adaptor.Client.ProducerSession.StorageDir = ./logs jms.adaptor.Client.ProducerSession.SessionType = Producer jms.adaptor.Client.ProducerSession.MessagingMode = Queue jms.adaptor.Client.ProducerSession.DestinationURI = queue1 jms.adaptor.Client.ProducerSession.DeliveryMode = NoPersist jms.adaptor.Client.ProducerSession.TimeToLive = 100000 jms.adaptor.Client.ProducerSession.SessionAckMode = Auto jms.adaptor.Client.ProducerSession.MessageType = Text # Consumer client jms.adaptor.Client.ConsumerSession.ConnectionName = Connection1 jms.adaptor.Client.ConsumerSession.StorageDir = ./logs jms.adaptor.Client.ConsumerSession.SessionType = Consumer jms.adaptor.Client.ConsumerSession.MessagingMode = Queue jms.adaptor.Client.ConsumerSession.DestinationURI = queue2 jms.adaptor.Client.ConsumerSession.DeliveryMode = NoPersist jms.adaptor.Client.ConsumerSession.TimeToLive = 100000 jms.adaptor.Client.ConsumerSession.SessionAckMode = Auto jms.adaptor.Client.ConsumerSession.MessageType = Text