jms ingress connector

JMS Ingress Connector

Version: 17.07

Supported Since: 17.01

What is Spring JMS Ingress Connector?

The Spring JMS Ingress Connector can be used to obtain messages from a remote JMS queue and inject those messages to the UltraESB engine. At the moment, UltraESB supports JMS specification 1.0.2+ and if you are using any proprietary JMS server it MUST be compatible with the 1.0.2+ specification.

When you are obtaining a message from the queue you can use a transaction to make sure, that no message is lost. The sample use cases below depict the two integration flows with and without transactions

In order to use the JMS Ingress Connector, you must first select the Spring JMS Connector dependency from the connector list when you are creating an empty Ultra project. If you have already created a project, you can add the Spring JMS Connector dependency via Component Registry. From Tools menu, select Ultra Studio → Component Registry and from the Connectors list, select the Spring JMS Connector dependency.
jms ingress connector 7

Out Ports

Processor

The message received to the Ingress Connector will be emitted through this outport

On Exception

The message will be sent to this outport if the Ingress Connector fails to process the message due to some reason

Parameters

* marked fields are mandatory

Source queue *

Basic

Name of the source queue

Connection Factory *

Basic

Connection Factory to be used with the connector

Transaction Manager

Transaction

The org.adroitlogic.x.base.trp.UltraPlatformTransactionManager instance to be used with the connector

Session Acknowledgement Mode

Transaction

Set the JMS acknowledgement mode that is used when creating a JMS Session to send a message.

Default is AUTO_ACKNOWLEDGE. Vendor-specific extensions to the acknowledgment mode can be set here as well.

0 - SESSION_TRANSACTED
1 - AUTO_ACKNOWLEDGE
2 - CLIENT_ACKNOWLEDGE
3 - DUPS_OK_ACKNOWLEDGE

Transaction Timeout

Transaction

Specify the transaction timeout to use for transactional wrapping, in seconds. Default is none, using the transaction manager’s default timeout

Cache Level

Advanced

Specify the level of caching that this Connector is allowed to apply.

Default is CACHE_NONE if an external transaction manager has been specified to re-obtain all resources freshly within the scope of the external transaction), and CACHE_CONSUMER otherwise (operating with local JMS resources).

0 - CACHE_NONE
1 - CACHE_CONNECTION
2 - CACHE_SESSION
3 - CACHE_CONSUMER
4 - CACHE_AUTO.

Default is CACHE_AUTO

Concurrent Consumers

Advanced

Specify the number of concurrent consumers to create. Default is 1. Specifying a higher value for this setting will increase the standard level of scheduled concurrent consumers at runtime: This is effectively the minimum number of concurrent consumers which will be scheduled at any given time. This is a static setting; for dynamic scaling, consider specifying the "maxConcurrentConsumers" setting instead.

Raising the number of concurrent consumers is recommendable in order to scale the consumption of messages coming in from a queue. However, note that any ordering guarantees are lost once multiple consumers are registered. In general, stick with 1 consumer for low-volume queues. Do not raise the number of concurrent consumers for a topic, unless vendor-specific setup measures clearly allow for it.

With regular setup, this would lead to concurrent consumption of the same message, which is hardly ever desirable.

Maximum Concurrent Consumers

Advanced

Specify the maximum number of concurrent consumers to create. Default is 1. If this setting is higher than "concurrentConsumers", the connector will dynamically schedule new consumers at runtime, provided that enough incoming messages are encountered. Once the load goes down again, the number of consumers will be reduced to the standard level ("concurrentConsumers") again. Raising the number of concurrent consumers is recommendable in order to scale the consumption of messages coming in from a queue.

However, note that any ordering guarantees are lost once multiple consumers are registered. In general, stick with 1 consumer for low-volume queues. Do not raise the number of concurrent consumers for a topic, unless vendor-specific setup measures clearly allow for it. With regular setup, this would lead to concurrent consumption of the same message, which is hardly ever desirable.

Maximum Messages per task

Advanced

Specify the maximum number of messages to process in one task. More concretely, this limits the number of message reception attempts per task, which includes receive iterations that did not actually pick up a message until they hit their timeout (see the "receiveTimeout").

Default is unlimited (-1) in case of a standard TaskExecutor, reusing the original invoker threads until shutdown (at the expense of limited dynamic scheduling).

Long-lived tasks avoid frequent thread context switches through sticking with the same thread all the way through, while short-lived tasks allow thread pools to control the scheduling. Hence, thread pools will usually prefer short-lived tasks.

Idle Task Execution Limit

Advanced

Specify the limit for idle executions of a consumer task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks.

The default is 1, closing idle resources early once a task didn’t receive a message. This applies to dynamic scheduling only; see the "maxConcurrentConsumers" setting. The minimum number of consumers (see "concurrentConsumers") will be kept around until shutdown in any case.

Within each task execution, a number of message reception attempts (according to the "maxMessagesPerTask" setting) will each wait for an incoming message (according to the "receiveTimeout" setting). If all of those receive attempts in a given task return without a message, the task is considered idle with respect to received messages. Such a task may still be rescheduled; however, once it reached the specified "idleTaskExecutionLimit", it will shut down (in case of dynamic scaling).

Raise this limit if you encounter too frequent scaling up and down. With this limit being higher, an idle consumer will be kept around longer, avoiding the restart of a consumer once a new load of messages comes in. Alternatively, specify a higher "maxMessagesPerTask" and/or "receiveTimeout" value, which will also lead to idle consumers being kept around for a longer time

Recovery Interval

Advanced

Specify the interval between recovery attempts, in milliseconds. The default is 5000 ms, that is, 5 seconds. This is a convenience method to create a FixedBackOff with the specified interval. Specify the interval between recovery attempts, in milliseconds. Default is 5000ms

Message Selector

Advanced

Set the JMS message selector expression (or null if none). Default is none.

See the JMS specification for a detailed definition of selector expressions. However, this is considered advanced usage; use it with care!

Pub-Sub Domain

Advanced

Configure the destination accessor with knowledge of the JMS domain used. Default is Point-to-Point (Queues).

This setting primarily indicates what type of destination to resolve if dynamic destinations are enabled. Select it for the Publish/Subscribe domain (javax.jms.Topic Topics}), otherwise Point-to-Point domain (javax.jms.Queue Queues})

Pub-Sub No Local

Advanced

Set whether to inhibit the delivery of messages published by its own connection. Default is false

Subscription Durable

Advanced

Set whether to make the subscription durable. The durable subscription name to be used can be specified through the "subscriptionName" property.

Default is "false". Set this to "true" to register a durable subscription, typically in combination with a "subscriptionName" value (unless your message listener class name is good enough as subscription name).

Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the "pubSubDomain" flag as well.

Durable Subscription Name

Advanced

Set the name of a durable subscription to create. This method switches to pub-sub domain mode and activates subscription durability as well.

Receive Timeout

Advanced

Set the timeout to use for receive calls, in milliseconds. The default is 1000 ms, that is, 1 second.

This value needs to be smaller than the transaction timeout used by the transaction manager (in the appropriate unit, of course). -1 indicates no timeout at all; however, this is only feasible if not running within a transaction manager.

Accept messages while stopping

Advanced

Set whether to accept received messages while the listener container in the process of stopping.

Default is "false", rejecting such messages through aborting the receive attempt. Switch this flag on to fully process such messages even in the stopping phase, with the drawback that even newly sent messages might still get processed (if coming in before all receive timeouts have expired).

Aborting receive attempts for such incoming messages might lead to the provider’s retry count decreasing for the affected messages. If you have a high number of concurrent consumers, make sure that the number of retries is higher than the number of consumers, to be on the safe side for all potential stopping scenarios.

JMS Exception Listener

Advanced

Set the JMS ExceptionListener to notify in case of a JMSException thrown by the registered message listener or the invocation infrastructure

JMS Error Handler

Advanced

Set the ErrorHandler to be invoked in case of any uncaught exceptions thrown while processing a Message

Sample Use Case

Prerequisite

You need to specify a JMS Template to send messages to the destination. For this example let’s use ActiveMQ and if you have not already installed ActiveMQ please follow the installation guide.

First open the project.xpml file of the project and right click on it (on the XML content of the file). From the context menu, select Resource Template as shown in below figure

jms egress connector 5

After that from the shown dialog box, select ActiveMQ JMS template.

jms egress connector 6

Next you need to specify the required parameters as shown below. It is mandatory to specify a bean prefix and for that you can specify any value. The only other mandatory field is the ActiveMQ Broker URL.

jms egress connector 7
1. Obtaining a message from a JMS queue

First let’s create our integration flow named SampleFlow and add a JMS IngressConnector to that, and as for the source queue specify the name of the source queue and under connection factory, select MQ1-activeMq-springCachingConnectionFactory and save the configuration.

jms ingress connector 3

After that, we’ll add a Logger Element to log the payload of the message to the console. Next include a Successful Flow End element and connect it to the Logger Element to complete the flow as shown below.