Skip to content

chore: the JMS Kamelets take transactions, priority, expiry and an AMQP login (#3170) - #3219

Merged
davsclaus merged 1 commit into
apache:mainfrom
davsclaus:ci-issue-3170-jms-options
Nov 18, 2026
Merged

davsclaus merged 1 commit into
apache:mainfrom
davsclaus:ci-issue-3170-jms-options

Conversation

@davsclaus

Copy link
Copy Markdown
Contributor

Part of #3170: the JMS sources can have a message delivered again when its flow fails, and process several messages at the same time; the JMS sinks set the persistence, priority, expiry and message type of what they send; jms-amqp-10-* take a login; jms-ibm-mq-* take a list of connections for a multi-instance queue manager, and say how TLS gets its key and trust stores.

Today a source removes each message from the queue when it receives it, so a message whose flow fails is lost.

The options

All are optional, with no default, as in #3174. When they are unset, the optional placeholders drop them, and the endpoint URIs are identical to main's.

Sources (jms-apache-artemis-source, jms-amqp-10-source, jms-ibm-mq-source)

Option Template mapping What it does
transacted transacted: "{{?transacted}}" Each message is received in a transaction, committed once the flow has processed it. When the flow fails, the broker delivers it again (JMSRedelivered true), then moves it to its dead letter queue (Artemis) or the backout queue of the queue (IBM MQ).
acknowledgementModeName acknowledgementModeName: "{{?acknowledgementModeName}}" AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE (redelivery without a transaction) or DUPS_OK_ACKNOWLEDGE (acknowledges in batches).
concurrentConsumers concurrentConsumers: "{{?concurrentConsumers}}" Processes several messages at the same time.

subscriptionShared was already added by #3179.

Sinks (jms-apache-artemis-sink, jms-amqp-10-sink, jms-ibm-mq-sink)

Option Template mapping What it does
deliveryPersistent deliveryPersistent: "{{?deliveryPersistent}}" false sends non-persistent messages, lost when the broker restarts.
timeToLive timeToLive: "{{?timeToLive}}" Milliseconds before an unreceived message expires.
priority priority: "{{?priority}}" 0 to 9; the broker delivers the highest first.
jmsMessageType jmsMessageType: "{{?jmsMessageType}}" Text or Bytes, whatever the body.

Setting any of the first three makes camel-jms turn on explicitQosEnabled on its own, so the Kamelets do not need that option.

jms-amqp-10-source, jms-amqp-10-sink

Option Template mapping What it does
username bean username: "{{?username}}" The login. Before, it could only go in remoteURI as jms.username.
password bean password: "{{?password}}" (format: password, credentials descriptor) The password. It is used instead of jms.password in remoteURI, which no longer needs to hold a secret.

jms-ibm-mq-source, jms-ibm-mq-sink

Option Template mapping What it does
connectionNameList bean XMSC_WMQ_CONNECTION_NAME_LIST: "{{?connectionNameList}}", with a pattern: host(port) entries separated by commas, for a multi-instance queue manager.
  • The first address of connectionNameList: Camel binds the bean properties in name order, so XMSC_WMQ_HOST_NAME and XMSC_WMQ_PORT are set after the list. The IBM MQ client then puts serverName(serverPort) in place of the first entry. The descriptions say this, and tell the user to set serverName and serverPort to the first instance. serverName stays required.
  • TLS for IBM MQ: sslCipherSuite already existed. The IBM MQ client takes its trust store and key store from the Java runtime (javax.net.ssl.*). Camel's camel.ssl does not reach it: the connection factory takes only an SSLSocketFactory object, which a Kamelet cannot build. So there are no new options. The descriptions of sslCipherSuite and the partial pages now say how to set the stores.

Descriptions: the "Good to know" paragraphs are updated:

  • Sources: a failed message is delivered again with transacted or CLIENT_ACKNOWLEDGE, and concurrentConsumers exists.
  • Sinks: messages are persistent, with priority 4, and never expire by default.
  • AMQP: the login options.
  • IBM MQ: the TLS stores, and connectionNameList.

Each partial page has a new example.

Left out

  • transacted on the sinks. A transacted sink commits each message as soon as it is sent, so the receiver sees no difference. That is also true when a transacted source is in the same flow and the flow then fails:

    Source transacted, sink → .out, then the flow fails Artemis AMQP 1.0 IBM MQ
    Sink not transacted 10 copies on .out 10 copies 0
    Sink transacted: true 10 copies 10 copies 0

    On IBM MQ, the send is rolled back with the source, with or without the option. The likely cause is that MQConnectionFactory is a Map, so the two beans are equals(). Spring then finds the source's session bound to the transaction and sends on it. This needs both Kamelets to have the same connection settings. It is not documented.

  • Map, Stream and Object for jmsMessageType.

    • Map with a text body fails with a NullPointerException.
    • Stream arrives as a stream.
    • Object messages are disabled in camel-jms by default (objectMessageEnabled).

    A Map body is already sent as a map message.

Verification

Tested with Camel JBang 4.24.0-SNAPSHOT:

  • apache/activemq-artemis:latest-alpine: core protocol, and AMQP 1.0 for the jms-amqp-10-* Kamelets.
  • icr.io/ibm-messaging/mq:10.0.1.0-r1: plain, and a second container with a TLS key, where DEV.APP.SVRCONN has SSLCIPH(ANY_TLS12_OR_HIGHER).

The queue depths come from artemis queue stat and runmqsc DISPLAY QLOCAL CURDEPTH.

Case Artemis AMQP 1.0 IBM MQ
Options unset, main and this branch, all six Kamelets camel get endpoint URIs identical identical identical
Source, flow throws, unset Delivered once, lost Same Same
Source transacted: true, flow throws 10 deliveries (JMSXDeliveryCount 1 to 10, JMSRedelivered true from the 2nd), then in DLQ 10, then in DLQ BOTHRESH(3) BOQNAME(DEV.DEAD.LETTER.QUEUE): 3 deliveries, then on the backout queue
IBM MQ backout queue without put/passall for the user Stuck: JMSWMQ1079, and the next message on the queue waits too
IBM MQ BOTHRESH(0) (the default) 7,538 deliveries in about 35 s
Source CLIENT_ACKNOWLEDGE, flow throws 10, then DLQ 259,277 deliveries in 40 s: the Qpid client redelivers by itself 3, then the backout queue
AMQP CLIENT_ACKNOWLEDGE with jms.redeliveryPolicy.maxRedeliveries=3 in remoteURI 4 deliveries, then stops
50 messages processed, then kill -9, unset 0 left on the queue 0 0
The same with DUPS_OK_ACKNOWLEDGE 50 left (redelivered) 0 10 left, delivered again on the next start
The same with DUPS_OK_ACKNOWLEDGE and transacted: true 0 left 0 0
Queue, 10 messages of 1 s each, concurrentConsumers: 5 5 threads, about 1.2 s Same Same
The same, unset 1 thread, about 9 s Same Same
concurrentConsumers: 5, random 0-500 ms per message Done out of order Same Same
Topic, concurrentConsumers: 2, not shared, 10 messages Each processed twice (20); camel-jms logs a warning Same Same
Topic, subscriptionShared: true and subscriptionName, two separate integrations, 20 messages Odd numbers to one, even to the other (10/10) 10/10 10/10
Topic, shared, concurrentConsumers: 2, 20 messages 20 distinct, 2 threads Same Same
Topic, durable not shared, concurrentConsumers: 2, 5 messages 5 received once; the second consumer fails (AMQ229019 … already exists) 0 received: A non-shared durable subscription is already active 5 received once
Sink priority: 1 × 5, then priority: 9 × 5, then a source starts high1…high5 (JMSPriority 9) before low1…low5 Same Same
Sink priority: 0 Received with JMSPriority 0 Same Same
Sink timeToLive: 3000, source started after 10 s Nothing received; 3 in ExpiryQueue Nothing; 3 in ExpiryQueue Nothing; queue depth 0
The same, unset All 3 received, JMSExpiration 0, JMSPriority 4, JMSDeliveryMode 2 Same Same
Sink deliveryPersistent: false, broker restarted 3 → 0 3 → 0 3 → 0
The same, unset 3 → 3 3 → 3 3 → 3
Sink jmsMessageType: Bytes, text body Received as byte[] Same Same
Sink jmsMessageType: Text, byte[] body Received as String (unset: byte[]) Same Same
AMQP username/password options, no login in remoteURI Sent
AMQP wrong password option / no login at all failed to authenticate using SASL: PLAIN / unauthorized-access
AMQP jms.password=wrong in remoteURI + password option right; and jms.username=wrong + username right Sent: the options win
MQ connectionNameList: 127.0.0.1(1),localhost(31414) Connected
MQ serverName: bad.invalid, serverPort: 1, list 127.0.0.1(2),localhost(31414) Connected (via the 2nd entry)
MQ the same host and port, list localhost(31414) Fails: client tried bad.invalid(1)
MQ the same host and port, list localhost(31414),127.0.0.1(2) Fails: client tried bad.invalid(1),127.0.0.1(2)
MQ TLS channel, no sslCipherSuite Refused (AMQ9639E on the queue manager)
MQ sslCipherSuite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, no trust store PKIX path building failed
The same with -Djavax.net.ssl.trustStore=… Sent and received
The same with camel.ssl.enabled/camel.ssl.trustStore instead PKIX path building failed
MQ SSLCAUTH(REQUIRED), trust store only Refused (AMQ9637E no certificate)
The same with -Djavax.net.ssl.keyStore=… (client cert in the queue manager's trust) Sent and received

camel get endpoint showed every new option on the endpoint URI when set, such as jms://queue:prio.art?…&priority=9.

Build

The library copies of the six Kamelets were refreshed with ./mvnw -pl library/camel-kamelets resources:copy-resources@copy-resource-one. Then ./mvnw clean verify -DskipTests and ./mvnw clean verify passed from the root. KameletsCatalogTest needed no change. The build regenerated kamelets-index.json.

Claude Code on behalf of Claus Ibsen

🤖 Generated with Claude Code

…QP login (apache#3170)

The JMS sources (jms-apache-artemis-source, jms-amqp-10-source,
jms-ibm-mq-source) take:

- transacted: a message whose flow fails is rolled back and delivered
  again by the broker, which moves it to its dead letter queue (Artemis)
  or backout queue (IBM MQ) after a number of attempts. Today a message
  is removed when it is received, even when the flow then fails.
- acknowledgementModeName: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE or
  DUPS_OK_ACKNOWLEDGE.
- concurrentConsumers: process several messages at the same time.

The JMS sinks take deliveryPersistent, timeToLive, priority, and
jmsMessageType (Text or Bytes).

jms-amqp-10-source and jms-amqp-10-sink take username and password,
which are used instead of jms.username and jms.password in remoteURI.

jms-ibm-mq-source and jms-ibm-mq-sink take connectionNameList, for a
multi-instance queue manager. serverName and serverPort take the place
of the first address of the list. The descriptions of sslCipherSuite
now say that the IBM MQ client takes the trust store and key store of
the Java runtime (javax.net.ssl.*), and not camel.ssl.

All the new options are optional and have no default: with them unset,
the endpoint URIs are the same as before.

Left out:
- transacted on the sinks: it commits each message as soon as it is
  sent, whether or not a transacted source is in the same flow, so it
  changes nothing a receiver sees.
- Map, Stream and Object for jmsMessageType: Map fails on a body that
  is not a Map, Stream is received as a stream that most receivers do
  not expect, and Object messages are disabled in camel-jms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@davsclaus
davsclaus force-pushed the ci-issue-3170-jms-options branch from 45c4bc9 to ac0037b Compare November 18, 2026 20:01
@davsclaus
davsclaus merged commit f5e4fba into apache:main Nov 18, 2026
6 checks passed
@davsclaus
davsclaus deleted the ci-issue-3170-jms-options branch November 18, 2026 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant