THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Wiki Markup |
|---|
h2. SJMS Component
*Available as of Camel 2.11*
{note}
This component is under active development.
{note}
The SJMS Component is a JMS client API for use with Camel. It is based purely on the JMS API and as such does not rely on any third party messaging implementations keeping it light and flexible. It is willscheduled to be released as part of Camel 2.11 with the following functionality:
* Standard Queue and Topic Support (Durable & Non-Durable)
* InOnly & InOut MEP Support
* Plugable Asynchronous Producer and Consumer Processing
* Internal JMS Transaction Support
Additional key features include:
* Plugable Connection Resource Management
* Session, Consumer, & Producer Pooling & Caching Management
* AsynchronousTransacted ProducerBatch andConsumers Consumer& ProcessingProducers
* Support Internalfor JMSCustomizable Transaction Support
{ Commit Strategies (Local JMS Transactions only)
{info:title=Why the S in SJMS}
S stands for Simple and Standard and Springless. Also camel-jms was already taken. :)
{info}
Maven users will need to add the following dependency to their {{pom.xml}} for this component:
{code:xml}
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-sjms</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
{code}
h3h4. URI format
{code}
sjms:[queue:|topic:]destinationName[?options]
{code}
Where {{destinationName}} is a JMS queue or topic name. By default, the {{destinationName}} is interpreted as a queue name. For example, to connect to the queue, {{FOO.BAR}} use:
{code}
sjms:FOO.BAR
{code}
You can include the optional {{queue:}} prefix, if you prefer:
{code}
sjms:queue:FOO.BAR
{code}
To connect to a topic, you _must_ include the {{topic:}} prefix. For example, to connect to the topic, {{Stocks.Prices}}, use:
{code}
sjms:topic:Stocks.Prices
{code}
You append query options to the URI using the following format, {{?option=value&option=value&...}}
h3. SjmsComponent Options and ConfigurationsUsage Notes
BelowAs isstated anabove exampleSJMS ofComponent howuses toa configureJMS theclient SjmsComponentAPI withthat itswas requiredwritten ConnectionFactoryfrom provider.the ground Itup willfor createuse ain singleCamel. connectionAs bysuch defaultthere andare storesome itkey usingbehaviors theand componentsfeatures internalthat pooling APIs to ensure that it is able to service Session creation requests in a thread safe manner.
{code}
SjmsComponent component = new SjmsComponent();
component.setConnectionFactory(new ActiveMQConnectionFactory("tcp://localhost:61616"));
getContext().addComponent("sjms", component);
{code}
For a SjmsComponent that is required to support a durable subscription, you can override the default ConnectionFactoryResource instance and set the *clientId* property.
{code}
ConnectionFactoryResource connectionResource = new ConnectionFactoryResource();
connectionResource.setConnectionFactory(new ActiveMQConnectionFactory("tcp://localhost:61616"));
connectionResource.setClientId("myclient-id");
SjmsComponent component = new SjmsComponent();
component.setConnectionResource(connectionResource);
component.setMaxConnections(1);
{code}
h3. Producers
The SjmsProducer Endpoint supports the following properties:
{div:class=confluenceTableSmall}
|| Option || Default Value || Description ||
| {{acknowledgementMode}} | {{AUTO_ACKNOWLEDGE}} | The JMS acknowledgement name, which is one of: {{TRANSACTED}}, {{AUTO_ACKNOWLEDGE}} or {{DUPS_OK_ACKNOWLEDGE}}. {{CLIENT_ACKNOWLEDGE}} is not supported at this time. |
| {{consumerCountdeserve noting.
h4. Plugable Connection Resource Management
Coming soon ...
h4. Session, Consumer, & Producer Pooling & Caching Management
Coming soon ...
h4. Transacted Batch Consumers & Producers
Coming soon ...
h4. Customizable Transaction Commit Strategies (Local JMS Transactions only)
Coming soon ...
h3. Component Options and Configurations
The SJMS Component supports the following configuration options:
{div:class=confluenceTableSmall}
|| Option || Default Value || Description ||
| {{connectionFactory}} | {{null}} | |
| {{connectionResource}} | {{null}} | |
| {{headerFilterStrategy}} | {{DefaultJmsKeyFormatStrategy}} | |
| {{keyFormatStrategy}} | {{DefaultJmsKeyFormatStrategy}} | |
| {{maxConnections}} | {{1}} | The maximum number of connections available to endpoints started under this component |
| {{transactionCommitStrategy}} | {{DefaultTransactionCommitStrategy()}} | Defines the number of MessageProducer instances. |
{div}
Below is an example of how to configure the SjmsComponent with its required ConnectionFactory provider. It will create a single connection by default and store it using the components internal pooling APIs to ensure that it is able to service Session creation requests in a thread safe manner.
{code}
SjmsComponent component = new SjmsComponent();
component.setConnectionFactory(new ActiveMQConnectionFactory("tcp://localhost:61616"));
getContext().addComponent("sjms", component);
{code}
For a SjmsComponent that is required to support a durable subscription, you can override the default ConnectionFactoryResource instance and set the *clientId* property.
{code}
ConnectionFactoryResource connectionResource = new ConnectionFactoryResource();
connectionResource.setConnectionFactory(new ActiveMQConnectionFactory("tcp://localhost:61616"));
connectionResource.setClientId("myclient-id");
SjmsComponent component = new SjmsComponent();
component.setConnectionResource(connectionResource);
component.setMaxConnections(1);
{code}
h3. Producer Configuration Options
The SjmsProducer Endpoint supports the following properties:
{div:class=confluenceTableSmall}
|| Option || Default Value || Description ||
| {{acknowledgementMode}} | {{AUTO_ACKNOWLEDGE}} | The JMS acknowledgement name, which is one of: {{TRANSACTED}}, {{AUTO_ACKNOWLEDGE}} or {{DUPS_OK_ACKNOWLEDGE}}. {{CLIENT_ACKNOWLEDGE}} is not supported at this time. |
| {{consumerCount}} | {{1}} | *InOut only.* Defines the number of MessageListener instances that for response consumers. |
| {{exchangePattern}} | {{InOnly}} | Sets the Producers message exchange pattern. |
| {{namedReplyTo}} | {{null}} | *InOut only.* Specifies a named reply to destination for responses. |
| {{persistent}} | {{true}} | Whether a message should be delivered with persistence enabled. |
| {{producerCount}} | {{1}} | Defines the number of MessageProducer instances. |
| {{responseTimeOut}} | {{5000}} | *InOut only.* Specifies the amount of time an InOut Producer will wait for its response. |
| {{synchronous}} | {{true}} | Sets whether the Endpoint will use synchronous or asynchronous processing. |
| {{transacted}} | {{false}} | If the endpoint should use a JMS Session transaction. |
| {{ttl}} | {{-1}} | Disabled by default. Sets the Message time to live header. |
{div}
h3. Consumers Configuration Options
The SjmsConsumer Endpoint supports the following properties:
{div:class=confluenceTableSmall}
|| Option || Default Value || Description ||
| {{acknowledgementMode}} | {{AUTO_ACKNOWLEDGE}} | The JMS acknowledgement name, which is one of: {{TRANSACTED}}, {{AUTO_ACKNOWLEDGE}} or {{DUPS_OK_ACKNOWLEDGE}}. {{CLIENT_ACKNOWLEDGE}} is not supported at this time. |
| {{consumerCount}} | {{1}} | Defines the number of MessageListener instances. |
| {{durableSubscriptionId}} | {{null}} | Required for a durable subscriptions. |
| {{exchangePattern}} | {{InOnly}} | Sets the Consumers message exchange pattern. |
| {{messageSelector}} | {{null}} | Sets the message selector. |
| {{synchronous}} | {{true}} | Sets whether the Endpoint will use synchronous or asynchronous processing. |
| {{transacted}} | {{false}} | If the endpoint should use a JMS Session transaction. |
| {{transactionBatchCount}} | {{1}} | *InOut only.* Defines the number of MessageListener instances that for response consumers. |
| {{exchangePattern}} | {{InOnly}} | Sets the Producers message exchange patternThe number of exchanges to process before committing a local JMS transaction. The {{transacted}} property must also be set to true or this property will be ignored. |
| {{namedReplyTottl}} | {{null-1}} | Disabled *InOutby onlydefault.* SpecifiesSets athe namedMessage replytime to destinationlive for responsesheader. |
| {{persistent}} | {{true}} | Whether a message should be delivered with persistence enabled. |
| {{producerCount}} | {{1}} | Defines the number of MessageProducer instances. |
| {{responseTimeOut}} | {{5000}} | *InOut only.* Specifies the amount of time an InOut Producer will wait for its response. |
| {{synchronous}} | {{true}} | Sets whether the Endpoint will use synchronous or asynchronous processing. |
| {{transacted}} | {{false}} | If the endpoint should use a JMS Session transaction. |
| {{ttl}} | {{-1}} | Disabled by default. Sets the Message time to live header. |
{div}
h3. Consumers
The SjmsConsumer Endpoint supports the following properties:
{div:class=confluenceTableSmall}
|| Option || Default Value || Description ||
| {{acknowledgementMode}} | {{AUTO_ACKNOWLEDGE}} | The JMS acknowledgement name, which is one of: {{TRANSACTED}}, {{AUTO_ACKNOWLEDGE}} or {{DUPS_OK_ACKNOWLEDGE}}. {{CLIENT_ACKNOWLEDGE}} is not supported at this time. |
| {{consumerCount}} | {{1}} | Defines the number of MessageListener instances. |
| {{durableSubscriptionId}} | {{null}} | Required for a durable subscriptions. |
| {{exchangePattern}} | {{InOnly}} | Sets the Consumers message exchange pattern. |
| {{messageSelector}} | {{null}} | Sets the message selector. |
| {{synchronous}} | {{true}} | Sets whether the Endpoint will use synchronous or asynchronous processing. |
| {{transacted}} | {{false}} | If the endpoint should use a JMS Session transaction. |
| {{ttl}} | {{-1}} | Disabled by default. Sets the Message time to live header. |
{div}
h3. Examplesdiv}
h3. Usage Notes
h4. Message Header Format
The SJMS Component uses the same header format strategy that is used in the Camel JMS Component. This plugable strategy ensures that messages sent over the wire conform to the JMS Message spec.
For the exchange.in.header the following rules apply for the header keys:
Keys starting with JMS or JMSX are reserved.
exchange.in.headers keys must be literals and all be valid Java identifiers (do not use dots in the key name).
Camel replaces dots & hyphens and the reverse when when consuming JMS messages:
. is replaced by _DOT_ and the reverse replacement when Camel consumes the message.
- is replaced by _HYPHEN_ and the reverse replacement when Camel consumes the message.
See also the option jmsKeyFormatStrategy, which allows use of your own custom strategy for formatting keys.
For the exchange.in.header, the following rules apply for the header values:
h4. Message Content
To deliver content over the wire we must ensure that the body of the message that is being delivered adheres to the JMS Message Specification. Therefore, all that are produced must either be primitives or their counter objects (such as Integer, Long, Character). The types, String, CharSequence, Date, BigDecimal and BigInteger are all converted to their toString() representation. All other types are dropped.
h3. Example Usage
h4. InOnly Producer - (Default)
The InOnly Producer is the default behavior of the SJMS Producer Endpoint.
{code}
from("direct:start")
.to("sjms:queue:bar");
{code}
h4. InOut Producer
To enable InOut behavior append the {{exchangePattern}} attribute to the URI. By default it will use a dedicated TemporaryQueue for each consumer.
{code}
from("direct:start")
.to("sjms:queue:bar?exchangePattern=InOut");
{code}
You can specify a {{namedReplyTo}} though which can provide a better monitor point.
{code}
from("direct:start")
.to("sjms:queue:bar?exchangePattern=InOut&namedReplyTo=my.reply.to.queue");
{code}
h3. Additional Notes
h4. Does Springless Mean I Can't Use Spring?
Not at all. Below is an example of the SJMS component using the Spring DSL:
{code}
<route
id="inout.named.reply.to.producer.route">
<from
uri="direct:invoke.named.reply.to.queue" />
<to
uri="sjms:queue:named.reply.to.queue?namedReplyTo=my.response.queue&exchangePattern=InOut" />
</route>
{code}
Springless refers to moving away from the dependency on the Spring JMS API. A new JMS client API is being developed from the ground up to power SJMS.
h4. Clustering
When using InOut with SJMS in a clustered environment you must either use TemporaryQueue destinations or use a unique named reply to destination per InOut producer endpoint. Message correlation is handled by the endpoint, not with message selectors at the broker. The InOut Producer Endpoint uses Java Concurrency Exchangers cached by the Message JMSCorrelationID. This provides a nice performance increase while reducing the overhead on the broker since all the messages are consumed from the destination in the order they are produced by the interested consumer.
Currently the only correlation strategy is to use the JMSCorrelationId. The InOut Consumer uses this strategy as well ensuring that all responses messages to the included JMSReplyTo destination also have the JMSCorrelationId copied from the request as well.
h3. Transaction Support {anchor:transactionCacheLevelstransactions}
SJMS currently only supports the use of internal JMS Transactions. There is currently no support for the Camel Transaction Processor nor does it support or the Java Transaction API (JTA). Only internal JMS Session Transactions are supported at this time. |