svn commit: r994391 [3/3] - in /websites/production/camel/content: book-component-appendix.html book-in-one-page.html cache/main.pageCache jms.html

Wed, 03 Aug 2016 12:19:30 -0700 

Modified: websites/production/camel/content/jms.html
==============================================================================
--- websites/production/camel/content/jms.html (original)
+++ websites/production/camel/content/jms.html Wed Aug  3 19:18:54 2016
@@ -123,7 +123,7 @@
 <script class="brush: text; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[2008-07-09 06:43:04,046 [main           ] 
DEBUG JmsBinding
   - Ignoring non primitive header: order of class: 
org.apache.camel.component.jms.issues.DummyOrder with value: 
DummyOrder{orderId=333, itemId=4444, quantity=2}
 ]]></script>
-</div></div><h3 id="JMS-Messageformatwhenreceiving">Message format when 
receiving</h3><p>Camel adds the following properties to the 
<code>Exchange</code> when it receives a message:</p><div 
class="confluenceTableSmall"><div class="table-wrap"><table 
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Property</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>org.apache.camel.jms.replyDestination</code></p></td><td
 colspan="1" rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The reply 
destination.</p></td></tr></tbody></table></div></div><p>Camel adds the 
following JMS properties to the In message headers when it receives a JMS 
message:</p><div class="confluenceTableSmall"><div class="table-wrap"><table 
class=
 "confluenceTable"><tbody><tr><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Header</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>JMSCorrelationID</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS correlation 
ID.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSDeliveryMode</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS delivery mode.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSDestination</code></p></td><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p
 >The JMS destination.</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSExpiration</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>The JMS expiration.</p></td></tr><tr><td 
 >colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSMessageID</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
 >colspan="1" rowspan="1" class="confluenceTd"><p>The JMS unique message 
 >ID.</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSPriority</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>The JMS priority (with 0 as the lowest 
 >priority and 9 as the highest).</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSRedelivered</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>
 <code>boolean</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>Is the JMS message redelivered.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSReplyTo</code></p></td><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS reply-to 
destination.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSTimestamp</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS timestamp.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSType</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS type.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSXGroupID</code></p></td><td cols
 pan="1" rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS group 
ID.</p></td></tr></tbody></table></div></div><p>As all the above information is 
standard JMS you can check the <a shape="rect" class="external-link" 
href="http://java.sun.com/javaee/5/docs/api/javax/jms/Message.html"; 
rel="nofollow">JMS documentation</a> for further details.</p><h3 
id="JMS-AboutusingCameltosendandreceivemessagesandJMSReplyTo">About using Camel 
to send and receive messages and JMSReplyTo</h3><p>The JMS component is complex 
and you have to pay close attention to how it works in some cases. So this is a 
short summary of some of the areas/pitfalls to look for.</p><p>When Camel sends 
a message using its <code>JMSProducer</code> it checks the following 
conditions:</p><ul class="alternate"><li><p>The message exchange pattern 
(MEP)</p></li><li><p>Whether a <strong><code>JMSReplyTo</code></strong> was set 
in the endpoint or in the message h
 eaders</p></li><li><p>Whether any of the following options have been set on 
the JMS endpoint: 
<strong><code>disableReplyTo</code>,&#160;<code>preserveMessageQos</code></strong>
 or <strong><code>explicitQosEnabled</code>.</strong></p></li></ul><p>All this 
can be a tad complex to understand and configure to support your use 
case.</p><h4 id="JMS-JmsProducer">JmsProducer</h4><p>The 
<code>JmsProducer</code> behaves as follows, depending on 
configuration:</p><div class="confluenceTableSmall"><div 
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" 
rowspan="1" class="confluenceTh"><p>Exchange Pattern</p></th><th colspan="1" 
rowspan="1" class="confluenceTh"><p>Other options</p></th><th colspan="1" 
rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td 
colspan="1" rowspan="1" class="confluenceTd"><p><code>InOut</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p><code>-</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>Ca
 mel will expect a reply, set a temporary <code>JMSReplyTo</code>, and after 
sending the message, it will start to listen for the reply message on the 
temporary queue.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>InOut</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSReplyTo</code> is set</p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>Camel will expect a reply and, after 
sending the message, it will start to listen for the reply message on the 
specified <code>JMSReplyTo</code> queue.</p></td></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>-</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>Camel will send the message and 
<strong>not</strong> expect a reply.</p></td></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd">
 <p><code>JMSReplyTo</code> is set</p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>By default, Camel discards the <code>JMSReplyTo</code> 
destination and clears the <code>JMSReplyTo</code> header before sending the 
message. Camel then sends the message and does <strong>not</strong> expect a 
reply. Camel logs this in the log at <code>WARN</code> level (changed to 
<code>DEBUG</code> level from <strong>Camel 2.6</strong> onward). You can use 
<code>preserveMessageQuo=true</code> to instruct Camel to keep the 
<code>JMSReplyTo</code>.</p><p>In all situations the <code>JmsProducer</code> 
does <strong>not</strong> expect any reply and thus continue after sending the 
message.</p></td></tr></tbody></table></div></div><h4 
id="JMS-JmsConsumer">JmsConsumer</h4><p>The <code>JmsConsumer</code> behaves as 
follows, depending on configuration:</p><div class="confluenceTableSmall"><div 
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" 
rowspan="1" class="confluence
 Th"><p>Exchange Pattern</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Other options</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOut</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>-</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>Camel will send the reply back to the 
<code>JMSReplyTo</code> queue.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>-</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>Camel will not send a reply back, as the pattern is 
<em>InOnly</em>.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>-</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>disableReplyTo=true</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>This 
 option suppresses replies.</p></td></tr></tbody></table></div></div><p>So pay 
attention to the message exchange pattern set on your exchanges.</p><p>If you 
send a message to a JMS destination in the middle of your route you can specify 
the exchange pattern to use, see more at <a shape="rect" 
href="request-reply.html">Request Reply</a>. This is useful if you want to send 
an <code>InOnly</code> message to a JMS topic:</p><div class="code panel pdl" 
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="JMS-Messageformatwhenreceiving">Message format when 
receiving</h3><p>Camel adds the following properties to the 
<code>Exchange</code> when it receives a message:</p><div 
class="confluenceTableSmall"><div class="table-wrap"><table 
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Property</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>org.apache.camel.jms.replyDestination</code></p></td><td
 colspan="1" rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The reply 
destination.</p></td></tr></tbody></table></div></div><p>Camel adds the 
following JMS properties to the In message headers when it receives a JMS 
message:</p><div class="confluenceTableSmall"><div class="table-wrap"><table 
class=
 "confluenceTable"><tbody><tr><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Header</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>JMSCorrelationID</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS correlation 
ID.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSDeliveryMode</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS delivery mode.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSDestination</code></p></td><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p
 >The JMS destination.</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSExpiration</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>The JMS expiration.</p></td></tr><tr><td 
 >colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSMessageID</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
 >colspan="1" rowspan="1" class="confluenceTd"><p>The JMS unique message 
 >ID.</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSPriority</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>The JMS priority (with 0 as the lowest 
 >priority and 9 as the highest).</p></td></tr><tr><td colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>JMSRedelivered</code></p></td><td colspan="1" 
 >rowspan="1" class="confluenceTd"><p>
 <code>boolean</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>Is the JMS message redelivered.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSReplyTo</code></p></td><td colspan="1" 
rowspan="1" 
class="confluenceTd"><p><code>javax.jms.Destination</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS reply-to 
destination.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSTimestamp</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS timestamp.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSType</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>The JMS type.</p></td></tr><tr><td 
colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSXGroupID</code></p></td><td cols
 pan="1" rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>The JMS group 
ID.</p></td></tr></tbody></table></div></div><p>As all the above information is 
standard JMS you can check the <a shape="rect" class="external-link" 
href="http://java.sun.com/javaee/5/docs/api/javax/jms/Message.html"; 
rel="nofollow">JMS documentation</a> for further details.</p><h3 
id="JMS-AboutusingCameltosendandreceivemessagesandJMSReplyTo">About using Camel 
to send and receive messages and JMSReplyTo</h3><p>The JMS component is complex 
and you have to pay close attention to how it works in some cases. So this is a 
short summary of some of the areas/pitfalls to look for.</p><p>When Camel sends 
a message using its <code>JMSProducer</code> it checks the following 
conditions:</p><ul class="alternate"><li><p>The message <a shape="rect" 
class="external-link" 
href="http://camel.apache.org/exchange-pattern.html";>Exchange Pattern</a> 
(MEP)</p></li><li><p
 >Whether a <strong><code>JMSReplyTo</code></strong> was set in the endpoint or 
 >in the message headers</p></li><li><p>Whether any of the following options 
 >have been set on the JMS endpoint: 
 ><strong><code>disableReplyTo</code>,&#160;<code>preserveMessageQos</code></strong>
 > or <strong><code>explicitQosEnabled</code>.</strong></p></li></ul><p>All 
 >this can be a tad complex to understand and configure to support your use 
 >case.</p><h4 id="JMS-JmsProducer">JmsProducer</h4><p>The 
 ><code>JmsProducer</code> behaves as follows, depending on 
 >configuration:</p><div class="confluenceTableSmall"><div 
 >class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" 
 >rowspan="1" class="confluenceTh"><p>Exchange Pattern</p></th><th colspan="1" 
 >rowspan="1" class="confluenceTh"><p>Other options</p></th><th colspan="1" 
 >rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td 
 >colspan="1" rowspan="1" 
 >class="confluenceTd"><p><code>InOut</code></p></td><td colspan="1" 
 >rowspan="1" class=
 "confluenceTd"><p><code>-</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>Camel will expect a reply, set a temporary 
<code>JMSReplyTo</code>, and after sending the message, it will start to listen 
for the reply message on the temporary queue.</p></td></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOut</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>JMSReplyTo</code> is set</p></td><td 
colspan="1" rowspan="1" class="confluenceTd"><p>Camel will expect a reply and, 
after sending the message, it will start to listen for the reply message on the 
specified <code>JMSReplyTo</code> queue.</p></td></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>-</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>Camel will send the message and 
<strong>not</strong> expect a reply.</p></td></tr><tr><td colspan="1" 
rowspan="1" class=
 "confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>JMSReplyTo</code> is set</p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>By default, Camel discards the 
<code>JMSReplyTo</code> destination and clears the <code>JMSReplyTo</code> 
header before sending the message. Camel then sends the message and does 
<strong>not</strong> expect a reply. Camel logs this in the log at 
<code>WARN</code> level (changed to <code>DEBUG</code> level from <strong>Camel 
2.6</strong> onward). You can use <code>preserveMessageQuo=true</code> to 
instruct Camel to keep the <code>JMSReplyTo</code>.</p><p>In all situations the 
<code>JmsProducer</code> does <strong>not</strong> expect any reply and thus 
continue after sending the 
message.</p></td></tr></tbody></table></div></div><h4 
id="JMS-JmsConsumer">JmsConsumer</h4><p>The <code>JmsConsumer</code> behaves as 
follows, depending on configuration:</p><div class="confluenceTableSmall"><div 
class="tabl
 e-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Exchange Pattern</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Other options</p></th><th colspan="1" rowspan="1" 
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>InOut</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p><code>-</code></p></td><td colspan="1" 
rowspan="1" class="confluenceTd"><p>Camel will send the reply back to the 
<code>JMSReplyTo</code> queue.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>InOnly</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>-</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>Camel will not send a reply back, as the pattern is 
<em>InOnly</em>.</p></td></tr><tr><td colspan="1" rowspan="1" 
class="confluenceTd"><p><code>-</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p><co
 de>disableReplyTo=true</code></p></td><td colspan="1" rowspan="1" 
class="confluenceTd"><p>This option suppresses 
replies.</p></td></tr></tbody></table></div></div><p>So pay attention to the 
message exchange pattern set on your exchanges.</p><p>If you send a message to 
a JMS destination in the middle of your route you can specify the exchange 
pattern to use, see more at <a shape="rect" href="request-reply.html">Request 
Reply</a>. This is useful if you want to send an <code>InOnly</code> message to 
a JMS topic:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[from(&quot;activemq:queue:in&quot;)
    .to(&quot;bean:validateOrder&quot;)
    .to(ExchangePattern.InOnly, &quot;activemq:topic:order&quot;)
@@ -140,7 +140,7 @@
    exchange.getIn().setHeader(&quot;CamelJmsDestinationName&quot;, 
&quot;order:&quot; + id&quot;);
 }
 ]]></script>
-</div></div><p>Then Camel will read this header and use it as the destination 
instead of the one configured on the endpoint. So, in this example Camel sends 
the message to <code>activemq:queue:order:2</code>, assuming the 
<code>id</code> value was <code>2</code>.</p><p>If both the 
<code>CamelJmsDestination</code> and the <code>CamelJmsDestinationName</code> 
headers are set, <code>CamelJmsDestination</code> takes priority. Keep in mind 
that the JMS producer removes both <code>CamelJmsDestination</code> and 
<code>CamelJmsDestinationName</code> headers from the exchange and do not 
propagate them to the created JMS message<span class="entry">&#160;</span>in 
order to avoid the accidental loops in the routes (in scenarios when the 
message will be forwarded to the another JMS endpoint).</p><h3 
id="JMS-ConfiguringdifferentJMSproviders">Configuring different JMS 
providers</h3><p>You can configure your JMS provider in <a shape="rect" 
href="spring.html">Spring</a> XML as follows:</p><div class
 ="code panel pdl" style="border-width: 1px;"><div class="codeContent 
panelContent pdl">
+</div></div><p>Then Camel will read this header and use it as the destination 
instead of the one configured on the endpoint. So, in this example Camel sends 
the message to <code>activemq:queue:order:2</code>, assuming the 
<code>id</code> value was <code>2</code>.</p><p>If both the 
<code>CamelJmsDestination</code> and the <code>CamelJmsDestinationName</code> 
headers are set <code>CamelJmsDestination</code> will take priority. Note that 
the JMS producer removes both <code>CamelJmsDestination</code> and 
<code>CamelJmsDestinationName</code> headers from the exchange and does not 
propagate them to the created JMS message. This prevents accidental routing 
loops in scenarios where a message is forwarded to another JMS endpoint.</p><h3 
id="JMS-ConfiguringdifferentJMSproviders">Configuring different JMS 
providers</h3><p>A JMS provider can be configured in <a shape="rect" 
href="spring.html">Spring</a> XML as follows:</p><div class="code panel pdl" 
style="border-width: 1px;"><div class="codeCo
 ntent panelContent pdl">
 <script class="brush: xml; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[
 &lt;camelContext id=&quot;camel&quot; 
xmlns=&quot;http://camel.apache.org/schema/spring&quot;&gt;
     &lt;jmxAgent id=&quot;agent&quot; disabled=&quot;true&quot;/&gt;
@@ -154,7 +154,7 @@
   &lt;/property&gt;
 &lt;/bean&gt;
 ]]></script>
-</div></div><p>&#160;</p><p>Basically, you can configure as many JMS component 
instances as you wish giving them each a <strong>unique name using 
the</strong>&#160;<code>id</code> <strong>attribute</strong>. The preceding 
example configures an activemq component. You could do the same to configure 
MQSeries, TibCo, BEA, Sonic and so on.</p><p>Once you have a named JMS 
component, you can then refer to endpoints within that component using URIs. 
For example for the component name, <code>activemq</code>, you can then refer 
to destinations using the URI format, 
<code>activemq:[queue:|topic:]destinationName</code>. You can use the same 
approach for all other JMS providers.</p><p>This works by the 
SpringCamelContext lazily fetching components from the spring context for the 
scheme name you use for <a shape="rect" href="endpoint.html">Endpoint</a> <a 
shape="rect" href="uris.html">URIs</a> and having the <a shape="rect" 
href="component.html">Component</a> resolve the endpoint URIs.</p><h4 id
 ="JMS-UsingJNDItofindtheConnectionFactory">Using JNDI to find the 
ConnectionFactory</h4><p>If you are using a J2EE container, you might need to 
look up JNDI to find the JMS <code>ConnectionFactory</code> rather than use the 
usual <code>&lt;bean&gt;</code> mechanism in Spring. You can do this using 
Spring's factory bean or the new Spring XML namespace. For example:</p><div 
class="code panel pdl" style="border-width: 1px;"><div class="codeContent 
panelContent pdl">
+</div></div><p>&#160;</p><p>An unlimited number of JMS component instance can 
be created provided each has a <strong>unique value for 
its&#160;</strong><code>id</code> <strong>attribute</strong>. The preceding 
example configures an activemq component. You could do the same to configure 
MQSeries, TibCo, BEA, Sonic etc.</p><p>Once named a JMS component can be 
referenced from an endpoint's URI. For example, given the component name 
<code>activemq</code> a URI can reference the component using the format 
<code>activemq:[queue:|topic:]destinationName</code>. The same approach applies 
to all JMS providers. This is achieved by the SpringCamelContext lazily 
fetching components from the spring context for the scheme name referenced in 
the <a shape="rect" href="endpoint.html">Endpoint</a> <a shape="rect" 
href="uris.html">URIs</a> then having the <a shape="rect" 
href="component.html">Component</a> resolve the endpoint URI itself.</p><h4 
id="JMS-UsingJNDItofindtheConnectionFactory">Using JNDI t
 o find the ConnectionFactory</h4><p>If you are using a J2EE container, you 
might need to look up JNDI to find the JMS <code>ConnectionFactory</code> 
rather than use the usual <code>&lt;bean&gt;</code> mechanism in Spring. You 
can do this using Spring's factory bean or the new Spring XML namespace. For 
example:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
 <script class="brush: xml; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[&lt;bean id=&quot;weblogic&quot; 
class=&quot;org.apache.camel.component.jms.JmsComponent&quot;&gt;
   &lt;property name=&quot;connectionFactory&quot; 
ref=&quot;myConnectionFactory&quot;/&gt;
 &lt;/bean&gt;
@@ -215,7 +215,7 @@ from(aaa)
   .setHeader(&quot;CamelJmsRequestTimeout&quot;, method(ServiceBean.class, 
&quot;whatIsTheTimeout&quot;))
   .to(&quot;jms:queue:foo?replyTo=bar&amp;requestTimeout=30s&quot;)
   .to(&quot;bean:processReply&quot;);]]></script>
-</div></div><p>When you do fire and forget (<code>InOut</code>) over <a 
shape="rect" href="jms.html">JMS</a> Camel will, by default, 
<strong>not</strong> set a time to live value on the message. The value can be 
configured using the <code>timeToLive</code> option. For example to indicate a 
5 sec., you set <code>timeToLive=5000</code>. The option 
<code>disableTimeToLive</code> can be used to force disabling the time to live, 
also for&#160;<code>InOnly</code> messaging. The <code>requestTimeout</code> 
option is not being used for&#160;<code>InOnly</code> messaging.</p><h3 
id="JMS-EnablingTransactedConsumption">Enabling Transacted 
Consumption</h3><p><span class="confluence-anchor-link" 
id="JMS-transactedConsumption"></span></p><p>A common requirement is to consume 
from a queue in a transaction and then process the message using the Camel 
route. To do this, just ensure that you set the following properties on the 
component/endpoint:</p><ul><li><pre>transacted = true</pre></li><li><p><co
 de>transactionManager =</code> <em>&lt;SomeTransactionManager&gt;</em> 
(typically the JmsTransactionManager)</p></li></ul><p>See the <a shape="rect" 
href="transactional-client.html">Transactional Client</a> EIP pattern for 
further details.</p><div class="confluence-information-macro 
confluence-information-macro-information"><p class="title">Transactions and 
[Request Reply] over JMS</p><span class="aui-icon aui-icon-small 
aui-iconfont-info confluence-information-macro-icon"></span><div 
class="confluence-information-macro-body"><p>When using <a shape="rect" 
href="request-reply.html">Request Reply</a> over JMS you cannot use a single 
transaction; JMS will not send any messages until a commit is performed, so the 
server side won't receive anything at all until the transaction commits. 
Therefore to use <a shape="rect" href="request-reply.html">Request Reply</a> 
you must commit a transaction after sending the request and then use a separate 
transaction for receiving the response.</p><p>To
  address this issue the JMS component uses different properties to specify 
transaction use for oneway messaging and request reply 
messaging:</p><ul><li><p>The <code>transacted</code> property applies 
<strong>only</strong> to the&#160;<code>InOnly</code> message <a shape="rect" 
href="exchange-pattern.html">Exchange Pattern</a> (MEP).</p></li><li><p>The 
<code>transactedInOut</code> property applies to the&#160;<code>InOut</code> 
(<a shape="rect" href="request-reply.html">Request Reply</a>) message <a 
shape="rect" href="exchange-pattern.html">Exchange Pattern</a> (MEP). If you 
want to use transactions with the&#160;<code>InOut</code> (<a shape="rect" 
href="request-reply.html">Request Reply</a>) message <a shape="rect" 
href="exchange-pattern.html">Exchange Pattern</a> (MEP), you 
<strong>must</strong> set 
<code>transactedInOut=true</code>.</p></li></ul></div></div><p><strong>Available
 as of Camel 2.10</strong></p><p>You can leverage the <a shape="rect" 
class="external-link" href="http://
 
static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.html#setSessionTransacted(boolean)"
 rel="nofollow">DMLC transacted session API</a> using the following properties 
on component/endpoint:</p><ul><li><p><code>transacted = 
true</code></p></li><li><p><code>lazyCreateTransactionManager = 
false</code></p></li></ul><p>The benefit of doing so is that 
the&#160;<code>cacheLevel</code> setting will be honored when using local 
transactions without a configured TransactionManager. When a TransactionManager 
is configured, no caching happens at DMLC level and its necessary to rely on a 
pooled connection factory. For more details about this kind of setup see <a 
shape="rect" class="external-link" 
href="http://tmielke.blogspot.com/2012/03/camel-jms-with-transactions-lessons.html";
 rel="nofollow">here</a> and <a shape="rect" class="external-link" 
href="http://forum.springsource.org/showthread.php?123631-JMS-DMLC-not-caching 
co
 
nnection-when-using-TX-despite-cacheLevel-CACHE_CONSUMER&amp;p=403530&amp;posted=1#post403530"
 rel="nofollow">here</a>.</p><h3 id="JMS-UsingJMSReplyToforlatereplies">Using 
JMSReplyTo for late replies</h3><p>When using Camel as a JMS listener, it sets 
an Exchange property with the value of the ReplyTo 
<strong><code>javax.jms.Destination</code></strong> object, having the key 
<code>ReplyTo</code>. You can obtain this <code>Destination</code> as 
follows:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
+</div></div><p>When you do fire and forget (<code>InOut</code>) over <a 
shape="rect" href="jms.html">JMS</a> Camel will, by default, 
<strong>not</strong> set a time to live value on the message. The value can be 
configured using the <code>timeToLive</code> option. For example to indicate a 
5 sec., you set <code>timeToLive=5000</code>. The option 
<code>disableTimeToLive</code> can be used to force disabling the time to live, 
also for&#160;<code>InOnly</code> messaging. The <code>requestTimeout</code> 
option is not being used for&#160;<code>InOnly</code> messaging.</p><h3 
id="JMS-EnablingTransactedConsumption">Enabling Transacted 
Consumption</h3><p><span class="confluence-anchor-link" 
id="JMS-transactedConsumption"></span></p><p>A common requirement is to consume 
from a queue in a transaction and then process the message using the Camel 
route. To do this, just ensure that you set the following properties on the 
component/endpoint:</p><ul><li><p><code>transacted = true</code></p></li><
 li><p><code>transactionManager =</code> 
<em>&lt;SomeTransactionManager&gt;</em> (typically the 
JmsTransactionManager)</p></li></ul><p>See the <a shape="rect" 
href="transactional-client.html">Transactional Client</a> EIP pattern for 
further details.</p><div class="confluence-information-macro 
confluence-information-macro-information"><p class="title">Transactions and 
[Request Reply] over JMS</p><span class="aui-icon aui-icon-small 
aui-iconfont-info confluence-information-macro-icon"></span><div 
class="confluence-information-macro-body"><p>When using <a shape="rect" 
href="request-reply.html">Request Reply</a> over JMS you cannot use a single 
transaction; JMS will not send any messages until a commit is performed, so the 
server side won't receive anything at all until the transaction commits. 
Therefore to use <a shape="rect" href="request-reply.html">Request Reply</a> 
you must commit a transaction after sending the request and then use a separate 
transaction for receiving the response.
 </p><p>To address this issue the JMS component uses different properties to 
specify transaction use for oneway messaging and request reply 
messaging:</p><ul><li><p>The <code>transacted</code> property applies 
<strong>only</strong> to the&#160;<code>InOnly</code> message <a shape="rect" 
href="exchange-pattern.html">Exchange Pattern</a> (MEP).</p></li><li><p>The 
<code>transactedInOut</code> property applies to the&#160;<code>InOut</code> 
(<a shape="rect" href="request-reply.html">Request Reply</a>) message <a 
shape="rect" href="exchange-pattern.html">Exchange Pattern</a> (MEP). If you 
want to use transactions with the&#160;<code>InOut</code> (<a shape="rect" 
href="request-reply.html">Request Reply</a>) message <a shape="rect" 
href="exchange-pattern.html">Exchange Pattern</a> (MEP), you 
<strong>must</strong> set 
<code>transactedInOut=true</code>.</p></li></ul></div></div><p><strong>Available
 as of Camel 2.10</strong></p><p>You can leverage the <a shape="rect" 
class="external-link" href
 
="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.html#setSessionTransacted(boolean)"
 rel="nofollow">DMLC transacted session API</a> using the following properties 
on component/endpoint:</p><ul><li><p><code>transacted = 
true</code></p></li><li><p><code>lazyCreateTransactionManager = 
false</code></p></li></ul><p>The benefit of doing so is that 
the&#160;<code>cacheLevel</code> setting will be honored when using local 
transactions without a configured TransactionManager. When a TransactionManager 
is configured, no caching happens at DMLC level and its necessary to rely on a 
pooled connection factory. For more details about this kind of setup see <a 
shape="rect" class="external-link" 
href="http://tmielke.blogspot.com/2012/03/camel-jms-with-transactions-lessons.html";
 rel="nofollow">here</a> and <a shape="rect" class="external-link" 
href="http://forum.springsource.org/showthread.php?123631-JMS-DMLC-not-c
 aching 
connection-when-using-TX-despite-cacheLevel-CACHE_CONSUMER&amp;p=403530&amp;posted=1#post403530"
 rel="nofollow">here</a>.</p><h3 id="JMS-UsingJMSReplyToforlatereplies">Using 
JMSReplyTo for late replies</h3><p>When using Camel as a JMS listener, it sets 
an Exchange property with the value of the ReplyTo 
<strong><code>javax.jms.Destination</code></strong> object, having the key 
<code>ReplyTo</code>. You can obtain this <code>Destination</code> as 
follows:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[Destination replyDestination = 
exchange.getIn().getHeader(JmsConstants.JMS_REPLY_DESTINATION, 
Destination.class);
 ]]></script>
 </div></div><p>And then later use it to send a reply using regular JMS or 
Camel.</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
@@ -224,7 +224,7 @@ JmsEndpoint endpoint = JmsEndpoint.newIn
 
 // Now that we have the endpoint we can use regular Camel API to send a 
message to it
 template.sendBody(endpoint, &quot;Here is the late reply.&quot;);]]></script>
-</div></div><p>A different solution to sending a reply is to provide the 
<code>replyDestination</code> object in the same Exchange property when 
sending. Camel will then pick up this property and use it for the real 
destination. The endpoint URI must include a dummy destination, however. For 
example:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
+</div></div><p>A different solution to sending a reply is to provide the 
<code>replyDestination</code> object in the same Exchange property when 
sending. Camel will then pick up this property and use it for the real 
destination. The endpoint URI must include a dummy destination, 
however.</p><p>For example:</p><div class="code panel pdl" style="border-width: 
1px;"><div class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[// we pretend to send it to some non existing 
dummy queue
 template.send(&quot;activemq:queue:dummy, new Processor() {
     public void process(Exchange exchange) throws Exception {
@@ -261,7 +261,7 @@ Object out = template.requestBody(&quot;
   &lt;/filter&gt;
 &lt;/route&gt;
 ]]></script>
-</div></div><h4 id="JMS-Othersamples">Other samples</h4><p>JMS appears in many 
of the examples for other components and EIP patterns, as well in this Camel 
documentation. So feel free to browse the documentation. If you have time, 
check out the this tutorial that uses JMS but focuses on how well Spring 
Remoting and Camel works together <a shape="rect" 
href="tutorial-jmsremoting.html">Tutorial-JmsRemoting</a>.</p><h4 
id="JMS-UsingJMSasaDeadLetterQueuestoringExchange">Using JMS as a Dead Letter 
Queue storing Exchange</h4><p>Normally, when using <a shape="rect" 
href="jms.html">JMS</a> as the transport, it only transfers the body and 
headers as the payload. If you want to use <a shape="rect" 
href="jms.html">JMS</a> with a <a shape="rect" 
href="dead-letter-channel.html">Dead Letter Channel</a>, using a JMS queue as 
the Dead Letter Queue, then normally the caused Exception is not stored in the 
JMS message. You can, however, use the <strong>transferExchange</strong> option 
on the JMS dead 
 letter queue to instruct Camel to store the entire <a shape="rect" 
href="exchange.html">Exchange</a> in the queue as a 
<strong><code>javax.jms.ObjectMessage</code></strong> that holds a 
<strong><code>org.apache.camel.impl.DefaultExchangeHolder</code></strong>. This 
allows you to consume from the Dead Letter Queue and retrieve the caused 
exception from the Exchange property with the key 
<code>Exchange.EXCEPTION_CAUGHT</code>. The demo below illustrates 
this:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
+</div></div><h4 id="JMS-Othersamples">Other samples</h4><p>JMS appears in many 
of the examples for other components and EIP patterns, as well in this Camel 
documentation. So feel free to browse the documentation. If you have time, 
check out the this tutorial that uses JMS but focuses on how well Spring 
Remoting and Camel works together <a shape="rect" 
href="tutorial-jmsremoting.html">Tutorial-JmsRemoting</a>.</p><h4 
id="JMS-UsingJMSasaDeadLetterQueuestoringExchange">Using JMS as a Dead Letter 
Queue storing Exchange</h4><p>Normally, when using <a shape="rect" 
href="jms.html">JMS</a> as the transport, it only transfers the body and 
headers as the payload. If you want to use <a shape="rect" 
href="jms.html">JMS</a> with a <a shape="rect" 
href="dead-letter-channel.html">Dead Letter Channel</a>, using a JMS queue as 
the Dead Letter Queue, then normally the caused Exception is not stored in the 
JMS message. You can, however, use the 
<strong><code>transferExchange</code></strong> option on 
 the JMS dead letter queue to instruct Camel to store the entire <a 
shape="rect" href="exchange.html">Exchange</a> in the queue as a 
<strong><code>javax.jms.ObjectMessage</code></strong> that holds a 
<strong><code>org.apache.camel.impl.DefaultExchangeHolder</code></strong>. This 
allows you to consume from the Dead Letter Queue and retrieve the caused 
exception from the Exchange property with the key 
<code>Exchange.EXCEPTION_CAUGHT</code>.</p><p>For example:</p><div class="code 
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[// setup error handler to use JMS as queue 
and store the entire Exchange
 
errorHandler(deadLetterChannel(&quot;jms:queue:dead?transferExchange=true&quot;));
 ]]></script>
@@ -292,12 +292,12 @@ from(&quot;seda:dead&quot;)
         exchange.getIn().setHeader(&quot;JMSReplyTo&quot;, &quot;bar&quot;);
     }
 });]]></script>
-</div></div><p><strong>Note</strong>: we use 
<code>preserveMessageQos=true</code> to instruct Camel to keep 
the&#160;<code>JMSReplyTo</code> header.</p><h3 
id="JMS-SettingJMSprovideroptionsonthedestination">Setting JMS provider options 
on the destination</h3><p>Some JMS providers, like IBM's WebSphere MQ need 
options to be set on the JMS destination. For example, you may need to specify 
the targetClient option. Since targetClient is a WebSphere MQ option and not a 
Camel URI option, you need to set that on the JMS destination name like 
so:</p><div class="code panel pdl" style="border-width: 1px;"><div 
class="codeContent panelContent pdl">
+</div></div><p><strong>Note</strong>: we use 
<strong><code>preserveMessageQos=true</code></strong> to instruct Camel to keep 
the&#160;<code>JMSReplyTo</code> header.</p><h3 
id="JMS-SettingJMSprovideroptionsonthedestination">Setting JMS provider options 
on the destination</h3><p>Some JMS providers, like IBM's WebSphere MQ need 
options to be set on the JMS destination. For example, you may need to specify 
the&#160;<strong><code>targetClient</code></strong> option. Since targetClient 
is a WebSphere MQ option and not a Camel URI option, you need to set that on 
the JMS destination name like so:</p><div class="code panel pdl" 
style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[...
 .setHeader(&quot;CamelJmsDestinationName&quot;, 
constant(&quot;queue:///MY_QUEUE?targetClient=1&quot;))
 .to(&quot;wmq:queue:MY_QUEUE?useMessageIDAsCorrelationID=true&quot;);
 ]]></script>
-</div></div><p>Some versions of WMQ won't accept this option on the 
destination name and you will get an exception 
like:</p><blockquote><p>com.ibm.msg.client.jms.DetailedJMSException: JMSCC0005: 
The specified value 'MY_QUEUE?targetClient=1' is not allowed for 
'XMSC_DESTINATION_NAME'</p></blockquote><p>A workaround is to use a custom 
DestinationResolver:</p><div class="code panel pdl" style="border-width: 
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Some versions of Websphere MQ do not accept this option on the 
destination name. The following exception is raised when this 
happens:</p><blockquote><p><strong><code>com.ibm.msg.client.jms.DetailedJMSException:
 JMSCC0005: The specified value 'MY_QUEUE?targetClient=1' is not allowed for 
'XMSC_DESTINATION_NAME'</code></strong></p></blockquote><p>A workaround is to 
use a custom DestinationResolver:</p><div class="code panel pdl" 
style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" 
type="syntaxhighlighter"><![CDATA[JmsComponent wmq = new 
JmsComponent(connectionFactory);
 
 wmq.setDestinationResolver(new DestinationResolver(){

Reply via email to