You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by bu...@apache.org on 2016/08/31 16:22:14 UTC
svn commit: r996357 - in /websites/production/activemq/content:
cache/main.pageCache stomp.html
Author: buildbot
Date: Wed Aug 31 16:22:13 2016
New Revision: 996357
Log:
Production update by buildbot for activemq
Modified:
websites/production/activemq/content/cache/main.pageCache
websites/production/activemq/content/stomp.html
Modified: websites/production/activemq/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/activemq/content/stomp.html
==============================================================================
--- websites/production/activemq/content/stomp.html (original)
+++ websites/production/activemq/content/stomp.html Wed Aug 31 16:22:13 2016
@@ -103,7 +103,7 @@
<transportConnector name="stomp" uri="stomp://localhost:61613?transport.hbGracePeriodMultiplier=1.5"/>
</transportConnectors>
</pre>
-</div></div><p>This multiplier is used to calculate the effective read heart-beat timeout the broker will enforce for each client's connection. The multiplier is applied to the read-timeout interval the client specifies in its <strong><code>CONNECT</code></strong> frame:</p><p><code>  <strong><client specified read heart-beat interval> * <grace periodmultiplier> == <broker enforced read heart-beat timeout interval></strong></code></p><p>For backward compatibility, if the grace period multiplier is not configured the default enforcement mode remains strict, e.g., <strong><code>transport.hbGracePeriodMultiplier=1.0</code></strong>. Attempts to configure the grace period multiplier to a value less than, or equal to 1.0 will be silently ignored.</p><p>STOMP clients that wish to be tolerant of late arriving heart-beats from the broker must implement their own solution for doing so.</p><ul><li>Please check the <a shape="rect" class="external-link" href="ht
tp://stomp.github.io/stomp-specification-1.2.html#Heart-beating" rel="nofollow">STOMP specification</a> for the details on heart-beating</li><li>The JIRA that implemented this: <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/AMQ-4674">ActiveMQ 5.x does not support the notion of a grace-period for heart beats as supported by the STOMP protocol</a></li></ul><h3 id="Stomp-WorkingwithDestinationswithStomp">Working with Destinations with Stomp</h3><p>Note that the prefix in stomp <strong><code>/queue/</code></strong> or <strong><code>/topic/</code></strong> is removed from the string before passing it to ActiveMQ as a JMS destination. Also note that the default separator in MOM systems is <strong><code>.</code></strong> (dot). Whilst <strong><code>FOO.BAR</code></strong> is the normal syntax to identify a queue type destination the Stomp equivalent is <strong><code>/queue/FOO.BAR</code></strong></p><div class="confluence-information-macro confl
uence-information-macro-warning"><p class="title">Be careful about starting destinations with /</p><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>If in Stomp world you use <strong><code>/queue/foo/bar</code></strong> then in a JMS world the queue would be called <strong><code>foo/bar</code></strong> not <strong><code>/foo/bar</code></strong>.</p></div></div><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Persistent Messaging in STOMP</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">STOMP messages are non-persistent by default. To use persistent messaging add the following STOMP header to all <strong><code>SEND</code></strong> requests: <strong><code>persistent:true</code></strong>. This default is the opposite of that for
JMS messages.</div></div><h3 id="Stomp-WorkingwithJMSText/BytesMessagesandStomp">Working with JMS Text/Bytes Messages and Stomp</h3><p>Stomp is a very simple protocol - that's part of the beauty of it! As such, it does not have knowledge of JMS messages such as <strong><code>TextMessage</code></strong>'s or <strong><code>BytesMessage</code></strong>'s. The protocol does however support a <strong><code>content-length</code></strong> header. To provide more robust interaction between STOMP and JMS clients, ActiveMQ keys off of the inclusion of this header to determine what message type to create when sending from Stomp to JMS. The logic is simple:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Inclusion of content-length header</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Resulting Message</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>yes</p></td><td colspan="1" r
owspan="1" class="confluenceTd"><p><strong><code>BytesMessage</code></strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>no</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><code>TextMessage</code></strong></p></td></tr></tbody></table></div><p>This same logic can be followed when going from JMS to Stomp, as well. A Stomp client could be written to key off of the inclusion of the content-length header to determine what type of message structure to provide to the user.</p><h3 id="Stomp-Messagetransformations">Message transformations</h3><p>The <strong><code>transformation</code></strong> message header on <strong><code>SEND</code></strong> and <strong><code>SUBSCRIBE</code></strong> messages could be used to instruct ActiveMQ to transform messages from text to the format of your desire. Currently, ActiveMQ comes with a transformer that can transform XML/JSON text to Java objects, but you can add your own transformers as well.</p><p>Here's
a quick example of how to use built-in transformer (taken from test cases)</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This multiplier is used to calculate the effective read heart-beat timeout the broker will enforce for each client's connection. The multiplier is applied to the read-timeout interval the client specifies in its <strong><code>CONNECT</code></strong> frame:</p><p><code>  <strong><client specified read heart-beat interval> * <grace periodmultiplier> == <broker enforced read heart-beat timeout interval></strong></code></p><p>For backward compatibility, if the grace period multiplier is not configured the default enforcement mode remains strict, e.g., <strong><code>transport.hbGracePeriodMultiplier=1.0</code></strong>. Attempts to configure the grace period multiplier to a value less than, or equal to 1.0 will be silently ignored.</p><p>STOMP clients that wish to be tolerant of late arriving heart-beats from the broker must implement their own solution for doing so.</p><ul><li><p>Please check the <a shape="rect" class="external-link" href=
"http://stomp.github.io/stomp-specification-1.2.html#Heart-beating" rel="nofollow">STOMP specification</a> for the details on heart-beating</p></li><li><p>The JIRA that implemented this: <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/AMQ-4674">ActiveMQ 5.x does not support the notion of a grace-period for heart beats as supported by the STOMP protocol</a></p></li></ul><h3 id="Stomp-WorkingwithDestinationswithStomp">Working with Destinations with Stomp</h3><p>Note that the prefix in stomp <strong><code>/queue/</code></strong> or <strong><code>/topic/</code></strong> is removed from the string before passing it to ActiveMQ as a JMS destination. Also note that the default separator in MOM systems is <strong><code>.</code></strong> (dot). Whilst <strong><code>FOO.BAR</code></strong> is the normal syntax to identify a queue type destination the Stomp equivalent is <strong><code>/queue/FOO.BAR</code></strong></p><div class="confluence-informati
on-macro confluence-information-macro-warning"><p class="title">Be careful about starting destinations with /</p><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>If in Stomp world you use <strong><code>/queue/foo/bar</code></strong> then in a JMS world the queue would be called <strong><code>foo/bar</code></strong> not <strong><code>/foo/bar</code></strong>.</p></div></div><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Persistent Messaging in STOMP</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">STOMP messages are non-persistent by default. To use persistent messaging add the following STOMP header to all <strong><code>SEND</code></strong> requests: <strong><code>persistent:true</code></strong>. This default is the opposi
te of that for JMS messages.</div></div><h3 id="Stomp-WorkingwithJMSText/BytesMessagesandStomp">Working with JMS Text/Bytes Messages and Stomp</h3><p>Stomp is a very simple protocol - that's part of the beauty of it! As such, it does not have knowledge of JMS messages such as <strong><code>TextMessage</code></strong>'s or <strong><code>BytesMessage</code></strong>'s. The protocol does however support a <strong><code>content-length</code></strong> header. To provide more robust interaction between STOMP and JMS clients, ActiveMQ keys off of the inclusion of this header to determine what message type to create when sending from Stomp to JMS. The logic is simple:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Inclusion of content-length header</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Resulting Message</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>yes</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong><code>BytesMessage</code></strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>no</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><code>TextMessage</code></strong></p></td></tr></tbody></table></div><p>This same logic can be followed when going from JMS to Stomp, as well. A Stomp client could be written to key off of the inclusion of the content-length header to determine what type of message structure to provide to the user.</p><h3 id="Stomp-Messagetransformations">Message transformations</h3><p>The <strong><code>transformation</code></strong> message header on <strong><code>SEND</code></strong> and <strong><code>SUBSCRIBE</code></strong> messages could be used to instruct ActiveMQ to transform messages from text to the format of your desire. Currently, ActiveMQ comes with a transformer that can transform XML/JSON text to Java objects, but you can add your own transformers as well.
</p><p>Here's a quick example of how to use built-in transformer (taken from test cases)</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> private String xmlObject = "<pojo>\n"
+ " <name>Dejan</name>\n"
+ " <city>Belgrade</city>\n"
@@ -132,7 +132,7 @@
stompConnection.sendFrame(frame);
}
</pre>
-</div></div><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Dependencies</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>ActiveMQ uses <a shape="rect" class="external-link" href="http://xstream.codehaus.org" rel="nofollow">XStream</a> for its transformation needs. Since it's the optional dependency you have to add it to broker's classpath by putting the appropriate JAR into the <strong><code>lib/</code></strong> folder. Additionally, if you plan to use JSON transformations you have to add <a shape="rect" class="external-link" href="http://jettison.codehaus.org/" rel="nofollow">Jettison</a> JSON parser to the classpath.</p></div></div><p>In order to create your own transformer, you have to do the following:</p><ol><li>Build your transformer by implementing a <a shape="rect" class="external-link" href="http://activemq.apache.org/mave
n/activemq-core/apidocs/org/apache/activemq/transport/stomp/FrameTranslator.html">FrameTranslator</a> interface</li><li>Associate it with the appropriate header value by creating a file named as a value you want to use in the <strong><code>META-INF/services/org/apache/activemq/transport/frametranslator/</code></strong> folder of your JAR which will contain the value <strong><code>class=<em>fully qualified classname of your transformer</em></code></strong></li></ol><p>For example the built-in transformer contains the following value</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Dependencies</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>ActiveMQ uses <a shape="rect" class="external-link" href="http://xstream.codehaus.org" rel="nofollow">XStream</a> for its transformation needs. Since it's the optional dependency you have to add it to broker's classpath by putting the appropriate JAR into the <strong><code>lib/</code></strong> folder. Additionally, if you plan to use JSON transformations you have to add <a shape="rect" class="external-link" href="http://jettison.codehaus.org/" rel="nofollow">Jettison</a> JSON parser to the classpath.</p></div></div><p>In order to create your own transformer, you have to do the following:</p><ol><li><p>Build your transformer by implementing a <a shape="rect" class="external-link" href="http://activemq.apache.org/m
aven/activemq-core/apidocs/org/apache/activemq/transport/stomp/FrameTranslator.html">FrameTranslator</a> interface</p></li><li><p>Associate it with the appropriate header value by creating a file named as a value you want to use in the <strong><code>META-INF/services/org/apache/activemq/transport/frametranslator/</code></strong> folder of your JAR which will contain the value <strong><code>class=<em>fully qualified classname of your transformer</em></code></strong></p></li></ol><p>For example the built-in transformer contains the following value</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">class=org.apache.activemq.transport.stomp.XStreamFrameTranslator</pre>
</div></div><p>in the <strong><code>META-INF/services/org/apache/activemq/transport/frametranslator/jms-xml</code></strong> file.</p><h3 id="Stomp-Debugging"><span style="line-height: 1.5625;">Debugging</span></h3><p>In case you want to debug Stomp communication between broker and clients you should configure the Stomp connector with the <strong><code>trace</code></strong> parameter, like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><transportConnectors>