interoperability.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->
<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>
	&lt;acceptor name="stomp-acceptor">
		&lt;factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory&lt;/factory-class>
		&lt;param key="protocol"  value="stomp"/>
		&lt;param key="port"  value="61613"/>
	&lt;/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 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>
        <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 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>
  SUBSCRIBE
  destination:jms.topic.stocks
  
  ^@
                </programlisting>
              </listitem>
             </itemizedlist>
           </section>

           <section>
             <title>Send and consuming Stomp message from JMS</title>
             <para>Stomp messages can be sent and consumed from a JMS Destination by using <literal>BytesMessage</literal> where
                the Stomp message body is stored in the JMS BytesMessage body.</para>
             <para>If the Stomp message contained a UTF-8 String, the corresponding code to read the string from a JMS BytesMessage is:</para>
             <programlisting>
BytesMessage message = (BytesMessage)consumer.receive();
byte[] data = new byte[1024];
int size = message.readBytes(data);
String text = new String(data, 0, size, "UTF-8");
             </programlisting>
             <para>Conversely, to send a JMS BytesMessage destined to be consumed by Stomp as a UTF-8 String, the code is:</para>
             <programlisting>
String text = ...
BytesMessage message = session.createBytesMessage();
message.writeBytes(text.getBytes("UTF-8"));
producer.send(message);
             </programlisting>
          </section>
        </section>
    </section>
    <section>
        <title>REST</title>
        <para>REST support coming soon!</para>
    </section>
    <section>
        <title>AMQP</title>
        <para>AMQP support coming soon!</para>
    </section>
</chapter>