Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Moved section on STOMP from protocols --> advanced

  • Loading branch information...
commit 7b2601477a28a6ca2a64284c4aee32d13761bdf1 1 parent c563d6d
@belaban authored
View
119 doc/manual/en/modules/advanced.xml
@@ -1695,6 +1695,125 @@ On view change V:
</section>
</section>
+ <section id="STOMP">
+ <title>STOMP support</title>
+ <para>
+ STOMP is a JGroups protocol which implements the <ulink url="http://stomp.codehaus.org">STOMP</ulink>
+ protocol. Currently (as of Aug 2011), transactions and acks are not implemented.
+ </para>
+ <para>
+ Adding the STOMP protocol to a configuration means that
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Clients written in different languages can subscribe to destinations, send messages to destinations,
+ and receive messages posted to (subscribed) destinations. This is similar to JMS topics.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Clients don't need to join any cluster; this allows for light weight clients, and we can run many
+ of them.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Clients can access a cluster from a remote location (e.g. across a WAN).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ STOMP clients can send messages to cluster members, and vice versa.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The location of a STOMP protocol in a stack is shown in <xref linkend="StompProtocol"/>.
+ </para>
+ <para>
+ <figure id="StompProtocol">
+ <title>STOMP in a protocol stack</title>
+ <!--<graphic fileref="images/StompProtocol.png" format="PNG" align="left" scalefit="1" contentwidth="4in"/>-->
+ <graphic fileref="images/StompProtocol.png" format="PNG" align="center" scale="75"/>
+ </figure>
+ </para>
+
+ <para>
+ The STOMP protocol should be near the top of the stack.
+ </para>
+ <para>
+ A STOMP instance listens on a TCP socket for client connections. The port and bind address of the
+ server socket can be defined via properties.
+ </para>
+ <para>
+ A client can send SUBSCRIBE commands for various destinations. When a SEND for a given destination is
+ received, STOMP adds a header to the message and broadcasts it to all cluster nodes. Every node then in
+ turn forwards the message to all of its connected clients which have subscribed to the same destination.
+ When a destination is not given, STOMP simply forwards the message to <emphasis>all</emphasis> connected
+ clients.
+ </para>
+ <para>
+ Traffic can be generated by clients and by servers. In the latter case, we could for example have code
+ executing in the address space of a JGroups (server) node. In the former case, clients use the SEND
+ command to send messages to a JGroups server and receive messages via the MESSAGE command. If there is
+ code on the server which generates messages, it is important that both client and server code agree
+ on a marshalling format, e.g. JSON, so that they understand each other's messages.
+ </para>
+ <para>
+ Clients can be written in any language, as long as they understand the STOMP protocol. Note that the
+ JGroups STOMP protocol implementation sends additional information (e.g. INFO) to clients; non-JGroups
+ STOMP clients should simply ignore them.
+ </para>
+ <para>
+ JGroups comes with a STOMP client (org.jgroups.client.StompConnection) and a demo (StompDraw). Both
+ need to be started with the address and port of a JGroups cluster node. Once they have been started,
+ the JGroups STOMP protocol will notify clients of cluster changes, which is needed so client can
+ failover to another JGroups server node when a node is shut down. E.g. when a client connects to C, after
+ connection, it'll get a list of endpoints (e.g. A,B,C,D). When C is terminated, or crashes, the client
+ automatically reconnects to any of the remaining nodes, e.g. A, B, or D. When this happens, a client
+ is also re-subscribed to the destinations it registered for.
+ </para>
+ <para>
+ The JGroups STOMP protocol can be used when we have clients, which are either not in the same network
+ segment as the JGroups server nodes, or which don't want to become full-blown JGroups server nodes.
+ <xref linkend="StompArchitecture"/> shows a typical setup.
+ </para>
+
+ <para>
+ <figure id="StompArchitecture">
+ <title>STOMP architecture</title>
+ <!--<graphic fileref="images/StompArchitecture.png" format="PNG" align="left" scalefit="1" contentwidth="5in"/>-->
+ <graphic fileref="images/StompArchitecture.png" format="PNG" align="center" scale="75"/>
+ </figure>
+ </para>
+
+ <para>
+ There are 4 nodes in a cluster. Say the cluster is in a LAN, and communication is via IP multicasting
+ (UDP as transport). We now have clients which do not want to be part of the cluster themselves, e.g.
+ because they're in a different geographic location (and we don't want to switch the main cluster to TCP),
+ or because clients are frequently started and stopped, and therefore the cost of startup and joining
+ wouldn't be amortized over the lifetime of a client. Another reason could be that clients are written
+ in a different language, or perhaps, we don't want a large cluster, which could be the case if we
+ for example have 10 JGroups server nodes and 1000 clients connected to them.
+ </para>
+ <para>
+ In the example, we see 9 clients connected to every JGroups cluster node. If a client connected to
+ node A sends a message to destination /topics/chat, then the message is multicast from node A to all other
+ nodes (B, C and D). Every node then forwards the message to those clients which have previously subscribed
+ to /topics/chat.
+ </para>
+ <para>
+ When node A crashes (or leaves) the JGroups STOMP clients (org.jgroups.client.StompConnection) simply pick
+ another server node and connect to it.
+ </para>
+ <para>
+ For more information about STOMP see the blog entry at
+ <ulink url="http://belaban.blogspot.com/2010/10/stomp-for-jgroups.html"/>.
+ </para>
+ </section>
+
+
<section id="RelayAdvanced">
<title>Bridging between remote clusters</title>
<para>
View
90 doc/manual/en/modules/protocols.xml
@@ -1299,96 +1299,10 @@ keytool -genseckey -alias myKey -keypass changeit -storepass changeit -keyalg B
${RELAY}
</section>
- <section id="STOMP">
+ <section id="STOMP_Protocol">
<title>STOMP</title>
<para>
- STOMP is a JGroups protocol which implements the <ulink url="http://stomp.codehaus.org">STOMP</ulink>
- protocol. Currently (as of Nov 2010), transactions and acks are not implemented.
- </para>
- <para>
- The location of a STOMP protocol in a stack is shown in <xref linkend="StompProtocol"/>.
- </para>
- <para>
- <figure id="StompProtocol">
- <title>STOMP in a protocol stack</title>
- <!--<graphic fileref="images/StompProtocol.png" format="PNG" align="left" scalefit="1" contentwidth="4in"/>-->
- <graphic fileref="images/StompProtocol.png" format="PNG" align="center" scale="75"/>
- </figure>
- </para>
-
- <para>
- The STOMP protocol should be near the top of the stack.
- </para>
- <para>
- A STOMP instance listens on a TCP socket for client connections. The port and bind address of the
- server socket can be defined via properties.
- </para>
- <para>
- A client can send SUBSCRIBE commands for various destinations. When a SEND for a given destination is
- received, STOMP adds a header to the message and broadcasts it to all cluster nodes. Every node then in
- turn forwards the message to all of its connected clients which have subscribed to the same destination.
- When a destination is not given, STOMP simply forwards the message to <emphasis>all</emphasis> connected
- clients.
- </para>
- <para>
- Traffic can be generated by clients and by servers. In the latter case, we could for example have code
- executing in the address space of a JGroups (server) node. In the former case, clients use the SEND
- command to send messages to a JGroups server and receive messages via the MESSAGE command. If there is
- code on the server which generates messages, it is important that both client and server code agree
- on a marshalling format, e.g. JSON, so that they understand each other's messages.
- </para>
- <para>
- Clients can be written in any language, as long as they understand the STOMP protocol. Note that the
- JGroups STOMP protocol implementation sends additional information (e.g. INFO) to clients; non-JGroups
- STOMP clients should simply ignore them.
- </para>
- <para>
- JGroups comes with a STOMP client (org.jgroups.client.StompConnection) and a demo (StompDraw). Both
- need to be started with the address and port of a JGroups cluster node. Once they have been started,
- the JGroups STOMP protocol will notify clients of cluster changes, which is needed so client can
- failover to another JGroups server node when a node is shut down. E.g. when a client connects to C, after
- connection, it'll get a list of endpoints (e.g. A,B,C,D). When C is terminated, or crashes, the client
- automatically reconnects to any of the remaining nodes, e.g. A, B, or D. When this happens, a client
- is also re-subscribed to the destinations it registered for.
- </para>
- <para>
- The JGroups STOMP protocol can be used when we have clients, which are either not in the same network
- segment as the JGroups server nodes, or which don't want to become full-blown JGroups server nodes.
- <xref linkend="StompArchitecture"/> shows a typical setup.
- </para>
-
- <para>
- <figure id="StompArchitecture">
- <title>STOMP architecture</title>
- <!--<graphic fileref="images/StompArchitecture.png" format="PNG" align="left" scalefit="1" contentwidth="5in"/>-->
- <graphic fileref="images/StompArchitecture.png" format="PNG" align="center" scale="75"/>
- </figure>
- </para>
-
- <para>
- There are 4 nodes in a cluster. Say the cluster is in a LAN, and communication is via IP multicasting
- (UDP as transport). We now have clients which do not want to be part of the cluster themselves, e.g.
- because they're in a different geographic location (and we don't want to switch the main cluster to TCP),
- or because clients are frequently started and stopped, and therefore the cost of startup and joining
- wouldn't be amortized over the lifetime of a client. Another reason could be that clients are written
- in a different language, or perhaps, we don't want a large cluster, which could be the case if we
- for example have 10 JGroups server nodes and 1000 clients connected to them.
- </para>
- <para>
- In the example, we see 9 clients connected to every JGroups cluster node. If a client connected to
- node A sends a message to destination /topics/chat, then the message is multicast from node A to all other
- nodes (B, C and D). Every node then forwards the message to those clients which have previously subscribed
- to /topics/chat.
- </para>
- <para>
- When node A crashes (or leaves) the JGroups STOMP clients (org.jgroups.client.StompConnection) simply pick
- another server node and connect to it.
- </para>
-
- <para>
- </para>
- <para>
- The properties for STOMP are shown below:
+ STOMP is discussed in <xref linkend="STOMP"/>. The properties for it are shown below:
</para>
${STOMP}
</section>
Please sign in to comment.
Something went wrong with that request. Please try again.