camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Claus Ibsen (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Camel > SJMS
Date Sat, 14 Sep 2013 09:49:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/SJMS">SJMS</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~davsclaus">Claus
Ibsen</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{div:class=confluenceTableSmall} <br>||
Option || Default Value || Description || <br></td></tr>
            <tr><td class="diff-changed-lines" >| {{acknowledgementMode}} | {{AUTO_ACKNOWLEDGE}}
| The JMS acknowledgement name, which is one of: <span class="diff-changed-words">{{<span
class="diff-added-chars"style="background-color: #dfd;">SESSION_</span>TRANSACTED}},</span>
{{AUTO_ACKNOWLEDGE}} or {{DUPS_OK_ACKNOWLEDGE}}. {{CLIENT_ACKNOWLEDGE}} is not supported at
this time. | <br></td></tr>
            <tr><td class="diff-unchanged" >| {{consumerCount}} | {{1}} | *InOut
only.* Defines the number of [MessageListener|http://docs.oracle.com/javaee/5/api/javax/jms/MessageListener.html]
instances that for response consumers. | <br>| {{exchangePattern}} | {{InOnly}} | Sets
the Producers message exchange pattern. | <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The minimal value that will be
accepted is 1000ms as the amount of context switching may cause unnecessary performance impacts
without gaining <span class="diff-changed-words">ben<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">i</span><span
class="diff-added-chars"style="background-color: #dfd;">e</span>fit.</span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>The producer endpoint is
handled much differently though. With the producer after each message is delivered to its
destination the Exchange is closed and there is no longer a reference to that message. To
make a available all the messages available for redelivery you simply enable transactions
on a Producer Endpoint that is publishing BatchMessages. The transaction will commit at the
conclusion of the exchange which includes all messages in the batch list.  Nothing additional
need be configured. For example: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="SJMS-SJMSComponent"></a>SJMS Component</h2>
<p><b>Available as of Camel 2.11</b></p>

<p>The Simple JMS Component, or SJMS, is a JMS client for use with Camel that uses well
known best practices when it comes to JMS client creation and configuration. SJMS contains
a brand new JMS client API written explicitly for Camel eliminating third party messaging
implementations keeping it light and resilient.  It is scheduled to be released as part of
Camel 2.11 with the following functionality:</p>

<ul>
	<li>Standard Queue and Topic Support (Durable &amp; Non-Durable)</li>
	<li>InOnly &amp; InOut MEP Support</li>
	<li>Asynchronous Producer and Consumer Processing</li>
	<li>Internal JMS Transaction Support</li>
</ul>


<p>Additional key features include:</p>

<ul>
	<li>Plugable Connection Resource Management</li>
	<li>Session, Consumer, &amp; Producer Pooling &amp; Caching Management</li>
	<li>Batch Consumers and Producers</li>
	<li>Transacted Batch Consumers &amp; Producers</li>
	<li>Support for Customizable Transaction Commit Strategies (Local JMS Transactions
only)</li>
</ul>


<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Why the S
in SJMS</b><br />S stands for Simple and Standard and Springless.  Also camel-jms
was already taken. <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif"
height="20" width="20" align="absmiddle" alt="" border="0"/></td></tr></table></div>

<p>Maven users will need to add the following dependency to their <tt>pom.xml</tt>
for this component:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;dependency&gt;
    &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
    &lt;artifactId&gt;camel-sjms&lt;/artifactId&gt;
    &lt;version&gt;x.x.x&lt;/version&gt;
    &lt;!-- use the same version as your Camel core version --&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h4><a name="SJMS-URIformat"></a>URI format</h4>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:[queue:|topic:]destinationName[?options]
</pre>
</div></div>

<p>Where <tt>destinationName</tt> is a JMS queue or topic name. By default,
the <tt>destinationName</tt> is interpreted as a queue name. For example, to connect
to the queue, <tt>FOO.BAR</tt> use:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:FOO.BAR
</pre>
</div></div>

<p>You can include the optional <tt>queue:</tt> prefix, if you prefer:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:queue:FOO.BAR
</pre>
</div></div>

<p>To connect to a topic, you <em>must</em> include the <tt>topic:</tt>
prefix. For example, to connect to the topic, <tt>Stocks.Prices</tt>, use:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:topic:Stocks.Prices
</pre>
</div></div>

<p>You append query options to the URI using the following format, <tt>?option=value&amp;option=value&amp;...</tt></p>

<h3><a name="SJMS-ComponentOptionsandConfigurations"></a>Component Options
and Configurations</h3>

<p>The SJMS Component supports the following configuration options:</p>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Required </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>connectionCount</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <tt>1</tt> </td>
<td class='confluenceTd'> The maximum number of connections available to endpoints started
under this component </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>connectionFactory</tt> </td>
<td class='confluenceTd'> <img class="emoticon" src="/confluence/images/icons/emoticons/check.gif"
height="16" width="16" align="absmiddle" alt="" border="0"/> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> A <a href="http://docs.oracle.com/javaee/5/api/javax/jms/ConnectionFactory.html"
class="external-link" rel="nofollow">ConnectionFactory</a> is required to enable
the SjmsComponent. It can be set directly or set set as part of a ConnectionResource. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>connectionResource</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> A ConnectionResource is an interface that allows for customization
and container control of the ConnectionFactory.  See <a href="#SJMS-connectionresource">Plugable
Connection Resource Management</a> for further details. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>headerFilterStrategy</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <tt>DefaultJmsKeyFormatStrategy</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>keyFormatStrategy</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <tt>DefaultJmsKeyFormatStrategy</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>transactionCommitStrategy</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
</tbody></table>
</div>
</div>

<p>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.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
SjmsComponent component = new SjmsComponent();
component.setConnectionFactory(new ActiveMQConnectionFactory("tcp://localhost:61616"));
getContext().addComponent("sjms", component);
</pre>
</div></div>

<p>For a SjmsComponent that is required to support a durable subscription, you can override
the default ConnectionFactoryResource instance and set the <b>clientId</b> property.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
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);
</pre>
</div></div>

<h3><a name="SJMS-ProducerConfigurationOptions"></a>Producer Configuration
Options</h3>

<p>The SjmsProducer Endpoint supports the following properties:</p>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>acknowledgementMode</tt> </td>
<td class='confluenceTd'> <tt>AUTO_ACKNOWLEDGE</tt> </td>
<td class='confluenceTd'> The JMS acknowledgement name, which is one of: <tt>SESSION_TRANSACTED</tt>,
<tt>AUTO_ACKNOWLEDGE</tt> or <tt>DUPS_OK_ACKNOWLEDGE</tt>. <tt>CLIENT_ACKNOWLEDGE</tt>
is not supported at this time. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>consumerCount</tt> </td>
<td class='confluenceTd'> <tt>1</tt> </td>
<td class='confluenceTd'> <b>InOut only.</b> Defines the number of <a
href="http://docs.oracle.com/javaee/5/api/javax/jms/MessageListener.html" class="external-link"
rel="nofollow">MessageListener</a> instances that for response consumers. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>exchangePattern</tt> </td>
<td class='confluenceTd'> <tt>InOnly</tt> </td>
<td class='confluenceTd'> Sets the Producers message exchange pattern. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>namedReplyTo</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> <b>InOut only.</b> Specifies a named reply to
destination for responses. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>persistent</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> Whether a message should be delivered with persistence enabled.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>producerCount</tt> </td>
<td class='confluenceTd'> <tt>1</tt> </td>
<td class='confluenceTd'> Defines the number of <a href="http://docs.oracle.com/javaee/5/api/javax/jms/MessageProducer.html"
class="external-link" rel="nofollow">MessageProducer</a> instances. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>responseTimeOut</tt> </td>
<td class='confluenceTd'> <tt>5000</tt> </td>
<td class='confluenceTd'> <b>InOut only.</b> Specifies the amount of time
an InOut Producer will wait for its response. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>synchronous</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> Sets whether the Endpoint will use synchronous or asynchronous
processing. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>transacted</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> If the endpoint should use a JMS Session transaction. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ttl</tt> </td>
<td class='confluenceTd'> <tt>&#45;1</tt> </td>
<td class='confluenceTd'> Disabled by default.  Sets the Message time to live header.
</td>
</tr>
</tbody></table>
</div>
</div>

<h3><a name="SJMS-ProducerUsage"></a>Producer Usage</h3>

<h4><a name="SJMS-InOnlyProducer%28Default%29"></a>InOnly Producer - (Default)</h4>

<p>The InOnly Producer is the default behavior of the SJMS Producer Endpoint.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("direct:start")
    .to("sjms:queue:bar");
</pre>
</div></div>

<h4><a name="SJMS-InOutProducer"></a>InOut Producer</h4>

<p>To enable InOut behavior append the <tt>exchangePattern</tt> attribute
to the URI.  By default it will use a dedicated TemporaryQueue for each consumer.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("direct:start")
    .to("sjms:queue:bar?exchangePattern=InOut");
</pre>
</div></div>

<p>You can specify a <tt>namedReplyTo</tt> though which can provide a better
monitor point.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("direct:start")
    .to("sjms:queue:bar?exchangePattern=InOut&amp;namedReplyTo=my.reply.to.queue");
</pre>
</div></div>

<h3><a name="SJMS-ConsumersConfigurationOptions"></a>Consumers Configuration
Options</h3>

<p>The SjmsConsumer Endpoint supports the following properties:</p>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>acknowledgementMode</tt> </td>
<td class='confluenceTd'> <tt>AUTO_ACKNOWLEDGE</tt> </td>
<td class='confluenceTd'> The JMS acknowledgement name, which is one of: <tt>TRANSACTED</tt>,
<tt>AUTO_ACKNOWLEDGE</tt> or <tt>DUPS_OK_ACKNOWLEDGE</tt>. <tt>CLIENT_ACKNOWLEDGE</tt>
is not supported at this time. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>consumerCount</tt> </td>
<td class='confluenceTd'> <tt>1</tt> </td>
<td class='confluenceTd'> Defines the number of <a href="http://docs.oracle.com/javaee/5/api/javax/jms/MessageListener.html"
class="external-link" rel="nofollow">MessageListener</a> instances. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>durableSubscriptionId</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Required for a durable subscriptions. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>exchangePattern</tt> </td>
<td class='confluenceTd'> <tt>InOnly</tt> </td>
<td class='confluenceTd'> Sets the Consumers message exchange pattern. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>messageSelector</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Sets the message selector. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>synchronous</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> Sets whether the Endpoint will use synchronous or asynchronous
processing. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>transacted</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> If the endpoint should use a JMS Session transaction. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>transactionBatchCount</tt> </td>
<td class='confluenceTd'> <tt>1</tt> </td>
<td class='confluenceTd'> The number of exchanges to process before committing a local
JMS transaction.  The <tt>transacted</tt> property must also be set to true or
this property will be ignored. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>transactionBatchTimeout</tt> </td>
<td class='confluenceTd'> <tt>5000</tt> </td>
<td class='confluenceTd'> The amount of time a the transaction will stay open between
messages before committing what has already been consumed.  Minimum value is 1000ms. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ttl</tt> </td>
<td class='confluenceTd'> <tt>&#45;1</tt> </td>
<td class='confluenceTd'> Disabled by default.  Sets the Message time to live header.
</td>
</tr>
</tbody></table>
</div>
</div>

<h3><a name="SJMS-ConsumerUsage"></a>Consumer Usage</h3>

<h4><a name="SJMS-InOnlyConsumer%28Default%29"></a>InOnly Consumer - (Default)</h4>

<p>The InOnly Consumer is the default Exchange behavior of the SJMS Consumer Endpoint.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("sjms:queue:bar")
    .to("mock:result");
</pre>
</div></div>

<h4><a name="SJMS-InOutConsumer"></a>InOut Consumer</h4>

<p>To enable InOut behavior append the <tt>exchangePattern</tt> attribute
to the URI.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("sjms:queue:in.out.test?exchangePattern=InOut")
    .transform(constant("Bye Camel"));
</pre>
</div></div>

<h3><a name="SJMS-AdvancedUsageNotes"></a>Advanced Usage Notes</h3>

<h4><a name="SJMS-PlugableConnectionResourceManagement"></a>Plugable Connection
Resource Management <a name="SJMS-connectionresource"></a></h4>

<p>SJMS provides JMS <a href="http://docs.oracle.com/javaee/5/api/javax/jms/Connection.html"
class="external-link" rel="nofollow">Connection</a> resource management through built-in
connection pooling. This eliminates the need to depend on third party API pooling logic. However
there may be times that you are required to use an external Connection resource manager such
as those provided by J2EE or OSGi containers. For this SJMS provides an interface that can
be used to override the internal SJMS Connection pooling capabilities. This is accomplished
through the <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/jms/ConnectionResource.java"
class="external-link" rel="nofollow">ConnectionResource</a> interface. </p>

<p>The <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/jms/ConnectionResource.java"
class="external-link" rel="nofollow">ConnectionResource</a> provides methods for
borrowing and returning Connections as needed is the contract used to provide <a href="http://docs.oracle.com/javaee/5/api/javax/jms/Connection.html"
class="external-link" rel="nofollow">Connection</a> pools to the SJMS component.
A user should use when it is necessary to integrate SJMS with an external connection pooling
manager.</p>

<p>It is recommended though that for standard <a href="http://docs.oracle.com/javaee/5/api/javax/jms/ConnectionFactory.html"
class="external-link" rel="nofollow">ConnectionFactory</a> providers you use the
<a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/test/java/org/apache/camel/component/sjms/it/ConnectionResourceIT.java"
class="external-link" rel="nofollow">ConnectionFactoryResource</a> implementation
that is provided with SJMS as-is or extend as it is optimized for this component.</p>

<p>Below is an example of using the pluggable ConnectionResource with the ActiveMQ PooledConnectionFactory:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
public class AMQConnectionResource implements ConnectionResource {
    private PooledConnectionFactory pcf;

    public AMQConnectionResource(String connectString, int maxConnections) {
        super();
        pcf = new PooledConnectionFactory(connectString);
        pcf.setMaxConnections(maxConnections);
        pcf.start();
    }

    public void stop() {
        pcf.stop();
    }

    @Override
    public Connection borrowConnection() throws Exception {
        Connection answer = pcf.createConnection();
        answer.start();
        return answer;
    }

    @Override
    public Connection borrowConnection(long timeout) throws Exception {
        // SNIPPED...
    }

    @Override
    public void returnConnection(Connection connection) throws Exception {
        // Do nothing since there isn't a way to return a Connection
        // to the instance of PooledConnectionFactory
        log.info("Connection returned");
    }
}
</pre>
</div></div>

<p>Then pass in the ConnectionResource to the SjmsComponent:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
CamelContext camelContext = new DefaultCamelContext();
AMQConnectionResource pool = new AMQConnectionResource("tcp://localhost:33333", 1);
SjmsComponent component = new SjmsComponent();
component.setConnectionResource(pool);
camelContext.addComponent("sjms", component);
</pre>
</div></div>

<p>To see the full example of its usage please refer to the <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/test/java/org/apache/camel/component/sjms/it/ConnectionResourceIT.java"
class="external-link" rel="nofollow">ConnectionResourceIT</a>.</p>

<h4><a name="SJMS-Session%2CConsumer%2C%26ProducerPooling%26CachingManagement"></a>Session,
Consumer, &amp; Producer Pooling &amp; Caching Management</h4>

<p>Coming soon ...</p>

<h4><a name="SJMS-BatchMessageSupport"></a>Batch Message Support</h4>

<p>The SjmsProducer supports publishing a collection of messages by creating an Exchange
that encapsulates a List. This SjmsProducer will take then iterate through the contents of
the List and publish each message individually.</p>

<p>If when producing a batch of messages there is the need to set headers that are unique
to each message you can use the SJMS <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/BatchMessage.java"
class="external-link" rel="nofollow">BatchMessage</a> class. When the SjmsProducer
encounters a BatchMessage List it will iterate each BatchMessage and publish the included
payload and headers.</p>

<p>Below is an example of using the BatchMessage class.  First we create a List of BatchMessages:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
List&lt;BatchMessage&lt;String&gt;&gt; messages = new ArrayList&lt;BatchMessage&lt;String&gt;&gt;();
for (int i = 1; i &lt;= messageCount; i++) {
    String body = "Hello World " + i;
    BatchMessage&lt;String&gt; message = new BatchMessage&lt;String&gt;(body,
null);
    messages.add(message);
}
</pre>
</div></div>

<p>Then publish the List:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
template.sendBody("sjms:queue:batch.queue", messages);
</pre>
</div></div>

<h4><a name="SJMS-CustomizableTransactionCommitStrategies%28LocalJMSTransactionsonly%29"></a>Customizable
Transaction Commit Strategies (Local JMS Transactions only)</h4>

<p>SJMS provides a developer the means to create a custom and plugable transaction strategy
through the use of the <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/TransactionCommitStrategy.java"
class="external-link" rel="nofollow">TransactionCommitStrategy</a> interface. This
allows a user to define a unique set of circumstances that the <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/tx/SessionTransactionSynchronization.java"
class="external-link" rel="nofollow">SessionTransactionSynchronization</a> will use
to determine when to commit the Session. An example of its use is the <a href="https://svn.apache.org/repos/asf/camel/trunk/components/camel-sjms/src/main/java/org/apache/camel/component/sjms/tx/BatchTransactionCommitStrategy.java"
class="external-link" rel="nofollow">BatchTransactionCommitStrategy</a> which is
detailed further in the next section.</p>

<h4><a name="SJMS-TransactedBatchConsumers%26Producers"></a>Transacted Batch
Consumers &amp; Producers</h4>

<p>The SjmsComponent has been designed to support the batching of local JMS transactions
on both the Producer and Consumer endpoints. How they are handled on each is very different
though.</p>

<p>The SjmsConsumer endpoint is a straitforward implementation that will process X messages
before committing them with the associated Session.  To enable batched transaction on the
consumer first enable transactions by setting the <tt>transacted</tt> parameter
to true and then adding the <tt>transactionBatchCount</tt> and setting it to any
value that is greater than 0. For example the following configuration will commit the Session
every 10 messages:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:queue:transacted.batch.consumer?transacted=true&amp;transactionBatchCount=10
</pre>
</div></div>

<p>If an exception occurs during the processing of a batch on the consumer endpoint,
the Session rollback is invoked causing the messages to be redelivered to the next available
consumer. The counter is also reset to 0 for the BatchTransactionCommitStrategy for the associated
Session as well. It is the responsibility of the user to ensure they put hooks in their processors
of batch messages to watch for messages with the JMSRedelivered header set to true. This is
the indicator that messages were rolled back at some point and that a verification of a successful
processing should occur.</p>

<p>A transacted batch consumer also carries with it an instance of an internal timer
that waits a default amount of time (5000ms) between messages before committing the open transactions
on the Session. The default value of 5000ms (minimum of 1000ms) should be adequate for most
use-cases but if further tuning is necessary simply set the <tt>transactionBatchTimeout</tt>
parameter.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
sjms:queue:transacted.batch.consumer?transacted=true&amp;transactionBatchCount=10&amp;transactionBatchTimeout=2000
</pre>
</div></div>

<p>The minimal value that will be accepted is 1000ms as the amount of context switching
may cause unnecessary performance impacts without gaining benefit.</p>

<p>The producer endpoint is handled much differently though. With the producer after
each message is delivered to its destination the Exchange is closed and there is no longer
a reference to that message. To make a available all the messages available for redelivery
you simply enable transactions on a Producer Endpoint that is publishing BatchMessages. The
transaction will commit at the conclusion of the exchange which includes all messages in the
batch list.  Nothing additional need be configured. For example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
List&lt;BatchMessage&lt;String&gt;&gt; messages = new ArrayList&lt;BatchMessage&lt;String&gt;&gt;();
for (int i = 1; i &lt;= messageCount; i++) {
    String body = "Hello World " + i;
    BatchMessage&lt;String&gt; message = new BatchMessage&lt;String&gt;(body,
null);
    messages.add(message);
}
</pre>
</div></div>

<p>Now publish the List with transactions enabled:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
template.sendBody("sjms:queue:batch.queue?transacted=true", messages);
</pre>
</div></div>

<h3><a name="SJMS-AdditionalNotes"></a>Additional Notes</h3>

<h4><a name="SJMS-MessageHeaderFormat"></a>Message Header Format</h4>

<p>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.</p>

<p>For the exchange.in.header the following rules apply for the header keys:</p>

<p>Keys starting with JMS or JMSX are reserved.<br/>
exchange.in.headers keys must be literals and all be valid Java identifiers (do not use dots
in the key name).<br/>
Camel replaces dots &amp; hyphens and the reverse when when consuming JMS messages:</p>
<ul>
	<li>is replaced by <em>DOT</em> and the reverse replacement when Camel
consumes the message.</li>
	<li>is replaced by <em>HYPHEN</em> and the reverse replacement when Camel
consumes the message.<br/>
See also the option jmsKeyFormatStrategy, which allows use of your own custom strategy for
formatting keys.</li>
</ul>


<p>For the exchange.in.header, the following rules apply for the header values:</p>

<h4><a name="SJMS-MessageContent"></a>Message Content</h4>

<p>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.</p>

<h4><a name="SJMS-Clustering"></a>Clustering</h4>

<p>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.</p>

<p>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.</p>

<h3><a name="SJMS-TransactionSupport"></a>Transaction Support <a name="SJMS-transactions"></a></h3>

<p>SJMS currently only supports the use of internal JMS Transactions. There is no support
for the Camel Transaction Processor or the Java Transaction API (JTA).</p>

<h4><a name="SJMS-DoesSpringlessMeanICan%27tUseSpring%3F"></a>Does Springless
Mean I Can't Use Spring?</h4>

<p>Not at all.  Below is an example of the SJMS component using the Spring DSL:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;route
    id="inout.named.reply.to.producer.route"&gt;
    &lt;from
        uri="direct:invoke.named.reply.to.queue" /&gt;
    &lt;to
        uri="sjms:queue:named.reply.to.queue?namedReplyTo=my.response.queue&amp;amp;exchangePattern=InOut"
/&gt;
&lt;/route&gt;
</pre>
</div></div>

<p>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.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=CAMEL">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/SJMS">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=29688695&revisedVersion=30&originalVersion=29">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/SJMS?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message