[hornetq-commits] JBoss hornetq SVN: r11480 - branches/Branch_2_2_EAP/docs/user-manual/en.
do-not-reply at jboss.org
do-not-reply at jboss.org
Thu Oct 6 15:51:39 EDT 2011
Author: clebert.suconic at jboss.com
Date: 2011-10-06 15:51:38 -0400 (Thu, 06 Oct 2011)
New Revision: 11480
Modified:
branches/Branch_2_2_EAP/docs/user-manual/en/configuring-transports.xml
branches/Branch_2_2_EAP/docs/user-manual/en/interoperability.xml
Log:
little adjustments to docs
Modified: branches/Branch_2_2_EAP/docs/user-manual/en/configuring-transports.xml
===================================================================
--- branches/Branch_2_2_EAP/docs/user-manual/en/configuring-transports.xml 2011-10-06 19:31:54 UTC (rev 11479)
+++ branches/Branch_2_2_EAP/docs/user-manual/en/configuring-transports.xml 2011-10-06 19:51:38 UTC (rev 11480)
@@ -16,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
%BOOK_ENTITIES;
@@ -295,6 +294,22 @@
parameter is <literal>-1</literal> which means use the value from <literal
>Runtime.getRuntime().availableProcessors()</literal> * 3.</para>
</listitem>
+ <listitem>
+ <para><literal>cluster-connection</literal>. If you define more than one cluster
+ connection, you may define what cluster connection will be used to notify
+ topologies. This will be very useful when you are playing with multiple
+ network interface cards (NIC) and need to isolate the cluster
+ definitions.</para>
+ <para>The default value is the first cluster connection defined at the main
+ configuration.</para>
+ </listitem>
+ <listitem>
+ <para><literal>stomp-consumer-credits</literal>. When consuming messages in stomp, the server will flow control the channel
+ as messages are acknowledged. The default value is 10K. The server won't send more messages than 10K bytes until you ack more messages.
+ </para>
+ <para>Notice that if you use auto-ack subscriptions on stomp, you have to consume as fast as you can on your client,
+ or you may flood the channels on Netty what will lead to OutOfMemory errors.</para>
+ </listitem>
</itemizedlist>
</section>
<section>
Modified: branches/Branch_2_2_EAP/docs/user-manual/en/interoperability.xml
===================================================================
--- branches/Branch_2_2_EAP/docs/user-manual/en/interoperability.xml 2011-10-06 19:31:54 UTC (rev 11479)
+++ branches/Branch_2_2_EAP/docs/user-manual/en/interoperability.xml 2011-10-06 19:51:38 UTC (rev 11480)
@@ -16,160 +16,174 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
%BOOK_ENTITIES;
]>
<chapter id="interoperability">
- <title>Interoperability</title>
- <section id="stomp">
- <title>Stomp</title>
- <para><ulink url="http://stomp.codehaus.org/">Stomp</ulink> is a text-orientated wire protocol that allows
- Stomp clients to communicate with Stomp Brokers.</para>
- <para><ulink url="http://stomp.codehaus.org/Clients">Stomp clients</ulink> are available for
- several languages and platforms making it a good choice for interoperability.</para>
- <section id="stomp.native">
- <title>Native Stomp support</title>
- <para>HornetQ provides native support for Stomp. To be able to send and receive Stomp messages,
- you must configure a <literal>NettyAcceptor</literal> with a <literal>protocol</literal>
- parameter set to <literal>stomp</literal>:</para>
-<programlisting>
+ <title>Interoperability</title>
+ <section id="stomp">
+ <title>Stomp</title>
+ <para><ulink url="http://stomp.codehaus.org/">Stomp</ulink> is a text-orientated wire protocol
+ that allows Stomp clients to communicate with Stomp Brokers.</para>
+ <para><ulink url="http://stomp.codehaus.org/Clients">Stomp clients</ulink> are available for
+ several languages and platforms making it a good choice for interoperability.</para>
+ <section id="stomp.native">
+ <title>Native Stomp support</title>
+ <para>HornetQ provides native support for Stomp. To be able to send and receive Stomp
+ messages, you must configure a <literal>NettyAcceptor</literal> with a <literal
+ >protocol</literal> parameter set to <literal>stomp</literal>:</para>
+ <programlisting>
<acceptor name="stomp-acceptor">
<factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
<param key="protocol" value="stomp"/>
<param key="port" value="61613"/>
</acceptor>
</programlisting>
- <para>With this configuration, HornetQ will accept Stomp connections on
- the port <literal>61613</literal> (which is the default port of the Stomp brokers).</para>
- <para>See the <literal>stomp</literal> example which shows how to configure a HornetQ server with Stomp.</para>
- <section>
- <title>Limitations</title>
- <para>Message acknowledgements are not transactional. The ACK frame can not be part of a transaction
- (it will be ignored if its <literal>transaction</literal> header is set).</para>
- </section>
- </section>
-
- <section>
- <title>Mapping Stomp destinations to HornetQ addresses and queues</title>
- <para>Stomp clients deals with <emphasis>destinations</emphasis> when sending messages and subscribing.
- Destination names are simply strings which are mapped to some form of destination on the
- server - how the server translates these is left to the server implementation.</para>
- <para>In HornetQ, these destinations are mapped to <emphasis>addresses</emphasis> and <emphasis>queues</emphasis>.
- When a Stomp client sends a message (using a <literal>SEND</literal> frame), the specified destination is mapped
- to an address.
- When a Stomp client subscribes (or unsubscribes) for a destination (using a <literal>SUBSCRIBE</literal>
- or <literal>UNSUBSCRIBE</literal> frame), the destination is mapped to a HornetQ queue.</para>
- </section>
+ <para>With this configuration, HornetQ will accept Stomp connections on the port <literal
+ >61613</literal> (which is the default port of the Stomp brokers).</para>
+ <para>See the <literal>stomp</literal> example which shows how to configure a HornetQ server
+ with Stomp.</para>
<section>
- <title>STOMP and connection-ttl</title>
- <para>Well behaved STOMP clients will always send a DISCONNECT frame before closing their connections. In this case the server
- will clear up any server side resources such as sessions and consumers synchronously. However if STOMP clients exit without
- sending a DISCONNECT frame or if they crash the server will have no way of knowing immediately whether the client is still alive
- or not. STOMP connections therefore default to a connection-ttl value of 1 minute (see chapter on <link linkend="connection-ttl"
- >connection-ttl</link> for more information. This value can be overridden using connection-ttl-override.
- </para>
- <note><para>Please note that the STOMP protocol does not contain any heartbeat frame. It is therefore the user's responsibility to make sure
- data is sent within connection-ttl or the server will assume the client is dead and clean up server side resources.</para></note>
+ <title>Flow control</title>
+ <para>When consuming messages in stomp, it's preferrable to use Acknowledge consumers,
+ otherwise the server will send messages as fast as it can to the client (i.e. no flow
+ control). Refer to the parameter stomp-consumer-credits for more information.</para>
</section>
-
- <section>
- <title>Stomp and JMS interoperabilty</title>
- <section>
- <title>Using JMS destinations</title>
- <para>As explained in <xref linkend="jms-core-mapping" />, JMS destinations are also mapped to HornetQ addresses and queues.
- If you want to use Stomp to send messages to JMS destinations, the Stomp destinations must follow the same convention:</para>
- <itemizedlist>
- <listitem>
- <para>send or subscribe to a JMS <emphasis>Queue</emphasis> by prepending the queue name by <literal>jms.queue.</literal>.</para>
- <para>For example, to send a message to the <literal>orders</literal> JMS Queue, the Stomp client must send the frame:</para>
- <programlisting>
+ <section>
+ <title>Limitations</title>
+ <para>Message acknowledgements are not transactional. The ACK frame can not be part of a
+ transaction (it will be ignored if its <literal>transaction</literal> header is
+ set).</para>
+ </section>
+ </section>
+ <section>
+ <title>Mapping Stomp destinations to HornetQ addresses and queues</title>
+ <para>Stomp clients deals with <emphasis>destinations</emphasis> when sending messages and
+ subscribing. Destination names are simply strings which are mapped to some form of
+ destination on the server - how the server translates these is left to the server
+ implementation.</para>
+ <para>In HornetQ, these destinations are mapped to <emphasis>addresses</emphasis> and
+ <emphasis>queues</emphasis>. When a Stomp client sends a message (using a <literal
+ >SEND</literal> frame), the specified destination is mapped to an address. When a Stomp
+ client subscribes (or unsubscribes) for a destination (using a <literal>SUBSCRIBE</literal>
+ or <literal>UNSUBSCRIBE</literal> frame), the destination is mapped to a HornetQ
+ queue.</para>
+ </section>
+ <section>
+ <title>STOMP and connection-ttl</title>
+ <para>Well behaved STOMP clients will always send a DISCONNECT frame before closing their
+ connections. In this case the server will clear up any server side resources such as
+ sessions and consumers synchronously. However if STOMP clients exit without sending a
+ DISCONNECT frame or if they crash the server will have no way of knowing immediately whether
+ the client is still alive or not. STOMP connections therefore default to a connection-ttl
+ value of 1 minute (see chapter on <link linkend="connection-ttl">connection-ttl</link> for
+ more information. This value can be overridden using connection-ttl-override. </para>
+ <note>
+ <para>Please note that the STOMP protocol does not contain any heartbeat frame. It is
+ therefore the user's responsibility to make sure data is sent within connection-ttl or the
+ server will assume the client is dead and clean up server side resources.</para>
+ </note>
+ </section>
+ <section>
+ <title>Stomp and JMS interoperabilty</title>
+ <section>
+ <title>Using JMS destinations</title>
+ <para>As explained in <xref linkend="jms-core-mapping"/>, JMS destinations are also mapped
+ to HornetQ addresses and queues. If you want to use Stomp to send messages to JMS
+ destinations, the Stomp destinations must follow the same convention:</para>
+ <itemizedlist>
+ <listitem>
+ <para>send or subscribe to a JMS <emphasis>Queue</emphasis> by prepending the queue name
+ by <literal>jms.queue.</literal>.</para>
+ <para>For example, to send a message to the <literal>orders</literal> JMS Queue, the
+ Stomp client must send the frame:</para>
+ <programlisting>
SEND
destination:jms.queue.orders
hello queue orders
^@
</programlisting>
- </listitem>
- <listitem>
- <para>send or subscribe to a JMS <emphasis>Topic</emphasis> by prepending the topic name by <literal>jms.topic.</literal>.</para>
- <para>For example to subscribe to the <literal>stocks</literal> JMS Topic, the Stomp client must send the frame:</para>
- <programlisting>
+ </listitem>
+ <listitem>
+ <para>send or subscribe to a JMS <emphasis>Topic</emphasis> by prepending the topic name
+ by <literal>jms.topic.</literal>.</para>
+ <para>For example to subscribe to the <literal>stocks</literal> JMS Topic, the Stomp
+ client must send the frame:</para>
+ <programlisting>
SUBSCRIBE
destination:jms.topic.stocks
^@
</programlisting>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Send and consuming Stomp message from JMS or HornetQ Core API</title>
- <para>Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and HornetQ Core API,
- our Stomp implementation checks for presence of the <literal>content-length</literal> header to decide how to map a Stomp message
- to a JMS Message or a Core message.
- </para>
- <para>If the Stomp message does <emphasis>not</emphasis> have a <literal>content-length</literal> header, it will be mapped to a JMS <emphasis>TextMessage</emphasis>
- or a Core message with a <emphasis>single nullable SimpleString in the body buffer</emphasis>.</para>
- <para>Alternatively, if the Stomp message <emphasis>has</emphasis> a <literal>content-length</literal> header,
- it will be mapped to a JMS <emphasis>BytesMessage</emphasis>
- or a Core message with a <emphasis>byte[] in the body buffer</emphasis>.</para>
- <para>The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp client can check the presence
- of the <literal>content-length</literal> header to determine the type of the message body (String or bytes).</para>
- </section>
- </section>
-
- <section id="stomp.websockets">
- <title>Stomp Over Web Sockets</title>
- <para>HornetQ also support Stomp over <ulink url="http://dev.w3.org/html5/websockets/">Web Sockets</ulink>. Modern web browser which support Web Sockets can send and receive
- Stomp messages from HornetQ.</para>
- <para>To enable Stomp over Web Sockets, you must configure a <literal>NettyAcceptor</literal> with a <literal>protocol</literal>
- parameter set to <literal>stomp_ws</literal>:</para>
- <programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Send and consuming Stomp message from JMS or HornetQ Core API</title>
+ <para>Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with
+ JMS and HornetQ Core API, our Stomp implementation checks for presence of the <literal
+ >content-length</literal> header to decide how to map a Stomp message to a JMS Message
+ or a Core message. </para>
+ <para>If the Stomp message does <emphasis>not</emphasis> have a <literal
+ >content-length</literal> header, it will be mapped to a JMS
+ <emphasis>TextMessage</emphasis> or a Core message with a <emphasis>single nullable
+ SimpleString in the body buffer</emphasis>.</para>
+ <para>Alternatively, if the Stomp message <emphasis>has</emphasis> a <literal
+ >content-length</literal> header, it will be mapped to a JMS
+ <emphasis>BytesMessage</emphasis> or a Core message with a <emphasis>byte[] in the body
+ buffer</emphasis>.</para>
+ <para>The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp
+ client can check the presence of the <literal>content-length</literal> header to determine
+ the type of the message body (String or bytes).</para>
+ </section>
+ </section>
+ <section id="stomp.websockets">
+ <title>Stomp Over Web Sockets</title>
+ <para>HornetQ also support Stomp over <ulink url="http://dev.w3.org/html5/websockets/">Web
+ Sockets</ulink>. Modern web browser which support Web Sockets can send and receive Stomp
+ messages from HornetQ.</para>
+ <para>To enable Stomp over Web Sockets, you must configure a <literal>NettyAcceptor</literal>
+ with a <literal>protocol</literal> parameter set to <literal>stomp_ws</literal>:</para>
+ <programlisting>
<acceptor name="stomp-ws-acceptor">
<factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
<param key="protocol" value="stomp_ws"/>
<param key="port" value="61614"/>
</acceptor>
</programlisting>
- <para>With this configuration, HornetQ will accept Stomp connections over Web Sockets on
- the port <literal>61614</literal> with the URL path <literal>/stomp</literal>.
- Web browser can then connect to <literal>ws://<server>:61614/stomp</literal> using a Web Socket to send and receive Stomp
- messages.</para>
- <para>A companion JavaScript library to ease client-side development is available from
- <ulink url="http://github.com/jmesnil/stomp-websocket">GitHub</ulink> (please see
- its <ulink url="http://jmesnil.net/stomp-websocket/doc/">documentation</ulink> for a complete description).</para>
- <para>The <literal>stomp-websockets</literal> example shows how to configure HornetQ server to have web browsers and Java
- applications exchanges messages on a JMS topic.</para>
- </section>
-
- <section id="stompconnect">
- <title>StompConnect</title>
- <para><ulink url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that
- can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
- Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and
- use any of the available stomp clients. These include clients written in C, C++, c# and
- .net etc.</para>
- <para>To run StompConnect first start the HornetQ server and make sure that it is using
- JNDI.</para>
- <para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
- classpath. This should look something like:</para>
- <programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ <para>With this configuration, HornetQ will accept Stomp connections over Web Sockets on the
+ port <literal>61614</literal> with the URL path <literal>/stomp</literal>. Web browser can
+ then connect to <literal>ws://<server>:61614/stomp</literal> using a Web Socket to
+ send and receive Stomp messages.</para>
+ <para>A companion JavaScript library to ease client-side development is available from <ulink
+ url="http://github.com/jmesnil/stomp-websocket">GitHub</ulink> (please see its <ulink
+ url="http://jmesnil.net/stomp-websocket/doc/">documentation</ulink> for a complete
+ description).</para>
+ <para>The <literal>stomp-websockets</literal> example shows how to configure HornetQ server to
+ have web browsers and Java applications exchanges messages on a JMS topic.</para>
+ </section>
+ <section id="stompconnect">
+ <title>StompConnect</title>
+ <para><ulink url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server
+ that can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
+ Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and use
+ any of the available stomp clients. These include clients written in C, C++, c# and .net
+ etc.</para>
+ <para>To run StompConnect first start the HornetQ server and make sure that it is using
+ JNDI.</para>
+ <para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
+ classpath. This should look something like:</para>
+ <programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.provider.url=jnp://localhost:1099
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting>
- <para>Make sure this file is in the classpath along with the StompConnect jar and the
- HornetQ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
- </section>
-
+ <para>Make sure this file is in the classpath along with the StompConnect jar and the HornetQ
+ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
</section>
- <section>
- <title>REST</title>
- <para>REST support coming soon!</para>
- </section>
- <section>
- <title>AMQP</title>
- <para>AMQP support coming soon!</para>
- </section>
+ </section>
+ <section>
+ <title>REST</title>
+ <para>Refer to HornetQ Rest Manual for more information.</para>
+ </section>
</chapter>
More information about the hornetq-commits
mailing list