http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/ha.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/ha.xml b/docs/user-manual/en/ha.xml deleted file mode 100644 index 2df9e76..0000000 --- a/docs/user-manual/en/ha.xml +++ /dev/null @@ -1,985 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> - -<!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 "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> -<chapter id="ha"> - <title>High Availability and Failover</title> - - <para>We define high availability as the <emphasis>ability for the system to continue - functioning after failure of one or more of the servers</emphasis>.</para> - - <para>A part of high availability is <emphasis>failover</emphasis> which we define as the - <emphasis>ability for client connections to migrate from one server to another in event of - server failure so client applications can continue to operate</emphasis>.</para> - <section> - <title>Live - Backup Groups</title> - - <para>ActiveMQ allows servers to be linked together as <emphasis>live - backup</emphasis> - groups where each live server can have 1 or more backup servers. A backup server is owned by - only one live server. Backup servers are not operational until failover occurs, however 1 - chosen backup, which will be in passive mode, announces its status and waits to take over - the live servers work</para> - - <para>Before failover, only the live server is serving the ActiveMQ clients while the backup - servers remain passive or awaiting to become a backup server. When a live server crashes or - is brought down in the correct mode, the backup server currently in passive mode will become - live and another backup server will become passive. If a live server restarts after a - failover then it will have priority and be the next server to become live when the current - live server goes down, if the current live server is configured to allow automatic failback - then it will detect the live server coming back up and automatically stop.</para> - - <section id="ha.policies"> - <title>HA Policies</title> - <para>ActiveMQ supports two different strategies for backing up a server <emphasis>shared - store</emphasis> and <emphasis>replication</emphasis>. Which is configured via the - <literal>ha-policy</literal> configuration element.</para> - <programlisting> -<ha-policy> - <replication/> -</ha-policy> - </programlisting> - <para> - or - </para> - <programlisting> -<ha-policy> - <shared-store/> -</ha-policy> - </programlisting> - <para> - As well as these 2 strategies there is also a 3rd called <literal>live-only</literal>. This of course means there - will be no Backup Strategy and is the default if none is provided, however this is used to configure - <literal>scale-down</literal> which we will cover in a later chapter. - </para> - <note> - <para> - The <literal>ha-policy</literal> configurations replaces any current HA configuration in the root of the - <literal>activemq-configuration.xml</literal> configuration. All old configuration is now deprecated altho - best efforts will be made to honour it if configured this way. - </para> - </note> - <note> - <para>Only persistent message data will survive failover. Any non persistent message - data will not be available after failover.</para> - </note> - <para>The <literal>ha-policy</literal> type configures which strategy a cluster should use to provide the - backing up of a servers data. Within this configuration element is configured how a server should behave - within the cluster, either as a master (live), slave (backup) or colocated (both live and backup). This - would look something like: </para> - <programlisting> -<ha-policy> - <replication> - <master/> - </replication> -</ha-policy> - </programlisting> - <para> - or - </para> - <programlisting> -<ha-policy> - <shared-store/> - <slave/> - </shared-store/> -</ha-policy> - </programlisting> - <para> - or - </para> - <programlisting> -<ha-policy> - <replication> - <colocated/> - </replication> -</ha-policy> - </programlisting> - </section> - - <section id="ha.mode.replicated"> - <title>Data Replication</title> - <para>Support for network-based data replication was added in version 2.3.</para> - <para>When using replication, the live and the backup servers do not share the same - data directories, all data synchronization is done over the network. Therefore all (persistent) - data received by the live server will be duplicated to the backup.</para> - <graphic fileref="images/ha-replicated-store.png" align="center"/> - <para>Notice that upon start-up the backup server will first need to synchronize all - existing data from the live server before becoming capable of replacing the live - server should it fail. So unlike when using shared storage, a replicating backup will - not be a fully operational backup right after start-up, but only after it finishes - synchronizing the data with its live server. The time it will take for this to happen - will depend on the amount of data to be synchronized and the connection speed.</para> - - <note> - <para>Synchronization occurs in parallel with current network traffic so this won't cause any - blocking on current clients.</para> - </note> - <para>Replication will create a copy of the data at the backup. One issue to be aware - of is: in case of a successful fail-over, the backup's data will be newer than - the one at the live's storage. If you configure your live server to perform a - <xref linkend="ha.allow-fail-back">'fail-back'</xref> when restarted, it will synchronize - its data with the backup's. If both servers are shutdown, the administrator will have - to determine which one has the latest data.</para> - - <para>The replicating live and backup pair must be part of a cluster. The Cluster - Connection also defines how backup servers will find the remote live servers to pair - with. Refer to <xref linkend="clusters"/> for details on how this is done, and how - to configure a cluster connection. Notice that:</para> - - <itemizedlist> - <listitem> - <para>Both live and backup servers must be part of the same cluster. Notice - that even a simple live/backup replicating pair will require a cluster configuration.</para> - </listitem> - <listitem> - <para>Their cluster user and password must match.</para> - </listitem> - </itemizedlist> - - <para>Within a cluster, there are two ways that a backup server will locate a live server to replicate - from, these are:</para> - - <itemizedlist> - <listitem> - <para><literal>specifying a node group</literal>. You can specify a group of live servers that a backup - server can connect to. This is done by configuring <literal>group-name</literal> in either the <literal>master</literal> - or the <literal>slave</literal> element of the - <literal>activemq-configuration.xml</literal>. A Backup server will only connect to a live server that - shares the same node group name</para> - </listitem> - <listitem> - <para><literal>connecting to any live</literal>. This will be the behaviour if <literal>group-name</literal> - is not configured allowing a backup server to connect to any live server</para> - </listitem> - </itemizedlist> - <note> - <para>A <literal>group-name</literal> example: suppose you have 5 live servers and 6 backup - servers:</para> - <itemizedlist> - <listitem> - <para><literal>live1</literal>, <literal>live2</literal>, <literal>live3</literal>: with - <literal>group-name=fish</literal></para> - </listitem> - <listitem> - <para><literal>live4</literal>, <literal>live5</literal>: with <literal>group-name=bird</literal></para> - </listitem> - <listitem> - <para><literal>backup1</literal>, <literal>backup2</literal>, <literal>backup3</literal>, - <literal>backup4</literal>: with <literal>group-name=fish</literal></para> - </listitem> - <listitem> - <para><literal>backup5</literal>, <literal>backup6</literal>: with - <literal>group-name=bird</literal></para> - </listitem> - </itemizedlist> - <para>After joining the cluster the backups with <literal>group-name=fish</literal> will - search for live servers with <literal>group-name=fish</literal> to pair with. Since there - is one backup too many, the <literal>fish</literal> will remain with one spare backup.</para> - <para>The 2 backups with <literal>group-name=bird</literal> (<literal>backup5</literal> and - <literal>backup6</literal>) will pair with live servers <literal>live4</literal> and - <literal>live5</literal>.</para> - </note> - <para>The backup will search for any live server that it is configured to connect to. It then tries to - replicate with each live server in turn until it finds a live server that has no current backup - configured. If no live server is available it will wait until the cluster topology changes and - repeats the process.</para> - <note> - <para>This is an important distinction from a shared-store backup, if a backup starts and does not find - a live server, the server will just activate and start to serve client requests. - In the replication case, the backup just keeps - waiting for a live server to pair with. Note that in replication the backup server - does not know whether any data it might have is up to date, so it really cannot - decide to activate automatically. To activate a replicating backup server using the data - it has, the administrator must change its configuration to make it a live server by changing - <literal>slave</literal> to <literal>master</literal>.</para> - </note> - - <para>Much like in the shared-store case, when the live server stops or crashes, - its replicating backup will become active and take over its duties. Specifically, - the backup will become active when it loses connection to its live server. This can - be problematic because this can also happen because of a temporary network - problem. In order to address this issue, the backup will try to determine whether it - still can connect to the other servers in the cluster. If it can connect to more - than half the servers, it will become active, if more than half the servers also - disappeared with the live, the backup will wait and try reconnecting with the live. - This avoids a split brain situation.</para> - - <section> - <title>Configuration</title> - - <para>To configure the live and backup servers to be a replicating pair, configure - the live server in ' <literal>activemq-configuration.xml</literal> to have:</para> - - <programlisting> -<ha-policy> - <replication> - <master/> - </replication> -</ha-policy> -. -<cluster-connections> - <cluster-connection name="my-cluster"> - ... - </cluster-connection> -</cluster-connections> - </programlisting> - - <para>The backup server must be similarly configured but as a <literal>slave</literal></para> - - <programlisting> -<ha-policy> - <replication> - <slave/> - </replication> -</ha-policy></programlisting> - </section> - <section> - <title>All Replication Configuration</title> - - <para>The following table lists all the <literal>ha-policy</literal> configuration elements for HA strategy - Replication for <literal>master</literal>:</para> - <table> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>check-for-live-server</literal></entry> - <entry>Whether to check the cluster for a (live) server using our own server ID when starting - up. This option is only necessary for performing 'fail-back' on replicating servers.</entry> - </row> - <row> - <entry><literal>cluster-name</literal></entry> - <entry>Name of the cluster configuration to use for replication. This setting is only necessary if you - configure multiple cluster connections. If configured then the connector configuration of the - cluster configuration with this name will be used when connecting to the cluster to discover - if a live server is already running, see <literal>check-for-live-server</literal>. If unset then - the default cluster connections configuration is used (the first one configured)</entry> - </row> - <row> - <entry><literal>group-name</literal></entry> - <entry>If set, backup servers will only pair with live servers with matching group-name</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The following table lists all the <literal>ha-policy</literal> configuration elements for HA strategy - Replication for <literal>slave</literal>:</para> - <table> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>cluster-name</literal></entry> - <entry>Name of the cluster configuration to use for replication. This setting is only necessary if you - configure multiple cluster connections. If configured then the connector configuration of the - cluster configuration with this name will be used when connecting to the cluster to discover - if a live server is already running, see <literal>check-for-live-server</literal>. If unset then - the default cluster connections configuration is used (the first one configured)</entry> - </row> - <row> - <entry><literal>group-name</literal></entry> - <entry>If set, backup servers will only pair with live servers with matching group-name</entry> - </row> - <row> - <entry><literal>max-saved-replicated-journals-size</literal></entry> - <entry>This specifies how many times a replicated backup server can restart after moving its files on start. - Once there are this number of backup journal files the server will stop permanently after if fails - back.</entry> - </row> - <row> - <entry><literal>allow-failback</literal></entry> - <entry>Whether a server will automatically stop when a another places a request to take over - its place. The use case is when the backup has failed over </entry> - </row> - <row> - <entry><literal>failback-delay</literal></entry> - <entry>delay to wait before fail-back occurs on (failed over live's) restart</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - - <section id="ha.mode.shared"> - <title>Shared Store</title> - <para>When using a shared store, both live and backup servers share the - <emphasis>same</emphasis> entire data directory using a shared file system. - This means the paging directory, journal directory, large messages and binding - journal.</para> - <para>When failover occurs and a backup server takes over, it will load the - persistent storage from the shared file system and clients can connect to - it.</para> - <para>This style of high availability differs from data replication in that it - requires a shared file system which is accessible by both the live and backup - nodes. Typically this will be some kind of high performance Storage Area Network - (SAN). We do not recommend you use Network Attached Storage (NAS), e.g. NFS - mounts to store any shared journal (NFS is slow).</para> - <para>The advantage of shared-store high availability is that no replication occurs - between the live and backup nodes, this means it does not suffer any performance - penalties due to the overhead of replication during normal operation.</para> - <para>The disadvantage of shared store replication is that it requires a shared file - system, and when the backup server activates it needs to load the journal from - the shared store which can take some time depending on the amount of data in the - store.</para> - <para>If you require the highest performance during normal operation, have access to - a fast SAN and live with a slightly slower failover (depending on amount of - data).</para> - <graphic fileref="images/ha-shared-store.png" align="center"/> - - <section id="ha/mode.shared.configuration"> - <title>Configuration</title> - <para>To configure the live and backup servers to share their store, configure - id via the <literal>ha-policy</literal> configuration in <literal>activemq-configuration.xml</literal>:</para> - <programlisting> -<ha-policy> - <shared-store> - <master/> - </shared-store> -</ha-policy> -. -<cluster-connections> - <cluster-connection name="my-cluster"> -... - </cluster-connection> -</cluster-connections> - </programlisting> - - <para>The backup server must also be configured as a backup.</para> - - <programlisting> -<ha-policy> - <shared-store> - <slave/> - </shared-store> -</ha-policy> - </programlisting> - <para>In order for live - backup groups to operate properly with a shared store, - both servers must have configured the location of journal directory to point - to the <emphasis>same shared location</emphasis> (as explained in - <xref linkend="configuring.message.journal"/>)</para> - <note> - <para>todo write something about GFS</para> - </note> - <para>Also each node, live and backups, will need to have a cluster connection defined even if not - part of a cluster. The Cluster Connection info defines how backup servers announce there presence - to its live server or any other nodes in the cluster. Refer to <xref linkend="clusters"/> for details - on how this is done.</para> - </section> - </section> - <section id="ha.allow-fail-back"> - <title>Failing Back to live Server</title> - <para>After a live server has failed and a backup taken has taken over its duties, you may want to - restart the live server and have clients fail back.</para> - <para>In case of "shared disk", simply restart the original live server and kill the new live server by can - do this by killing the process itself. Alternatively you can set <literal>allow-fail-back</literal> to - <literal>true</literal> on the slave config which will force the backup that has become live to automatically - stop. This configuration would look like:</para> - <programlisting> -<ha-policy> - <shared-store> - <slave> - <allow-failback>true</allow-failback> - <failback-delay>5000</failback-delay> - </slave> - </shared-store> -</ha-policy> - </programlisting> - <para>The <literal>failback-delay</literal> configures how long the backup must wait after automatically - stopping before it restarts. This is to gives the live server time to start and obtain its lock.</para> - <para id="hq.check-for-live-server">In replication HA mode you need to set an extra property <literal>check-for-live-server</literal> - to <literal>true</literal> in the <literal>master</literal> configuration. If set to true, during start-up - a live server will first search the cluster for another server using its nodeID. If it finds one, it will - contact this server and try to "fail-back". Since this is a remote replication scenario, the "starting live" - will have to synchronize its data with the server running with its ID, once they are in sync, it will - request the other server (which it assumes it is a back that has assumed its duties) to shutdown for it to - take over. This is necessary because otherwise the live server has no means to know whether there was a - fail-over or not, and if there was if the server that took its duties is still running or not. - To configure this option at your <literal>activemq-configuration.xml</literal> configuration file as follows:</para> - <programlisting> -<ha-policy> - <replication> - <master> - <check-for-live-server>true</check-for-live-server> - <master> - </replication> -</ha-policy></programlisting> - <warning> - <para> - Be aware that if you restart a live server while after failover has occurred then this value must be - set to <literal><emphasis role="bold">true</emphasis></literal>. If not the live server will restart and server the same - messages that the backup has already handled causing duplicates. - </para> - </warning> - <para>It is also possible, in the case of shared store, to cause failover to occur on normal server shutdown, - to enable this set the following property to true in the <literal>ha-policy</literal> configuration on either - the <literal>master</literal> or <literal>slave</literal> like so:</para> - <programlisting> -<ha-policy> - <shared-store> - <master> - <failover-on-shutdown>true</failover-on-shutdown> - </master> - </shared-store> -</ha-policy></programlisting> - <para>By default this is set to false, if by some chance you have set this to false but still - want to stop the server normally and cause failover then you can do this by using the management - API as explained at <xref linkend="management.core.server"/></para> - <para>You can also force the running live server to shutdown when the old live server comes back up allowing - the original live server to take over automatically by setting the following property in the - <literal>activemq-configuration.xml</literal> configuration file as follows:</para> - <programlisting> -<ha-policy> - <shared-store> - <slave> - <allow-failback>true</allow-failback> - </slave> - </shared-store> -</ha-policy></programlisting> - - <section> - <title>All Shared Store Configuration</title> - - <para>The following table lists all the <literal>ha-policy</literal> configuration elements for HA strategy - shared store for <literal>master</literal>:</para> - <table> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>failback-delay</literal></entry> - <entry>If a backup server is detected as being live, via the lock file, then the live server - will wait announce itself as a backup and wait this amount of time (in ms) before starting as - a live</entry> - </row> - <row> - <entry><literal>failover-on-server-shutdown</literal></entry> - <entry>If set to true then when this server is stopped normally the backup will become live - assuming failover. If false then the backup server will remain passive. Note that if false you - want failover to occur the you can use the the management API as explained at <xref linkend="management.core.server"/></entry> - </row> - </tbody> - </tgroup> - </table> - <para>The following table lists all the <literal>ha-policy</literal> configuration elements for HA strategy - Shared Store for <literal>slave</literal>:</para> - <table> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>failover-on-server-shutdown</literal></entry> - <entry>In the case of a backup that has become live. then when set to true then when this server - is stopped normally the backup will become liveassuming failover. If false then the backup - server will remain passive. Note that if false you want failover to occur the you can use - the the management API as explained at <xref linkend="management.core.server"/></entry> - </row> - <row> - <entry><literal>allow-failback</literal></entry> - <entry>Whether a server will automatically stop when a another places a request to take over - its place. The use case is when the backup has failed over.</entry> - </row> - <row> - <entry><literal>failback-delay</literal></entry> - <entry>After failover and the slave has become live, this is set on the new live server. - When starting If a backup server is detected as being live, via the lock file, then the live server - will wait announce itself as a backup and wait this amount of time (in ms) before starting as - a live, however this is unlikely since this backup has just stopped anyway. It is also used - as the delay after failback before this backup will restart (if <literal>allow-failback</literal> - is set to true.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - </section> - <section id="ha.colocated"> - <title>Colocated Backup Servers</title> - <para>It is also possible when running standalone to colocate backup servers in the same - JVM as another live server. Live Servers can be configured to request another live server in the cluster - to start a backup server in the same JVM either using shared store or replication. The new backup server - will inherit its configuration from the live server creating it apart from its name, which will be set to - <literal>colocated_backup_n</literal> where n is the number of backups the server has created, and any directories - and its Connectors and Acceptors which are discussed later on in this chapter. A live server can also - be configured to allow requests from backups and also how many backups a live server can start. this way - you can evenly distribute backups around the cluster. This is configured via the <literal>ha-policy</literal> - element in the <literal>activemq-configuration.xml</literal> file like so:</para> - <programlisting> -<ha-policy> - <replication> - <colocated> - <request-backup>true</request-backup> - <max-backups>1</max-backups> - <backup-request-retries>-1</backup-request-retries> - <backup-request-retry-interval>5000</backup-request-retry-interval> - <master/> - <slave/> - </colocated> - <replication> -</ha-policy> - </programlisting> - <para>the above example is configured to use replication, in this case the <literal>master</literal> and - <literal>slave</literal> configurations must match those for normal replication as in the previous chapter. - <literal>shared-store</literal> is also supported</para> - - <graphic fileref="images/ha-colocated.png" align="center"/> - <section id="ha.colocated.connectorsandacceptors"> - <title>Configuring Connectors and Acceptors</title> - <para>If the HA Policy is colocated then connectors and acceptors will be inherited from the live server - creating it and offset depending on the setting of <literal>backup-port-offset</literal> configuration element. - If this is set to say 100 (which is the default) and a connector is using port 5445 then this will be - set to 5545 for the first server created, 5645 for the second and so on.</para> - <note><para>for INVM connectors and Acceptors the id will have <literal>colocated_backup_n</literal> appended, - where n is the backup server number.</para></note> - <section id="ha.colocated.connectorsandacceptors.remote"> - <title>Remote Connectors</title> - <para>It may be that some of the Connectors configured are for external servers and hence should be excluded from the offset. - for instance a Connector used by the cluster connection to do quorum voting for a replicated backup server, - these can be omitted from being offset by adding them to the <literal>ha-policy</literal> configuration like so:</para> - <programlisting> -<ha-policy> - <replication> - <colocated> - <excludes> - <connector-ref>remote-connector</connector-ref> - </excludes> -......... -</ha-policy> - </programlisting> - </section> - </section> - <section id="ha.colocated.directories"> - <title>Configuring Directories</title> - <para>Directories for the Journal, Large messages and Paging will be set according to what the HA strategy is. - If shared store the the requesting server will notify the target server of which directories to use. If replication - is configured then directories will be inherited from the creating server but have the new backups name - appended.</para> - </section> - - <para>The following table lists all the <literal>ha-policy</literal> configuration elements:</para> - <table> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>request-backup</literal></entry> - <entry>If true then the server will request a backup on another node</entry> - </row> - <row> - <entry><literal>backup-request-retries</literal></entry> - <entry>How many times the live server will try to request a backup, -1 means for ever.</entry> - </row> - <row> - <entry><literal>backup-request-retry-interval</literal></entry> - <entry>How long to wait for retries between attempts to request a backup server.</entry> - </row> - <row> - <entry><literal>max-backups</literal></entry> - <entry>Whether or not this live server will accept backup requests from other live servers.</entry> - </row> - <row> - <entry><literal>backup-port-offset</literal></entry> - <entry>The offset to use for the Connectors and Acceptors when creating a new backup server.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - <section id="ha.scaledown"> - <title>Scaling Down</title> - <para>An alternative to using Live/Backup groups is to configure scaledown. when configured for scale down a server - can copy all its messages and transaction state to another live server. The advantage of this is that you dont need - full backups to provide some form of HA, however there are disadvantages with this approach the first being that it - only deals with a server being stopped and not a server crash. The caveat here is if you configure a backup to scale down. </para> - <para>Another disadvantage is that it is possible to lose message ordering. This happens in the following scenario, - say you have 2 live servers and messages are distributed evenly between the servers from a single producer, if one - of the servers scales down then the messages sent back to the other server will be in the queue after the ones - already there, so server 1 could have messages 1,3,5,7,9 and server 2 would have 2,4,6,8,10, if server 2 scales - down the order in server 1 would be 1,3,5,7,9,2,4,6,8,10.</para> - <graphic fileref="images/ha-scaledown.png" align="center"/> - <para>The configuration for a live server to scale down would be something like:</para> - <programlisting> -<ha-policy> - <live-only> - <scale-down> - <connectors> - <connector-ref>server1-connector</connector-ref> - </connectors> - </scale-down> - </live-only> -</ha-policy> - </programlisting> - <para>In this instance the server is configured to use a specific connector to scale down, if a connector is not - specified then the first INVM connector is chosen, this is to make scale down fromm a backup server easy to configure. - It is also possible to use discovery to scale down, this would look like:</para> - <programlisting> -<ha-policy> - <live-only> - <scale-down> - <discovery-group>my-discovery-group</discovery-group> - </scale-down> - </live-only> -</ha-policy> - </programlisting> - <section id="ha.scaledown.group"> - <title>Scale Down with groups</title> - <para>It is also possible to configure servers to only scale down to servers that belong in the same group. This - is done by configuring the group like so:</para> - <programlisting> -<ha-policy> - <live-only> - <scale-down> - ... - <group-name>my-group</group-name> - </scale-down> - </live-only> -</ha-policy> - </programlisting> - <para>In this scenario only servers that belong to the group <literal>my-group</literal> will be scaled down to</para> - </section> - <section> - <title>Scale Down and Backups</title> - <para>It is also possible to mix scale down with HA via backup servers. If a slave is configured to scale down - then after failover has occurred, instead of starting fully the backup server will immediately scale down to - another live server. The most appropriate configuration for this is using the <literal>colocated</literal> approach. - it means as you bring up live server they will automatically be backed up by server and as live servers are - shutdown, there messages are made available on another live server. A typical configuration would look like:</para> - <programlisting> -<ha-policy> - <replication> - <colocated> - <backup-request-retries>44</backup-request-retries> - <backup-request-retry-interval>33</backup-request-retry-interval> - <max-backups>3</max-backups> - <request-backup>false</request-backup> - <backup-port-offset>33</backup-port-offset> - <master> - <group-name>purple</group-name> - <check-for-live-server>true</check-for-live-server> - <cluster-name>abcdefg</cluster-name> - </master> - <slave> - <group-name>tiddles</group-name> - <max-saved-replicated-journals-size>22</max-saved-replicated-journals-size> - <cluster-name>33rrrrr</cluster-name> - <restart-backup>false</restart-backup> - <scale-down> - <!--a grouping of servers that can be scaled down to--> - <group-name>boo!</group-name> - <!--either a discovery group--> - <discovery-group>wahey</discovery-group> - </scale-down> - </slave> - </colocated> - </replication> -</ha-policy> - </programlisting> - </section> - <section id="ha.scaledown.client"> - <title>Scale Down and Clients</title> - <para>When a server is stopping and preparing to scale down it will send a message to all its clients informing them - which server it is scaling down to before disconnecting them. At this point the client will reconnect however this - will only succeed once the server has completed scaledown. This is to ensure that any state such as queues or transactions - are there for the client when it reconnects. The normal reconnect settings apply when the client is reconnecting so - these should be high enough to deal with the time needed to scale down.</para> - </section> - </section> - <section id="failover"> - <title>Failover Modes</title> - <para>ActiveMQ defines two types of client failover:</para> - <itemizedlist> - <listitem> - <para>Automatic client failover</para> - </listitem> - <listitem> - <para>Application-level client failover</para> - </listitem> - </itemizedlist> - <para>ActiveMQ also provides 100% transparent automatic reattachment of connections to the - same server (e.g. in case of transient network problems). This is similar to failover, - except it is reconnecting to the same server and is discussed in - <xref linkend="client-reconnection"/></para> - <para>During failover, if the client has consumers on any non persistent or temporary - queues, those queues will be automatically recreated during failover on the backup node, - since the backup node will not have any knowledge of non persistent queues.</para> - <section id="ha.automatic.failover"> - <title>Automatic Client Failover</title> - <para>ActiveMQ clients can be configured to receive knowledge of all live and backup servers, so - that in event of connection failure at the client - live server connection, the - client will detect this and reconnect to the backup server. The backup server will - then automatically recreate any sessions and consumers that existed on each - connection before failover, thus saving the user from having to hand-code manual - reconnection logic.</para> - <para>ActiveMQ clients detect connection failure when it has not received packets from - the server within the time given by <literal>client-failure-check-period</literal> - as explained in section <xref linkend="connection-ttl"/>. If the client does not - receive data in good time, it will assume the connection has failed and attempt - failover. Also if the socket is closed by the OS, usually if the server process is - killed rather than the machine itself crashing, then the client will failover straight away. - </para> - <para>ActiveMQ clients can be configured to discover the list of live-backup server groups in a - number of different ways. They can be configured explicitly or probably the most - common way of doing this is to use <emphasis>server discovery</emphasis> for the - client to automatically discover the list. For full details on how to configure - server discovery, please see <xref linkend="clusters"/>. - Alternatively, the clients can explicitly connect to a specific server and download - the current servers and backups see <xref linkend="clusters"/>.</para> - <para>To enable automatic client failover, the client must be configured to allow - non-zero reconnection attempts (as explained in <xref linkend="client-reconnection" - />).</para> - <para>By default failover will only occur after at least one connection has been made to - the live server. In other words, by default, failover will not occur if the client - fails to make an initial connection to the live server - in this case it will simply - retry connecting to the live server according to the reconnect-attempts property and - fail after this number of attempts.</para> - <section> - <title>Failing over on the Initial Connection</title> - <para> - Since the client does not learn about the full topology until after the first - connection is made there is a window where it does not know about the backup. If a failure happens at - this point the client can only try reconnecting to the original live server. To configure - how many attempts the client will make you can set the property <literal>initialConnectAttempts</literal> - on the <literal>ClientSessionFactoryImpl</literal> or <literal >ActiveMQConnectionFactory</literal> or - <literal>initial-connect-attempts</literal> in xml. The default for this is <literal>0</literal>, that - is try only once. Once the number of attempts has been made an exception will be thrown. - </para> - </section> - <para>For examples of automatic failover with transacted and non-transacted JMS - sessions, please see <xref linkend="examples.transaction-failover"/> and <xref - linkend="examples.non-transaction-failover"/>.</para> - <section id="ha.automatic.failover.noteonreplication"> - <title>A Note on Server Replication</title> - <para>ActiveMQ does not replicate full server state between live and backup servers. - When the new session is automatically recreated on the backup it won't have any - knowledge of messages already sent or acknowledged in that session. Any - in-flight sends or acknowledgements at the time of failover might also be - lost.</para> - <para>By replicating full server state, theoretically we could provide a 100% - transparent seamless failover, which would avoid any lost messages or - acknowledgements, however this comes at a great cost: replicating the full - server state (including the queues, session, etc.). This would require - replication of the entire server state machine; every operation on the live - server would have to replicated on the replica server(s) in the exact same - global order to ensure a consistent replica state. This is extremely hard to do - in a performant and scalable way, especially when one considers that multiple - threads are changing the live server state concurrently.</para> - <para>It is possible to provide full state machine replication using techniques such - as <emphasis role="italic">virtual synchrony</emphasis>, but this does not scale - well and effectively serializes all operations to a single thread, dramatically - reducing concurrency.</para> - <para>Other techniques for multi-threaded active replication exist such as - replicating lock states or replicating thread scheduling but this is very hard - to achieve at a Java level.</para> - <para>Consequently it has decided it was not worth massively reducing performance - and concurrency for the sake of 100% transparent failover. Even without 100% - transparent failover, it is simple to guarantee <emphasis role="italic">once and - only once</emphasis> delivery, even in the case of failure, by using a - combination of duplicate detection and retrying of transactions. However this is - not 100% transparent to the client code.</para> - </section> - <section id="ha.automatic.failover.blockingcalls"> - <title>Handling Blocking Calls During Failover</title> - <para>If the client code is in a blocking call to the server, waiting for a response - to continue its execution, when failover occurs, the new session will not have - any knowledge of the call that was in progress. This call might otherwise hang - for ever, waiting for a response that will never come.</para> - <para>To prevent this, ActiveMQ will unblock any blocking calls that were in progress - at the time of failover by making them throw a <literal - >javax.jms.JMSException</literal> (if using JMS), or a <literal - >ActiveMQException</literal> with error code <literal - >ActiveMQException.UNBLOCKED</literal>. It is up to the client code to catch - this exception and retry any operations if desired.</para> - <para>If the method being unblocked is a call to commit(), or prepare(), then the - transaction will be automatically rolled back and ActiveMQ will throw a <literal - >javax.jms.TransactionRolledBackException</literal> (if using JMS), or a - <literal>ActiveMQException</literal> with error code <literal - >ActiveMQException.TRANSACTION_ROLLED_BACK</literal> if using the core - API.</para> - </section> - <section id="ha.automatic.failover.transactions"> - <title>Handling Failover With Transactions</title> - <para>If the session is transactional and messages have already been sent or - acknowledged in the current transaction, then the server cannot be sure that - messages sent or acknowledgements have not been lost during the failover.</para> - <para>Consequently the transaction will be marked as rollback-only, and any - subsequent attempt to commit it will throw a <literal - >javax.jms.TransactionRolledBackException</literal> (if using JMS), or a - <literal>ActiveMQException</literal> with error code <literal - >ActiveMQException.TRANSACTION_ROLLED_BACK</literal> if using the core - API.</para> - <warning> - <title>2 phase commit</title> - <para> - The caveat to this rule is when XA is used either via JMS or through the core API. - If 2 phase commit is used and prepare has already been called then rolling back could - cause a <literal>HeuristicMixedException</literal>. Because of this the commit will throw - a <literal>XAException.XA_RETRY</literal> exception. This informs the Transaction Manager - that it should retry the commit at some later point in time, a side effect of this is - that any non persistent messages will be lost. To avoid this use persistent - messages when using XA. With acknowledgements this is not an issue since they are - flushed to the server before prepare gets called. - </para> - </warning> - <para>It is up to the user to catch the exception, and perform any client side local - rollback code as necessary. There is no need to manually rollback the session - - it is already rolled back. The user can then just retry the transactional - operations again on the same session.</para> - <para>ActiveMQ ships with a fully functioning example demonstrating how to do this, - please see <xref linkend="examples.transaction-failover"/></para> - <para>If failover occurs when a commit call is being executed, the server, as - previously described, will unblock the call to prevent a hang, since no response - will come back. In this case it is not easy for the client to determine whether - the transaction commit was actually processed on the live server before failure - occurred.</para> - <note> - <para> - If XA is being used either via JMS or through the core API then an <literal>XAException.XA_RETRY</literal> - is thrown. This is to inform Transaction Managers that a retry should occur at some point. At - some later point in time the Transaction Manager will retry the commit. If the original - commit has not occurred then it will still exist and be committed, if it does not exist - then it is assumed to have been committed although the transaction manager may log a warning. - </para> - </note> - <para>To remedy this, the client can simply enable duplicate detection (<xref - linkend="duplicate-detection"/>) in the transaction, and retry the - transaction operations again after the call is unblocked. If the transaction had - indeed been committed on the live server successfully before failover, then when - the transaction is retried, duplicate detection will ensure that any durable - messages resent in the transaction will be ignored on the server to prevent them - getting sent more than once.</para> - <note> - <para>By catching the rollback exceptions and retrying, catching unblocked calls - and enabling duplicate detection, once and only once delivery guarantees for - messages can be provided in the case of failure, guaranteeing 100% no loss - or duplication of messages.</para> - </note> - </section> - <section id="ha.automatic.failover.nontransactional"> - <title>Handling Failover With Non Transactional Sessions</title> - <para>If the session is non transactional, messages or acknowledgements can be lost - in the event of failover.</para> - <para>If you wish to provide <emphasis role="italic">once and only once</emphasis> - delivery guarantees for non transacted sessions too, enabled duplicate - detection, and catch unblock exceptions as described in <xref - linkend="ha.automatic.failover.blockingcalls"/></para> - </section> - </section> - <section> - <title>Getting Notified of Connection Failure</title> - <para>JMS provides a standard mechanism for getting notified asynchronously of - connection failure: <literal>java.jms.ExceptionListener</literal>. Please consult - the JMS javadoc or any good JMS tutorial for more information on how to use - this.</para> - <para>The ActiveMQ core API also provides a similar feature in the form of the class - <literal>org.apache.activemq.core.client.SessionFailureListener</literal></para> - <para>Any ExceptionListener or SessionFailureListener instance will always be called by - ActiveMQ on event of connection failure, <emphasis role="bold" - >irrespective</emphasis> of whether the connection was successfully failed over, - reconnected or reattached, however you can find out if reconnect or reattach has happened - by either the <literal>failedOver</literal> flag passed in on the <literal>connectionFailed</literal> - on <literal>SessionfailureListener</literal> or by inspecting the error code on the - <literal>javax.jms.JMSException</literal> which will be one of the following:</para> - <table frame="topbot" border="2"> - <title>JMSException error codes</title> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>error code</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>FAILOVER</entry> - <entry> - Failover has occurred and we have successfully reattached or reconnected. - </entry> - </row> - <row> - <entry>DISCONNECT</entry> - <entry> - No failover has occurred and we are disconnected. - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section> - <title>Application-Level Failover</title> - <para>In some cases you may not want automatic client failover, and prefer to handle any - connection failure yourself, and code your own manually reconnection logic in your - own failure handler. We define this as <emphasis>application-level</emphasis> - failover, since the failover is handled at the user application level.</para> - <para>To implement application-level failover, if you're using JMS then you need to set - an <literal>ExceptionListener</literal> class on the JMS connection. The - <literal>ExceptionListener</literal> will be called by ActiveMQ in the event that - connection failure is detected. In your <literal>ExceptionListener</literal>, you - would close your old JMS connections, potentially look up new connection factory - instances from JNDI and creating new connections. In this case you may well be using - <ulink url="http://www.jboss.org/community/wiki/JBossHAJNDIImpl";>HA-JNDI</ulink> - to ensure that the new connection factory is looked up from a different server.</para> - <para>For a working example of application-level failover, please see - <xref linkend="application-level-failover"/>.</para> - <para>If you are using the core API, then the procedure is very similar: you would set a - <literal>FailureListener</literal> on the core <literal>ClientSession</literal> - instances.</para> - </section> - </section> -</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/images/activemq-logo.jpg ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/images/activemq-logo.jpg b/docs/user-manual/en/images/activemq-logo.jpg new file mode 100644 index 0000000..d514448 Binary files /dev/null and b/docs/user-manual/en/images/activemq-logo.jpg differ http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/intercepting-operations.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/intercepting-operations.md b/docs/user-manual/en/intercepting-operations.md new file mode 100644 index 0000000..7d78976 --- /dev/null +++ b/docs/user-manual/en/intercepting-operations.md @@ -0,0 +1,84 @@ +Intercepting Operations +======================= + +ActiveMQ supports *interceptors* to intercept packets entering and +exiting the server. Incoming and outgoing interceptors are be called for +any packet entering or exiting the server respectively. This allows +custom code to be executed, e.g. for auditing packets, filtering or +other reasons. Interceptors can change the packets they intercept. This +makes interceptors powerful, but also potentially dangerous. + +Implementing The Interceptors +============================= + +An interceptor must implement the `Interceptor interface`: + + package org.apache.activemq.api.core.interceptor; + + public interface Interceptor + { + boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException; + } + +The returned boolean value is important: + +- if `true` is returned, the process continues normally + +- if `false` is returned, the process is aborted, no other + interceptors will be called and the packet will not be processed + further by the server. + +Configuring The Interceptors +============================ + +Both incoming and outgoing interceptors are configured in +`activemq-configuration.xml`: + + <remoting-incoming-interceptors> + <class-name>org.apache.activemq.jms.example.LoginInterceptor</class-name> + <class-name>org.apache.activemq.jms.example.AdditionalPropertyInterceptor</class-name> + </remoting-incoming-interceptors> + + <remoting-outgoing-interceptors> + <class-name>org.apache.activemq.jms.example.LogoutInterceptor</class-name> + <class-name>org.apache.activemq.jms.example.AdditionalPropertyInterceptor</class-name> + </remoting-outgoing-interceptors> + +The interceptors classes (and their dependencies) must be added to the +server classpath to be properly instantiated and called. + +Interceptors on the Client Side +=============================== + +The interceptors can also be run on the client side to intercept packets +either sent by the client to the server or by the server to the client. +This is done by adding the interceptor to the `ServerLocator` with the +`addIncomingInterceptor(Interceptor)` or +`addOutgoingInterceptor(Interceptor)` methods. + +As noted above, if an interceptor returns `false` then the sending of +the packet is aborted which means that no other interceptors are be +called and the packet is not be processed further by the client. +Typically this process happens transparently to the client (i.e. it has +no idea if a packet was aborted or not). However, in the case of an +outgoing packet that is sent in a `blocking` fashion a +`ActiveMQException` will be thrown to the caller. The exception is +thrown because blocking sends provide reliability and it is considered +an error for them not to succeed. `Blocking` sends occurs when, for +example, an application invokes `setBlockOnNonDurableSend(true)` or +`setBlockOnDurableSend(true)` on its `ServerLocator` or if an +application is using a JMS connection factory retrieved from JNDI that +has either `block-on-durable-send` or `block-on-non-durable-send` set to +`true`. Blocking is also used for packets dealing with transactions +(e.g. commit, roll-back, etc.). The `ActiveMQException` thrown will +contain the name of the interceptor that returned false. + +As on the server, the client interceptor classes (and their +dependencies) must be added to the classpath to be properly instantiated +and invoked. + +Example +======= + +See ? for an example which shows how to use interceptors to add +properties to a message on the server. http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/intercepting-operations.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/intercepting-operations.xml b/docs/user-manual/en/intercepting-operations.xml deleted file mode 100644 index f89e1a6..0000000 --- a/docs/user-manual/en/intercepting-operations.xml +++ /dev/null @@ -1,99 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> - -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> - -<!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 "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> - -<chapter id="intercepting-operations"> - <title>Intercepting Operations</title> - <para>ActiveMQ supports <emphasis>interceptors</emphasis> to intercept packets entering - and exiting the server. Incoming and outgoing interceptors are be called for any packet - entering or exiting the server respectively. This allows custom code to be executed, - e.g. for auditing packets, filtering or other reasons. Interceptors can change the - packets they intercept. This makes interceptors powerful, but also potentially - dangerous.</para> - <section> - <title>Implementing The Interceptors</title> - <para>An interceptor must implement the <literal>Interceptor interface</literal>:</para> - <programlisting> -package org.apache.activemq.api.core.interceptor; - -public interface Interceptor -{ - boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException; -}</programlisting> - <para>The returned boolean value is important:</para> - <itemizedlist> - <listitem> - <para>if <literal>true</literal> is returned, the process continues normally</para> - </listitem> - <listitem> - <para>if <literal>false</literal> is returned, the process is aborted, no other interceptors - will be called and the packet will not be processed further by the server.</para> - </listitem> - </itemizedlist> - </section> - <section> - <title>Configuring The Interceptors</title> - <para>Both incoming and outgoing interceptors are configured in - <literal>activemq-configuration.xml</literal>:</para> - <programlisting> -<remoting-incoming-interceptors> - <class-name>org.apache.activemq.jms.example.LoginInterceptor</class-name> - <class-name>org.apache.activemq.jms.example.AdditionalPropertyInterceptor</class-name> -</remoting-incoming-interceptors></programlisting> - <programlisting> -<remoting-outgoing-interceptors> - <class-name>org.apache.activemq.jms.example.LogoutInterceptor</class-name> - <class-name>org.apache.activemq.jms.example.AdditionalPropertyInterceptor</class-name> -</remoting-outgoing-interceptors></programlisting> - <para>The interceptors classes (and their dependencies) must be added to the server classpath - to be properly instantiated and called.</para> - </section> - <section> - <title>Interceptors on the Client Side</title> - <para>The interceptors can also be run on the client side to intercept packets either sent by the - client to the server or by the server to the client. This is done by adding the interceptor to - the <code>ServerLocator</code> with the <code>addIncomingInterceptor(Interceptor)</code> or - <code>addOutgoingInterceptor(Interceptor)</code> methods.</para> - <para>As noted above, if an interceptor returns <literal>false</literal> then the sending of the - packet is aborted which means that no other interceptors are be called and the packet is not - be processed further by the client. Typically this process happens transparently to the client - (i.e. it has no idea if a packet was aborted or not). However, in the case of an outgoing packet - that is sent in a <literal>blocking</literal> fashion a <literal>ActiveMQException</literal> will - be thrown to the caller. The exception is thrown because blocking sends provide reliability and - it is considered an error for them not to succeed. <literal>Blocking</literal> sends occurs when, - for example, an application invokes <literal>setBlockOnNonDurableSend(true)</literal> or - <literal>setBlockOnDurableSend(true)</literal> on its <literal>ServerLocator</literal> or if an - application is using a JMS connection factory retrieved from JNDI that has either - <literal>block-on-durable-send</literal> or <literal>block-on-non-durable-send</literal> - set to <literal>true</literal>. Blocking is also used for packets dealing with transactions (e.g. - commit, roll-back, etc.). The <literal>ActiveMQException</literal> thrown will contain the name - of the interceptor that returned false.</para> - <para>As on the server, the client interceptor classes (and their dependencies) must be added to the classpath - to be properly instantiated and invoked.</para> - </section> - <section> - <title>Example</title> - <para>See <xref linkend="examples.interceptor" /> for an example which - shows how to use interceptors to add properties to a message on the server.</para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/interoperability.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/interoperability.md b/docs/user-manual/en/interoperability.md new file mode 100644 index 0000000..58b2257 --- /dev/null +++ b/docs/user-manual/en/interoperability.md @@ -0,0 +1,365 @@ +Interoperability +================ + +Stomp +===== + +[Stomp](http://stomp.github.com/) is a text-orientated wire protocol +that allows Stomp clients to communicate with Stomp Brokers. ActiveMQ +now supports Stomp 1.0, 1.1 and 1.2. + +Stomp clients are available for several languages and platforms making +it a good choice for interoperability. + +Native Stomp support +-------------------- + +ActiveMQ provides native support for Stomp. To be able to send and +receive Stomp messages, you must configure a `NettyAcceptor` with a +`protocols` parameter set to have `stomp`: + + <acceptor name="stomp-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="STOMP"/> + <param key="port" value="61613"/> + </acceptor> + +With this configuration, ActiveMQ will accept Stomp connections on the +port `61613` (which is the default port of the Stomp brokers). + +See the `stomp` example which shows how to configure a ActiveMQ server +with Stomp. + +### Limitations + +Message acknowledgements are not transactional. The ACK frame can not be +part of a transaction (it will be ignored if its `transaction` header is +set). + +### Stomp 1.1/1.2 Notes + +#### Virtual Hosting + +ActiveMQ currently doesn't support virtual hosting, which means the +'host' header in CONNECT fram will be ignored. + +#### Heart-beating + +ActiveMQ specifies a minimum value for both client and server heart-beat +intervals. The minimum interval for both client and server heartbeats is +500 milliseconds. That means if a client sends a CONNECT frame with +heartbeat values lower than 500, the server will defaults the value to +500 milliseconds regardless the values of the 'heart-beat' header in the +frame. + +Mapping Stomp destinations to ActiveMQ addresses and queues +----------------------------------------------------------- + +Stomp clients deals with *destinations* 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. + +In ActiveMQ, these destinations are mapped to *addresses* and *queues*. +When a Stomp client sends a message (using a `SEND` frame), the +specified destination is mapped to an address. When a Stomp client +subscribes (or unsubscribes) for a destination (using a `SUBSCRIBE` or +`UNSUBSCRIBE` frame), the destination is mapped to a ActiveMQ queue. + +STOMP and connection-ttl +------------------------ + +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 +[connection-ttl](#connection-ttl) for more information. This value can +be overridden using connection-ttl-override. + +If you need a specific connection-ttl for your stomp connections without +affecting the connection-ttl-override setting, you can configure your +stomp acceptor with the "connection-ttl" property, which is used to set +the ttl for connections that are created from that acceptor. For +example: + + <acceptor name="stomp-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="STOMP"/> + <param key="port" value="61613"/> + <param key="connection-ttl" value="20000"/> + </acceptor> + +The above configuration will make sure that any stomp connection that is +created from that acceptor will have its connection-ttl set to 20 +seconds. + +> **Note** +> +> Please note that the STOMP protocol version 1.0 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. With `Stomp 1.1` +> users can use heart-beats to maintain the life cycle of stomp +> connections. + +Stomp and JMS interoperability +------------------------------ + +### Using JMS destinations + +As explained in ?, JMS destinations are also mapped to ActiveMQ +addresses and queues. If you want to use Stomp to send messages to JMS +destinations, the Stomp destinations must follow the same convention: + +- send or subscribe to a JMS *Queue* by prepending the queue name by + `jms.queue.`. + + For example, to send a message to the `orders` JMS Queue, the Stomp + client must send the frame: + + SEND + destination:jms.queue.orders + + hello queue orders + ^@ + +- send or subscribe to a JMS *Topic* by prepending the topic name by + `jms.topic.`. + + For example to subscribe to the `stocks` JMS Topic, the Stomp client + must send the frame: + + SUBSCRIBE + destination:jms.topic.stocks + + ^@ + +### Sending and consuming Stomp message from JMS or ActiveMQ Core API + +Stomp is mainly a text-orientated protocol. To make it simpler to +interoperate with JMS and ActiveMQ Core API, our Stomp implementation +checks for presence of the `content-length` header to decide how to map +a Stomp message to a JMS Message or a Core message. + +If the Stomp message does *not* have a `content-length` header, it will +be mapped to a JMS *TextMessage* or a Core message with a *single +nullable SimpleString in the body buffer*. + +Alternatively, if the Stomp message *has* a `content-length` header, it +will be mapped to a JMS *BytesMessage* or a Core message with a *byte[] +in the body buffer*. + +The same logic applies when mapping a JMS message or a Core message to +Stomp. A Stomp client can check the presence of the `content-length` +header to determine the type of the message body (String or bytes). + +### Message IDs for Stomp messages + +When receiving Stomp messages via a JMS consumer or a QueueBrowser, the +messages have no properties like JMSMessageID by default. However this +may bring some inconvenience to clients who wants an ID for their +purpose. ActiveMQ Stomp provides a parameter to enable message ID on +each incoming Stomp message. If you want each Stomp message to have a +unique ID, just set the `stomp-enable-message-id` to true. For example: + + <acceptor name="stomp-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="STOMP"/> + <param key="port" value="61613"/> + <param key="stomp-enable-message-id" value="true"/> + </acceptor> + +When the server starts with the above setting, each stomp message sent +through this acceptor will have an extra property added. The property +key is ` + hq-message-id` and the value is a String representation of a +long type internal message id prefixed with "`STOMP`", like: + + hq-message-id : STOMP12345 + +If `stomp-enable-message-id` is not specified in the configuration, +default is `false`. + +### Handling of Large Messages with Stomp + +Stomp clients may send very large bodys of frames which can exceed the +size of ActiveMQ server's internal buffer, causing unexpected errors. To +prevent this situation from happening, ActiveMQ provides a stomp +configuration attribute `stomp-min-large-message-size`. This attribute +can be configured inside a stomp acceptor, as a parameter. For example: + + <acceptor name="stomp-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="STOMP"/> + <param key="port" value="61613"/> + <param key="stomp-min-large-message-size" value="10240"/> + </acceptor> + +The type of this attribute is integer. When this attributed is +configured, ActiveMQ server will check the size of the body of each +Stomp frame arrived from connections established with this acceptor. If +the size of the body is equal or greater than the value of +`stomp-min-large-message`, the message will be persisted as a large +message. When a large message is delievered to a stomp consumer, the +HorentQ server will automatically handle the conversion from a large +message to a normal message, before sending it to the client. + +If a large message is compressed, the server will uncompressed it before +sending it to stomp clients. The default value of +`stomp-min-large-message-size` is the same as the default value of +[min-large-message-size](#large-messages.core.config). + +Stomp Over Web Sockets +---------------------- + +ActiveMQ also support Stomp over [Web +Sockets](http://dev.w3.org/html5/websockets/). Modern web browser which +support Web Sockets can send and receive Stomp messages from ActiveMQ. + +To enable Stomp over Web Sockets, you must configure a `NettyAcceptor` +with a `protocol` parameter set to `stomp_ws`: + + <acceptor name="stomp-ws-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="STOMP_WS"/> + <param key="port" value="61614"/> + </acceptor> + +With this configuration, ActiveMQ will accept Stomp connections over Web +Sockets on the port `61614` with the URL path `/stomp`. Web browser can +then connect to `ws://<server>:61614/stomp` using a Web Socket to send +and receive Stomp messages. + +A companion JavaScript library to ease client-side development is +available from [GitHub](http://github.com/jmesnil/stomp-websocket) +(please see its [documentation](http://jmesnil.net/stomp-websocket/doc/) +for a complete description). + +The `stomp-websockets` example shows how to configure ActiveMQ server to +have web browsers and Java applications exchanges messages on a JMS +topic. + +StompConnect +------------ + +[StompConnect](http://stomp.codehaus.org/StompConnect) 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 +ActiveMQ into a Stomp Broker and use any of the available stomp clients. +These include clients written in C, C++, c\# and .net etc. + +To run StompConnect first start the ActiveMQ server and make sure that +it is using JNDI. + +Stomp requires the file `jndi.properties` to be available on the +classpath. This should look something like: + + java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory + +Configure any required JNDI resources in this file according to the +documentation. + +Make sure this file is in the classpath along with the StompConnect jar +and the ActiveMQ jars and simply run `java org.codehaus.stomp.jms.Main`. + +REST +==== + +Please see ? + +AMQP +==== + +ActiveMQ supports the [AMQP +1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp) +specification. To enable AMQP you must configure a Netty Acceptor to +receive AMQP clients, like so: + + <acceptor name="stomp-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="AMQP"/> + <param key="port" value="5672"/> + </acceptor> + + +ActiveMQ will then accept AMQP 1.0 clients on port 5672 which is the +default AMQP port. + +There are 2 Stomp examples available see proton-j and proton-ruby which +use the qpid Java and Ruby clients respectively + +AMQP and security +----------------- + +The ActiveMQ Server accepts AMQP SASL Authentication and will use this +to map onto the underlying session created for the connection so you can +use the normal ActiveMQ security configuration. + +AMQP Links +---------- + +An AMQP Link is a uni directional transport for messages between a +source and a target, i.e. a client and the ActiveMQ Broker. A link will +have an endpoint of which there are 2 kinds, a Sender and A Receiver. At +the Broker a Sender will have its messages converted into a ActiveMQ +Message and forwarded to its destination or target. A Receiver will map +onto a ActiveMQ Server Consumer and convert ActiveMQ messages back into +AMQP messages before being delivered. + +AMQP and destinations +--------------------- + +If an AMQP Link is dynamic then a temporary queue will be created and +either the remote source or remote target address will be set to the +name of the temporary queue. If the Link is not dynamic then the the +address of the remote target or source will used for the queue. If this +does not exist then an exception will be sent + +> **Note** +> +> For the next version we will add a flag to aut create durable queue +> but for now you will have to add them via the configuration + +AMQP and Coordinations - Handling Transactions +---------------------------------------------- + +An AMQP links target can also be a Coordinator, the Coordinator is used +to handle transactions. If a coordinator is used the the underlying +HormetQ Server session will be transacted and will be either rolled back +or committed via the coordinator. + +> **Note** +> +> AMQP allows the use of multiple transactions per session, +> `amqp:multi-txns-per-ssn`, however in this version ActiveMQ will only +> support single transactions per session + +OpenWire +======== + +ActiveMQ now supports the +[OpenWire](http://activemq.apache.org/openwire.html) protocol so that an +ActiveMQ JMS client can talk directly to a ActiveMQ server. To enable +OpenWire support you must configure a Netty Acceptor, like so: + + <acceptor name="openwire-acceptor"> + <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class> + <param key="protocols" value="OPENWIRE"/> + <param key="port" value="61616"/> + </acceptor> + + +The ActiveMQ server will then listens on port 61616 for incoming +openwire commands. Please note the "protocols" is not mandatory here. +The openwire configuration conforms to ActiveMQ's "Single Port" feature. +Please refer to [Configuring Single +Port](#configuring-transports.single-port) for details. + +Please refer to the openwire example for more coding details. + +Currently we support ActiveMQ clients that using standard JMS APIs. In +the future we will get more supports for some advanced, ActiveMQ +specific features into ActiveMQ.
