You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/08 16:49:32 UTC
[01/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Repository: activemq-6
Updated Branches:
refs/heads/master d42481db5 -> 6309dd042
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/src/main/resources/schemaToTable.xsl
----------------------------------------------------------------------
diff --git a/docs/user-manual/src/main/resources/schemaToTable.xsl b/docs/user-manual/src/main/resources/schemaToTable.xsl
deleted file mode 100644
index 85398c5..0000000
--- a/docs/user-manual/src/main/resources/schemaToTable.xsl
+++ /dev/null
@@ -1,374 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-
-<xsl:stylesheet version="2.0"
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema"
- xmlns:amq="urn:org.apache.activemq"
- xmlns:fn="http://www.w3.org/2005/xpath-functions">
-
- <!--
- XSL to transform ActiveMQ schemas into DocBook tables to be used in our user manual reference.
-
- For each option element defined in the schema, it tries to create something like
-
- <row>
- <entry>
- <link linkend="DocBookIdReference">ELEMENT-NAME</link>
- </entry>
- <entry>TYPE</entry>
- <entry>DESCRIPTION</entry>
- <entry>DEFAULT_VALUE</entry>
- </row>
-
- TODO:
- - generate Java code with the defaults (instead of duplicating them there).
- -->
-
- <xsl:output method="xml" indent="yes"/>
-
- <xsl:function name="amq:name-or-ref">
- <xsl:param name="ename"/>
- <xsl:param name="eref"/>
- <xsl:choose>
- <xsl:when test="string-length($ename) > 0 ">
- <xsl:value-of select="$ename"/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:value-of select="$eref"/>
- </xsl:otherwise>
- </xsl:choose>
- </xsl:function>
-
- <xsl:template match="/">
- <tbody>
-
- <xsl:comment>
- THIS IS A GENERATED FILE. DO NOT EDIT IT DIRECTLY!
-
- ActiveMQ options reference table generated from:
- <xsl:copy-of select="concat('activemq-', substring-after(base-uri(), 'activemq-'))"/>
-
- =======================================================================
-
- XSLT Version = <xsl:copy-of select="system-property('xsl:version')"/>
- XSLT Vendor = <xsl:copy-of select="system-property('xsl:vendor')"/>
- XSLT Vendor URL = <xsl:copy-of select="system-property('xsl:vendor-url')"/>
- <xsl:text>
</xsl:text>
- </xsl:comment>
-
- <!-- Add some new lines of text.. -->
- <xsl:text>
</xsl:text>
- <xsl:text>
</xsl:text>
-
- <!-- main 'for-each' for "activemq-configuration.xsd". Notice the attribute matching at the
- select which ensures this only matches "activemq-configuration.xsd". -->
- <xsl:for-each-group select="xsd:schema/xsd:element[@amq:schema='activemq-configuration']"
- group-by="@name">
- <!-- the manual reference should list options in sorted order.
- Notice that this is only OK because the first level of options is "xsd:all".
-
- Options of sub-types are not ordered because they are often "xsd:sequence" (meaning that
- their order matters), so those options should not have its order changed.
- -->
- <xsl:sort select="@name" data-type="text" />
-
- <!-- <xsl:if test="not(./xsd:annotation/@amq:linkend)"> -->
- <!-- <xsl:message terminate="yes"> -->
- <!-- Error: Lacks proper Docbook link: xsd:annotation/@amq:linkend -->
- <!-- <xsl:copy-of select="."/> -->
- <!-- </xsl:message> -->
- <!-- </xsl:if> -->
- <xsl:call-template name="xsd_element">
- <xsl:with-param name="prefix"/>
- <xsl:with-param name="parentLinkend" select="xsd:annotation/@amq:linkend"/>
- </xsl:call-template>
-
- <!-- Add 2 new lines between each option -->
- <xsl:text>
</xsl:text>
- <xsl:text>
</xsl:text>
- </xsl:for-each-group>
-
- <!-- JMS: main 'for-each' for "activemq-jms.xsd". Notice the attribute matching at the
- select which ensures this only matches "activemq-jms.xsd". -->
- <xsl:for-each select="xsd:schema/xsd:element[@amq:schema='activemq-jms-configuration']/xsd:complexType/xsd:sequence/xsd:element">
-
- <xsl:call-template name="xsd_element">
- <xsl:with-param name="prefix"/>
- <xsl:with-param name="parentLinkend" select="xsd:annotation/@amq:linkend"/>
- </xsl:call-template>
-
- <!-- Add 2 new lines between each option -->
- <xsl:text>
</xsl:text>
- <xsl:text>
</xsl:text>
- </xsl:for-each>
-
- </tbody>
- </xsl:template>
-
- <xsl:template name="xsd_complexType" match="xsd:complexType">
- <xsl:param name="prefix" />
- <xsl:param name="linkend" />
-
- <xsl:comment>
- 
VALUE OF COMPLEX TYPE

- </xsl:comment>
-
- <xsl:apply-templates select="xsd:attribute">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="parentLinkend" select="$linkend"/>
- </xsl:apply-templates>
-
- <xsl:for-each select="(xsd:sequence|xsd:all)/xsd:element">
- <xsl:call-template name="xsd_element">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="parentLinkend" select="$linkend"/>
- </xsl:call-template>
- </xsl:for-each>
- </xsl:template>
-
- <xsl:template name="entry-for-default-value">
- <entry>
- <xsl:value-of select="string-join((@default,xsd:annotation/@amq:default), ' ')"/>
- </entry>
- </xsl:template>
-
- <xsl:template name="entry-for-description">
- <entry>
- <xsl:value-of select="normalize-space(xsd:annotation/xsd:documentation)"/>
- </entry>
- </xsl:template>
-
- <xsl:template name="entry-for-simple-type">
- <entry>
- <xsl:value-of select="@type"/>
- </entry>
- </xsl:template>
-
- <xsl:template name="entry-type-of-complex-element">
- <entry>
- <xsl:choose>
- <xsl:when test="count(xsd:complexType/xsd:sequence/xsd:element)=1">
- <xsl:value-of
- select="concat('Sequence of <', xsd:complexType/xsd:sequence/xsd:element/( amq:name-or-ref(@name,@ref) ), '/>')"/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:text>Complex element</xsl:text>
- </xsl:otherwise>
- </xsl:choose>
- </entry>
- </xsl:template>
-
- <xsl:template match="xsd:attribute">
- <xsl:param name="prefix" />
- <xsl:param name="parentLinkend" />
-
- <xsl:variable name="linkend">
- <xsl:choose>
- <xsl:when test="xsd:annotation/@amq:linkend">
- <xsl:value-of select="xsd:annotation/@amq:linkend"/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:value-of select="$parentLinkend"/>
- </xsl:otherwise>
- </xsl:choose>
- </xsl:variable>
-
- <row>
- <entry>
- <xsl:element name="link">
- <xsl:attribute name="linkend">
- <xsl:value-of select="$linkend"/>
- </xsl:attribute>
- <xsl:value-of select="$prefix"/>
- <xsl:value-of select="@name"/>
- <xsl:text> (</xsl:text>
- <xsl:if test="@use = 'required'">
- <xsl:text>required </xsl:text>
- </xsl:if>
- <xsl:text>attribute)</xsl:text>
- </xsl:element>
- </entry>
- <xsl:call-template name="entry-for-simple-type"/>
- <xsl:call-template name="entry-for-description"/>
- <xsl:call-template name="entry-for-default-value"/>
- </row>
- </xsl:template>
-
-
- <!-- ELEMENT -->
- <xsl:template name="xsd_element">
- <xsl:param name="prefix" />
- <xsl:param name="parentLinkend" />
-
- <xsl:comment>
ELEMENT TEMPLATE name=<xsl:value-of select="@name"/>
- <xsl:text>
</xsl:text>
- </xsl:comment>
-
- <xsl:text>
</xsl:text>
- <!--
-
- We handle the following situations (differently):
- 1. <element name="foo" /> find definition using 'name'
- 2. <element name="foo>....</element>: complexType,simpleType,etc
- 3. <element name="foo" type="xsd:BUILTIN"/> 'simple' simpleType
- 4. <element name="foo" type="fooType"/> find definition using 'type'
- 5. <element ref="foo"> find definition using 'ref'
-
- -->
-
- <xsl:variable name="linkend">
- <xsl:choose>
- <xsl:when test="xsd:annotation/@amq:linkend">
- <xsl:value-of select="xsd:annotation/@amq:linkend"/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:value-of select="$parentLinkend"/>
- </xsl:otherwise>
- </xsl:choose>
- </xsl:variable>
-
- <xsl:choose>
-
- <xsl:when test="@name">
- <!-- cases 1,2,3,4 -->
-
- <xsl:choose>
- <!-- XSD:BUILT-IN -->
- <xsl:when test="starts-with(string(@type), 'xsd:')">
- <row>
- <xsl:call-template name="entry-for-name">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:call-template>
- <xsl:call-template name="entry-for-simple-type"/>
- <xsl:call-template name="entry-for-description"/>
- <xsl:call-template name="entry-for-default-value"/>
- </row>
- </xsl:when>
-
- <xsl:when test="not(@type)">
- <xsl:choose>
- <xsl:when test="xsd:complexType">
- <row>
- <xsl:call-template name="entry-for-name">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:call-template>
- <xsl:call-template name="entry-type-of-complex-element"/>
- <xsl:call-template name="entry-for-description"/>
- <entry/> <!-- complexTypes have no 'default' value. -->
- </row>
-
- <!-- backup-servers is a recursive type, which I need to take it out otherwise
- there would be an infinite recursive loop -->
- <xsl:if test="fn:not(@name='backup-servers')">
- <!-- Process child nodes -->
- <xsl:apply-templates select="xsd:complexType">
- <xsl:with-param name="prefix" select="concat($prefix,@name,'.')"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:apply-templates>
- </xsl:if>
- </xsl:when>
-
- <!-- simpleType. Normally string restrictions: A|B|C -->
- <xsl:when test="xsd:simpleType">
- <row>
- <xsl:call-template name="entry-for-name">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:call-template>
- <entry>
- <xsl:if test="xsd:simpleType/xsd:restriction[@base='xsd:string']">
- <xsl:value-of select="fn:string-join(xsd:simpleType/xsd:restriction/xsd:enumeration/@value,'|')"/>
- </xsl:if>
- </entry>
- <xsl:call-template name="entry-for-description"/>
- <xsl:call-template name="entry-for-default-value"/>
- </row>
- </xsl:when>
-
- <xsl:otherwise>
- <!-- the NAME is a reference -->
- <xsl:comment>
E.NAME-ref name=<xsl:copy-of select="@name"/><xsl:text>
</xsl:text></xsl:comment>
- <xsl:variable name="my-type" select="@name"/>
- <row>
- <xsl:call-template name="entry-for-name">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:call-template>
- <xsl:call-template name="entry-type-of-complex-element"/>
- <entry>
- <xsl:value-of select="normalize-space(xsd:annotation/xsd:documentation)"/>
- <xsl:value-of select="normalize-space(/xsd:schema/xsd:complexType[@name=$my-type]/xsd:annotation/xsd:documentation)"/>
- </entry>
- <entry/> <!-- no default value -->
- </row>
- <xsl:apply-templates select="/xsd:schema/xsd:complexType[@name=$my-type]">
- <xsl:with-param name="prefix" select="concat($prefix,@name,'.')"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:apply-templates>
- </xsl:otherwise>
- </xsl:choose>
- </xsl:when>
-
- <xsl:otherwise>
- <!-- the TYPE is a reference -->
- <!-- There is a type but it is not built-in, so we need to find its definition -->
- <xsl:variable name="my-type" select="@type"/>
- <row>
- <xsl:call-template name="entry-for-name">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:call-template>
- <xsl:call-template name="entry-type-of-complex-element"/>
- <entry>
- <xsl:value-of select="normalize-space(xsd:annotation/xsd:documentation)"/>
- <xsl:value-of select="normalize-space(/xsd:schema/xsd:complexType[@name=$my-type]/xsd:annotation/xsd:documentation)"/>
- </entry>
- <entry/> <!-- no default value -->
- </row>
- <xsl:comment>
ELEMENT TYPE-ref TEMPLATE CHILDREN
</xsl:comment>
- <xsl:text>
</xsl:text>
- <xsl:apply-templates select="/xsd:schema/xsd:complexType[@name=$my-type]">
- <xsl:with-param name="prefix" select="concat($prefix,@name,'.')"/>
- <xsl:with-param name="linkend" select="$linkend"/>
- </xsl:apply-templates>
- </xsl:otherwise>
- </xsl:choose>
-
- </xsl:when>
-
- <xsl:when test="@ref">
- <xsl:comment>
ELEMENT REF TEMPLATE ref=<xsl:copy-of select="@ref"/>
</xsl:comment>
- <xsl:text>
</xsl:text>
-
- <xsl:variable name="my-ref" select="@ref"/>
- <xsl:for-each select="/xsd:schema/xsd:element[ @name = string($my-ref) ]">
- <xsl:call-template name="xsd_element">
- <xsl:with-param name="prefix" select="$prefix"/>
- <xsl:with-param name="parentLinkend" select="$linkend"/>
- </xsl:call-template>
- </xsl:for-each>
- </xsl:when>
- <xsl:otherwise>
- <!-- FAIL? -->
- </xsl:otherwise>
- </xsl:choose>
- </xsl:template>
-
- <xsl:template name="entry-for-name">
- <xsl:param name="prefix" />
- <xsl:param name="linkend" />
-
- <entry>
- <xsl:element name="link">
- <xsl:attribute name="linkend">
- <xsl:value-of select="$linkend"/>
- </xsl:attribute>
- <xsl:value-of select="$prefix"/>
- <xsl:value-of select="@name"/>
- </xsl:element>
- </entry>
- </xsl:template>
-
-</xsl:stylesheet>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index caaeff9..f236376 100644
--- a/pom.xml
+++ b/pom.xml
@@ -494,7 +494,6 @@
<module>integration/activemq-aerogear-integration</module>
<module>integration/activemq-vertx-integration</module>
<module>examples</module>
- <module>docs</module>
<module>distribution</module>
</modules>
</profile>
[12/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/interoperability.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/interoperability.xml b/docs/user-manual/en/interoperability.xml
deleted file mode 100644
index f3f3bdd..0000000
--- a/docs/user-manual/en/interoperability.xml
+++ /dev/null
@@ -1,305 +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="interoperability">
- <title>Interoperability</title>
- <section id="stomp">
- <title>Stomp</title>
- <para><ulink url="http://stomp.github.com/">Stomp</ulink> 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.</para>
- <para>Stomp clients 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>ActiveMQ provides native support for Stomp. To be able to send and receive Stomp messages,
- you must configure a <literal>NettyAcceptor</literal> with a <literal>protocols</literal>
- parameter set to have <literal>stomp</literal>:</para>
-<programlisting>
-<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></programlisting>
- <para>With this configuration, ActiveMQ 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 ActiveMQ 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>
- <title>Stomp 1.1/1.2 Notes</title>
- <section>
- <title>Virtual Hosting</title>
- <para>ActiveMQ currently doesn't support virtual hosting, which means the 'host' header
- in CONNECT fram will be ignored.</para>
- </section>
- <section>
- <title>Heart-beating</title>
- <para>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.</para>
- </section>
- </section>
- </section>
-
- <section>
- <title>Mapping Stomp destinations to ActiveMQ 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 ActiveMQ, 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 ActiveMQ queue.</para>
- </section>
- <section>
- <title>STOMP and connection-ttl</title>
- <para>Well behaved STOMP clients will always send a DISCONNECT frame before closing their connections. In this case the server
- will clear up any server side resources such as sessions and consumers synchronously. However if STOMP clients exit without
- sending a DISCONNECT frame or if they crash the server will have no way of knowing immediately whether the client is still alive
- or not. STOMP connections therefore default to a connection-ttl value of 1 minute (see chapter on <link linkend="connection-ttl"
- >connection-ttl</link> for more information. This value can be overridden using connection-ttl-override.
- </para>
- <para>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:
- </para>
-<programlisting>
-<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></programlisting>
- <para>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.</para>
-
- <note><para>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 <literal>Stomp 1.1</literal> users can use heart-beats to maintain the life cycle of stomp
- connections.</para></note>
- </section>
-
- <section>
- <title>Stomp and JMS interoperability</title>
- <section>
- <title>Using JMS destinations</title>
- <para>As explained in <xref linkend="jms-core-mapping" />, 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:</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>Sending and consuming Stomp message from JMS or ActiveMQ Core API</title>
- <para>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 <literal>content-length</literal> header to decide how to map a Stomp message
- to a JMS Message or a Core message.
- </para>
- <para>If the Stomp message does <emphasis>not</emphasis> have a <literal>content-length</literal> header, it will be mapped to a JMS <emphasis>TextMessage</emphasis>
- or a Core message with a <emphasis>single nullable SimpleString in the body buffer</emphasis>.</para>
- <para>Alternatively, if the Stomp message <emphasis>has</emphasis> a <literal>content-length</literal> header,
- it will be mapped to a JMS <emphasis>BytesMessage</emphasis>
- or a Core message with a <emphasis>byte[] in the body buffer</emphasis>.</para>
- <para>The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp client can check the presence
- of the <literal>content-length</literal> header to determine the type of the message body (String or bytes).</para>
- </section>
- <section>
- <title>Message IDs for Stomp messages</title>
- <para>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 <literal>stomp-enable-message-id</literal> to true. For example:</para>
-<programlisting>
-<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></programlisting>
- <para>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 <literal>
- hq-message-id</literal> and the value is a String representation of a long type internal
- message id prefixed with "<literal>STOMP</literal>", like:
-<programlisting>
-hq-message-id : STOMP12345</programlisting>
- If <literal>stomp-enable-message-id</literal> is not specified in the configuration, default
- is <literal>false</literal>. </para>
- </section>
- <section>
- <title>Handling of Large Messages with Stomp</title>
- <para>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 <literal>stomp-min-large-message-size</literal>.
- This attribute can be configured inside a stomp acceptor, as a parameter. For example: </para>
-<programlisting>
- <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></programlisting>
- <para>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
- <literal>stomp-min-large-message</literal>, 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.</para>
- <para>If a large message is compressed, the server will uncompressed it before sending it to
- stomp clients. The default value of <literal>stomp-min-large-message-size</literal> is the same
- as the default value of <link linkend="large-messages.core.config">min-large-message-size</link>.</para>
- </section>
- </section>
-
- <section id="stomp.websockets">
- <title>Stomp Over Web Sockets</title>
- <para>ActiveMQ also support Stomp over <ulink url="http://dev.w3.org/html5/websockets/">Web Sockets</ulink>. Modern web browser which support Web Sockets can send and receive
- Stomp messages from ActiveMQ.</para>
- <para>To enable Stomp over Web Sockets, you must configure a <literal>NettyAcceptor</literal> with a <literal>protocol</literal>
- parameter set to <literal>stomp_ws</literal>:</para>
- <programlisting>
-<acceptor name="stomp-ws-acceptor">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
- <param key="protocols" value="STOMP_WS"/>
- <param key="port" value="61614"/>
-</acceptor></programlisting>
- <para>With this configuration, ActiveMQ will accept Stomp connections over Web Sockets on
- the port <literal>61614</literal> with the URL path <literal>/stomp</literal>.
- Web browser can then connect to <literal>ws://<server>:61614/stomp</literal> using a Web Socket to send and receive Stomp
- messages.</para>
- <para>A companion JavaScript library to ease client-side development is available from
- <ulink url="http://github.com/jmesnil/stomp-websocket">GitHub</ulink> (please see
- its <ulink url="http://jmesnil.net/stomp-websocket/doc/">documentation</ulink> for a complete description).</para>
- <para>The <literal>stomp-websockets</literal> example shows how to configure ActiveMQ server to have web browsers and Java
- applications exchanges messages on a JMS topic.</para>
- </section>
-
- <section id="stompconnect">
- <title>StompConnect</title>
- <para><ulink url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that
- can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
- Consequently, using StompConnect it is possible to turn ActiveMQ 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 ActiveMQ 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.apache.activemq.jndi.ActiveMQInitialContextFactory</programlisting>
- <para>Configure any required JNDI resources in this file according to the documentation.</para>
- <para>Make sure this file is in the classpath along with the StompConnect jar and the
- ActiveMQ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
- </section>
-
- </section>
- <section>
- <title>REST</title>
- <para>Please see <xref linkend="rest"/></para>
- </section>
- <section>
- <title>AMQP</title>
- <para>ActiveMQ supports the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink>
- specification. To enable AMQP you must configure a Netty Acceptor to receive AMQP clients, like so:</para>
- <programlisting>
-<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>
- </programlisting>
- <para>ActiveMQ will then accept AMQP 1.0 clients on port 5672 which is the default AMQP port.</para>
- <para>There are 2 Stomp examples available see proton-j and proton-ruby which use the qpid Java and Ruby clients
- respectively</para>
- <section>
- <title>AMQP and security</title>
- <para>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.</para>
- </section>
- <section>
- <title>AMQP Links</title>
- <para>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.</para>
- </section>
- <section>
- <title>AMQP and destinations</title>
- <para>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</para>
- <note><para>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</para></note>
- </section>
- <section>
- <title>AMQP and Coordinations - Handling Transactions</title>
- <para>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.</para>
- <note><para>AMQP allows the use of multiple transactions per session, <literal>amqp:multi-txns-per-ssn</literal>,
- however in this version ActiveMQ will only support single transactions per session</para></note>
- </section>
- </section>
- <section>
- <title>OpenWire</title>
- <para>ActiveMQ now supports the <ulink url="http://activemq.apache.org/openwire.html">OpenWire</ulink>
- 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:</para>
- <programlisting>
-<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>
- </programlisting>
- <para>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
- <link linkend="configuring-transports.single-port">Configuring Single Port</link> for details.</para>
- <para>Please refer to the openwire example for more coding details.</para>
- <para>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.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/jms-bridge.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/jms-bridge.md b/docs/user-manual/en/jms-bridge.md
new file mode 100644
index 0000000..437a177
--- /dev/null
+++ b/docs/user-manual/en/jms-bridge.md
@@ -0,0 +1,460 @@
+The JMS Bridge
+==============
+
+ActiveMQ includes a fully functional JMS message bridge.
+
+The function of the bridge is to consume messages from a source queue or
+topic, and send them to a target queue or topic, typically on a
+different server.
+
+The source and target servers do not have to be in the same cluster
+which makes bridging suitable for reliably sending messages from one
+cluster to another, for instance across a WAN, and where the connection
+may be unreliable.
+
+A bridge can be deployed as a standalone application, with ActiveMQ
+standalone server or inside a JBoss AS instance. The source and the
+target can be located in the same virtual machine or another one.
+
+The bridge can also be used to bridge messages from other non ActiveMQ
+JMS servers, as long as they are JMS 1.1 compliant.
+
+> **Note**
+>
+> Do not confuse a JMS bridge with a core bridge. A JMS bridge can be
+> used to bridge any two JMS 1.1 compliant JMS providers and uses the
+> JMS API. A core bridge (described in ?) is used to bridge any two
+> ActiveMQ instances and uses the core API. Always use a core bridge if
+> you can in preference to a JMS bridge. The core bridge will typically
+> provide better performance than a JMS bridge. Also the core bridge can
+> provide *once and only once* delivery guarantees without using XA.
+
+The bridge has built-in resilience to failure so if the source or target
+server connection is lost, e.g. due to network failure, the bridge will
+retry connecting to the source and/or target until they come back
+online. When it comes back online it will resume operation as normal.
+
+The bridge can be configured with an optional JMS selector, so it will
+only consume messages matching that JMS selector
+
+It can be configured to consume from a queue or a topic. When it
+consumes from a topic it can be configured to consume using a non
+durable or durable subscription
+
+Typically, the bridge is deployed by the JBoss Micro Container via a
+beans configuration file. This would typically be deployed inside the
+JBoss Application Server and the following example shows an example of a
+beans file that bridges 2 destinations which are actually on the same
+server.
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+ <bean name="JMSBridge" class="org.apache.activemq.api.jms.bridge.impl.JMSBridgeImpl">
+ <!-- ActiveMQ must be started before the bridge -->
+ <depends>ActiveMQServer</depends>
+ <constructor>
+ <!-- Source ConnectionFactory Factory -->
+ <parameter>
+ <inject bean="SourceCFF"/>
+ </parameter>
+ <!-- Target ConnectionFactory Factory -->
+ <parameter>
+ <inject bean="TargetCFF"/>
+ </parameter>
+ <!-- Source DestinationFactory -->
+ <parameter>
+ <inject bean="SourceDestinationFactory"/>
+ </parameter>
+ <!-- Target DestinationFactory -->
+ <parameter>
+ <inject bean="TargetDestinationFactory"/>
+ </parameter>
+ <!-- Source User Name (no username here) -->
+ <parameter><null /></parameter>
+ <!-- Source Password (no password here)-->
+ <parameter><null /></parameter>
+ <!-- Target User Name (no username here)-->
+ <parameter><null /></parameter>
+ <!-- Target Password (no password here)-->
+ <parameter><null /></parameter>
+ <!-- Selector -->
+ <parameter><null /></parameter>
+ <!-- Failure Retry Interval (in ms) -->
+ <parameter>5000</parameter>
+ <!-- Max Retries -->
+ <parameter>10</parameter>
+ <!-- Quality Of Service -->
+ <parameter>ONCE_AND_ONLY_ONCE</parameter>
+ <!-- Max Batch Size -->
+ <parameter>1</parameter>
+ <!-- Max Batch Time (-1 means infinite) -->
+ <parameter>-1</parameter>
+ <!-- Subscription name (no subscription name here)-->
+ <parameter><null /></parameter>
+ <!-- Client ID (no client ID here)-->
+ <parameter><null /></parameter>
+ <!-- Add MessageID In Header -->
+ <parameter>true</parameter>
+ <!-- register the JMS Bridge in the AS MBeanServer -->
+ <parameter>
+ <inject bean="MBeanServer"/>
+ </parameter>
+ <parameter>org.apache.activemq:service=JMSBridge</parameter>
+ </constructor>
+ <property name="transactionManager">
+ <inject bean="RealTransactionManager"/>
+ </property>
+ </bean>
+
+ <!-- SourceCFF describes the ConnectionFactory used to connect to the source destination -->
+ <bean name="SourceCFF"
+ class="org.apache.activemq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/ConnectionFactory</parameter>
+ </constructor>
+ </bean>
+
+ <!-- TargetCFF describes the ConnectionFactory used to connect to the target destination -->
+ <bean name="TargetCFF"
+ class="org.apache.activemq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/ConnectionFactory</parameter>
+ </constructor>
+ </bean>
+
+ <!-- SourceDestinationFactory describes the Destination used as the source -->
+ <bean name="SourceDestinationFactory" class="org.apache.activemq.api.jms.bridge.impl.JNDIDestinationFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/queue/source</parameter>
+ </constructor>
+ </bean>
+
+ <!-- TargetDestinationFactory describes the Destination used as the target -->
+ <bean name="TargetDestinationFactory" class="org.apache.activemq.api.jms.bridge.impl.JNDIDestinationFactory">
+ <constructor>
+ <parameter>
+ <inject bean="JNDI" />
+ </parameter>
+ <parameter>/queue/target</parameter>
+ </constructor>
+ </bean>
+
+ <!-- JNDI is a Hashtable containing the JNDI properties required -->
+ <!-- to connect to the sources and targets JMS resrouces -->
+ <bean name="JNDI" class="java.util.Hashtable">
+ <constructor class="java.util.Map">
+ <map class="java.util.Hashtable" keyClass="String"
+ valueClass="String">
+ <entry>
+ <key>java.naming.factory.initial</key>
+ <value>org.jnp.interfaces.NamingContextFactory</value>
+ </entry>
+ <entry>
+ <key>java.naming.provider.url</key>
+ <value>jnp://localhost:1099</value>
+ </entry>
+ <entry>
+ <key>java.naming.factory.url.pkgs</key>
+ <value>org.jboss.naming:org.jnp.interfaces"</value>
+ </entry>
+ <entry>
+ <key>jnp.timeout</key>
+ <value>5000</value>
+ </entry>
+ <entry>
+ <key>jnp.sotimeout</key>
+ <value>5000</value>
+ </entry>
+ </map>
+ </constructor>
+ </bean>
+
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator" factoryMethod="locateJBoss"/>
+ </bean>
+ </deployment>
+
+JMS Bridge Parameters
+=====================
+
+The main bean deployed is the `JMSBridge` bean. The bean is configurable
+by the parameters passed to its constructor.
+
+> **Note**
+>
+> To let a parameter be unspecified (for example, if the authentication
+> is anonymous or no message selector is provided), use `<null
+> />` for the unspecified parameter value.
+
+- Source Connection Factory Factory
+
+ This injects the `SourceCFF` bean (also defined in the beans file).
+ This bean is used to create the *source* `ConnectionFactory`
+
+- Target Connection Factory Factory
+
+ This injects the `TargetCFF` bean (also defined in the beans file).
+ This bean is used to create the *target* `ConnectionFactory`
+
+- Source Destination Factory Factory
+
+ This injects the `SourceDestinationFactory` bean (also defined in
+ the beans file). This bean is used to create the *source*
+ `Destination`
+
+- Target Destination Factory Factory
+
+ This injects the `TargetDestinationFactory` bean (also defined in
+ the beans file). This bean is used to create the *target*
+ `Destination`
+
+- Source User Name
+
+ this parameter is the username for creating the *source* connection
+
+- Source Password
+
+ this parameter is the parameter for creating the *source* connection
+
+- Target User Name
+
+ this parameter is the username for creating the *target* connection
+
+- Target Password
+
+ this parameter is the password for creating the *target* connection
+
+- Selector
+
+ This represents a JMS selector expression used for consuming
+ messages from the source destination. Only messages that match the
+ selector expression will be bridged from the source to the target
+ destination
+
+ The selector expression must follow the [JMS selector
+ syntax](http://docs.oracle.com/javaee/6/api/javax/jms/Message.html)
+
+- Failure Retry Interval
+
+ This represents the amount of time in ms to wait between trying to
+ recreate connections to the source or target servers when the bridge
+ has detected they have failed
+
+- Max Retries
+
+ This represents the number of times to attempt to recreate
+ connections to the source or target servers when the bridge has
+ detected they have failed. The bridge will give up after trying this
+ number of times. `-1` represents 'try forever'
+
+- Quality Of Service
+
+ This parameter represents the desired quality of service mode
+
+ Possible values are:
+
+ - `AT_MOST_ONCE`
+
+ - `DUPLICATES_OK`
+
+ - `ONCE_AND_ONLY_ONCE`
+
+ See ? for a explanation of these modes.
+
+- Max Batch Size
+
+ This represents the maximum number of messages to consume from the
+ source destination before sending them in a batch to the target
+ destination. Its value must `>= 1`
+
+- Max Batch Time
+
+ This represents the maximum number of milliseconds to wait before
+ sending a batch to target, even if the number of messages consumed
+ has not reached `MaxBatchSize`. Its value must be `-1` to represent
+ 'wait forever', or `>= 1` to specify an actual time
+
+- Subscription Name
+
+ If the source destination represents a topic, and you want to
+ consume from the topic using a durable subscription then this
+ parameter represents the durable subscription name
+
+- Client ID
+
+ If the source destination represents a topic, and you want to
+ consume from the topic using a durable subscription then this
+ attribute represents the the JMS client ID to use when
+ creating/looking up the durable subscription
+
+- Add MessageID In Header
+
+ If `true`, then the original message's message ID will be appended
+ in the message sent to the destination in the header
+ `ACTIVEMQ_BRIDGE_MSG_ID_LIST`. If the message is bridged more than
+ once, each message ID will be appended. This enables a distributed
+ request-response pattern to be used
+
+ > **Note**
+ >
+ > when you receive the message you can send back a response using
+ > the correlation id of the first message id, so when the original
+ > sender gets it back it will be able to correlate it.
+
+- MBean Server
+
+ To manage the JMS Bridge using JMX, set the MBeanServer where the
+ JMS Bridge MBean must be registered (e.g. the JVM Platform
+ MBeanServer or JBoss AS MBeanServer)
+
+- ObjectName
+
+ If you set the MBeanServer, you also need to set the ObjectName used
+ to register the JMS Bridge MBean (must be unique)
+
+The "transactionManager" property points to a JTA transaction manager
+implementation. ActiveMQ doesn't ship with such an implementation, but
+one is available in the JBoss Community. If you are running ActiveMQ in
+standalone mode and wish to use a JMS bridge simply download the latest
+version of JBossTS from http://www.jboss.org/jbosstm/downloads and add
+it to ActiveMQ's classpath. If you are running ActiveMQ with JBoss AS
+then you won't need to do this as JBoss AS ships with a JTA transaction
+manager already. The bean definition for the transaction manager would
+look something like this:
+
+ <bean name="RealTransactionManager" class="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/>
+
+Source and Target Connection Factories
+======================================
+
+The source and target connection factory factories are used to create
+the connection factory used to create the connection for the source or
+target server.
+
+The configuration example above uses the default implementation provided
+by ActiveMQ that looks up the connection factory using JNDI. For other
+Application Servers or JMS providers a new implementation may have to be
+provided. This can easily be done by implementing the interface
+`org.apache.activemq.jms.bridge.ConnectionFactoryFactory`.
+
+Source and Target Destination Factories
+=======================================
+
+Again, similarly, these are used to create or lookup up the
+destinations.
+
+In the configuration example above, we have used the default provided by
+ActiveMQ that looks up the destination using JNDI.
+
+A new implementation can be provided by implementing
+`org.apache.activemq.jms.bridge.DestinationFactory` interface.
+
+Quality Of Service
+==================
+
+The quality of service modes used by the bridge are described here in
+more detail.
+
+AT\_MOST\_ONCE
+--------------
+
+With this QoS mode messages will reach the destination from the source
+at most once. The messages are consumed from the source and acknowledged
+before sending to the destination. Therefore there is a possibility that
+if failure occurs between removing them from the source and them
+arriving at the destination they could be lost. Hence delivery will
+occur at most once.
+
+This mode is available for both durable and non-durable messages.
+
+DUPLICATES\_OK
+--------------
+
+With this QoS mode, the messages are consumed from the source and then
+acknowledged after they have been successfully sent to the destination.
+Therefore there is a possibility that if failure occurs after sending to
+the destination but before acknowledging them, they could be sent again
+when the system recovers. I.e. the destination might receive duplicates
+after a failure.
+
+This mode is available for both durable and non-durable messages.
+
+ONCE\_AND\_ONLY\_ONCE
+---------------------
+
+This QoS mode ensures messages will reach the destination from the
+source once and only once. (Sometimes this mode is known as "exactly
+once"). If both the source and the destination are on the same ActiveMQ
+server instance then this can be achieved by sending and acknowledging
+the messages in the same local transaction. If the source and
+destination are on different servers this is achieved by enlisting the
+sending and consuming sessions in a JTA transaction. The JTA transaction
+is controlled by JBoss Transactions JTA \* implementation which is a
+fully recovering transaction manager, thus providing a very high degree
+of durability. If JTA is required then both supplied connection
+factories need to be XAConnectionFactory implementations. This is likely
+to be the slowest mode since it requires extra persistence for the
+transaction logging.
+
+This mode is only available for durable messages.
+
+> **Note**
+>
+> For a specific application it may possible to provide once and only
+> once semantics without using the ONCE\_AND\_ONLY\_ONCE QoS level. This
+> can be done by using the DUPLICATES\_OK mode and then checking for
+> duplicates at the destination and discarding them. Some JMS servers
+> provide automatic duplicate message detection functionality, or this
+> may be possible to implement on the application level by maintaining a
+> cache of received message ids on disk and comparing received messages
+> to them. The cache would only be valid for a certain period of time so
+> this approach is not as watertight as using ONCE\_AND\_ONLY\_ONCE but
+> may be a good choice depending on your specific application.
+
+Time outs and the JMS bridge
+----------------------------
+
+There is a possibility that the target or source server will not be
+available at some point in time. If this occurs then the bridge will try
+`Max Retries` to reconnect every `Failure Retry Interval` milliseconds
+as specified in the JMS Bridge definition.
+
+However since a third party JNDI is used, in this case the JBoss naming
+server, it is possible for the JNDI lookup to hang if the network were
+to disappear during the JNDI lookup. To stop this from occurring the
+JNDI definition can be configured to time out if this occurs. To do this
+set the `jnp.timeout` and the `jnp.sotimeout` on the Initial Context
+definition. The first sets the connection timeout for the initial
+connection and the second the read timeout for the socket.
+
+> **Note**
+>
+> Once the initial JNDI connection has succeeded all calls are made
+> using RMI. If you want to control the timeouts for the RMI connections
+> then this can be done via system properties. JBoss uses Sun's RMI and
+> the properties can be found
+> [here](http://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html).
+> The default connection timeout is 10 seconds and the default read
+> timeout is 18 seconds.
+
+If you implement your own factories for looking up JMS resources then
+you will have to bear in mind timeout issues.
+
+Examples
+--------
+
+Please see ? which shows how to configure and use a JMS Bridge with
+JBoss AS to send messages to the source destination and consume them
+from the target destination.
+
+Please see ? which shows how to configure and use a JMS Bridge between
+two standalone ActiveMQ servers.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/jms-bridge.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/jms-bridge.xml b/docs/user-manual/en/jms-bridge.xml
deleted file mode 100644
index bc5dd5c..0000000
--- a/docs/user-manual/en/jms-bridge.xml
+++ /dev/null
@@ -1,449 +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="jms-bridge">
- <title>The JMS Bridge</title>
- <para>ActiveMQ includes a fully functional JMS message bridge.</para>
- <para>The function of the bridge is to consume messages from a source queue or topic, and
- send them to a target queue or topic, typically on a different server.</para>
- <para>The source and target servers do not have to be in the same cluster which makes
- bridging suitable for reliably sending messages from one cluster to another, for
- instance across a WAN, and where the connection may be unreliable.</para>
- <para>A bridge can be deployed as a standalone application, with ActiveMQ standalone server or inside a JBoss AS
- instance. The source and the target can be located in the same virtual machine or another one.</para>
- <para>The bridge can also be used to bridge messages from other non ActiveMQ JMS servers, as
- long as they are JMS 1.1 compliant.<note><para>Do not confuse a JMS bridge with a core
- bridge. A JMS bridge can be used to bridge any two JMS 1.1 compliant JMS
- providers and uses the JMS API. A core bridge (described in <xref
- linkend="core-bridges"/>) is used to bridge any two ActiveMQ instances and
- uses the core API. Always use a core bridge if you can in preference to a JMS
- bridge. The core bridge will typically provide better performance than a JMS
- bridge. Also the core bridge can provide <emphasis>once and only once</emphasis>
- delivery guarantees without using XA.</para></note></para>
- <para>The bridge has built-in resilience to failure so if the source or target server
- connection is lost, e.g. due to network failure, the bridge will retry connecting to the
- source and/or target until they come back online. When it comes back online it will
- resume operation as normal.</para>
- <para>The bridge can be configured with an optional JMS selector, so it will only consume
- messages matching that JMS selector</para>
- <para>It can be configured to consume from a queue or a topic. When it consumes from a topic
- it can be configured to consume using a non durable or durable subscription</para>
- <para>Typically, the bridge is deployed by the JBoss Micro Container via a beans configuration file.
- This would typically be deployed inside the JBoss Application Server and the following
- example shows an example of a beans file that bridges 2 destinations which are actually
- on the same server. </para>
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<deployment xmlns="urn:jboss:bean-deployer:2.0">
- <bean name="JMSBridge" class="org.apache.activemq.api.jms.bridge.impl.JMSBridgeImpl">
- <!-- ActiveMQ must be started before the bridge -->
- <depends>ActiveMQServer</depends>
- <constructor>
- <!-- Source ConnectionFactory Factory -->
- <parameter>
- <inject bean="SourceCFF"/>
- </parameter>
- <!-- Target ConnectionFactory Factory -->
- <parameter>
- <inject bean="TargetCFF"/>
- </parameter>
- <!-- Source DestinationFactory -->
- <parameter>
- <inject bean="SourceDestinationFactory"/>
- </parameter>
- <!-- Target DestinationFactory -->
- <parameter>
- <inject bean="TargetDestinationFactory"/>
- </parameter>
- <!-- Source User Name (no username here) -->
- <parameter><null /></parameter>
- <!-- Source Password (no password here)-->
- <parameter><null /></parameter>
- <!-- Target User Name (no username here)-->
- <parameter><null /></parameter>
- <!-- Target Password (no password here)-->
- <parameter><null /></parameter>
- <!-- Selector -->
- <parameter><null /></parameter>
- <!-- Failure Retry Interval (in ms) -->
- <parameter>5000</parameter>
- <!-- Max Retries -->
- <parameter>10</parameter>
- <!-- Quality Of Service -->
- <parameter>ONCE_AND_ONLY_ONCE</parameter>
- <!-- Max Batch Size -->
- <parameter>1</parameter>
- <!-- Max Batch Time (-1 means infinite) -->
- <parameter>-1</parameter>
- <!-- Subscription name (no subscription name here)-->
- <parameter><null /></parameter>
- <!-- Client ID (no client ID here)-->
- <parameter><null /></parameter>
- <!-- Add MessageID In Header -->
- <parameter>true</parameter>
- <!-- register the JMS Bridge in the AS MBeanServer -->
- <parameter>
- <inject bean="MBeanServer"/>
- </parameter>
- <parameter>org.apache.activemq:service=JMSBridge</parameter>
- </constructor>
- <property name="transactionManager">
- <inject bean="RealTransactionManager"/>
- </property>
- </bean>
-
- <!-- SourceCFF describes the ConnectionFactory used to connect to the source destination -->
- <bean name="SourceCFF"
- class="org.apache.activemq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
- <constructor>
- <parameter>
- <inject bean="JNDI" />
- </parameter>
- <parameter>/ConnectionFactory</parameter>
- </constructor>
- </bean>
-
- <!-- TargetCFF describes the ConnectionFactory used to connect to the target destination -->
- <bean name="TargetCFF"
- class="org.apache.activemq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
- <constructor>
- <parameter>
- <inject bean="JNDI" />
- </parameter>
- <parameter>/ConnectionFactory</parameter>
- </constructor>
- </bean>
-
- <!-- SourceDestinationFactory describes the Destination used as the source -->
- <bean name="SourceDestinationFactory" class="org.apache.activemq.api.jms.bridge.impl.JNDIDestinationFactory">
- <constructor>
- <parameter>
- <inject bean="JNDI" />
- </parameter>
- <parameter>/queue/source</parameter>
- </constructor>
- </bean>
-
- <!-- TargetDestinationFactory describes the Destination used as the target -->
- <bean name="TargetDestinationFactory" class="org.apache.activemq.api.jms.bridge.impl.JNDIDestinationFactory">
- <constructor>
- <parameter>
- <inject bean="JNDI" />
- </parameter>
- <parameter>/queue/target</parameter>
- </constructor>
- </bean>
-
- <!-- JNDI is a Hashtable containing the JNDI properties required -->
- <!-- to connect to the sources and targets JMS resrouces -->
- <bean name="JNDI" class="java.util.Hashtable">
- <constructor class="java.util.Map">
- <map class="java.util.Hashtable" keyClass="String"
- valueClass="String">
- <entry>
- <key>java.naming.factory.initial</key>
- <value>org.jnp.interfaces.NamingContextFactory</value>
- </entry>
- <entry>
- <key>java.naming.provider.url</key>
- <value>jnp://localhost:1099</value>
- </entry>
- <entry>
- <key>java.naming.factory.url.pkgs</key>
- <value>org.jboss.naming:org.jnp.interfaces"</value>
- </entry>
- <entry>
- <key>jnp.timeout</key>
- <value>5000</value>
- </entry>
- <entry>
- <key>jnp.sotimeout</key>
- <value>5000</value>
- </entry>
- </map>
- </constructor>
- </bean>
-
- <bean name="MBeanServer" class="javax.management.MBeanServer">
- <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator" factoryMethod="locateJBoss"/>
- </bean>
-</deployment></programlisting>
- <section>
- <title>JMS Bridge Parameters</title>
- <para>The main bean deployed is the <literal>JMSBridge</literal> bean. The bean is
- configurable by the parameters passed to its constructor.</para>
- <note>
- <para>To let a parameter be unspecified (for example, if the authentication is
- anonymous or no message selector is provided), use <literal><null
- /></literal> for the unspecified parameter value.</para>
- </note>
- <itemizedlist>
- <listitem>
- <para>Source Connection Factory Factory</para>
- <para>This injects the <literal>SourceCFF</literal> bean (also defined in the
- beans file). This bean is used to create the <emphasis>source</emphasis>
- <literal>ConnectionFactory</literal>
- </para>
- </listitem>
- <listitem>
- <para>Target Connection Factory Factory</para>
- <para>This injects the <literal>TargetCFF</literal> bean (also defined in the
- beans file). This bean is used to create the <emphasis>target</emphasis>
- <literal>ConnectionFactory</literal>
- </para>
- </listitem>
- <listitem>
- <para>Source Destination Factory Factory</para>
- <para>This injects the <literal>SourceDestinationFactory</literal> bean (also
- defined in the beans file). This bean is used to create the
- <emphasis>source</emphasis>
- <literal>Destination</literal>
- </para>
- </listitem>
- <listitem>
- <para>Target Destination Factory Factory</para>
- <para>This injects the <literal>TargetDestinationFactory</literal> bean (also
- defined in the beans file). This bean is used to create the
- <emphasis>target</emphasis>
- <literal>Destination</literal>
- </para>
- </listitem>
- <listitem>
- <para>Source User Name</para>
- <para>this parameter is the username for creating the
- <emphasis>source</emphasis> connection</para>
- </listitem>
- <listitem>
- <para>Source Password</para>
- <para>this parameter is the parameter for creating the
- <emphasis>source</emphasis> connection</para>
- </listitem>
- <listitem>
- <para>Target User Name</para>
- <para>this parameter is the username for creating the
- <emphasis>target</emphasis> connection</para>
- </listitem>
- <listitem>
- <para>Target Password</para>
- <para>this parameter is the password for creating the
- <emphasis>target</emphasis> connection</para>
- </listitem>
- <listitem>
- <para>Selector</para>
- <para>This represents a JMS selector expression used for consuming messages from
- the source destination. Only messages that match the selector expression
- will be bridged from the source to the target destination</para>
- <para>The selector expression must follow the <ulink
- url="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html">JMS
- selector syntax</ulink></para>
- </listitem>
- <listitem>
- <para>Failure Retry Interval</para>
- <para>This represents the amount of time in ms to wait between trying to
- recreate connections to the source or target servers when the bridge has
- detected they have failed</para>
- </listitem>
- <listitem>
- <para>Max Retries</para>
- <para>This represents the number of times to attempt to recreate connections to
- the source or target servers when the bridge has detected they have failed.
- The bridge will give up after trying this number of times. <literal
- >-1</literal> represents 'try forever'</para>
- </listitem>
- <listitem>
- <para>Quality Of Service</para>
- <para>This parameter represents the desired quality of service mode</para>
- <para>Possible values are:</para>
- <itemizedlist>
- <listitem>
- <para><literal>AT_MOST_ONCE</literal></para>
- </listitem>
- <listitem>
- <para><literal>DUPLICATES_OK</literal></para>
- </listitem>
- <listitem>
- <para><literal>ONCE_AND_ONLY_ONCE</literal></para>
- </listitem>
- </itemizedlist>
- <para>See <xref linkend="quality-of-service"/> for a explanation of these
- modes.</para>
- </listitem>
- <listitem>
- <para>Max Batch Size</para>
- <para>This represents the maximum number of messages to consume from the source
- destination before sending them in a batch to the target destination. Its
- value must <literal>>= 1</literal>
- </para>
- </listitem>
- <listitem>
- <para>Max Batch Time</para>
- <para>This represents the maximum number of milliseconds to wait before sending
- a batch to target, even if the number of messages consumed has not reached
- <literal>MaxBatchSize</literal>. Its value must be <literal>-1</literal>
- to represent 'wait forever', or <literal>>= 1</literal> to specify an actual
- time </para>
- </listitem>
- <listitem>
- <para>Subscription Name</para>
- <para>If the source destination represents a topic, and you want to consume from
- the topic using a durable subscription then this parameter represents the
- durable subscription name</para>
- </listitem>
- <listitem>
- <para>Client ID</para>
- <para>If the source destination represents a topic, and you want to consume from
- the topic using a durable subscription then this attribute represents the
- the JMS client ID to use when creating/looking up the durable
- subscription</para>
- </listitem>
- <listitem>
- <para>Add MessageID In Header</para>
- <para>If <literal>true</literal>, then the original message's message ID will be
- appended in the message sent to the destination in the header <literal
- >ACTIVEMQ_BRIDGE_MSG_ID_LIST</literal>. If the message is bridged more
- than once, each message ID will be appended. This enables a distributed
- request-response pattern to be used</para>
- <note>
- <para>when you receive the message you can send back a response using the
- correlation id of the first message id, so when the original sender gets
- it back it will be able to correlate it. </para>
- </note>
- </listitem>
- <listitem>
- <para>MBean Server</para>
- <para>To manage the JMS Bridge using JMX, set the MBeanServer where the JMS Bridge MBean
- must be registered (e.g. the JVM Platform MBeanServer or JBoss AS MBeanServer)</para>
- </listitem>
- <listitem>
- <para>ObjectName</para>
- <para>If you set the MBeanServer, you also need to set the ObjectName used to register
- the JMS Bridge MBean (must be unique)</para>
- </listitem>
- </itemizedlist>
- <para>The "transactionManager" property points to a JTA transaction manager implementation.
- ActiveMQ doesn't ship with such an implementation, but one is available in the JBoss
- Community. If you are running ActiveMQ in standalone mode and wish to use a JMS bridge
- simply download the latest version of JBossTS from http://www.jboss.org/jbosstm/downloads
- and add it to ActiveMQ's classpath. If you are running ActiveMQ with JBoss AS then you
- won't need to do this as JBoss AS ships with a JTA transaction manager already. The
- bean definition for the transaction manager would look something like this:
- </para>
- <programlisting><bean name="RealTransactionManager" class="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/></programlisting>
- </section>
- <section>
- <title>Source and Target Connection Factories</title>
- <para>The source and target connection factory factories are used to create the
- connection factory used to create the connection for the source or target
- server.</para>
- <para>The configuration example above uses the default implementation provided by
- ActiveMQ that looks up the connection factory using JNDI. For other Application
- Servers or JMS providers a new implementation may have to be provided. This can
- easily be done by implementing the interface <literal
- >org.apache.activemq.jms.bridge.ConnectionFactoryFactory</literal>.</para>
- </section>
- <section>
- <title>Source and Target Destination Factories</title>
- <para>Again, similarly, these are used to create or lookup up the destinations.</para>
- <para>In the configuration example above, we have used the default provided by ActiveMQ
- that looks up the destination using JNDI.</para>
- <para>A new implementation can be provided by implementing <literal
- >org.apache.activemq.jms.bridge.DestinationFactory</literal> interface.</para>
- </section>
- <section id="quality-of-service">
- <title>Quality Of Service</title>
- <para>The quality of service modes used by the bridge are described here in more
- detail.</para>
- <section>
- <title>AT_MOST_ONCE</title>
- <para>With this QoS mode messages will reach the destination from the source at most
- once. The messages are consumed from the source and acknowledged before sending
- to the destination. Therefore there is a possibility that if failure occurs
- between removing them from the source and them arriving at the destination they
- could be lost. Hence delivery will occur at most once.</para>
- <para>This mode is available for both durable and non-durable messages.</para>
- </section>
- <section>
- <title>DUPLICATES_OK</title>
- <para>With this QoS mode, the messages are consumed from the source and then
- acknowledged after they have been successfully sent to the destination.
- Therefore there is a possibility that if failure occurs after sending to the
- destination but before acknowledging them, they could be sent again when the
- system recovers. I.e. the destination might receive duplicates after a
- failure.</para>
- <para>This mode is available for both durable and non-durable messages.</para>
- </section>
- <section>
- <title>ONCE_AND_ONLY_ONCE</title>
- <para>This QoS mode ensures messages will reach the destination from the source once
- and only once. (Sometimes this mode is known as "exactly once"). If both the
- source and the destination are on the same ActiveMQ server instance then this can
- be achieved by sending and acknowledging the messages in the same local
- transaction. If the source and destination are on different servers this is
- achieved by enlisting the sending and consuming sessions in a JTA transaction.
- The JTA transaction is controlled by JBoss Transactions JTA * implementation
- which is a fully recovering transaction manager, thus providing a very high
- degree of durability. If JTA is required then both supplied connection factories
- need to be XAConnectionFactory implementations. This is likely to be the slowest
- mode since it requires extra persistence for the transaction logging.</para>
- <para>This mode is only available for durable messages.</para>
- <note>
- <para>For a specific application it may possible to provide once and only once
- semantics without using the ONCE_AND_ONLY_ONCE QoS level. This can be done
- by using the DUPLICATES_OK mode and then checking for duplicates at the
- destination and discarding them. Some JMS servers provide automatic
- duplicate message detection functionality, or this may be possible to
- implement on the application level by maintaining a cache of received
- message ids on disk and comparing received messages to them. The cache would
- only be valid for a certain period of time so this approach is not as
- watertight as using ONCE_AND_ONLY_ONCE but may be a good choice depending on
- your specific application.</para>
- </note>
- </section>
- <section>
- <title>Time outs and the JMS bridge</title>
- <para>There is a possibility that the target or source server will not be available at some point in time.
- If this occurs then the bridge will try <literal>Max Retries</literal> to reconnect every
- <literal>Failure Retry Interval</literal> milliseconds as specified in the JMS Bridge definition.</para>
- <para>However since a third party JNDI is used, in this case the JBoss naming server, it is possible for the
- JNDI lookup to hang if the network were to disappear during the JNDI lookup. To stop this from occurring the JNDI
- definition can be configured to time out if this occurs. To do this set the <literal>jnp.timeout</literal>
- and the <literal>jnp.sotimeout</literal> on the Initial Context definition. The first sets the connection
- timeout for the initial connection and the second the read timeout for the socket.</para>
- <note>
- <para>Once the initial JNDI connection has succeeded all calls are made using RMI. If you want to control
- the timeouts for the RMI connections then this can be done via system properties. JBoss uses Sun's RMI
- and the properties can be found <ulink
- url="http://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html">here</ulink>.
- The default connection timeout is 10 seconds and the default read timeout is 18 seconds.</para>
- </note>
- <para>If you implement your own factories for looking up JMS resources then you will have to bear in mind timeout issues.</para>
- </section>
- <section>
- <title>Examples</title>
- <para>Please see <xref linkend="examples.javaee.jms-bridge"/> which shows how to configure
- and use a JMS Bridge with JBoss AS to send messages to the source destination and consume them
- from the target destination.</para>
- <para>Please see <xref linkend="examples.jms.jms-bridge"/> which shows how to configure
- and use a JMS Bridge between two standalone ActiveMQ servers.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/jms-core-mapping.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/jms-core-mapping.md b/docs/user-manual/en/jms-core-mapping.md
new file mode 100644
index 0000000..0be2829
--- /dev/null
+++ b/docs/user-manual/en/jms-core-mapping.md
@@ -0,0 +1,39 @@
+Mapping JMS Concepts to the Core API
+====================================
+
+This chapter describes how JMS destinations are mapped to ActiveMQ
+addresses.
+
+ActiveMQ core is JMS-agnostic. It does not have any concept of a JMS
+topic. A JMS topic is implemented in core as an address (the topic name)
+with zero or more queues bound to it. Each queue bound to that address
+represents a topic subscription. Likewise, a JMS queue is implemented as
+an address (the JMS queue name) with one single queue bound to it which
+represents the JMS queue.
+
+By convention, all JMS queues map to core queues where the core queue
+name has the string `jms.queue.` prepended to it. E.g. the JMS queue
+with the name "orders.europe" would map to the core queue with the name
+"jms.queue.orders.europe". The address at which the core queue is bound
+is also given by the core queue name.
+
+For JMS topics the address at which the queues that represent the
+subscriptions are bound is given by prepending the string "jms.topic."
+to the name of the JMS topic. E.g. the JMS topic with name "news.europe"
+would map to the core address "jms.topic.news.europe"
+
+In other words if you send a JMS message to a JMS queue with name
+"orders.europe" it will get routed on the server to any core queues
+bound to the address "jms.queue.orders.europe". If you send a JMS
+message to a JMS topic with name "news.europe" it will get routed on the
+server to any core queues bound to the address "jms.topic.news.europe".
+
+If you want to configure settings for a JMS Queue with the name
+"orders.europe", you need to configure the corresponding core queue
+"jms.queue.orders.europe":
+
+ <!-- expired messages in JMS Queue "orders.europe" will be sent to the JMS Queue "expiry.europe" -->
+ <address-setting match="jms.queue.orders.europe">
+ <expiry-address>jms.queue.expiry.europe</expiry-address>
+ ...
+ </address-setting>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/jms-core-mapping.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/jms-core-mapping.xml b/docs/user-manual/en/jms-core-mapping.xml
deleted file mode 100644
index ae44f76..0000000
--- a/docs/user-manual/en/jms-core-mapping.xml
+++ /dev/null
@@ -1,50 +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="jms-core-mapping">
- <title>Mapping JMS Concepts to the Core API</title>
- <para>This chapter describes how JMS destinations are mapped to ActiveMQ addresses.</para>
- <para>ActiveMQ core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS topic is
- implemented in core as an address (the topic name) with zero or more queues bound to it.
- Each queue bound to that address represents a topic subscription. Likewise, a JMS queue is
- implemented as an address (the JMS queue name) with one single queue bound to it which
- represents the JMS queue.</para>
- <para>By convention, all JMS queues map to core queues where the core queue name has the string
- <literal>jms.queue.</literal> prepended to it. E.g. the JMS queue with the name
- "orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The
- address at which the core queue is bound is also given by the core queue name.</para>
- <para>For JMS topics the address at which the queues that represent the subscriptions are bound
- is given by prepending the string "jms.topic." to the name of the JMS topic. E.g. the JMS
- topic with name "news.europe" would map to the core address "jms.topic.news.europe"</para>
- <para>In other words if you send a JMS message to a JMS queue with name "orders.europe" it will
- get routed on the server to any core queues bound to the address "jms.queue.orders.europe".
- If you send a JMS message to a JMS topic with name "news.europe" it will get routed on the
- server to any core queues bound to the address "jms.topic.news.europe".</para>
- <para>If you want to configure settings for a JMS Queue with the name "orders.europe", you need
- to configure the corresponding core queue "jms.queue.orders.europe":</para>
- <programlisting>
-<!-- expired messages in JMS Queue "orders.europe" will be sent to the JMS Queue "expiry.europe" -->
-<address-setting match="jms.queue.orders.europe">
- <expiry-address>jms.queue.expiry.europe</expiry-address>
- ...
-</address-setting></programlisting>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/large-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/large-messages.md b/docs/user-manual/en/large-messages.md
new file mode 100644
index 0000000..b04f201
--- /dev/null
+++ b/docs/user-manual/en/large-messages.md
@@ -0,0 +1,275 @@
+Large Messages
+==============
+
+ActiveMQ supports sending and receiving of huge messages, even when the
+client and server are running with limited memory. The only realistic
+limit to the size of a message that can be sent or consumed is the
+amount of disk space you have available. We have tested sending and
+consuming messages up to 8 GiB in size with a client and server running
+in just 50MiB of RAM!
+
+To send a large message, the user can set an `InputStream` on a message
+body, and when that message is sent, ActiveMQ will read the
+`InputStream`. A `FileInputStream` could be used for example to send a
+huge message from a huge file on disk.
+
+As the `InputStream` is read the data is sent to the server as a stream
+of fragments. The server persists these fragments to disk as it receives
+them and when the time comes to deliver them to a consumer they are read
+back of the disk, also in fragments and sent down the wire. When the
+consumer receives a large message it initially receives just the message
+with an empty body, it can then set an `OutputStream` on the message to
+stream the huge message body to a file on disk or elsewhere. At no time
+is the entire message body stored fully in memory, either on the client
+or the server.
+
+Configuring the server
+======================
+
+Large messages are stored on a disk directory on the server side, as
+configured on the main configuration file.
+
+The configuration property `large-messages-directory` specifies where
+large messages are stored.
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
+ ...
+ <large-messages-directory>/data/large-messages</large-messages-directory>
+ ...
+ </configuration
+
+By default the large message directory is `data/largemessages`
+
+For the best performance we recommend large messages directory is stored
+on a different physical volume to the message journal or paging
+directory.
+
+Configuring Parameters
+======================
+
+Any message larger than a certain size is considered a large message.
+Large messages will be split up and sent in fragments. This is
+determined by the parameter `min-large-message-size`
+
+> **Note**
+>
+> ActiveMQ messages are encoded using 2 bytes per character so if the
+> message data is filled with ASCII characters (which are 1 byte) the
+> size of the resulting ActiveMQ message would roughly double. This is
+> important when calculating the size of a "large" message as it may
+> appear to be less than the `min-large-message-size` before it is sent,
+> but it then turns into a "large" message once it is encoded.
+
+The default value is 100KiB.
+
+Using Core API
+--------------
+
+If the ActiveMQ Core API is used, the minimal large message size is
+specified by `ServerLocator.setMinLargeMessageSize`.
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName()))
+
+ locator.setMinLargeMessageSize(25 * 1024);
+
+ ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory();
+
+? will provide more information on how to instantiate the session
+factory.
+
+Using JMS
+---------
+
+If JNDI is used to instantiate and look up the connection factory, the
+minimum large message size is configured in the JNDI context
+environment, e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.minLargeMessageSize=250000
+
+
+If the connection factory is being instantiated directly, the minimum
+large message size is specified by
+`ActiveMQConnectionFactory.setMinLargeMessageSize`.
+
+Compressed Large Messages
+-------------------------
+
+You can choose to send large messages in compressed form using `
+ compress-large-messages` attributes.
+
+### `compress-large-messages`
+
+If you specify the boolean property `compress-large-messages` on the
+`server locator` or `ConnectionFactory` as true, The system will use the
+ZIP algorithm to compress the message body as the message is transferred
+to the server's side. Notice that there's no special treatment at the
+server's side, all the compressing and uncompressing is done at the
+client.
+
+If the compressed size of a large message is below `
+ min-large-message-size`, it is sent to server as regular
+messages. This means that the message won't be written into the server's
+large-message data directory, thus reducing the disk I/O.
+
+###
+
+If JNDI is used to instantiate and look up the connection factory, large
+message compression can be configured in the JNDI context environment,
+e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.compressLargeMessages=true
+
+Streaming large messages
+========================
+
+ActiveMQ supports setting the body of messages using input and output
+streams (`java.lang.io`)
+
+These streams are then used directly for sending (input streams) and
+receiving (output streams) messages.
+
+When receiving messages there are 2 ways to deal with the output stream;
+you may choose to block while the output stream is recovered using the
+method `ClientMessage.saveOutputStream` or alternatively using the
+method `ClientMessage.setOutputstream` which will asynchronously write
+the message to the stream. If you choose the latter the consumer must be
+kept alive until the message has been fully received.
+
+You can use any kind of stream you like. The most common use case is to
+send files stored in your disk, but you could also send things like JDBC
+Blobs, `SocketInputStream`, things you recovered from `HTTPRequests`
+etc. Anything as long as it implements `java.io.InputStream` for sending
+messages or `java.io.OutputStream` for receiving them.
+
+Streaming over Core API
+-----------------------
+
+The following table shows a list of methods available at `ClientMessage`
+which are also available through JMS by the use of object properties.
+
+ Name Description JMS Equivalent Property
+ --------------------------------- ---------------------------------------------------------------------------------------------------------------------------------- -------------------------
+ setBodyInputStream(InputStream) Set the InputStream used to read a message body when sending it. JMS\_HQ\_InputStream
+ setOutputStream(OutputStream) Set the OutputStream that will receive the body of a message. This method does not block. JMS\_HQ\_OutputStream
+ saveOutputStream(OutputStream) Save the body of the message to the `OutputStream`. It will block until the entire content is transferred to the `OutputStream`. JMS\_HQ\_SaveStream
+
+ : org.apache.activemq.api.core.client.ClientMessage API
+
+To set the output stream when receiving a core message:
+
+ ...
+ ClientMessage msg = consumer.receive(...);
+
+
+ // This will block here until the stream was transferred
+ msg.saveOutputStream(someOutputStream);
+
+ ClientMessage msg2 = consumer.receive(...);
+
+ // This will not wait the transfer to finish
+ msg.setOutputStream(someOtherOutputStream);
+ ...
+
+Set the input stream when sending a core message:
+
+ ...
+ ClientMessage msg = session.createMessage();
+ msg.setInputStream(dataInputStream);
+ ...
+
+Notice also that for messages with more than 2GiB the getBodySize() will
+return invalid values since this is an integer (which is also exposed to
+the JMS API). On those cases you can use the message property
+\_HQ\_LARGE\_SIZE.
+
+Streaming over JMS
+------------------
+
+When using JMS, ActiveMQ maps the streaming methods on the core API (see
+?) by setting object properties . You can use the method
+`Message.setObjectProperty` to set the input and output streams.
+
+The `InputStream` can be defined through the JMS Object Property
+JMS\_HQ\_InputStream on messages being sent:
+
+ BytesMessage message = session.createBytesMessage();
+
+ FileInputStream fileInputStream = new FileInputStream(fileInput);
+
+ BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
+
+ message.setObjectProperty("JMS_HQ_InputStream", bufferedInput);
+
+ someProducer.send(message);
+
+The `OutputStream` can be set through the JMS Object Property
+JMS\_HQ\_SaveStream on messages being received in a blocking way.
+
+ BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
+
+ File outputFile = new File("huge_message_received.dat");
+
+ FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
+
+ BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
+
+ // This will block until the entire content is saved on disk
+ messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);
+
+Setting the `OutputStream` could also be done in a non blocking way
+using the property JMS\_HQ\_OutputStream.
+
+ // This won't wait the stream to finish. You need to keep the consumer active.
+ messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
+
+> **Note**
+>
+> When using JMS, Streaming large messages are only supported on
+> `StreamMessage` and `BytesMessage`.
+
+Streaming Alternative
+=====================
+
+If you choose not to use the `InputStream` or `OutputStream` capability
+of ActiveMQ You could still access the data directly in an alternative
+fashion.
+
+On the Core API just get the bytes of the body as you normally would.
+
+ ClientMessage msg = consumer.receive();
+
+ byte[] bytes = new byte[1024];
+ for (int i = 0 ; i < msg.getBodySize(); i += bytes.length)
+ {
+ msg.getBody().readBytes(bytes);
+ // Whatever you want to do with the bytes
+ }
+
+If using JMS API, `BytesMessage` and `StreamMessage` also supports it
+transparently.
+
+ BytesMessage rm = (BytesMessage)cons.receive(10000);
+
+ byte data[] = new byte[1024];
+
+ for (int i = 0; i < rm.getBodyLength(); i += 1024)
+ {
+ int numberOfBytes = rm.readBytes(data);
+ // Do whatever you want with the data
+ }
+
+Large message example
+=====================
+
+Please see ? for an example which shows how large message is configured
+and used with JMS.
[21/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/ActiveMQ_User_Manual.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/ActiveMQ_User_Manual.xml b/docs/user-manual/en/ActiveMQ_User_Manual.xml
deleted file mode 100644
index 37e10a1..0000000
--- a/docs/user-manual/en/ActiveMQ_User_Manual.xml
+++ /dev/null
@@ -1,79 +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.
- -->
-
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book 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;
-
-]>
-<book>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="notice.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="preface.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="project-info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="messaging-concepts.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="architecture.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using-server.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using-jms.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using-core.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="jms-core-mapping.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="client-classpath.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="examples.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="wildcard-routing.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="wildcard-syntax.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="filter-expressions.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="persistence.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="configuring-transports.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="connection-ttl.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="slow-consumers.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="transaction-config.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="flow-control.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="send-guarantees.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="undelivered-messages.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="message-expiry.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="large-messages.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="paging.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="queue-attributes.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="scheduled-messages.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="last-value-queues.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="message-grouping.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pre-acknowledge.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appserver-integration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="jms-bridge.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="client-reconnection.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="diverts.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="core-bridges.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="duplicate-detection.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="clusters.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ha.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libaio.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="thread-pooling.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="rest.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="embedding-activemq.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="spring-integration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="aerogear-integration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="vertx-integration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intercepting-operations.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="interoperability.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="perf-tuning.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="configuration-index.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/Author_Group.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/Author_Group.xml b/docs/user-manual/en/Author_Group.xml
deleted file mode 100644
index 7ecba78..0000000
--- a/docs/user-manual/en/Author_Group.xml
+++ /dev/null
@@ -1,86 +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 authorgroup 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;
-]>
-<authorgroup>
- <author>
- <firstname>Clebert</firstname>
- <surname>Suconic</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Project Lead</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>csuconic@redhat.com</email>
- </author>
- <author>
- <firstname>Andy</firstname>
- <surname>Taylor</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ataylor@redhat.com</email>
- </author>
- <author>
- <firstname>Tim</firstname>
- <surname>Fox</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- </author>
- <author>
- <firstname>Jeff</firstname>
- <surname>Mesnil</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- </author>
- <author>
- <firstname>Howard</firstname>
- <surname>Gao</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ghoward@redhat.com</email>
- </author>
- <author>
- <firstname>Francisco</firstname>
- <surname>Borges</surname>
- </author>
- <author>
- <firstname>Justin</firstname>
- <surname>Bertram</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>jbertram@redhat.com</email>
- </author>
-</authorgroup>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/Book_Info.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/Book_Info.xml b/docs/user-manual/en/Book_Info.xml
deleted file mode 100644
index e55b28f..0000000
--- a/docs/user-manual/en/Book_Info.xml
+++ /dev/null
@@ -1,48 +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 bookinfo 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;
-]>
-<bookinfo id="ActiveMQ_User_Manual">
- <title>ActiveMQ User Manual</title>
- <subtitle>Putting the buzz in messaging</subtitle>
- <productname>ActiveMQ</productname>
- <productnumber>2</productnumber>
- <edition>2.1.0</edition>
- <pubsnumber>1</pubsnumber>
- <abstract>
- <para>The User manual is an in depth manual on all aspects of ActiveMQ</para>
- </abstract>
- <!--corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>ActiveMQ Logo</phrase>
- </textobject>
- </inlinemediaobject>
- </corpauthor-->
- <copyright>
- <year>&YEAR;</year>
- <holder>&HOLDER;</holder>
- </copyright>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
-</bookinfo>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/README.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/README.md b/docs/user-manual/en/README.md
new file mode 100644
index 0000000..3eae03d
--- /dev/null
+++ b/docs/user-manual/en/README.md
@@ -0,0 +1,7 @@
+
+
+ActiveMQ User Manual
+====================
+
+The User manual is an in depth manual on all aspects of ActiveMQ
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
new file mode 100644
index 0000000..79f5d54
--- /dev/null
+++ b/docs/user-manual/en/SUMMARY.md
@@ -0,0 +1,53 @@
+* [Legal Notice](notice.md)
+* [Preface](preface.md)
+* [Project Info](project-info.md)
+* [Messaging Concepts](messaging-concepts.md)
+* [Architecture](architecture.md)
+* [Using the Server](using-server.md)
+* [Using JMS](using-jms.md)
+* [Using Core](using-core.md)
+* [Mapping JMS Concepts to the Core API](jms-core-mapping.md)
+* [The Client Classpath](client-classpath.md)
+* [Examples](examples.md)
+* [Routing Messages With Wild Cards](wildcard-routing.md)
+* [Understanding the ActiveMQ Wildcard Syntax](wildcard-syntax.md)
+* [Filter Expressions](filter-expressions.md)
+* [Persistence](persistence.md)
+* [Configuring Transports](configuring-transports.md)
+* [Detecting Dead Connections](connection-ttl.md)
+* [Detecting Slow Consumers](slow-consumers.md)
+* [Resource Manager Configuration](transaction-config.md)
+* [Flow Control](flow-control.md)
+* [Guarantees of sends and commits](send-guarantees.md)
+* [Message Redelivery and Undelivered Messages](undelivered-messages.md)
+* [Message Expiry](message-expiry.md)
+* [Large Messages](large-messages.md)
+* [Paging](paging.md)
+* [Queue Attributes](queue-attributes.md)
+* [Scheduled Messages](scheduled-messages.md)
+* [Last-Value Queues](last-value-queues.md)
+* [Message Grouping](message-grouping.md)
+* [Extra Acknowledge Modes](pre-acknowledge.md)
+* [Management](management.md)
+* [Security](security.md)
+* [Application Server Integration and Java EE](appserver-integration.md)
+* [The JMS Bridge](jms-bridge.md)
+* [Client Reconnection and Session Reattachment](client-reconnection.md)
+* [Diverting and Splitting Message Flows](diverts.md)
+* [Core Bridges](core-bridges.md)
+* [Duplicate Message Detection](duplicate-detection.md)
+* [Clusters](clusters.md)
+* [High Availability and Failover](ha.md)
+* [Libaio Native Libraries](libaio.md)
+* [Thread management](thread-pooling.md)
+* [Logging](logging.md)
+* [REST Interface](rest.md)
+* [Embedding ActiveMQ](embedding-activemq.md)
+* [Spring Integration](spring-integration.md)
+* [AeroGear Integration](aerogear-integration.md)
+* [VertX Integration](vertx-integration.md)
+* [Intercepting Operations](intercepting-operations.md)
+* [Interoperability](interoperability.md)
+* [Tools](tools.md)
+* [Performance Tuning](perf-tuning.md)
+* [Configuration Reference](configuration-index.md)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/aerogear-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/aerogear-integration.md b/docs/user-manual/en/aerogear-integration.md
new file mode 100644
index 0000000..e8c24f8
--- /dev/null
+++ b/docs/user-manual/en/aerogear-integration.md
@@ -0,0 +1,101 @@
+AeroGear Integration
+====================
+
+AeroGears push technology provides support for different push
+notification technologies like Google Cloud Messaging, Apple's APNs or
+Mozilla's SimplePush. ActiveMQ allows you to configure a Connector
+Service that will consume messages from a queue and forward them to an
+AeroGear push server and subsequently sent as notifications to mobile
+devices.
+
+Configuring an AeroGear Connector Service
+=========================================
+
+AeroGear Connector services are configured in the connector-services
+configuration:
+
+ <connector-service name="aerogear-connector">
+ <factory-class>org.apache.activemq.integration.aerogear.AeroGearConnectorServiceFactory</factory-class>
+ <param key="endpoint" value="endpoint"/>
+ <param key="queue" value="jms.queue.aerogearQueue"/>
+ <param key="application-id" value="an applicationid"/>
+ <param key="master-secret" value="a mastersecret"/>
+ </connector-service>
+ <address-setting match="jms.queue.lastValueQueue">
+ <last-value-queue>true</last-value-queue>
+ </address-setting>
+
+
+Shown are the required params for the connector service and are:
+
+- `endpoint`. The endpoint or URL of you AeroGear application.
+
+- `queue`. The name of the queue to consume from.
+
+- `application-id`. The application id of your mobile application in
+ AeroGear.
+
+- `master-secret`. The secret of your mobile application in AeroGear.
+
+As well as these required paramaters there are the following optional
+parameters
+
+- `ttl`. The time to live for the message once AeroGear receives it.
+
+- `badge`. The badge the mobile app should use for the notification.
+
+- `sound`. The sound the mobile app should use for the notification.
+
+- `filter`. A message filter(selector) to use on the connector.
+
+- `retry-interval`. If an error occurs on send, how long before we try
+ again to connect.
+
+- `retry-attempts`. How many times we should try to reconnect after an
+ error.
+
+- `variants`. A comma separated list of variants that should get the
+ message.
+
+- `aliases`. A list of aliases that should get the message.
+
+- `device-types`. A list of device types that should get the messag.
+
+More in depth explanations of the AeroGear related parameters can be
+found in the [AeroGear Push docs](http://aerogear.org/push/)
+
+How to send a message for AeroGear
+==================================
+
+To send a message intended for AeroGear simply send a JMS Message and
+set the appropriate headers, like so
+
+ Message message = session.createMessage();
+
+ message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from ActiveMQ");
+
+ producer.send(message);
+
+
+The 'AEROGEAR\_ALERT' property will be the alert sent to the mobile
+device.
+
+> **Note**
+>
+> If the message does not contain this property then it will be simply
+> ignored and left on the queue
+
+Its also possible to override any of the other AeroGear parameters by
+simply setting them on the message, for instance if you wanted to set
+ttl of a message you would:
+
+ message.setIntProperty("AEROGEAR_TTL", 1234);
+
+
+or if you wanted to set the list of variants you would use:
+
+ message.setStringProperty("AEROGEAR_VARIANTS", "variant1,variant2,variant3");
+
+
+Again refer to the AeroGear documentation for a more in depth view on
+how to use these settings
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/aerogear-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/aerogear-integration.xml b/docs/user-manual/en/aerogear-integration.xml
deleted file mode 100644
index c471d45..0000000
--- a/docs/user-manual/en/aerogear-integration.xml
+++ /dev/null
@@ -1,115 +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="aerogear-integration">
- <title>AeroGear Integration</title>
- <para>AeroGears push technology provides support for different push notification technologies like Google Cloud Messaging,
- Apple's APNs or Mozilla's SimplePush. ActiveMQ allows you to configure a Connector Service that will consume messages
- from a queue and forward them to an AeroGear push server and subsequently sent as notifications to mobile devices.</para>
- <section>
- <title>Configuring an AeroGear Connector Service</title>
- <para>AeroGear Connector services are configured in the connector-services configuration:</para>
- <programlisting>
- <connector-service name="aerogear-connector">
- <factory-class>org.apache.activemq.integration.aerogear.AeroGearConnectorServiceFactory</factory-class>
- <param key="endpoint" value="endpoint"/>
- <param key="queue" value="jms.queue.aerogearQueue"/>
- <param key="application-id" value="an applicationid"/>
- <param key="master-secret" value="a mastersecret"/>
- </connector-service>
- <address-setting match="jms.queue.lastValueQueue">
- <last-value-queue>true</last-value-queue>
- </address-setting>
- </programlisting>
- <para>Shown are the required params for the connector service and are:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>endpoint</literal>. The endpoint or URL of you AeroGear application.</para>
- </listitem>
- <listitem>
- <para><literal>queue</literal>. The name of the queue to consume from.</para>
- </listitem>
- <listitem>
- <para><literal>application-id</literal>. The application id of your mobile application in AeroGear.</para>
- </listitem>
- <listitem>
- <para><literal>master-secret</literal>. The secret of your mobile application in AeroGear.</para>
- </listitem>
- </itemizedlist>
- <para>As well as these required paramaters there are the following optional parameters</para>
- <itemizedlist>
- <listitem>
- <para><literal>ttl</literal>. The time to live for the message once AeroGear receives it.</para>
- </listitem>
- <listitem>
- <para><literal>badge</literal>. The badge the mobile app should use for the notification.</para>
- </listitem>
- <listitem>
- <para><literal>sound</literal>. The sound the mobile app should use for the notification.</para>
- </listitem>
- <listitem>
- <para><literal>filter</literal>. A message filter(selector) to use on the connector.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval</literal>. If an error occurs on send, how long before we try again to connect.</para>
- </listitem>
- <listitem>
- <para><literal>retry-attempts</literal>. How many times we should try to reconnect after an error.</para>
- </listitem>
- <listitem>
- <para><literal>variants</literal>. A comma separated list of variants that should get the message.</para>
- </listitem>
- <listitem>
- <para><literal>aliases</literal>. A list of aliases that should get the message.</para>
- </listitem>
- <listitem>
- <para><literal>device-types</literal>. A list of device types that should get the messag.</para>
- </listitem>
- </itemizedlist>
- <para>More in depth explanations of the AeroGear related parameters can be found in the <ulink
- url="http://aerogear.org/push/">AeroGear Push docs</ulink></para>
- </section>
- <section>
- <title>How to send a message for AeroGear</title>
- <para>To send a message intended for AeroGear simply send a JMS Message and set the appropriate headers, like so</para>
- <programlisting>
- Message message = session.createMessage();
-
- message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from ActiveMQ");
-
- producer.send(message);
- </programlisting>
- <para>The 'AEROGEAR_ALERT' property will be the alert sent to the mobile device.</para>
- <note><para>If the message does not contain this property then it will be simply ignored and left on the queue</para></note>
- <para>Its also possible to override any of the other AeroGear parameters by simply setting them on the message,
- for instance if you wanted to set ttl of a message you would:</para>
- <programlisting>
- message.setIntProperty("AEROGEAR_TTL", 1234);
- </programlisting>
- <para>or if you wanted to set the list of variants you would use:</para>
- <programlisting>
- message.setStringProperty("AEROGEAR_VARIANTS", "variant1,variant2,variant3");
- </programlisting>
- <para>Again refer to the AeroGear documentation for a more in depth view on how to use these settings</para>
- </section>
-</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/appserver-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/appserver-integration.md b/docs/user-manual/en/appserver-integration.md
new file mode 100644
index 0000000..8c4c9d5
--- /dev/null
+++ b/docs/user-manual/en/appserver-integration.md
@@ -0,0 +1,1031 @@
+Application Server Integration and Java EE
+==========================================
+
+ActiveMQ can be easily installed in JBoss Application Server 4 or later.
+For details on installing ActiveMQ in the JBoss Application Server
+please refer to quick-start guide.
+
+Since ActiveMQ also provides a JCA adapter, it is also possible to
+integrate ActiveMQ as a JMS provider in other JEE compliant app servers.
+For instructions on how to integrate a remote JCA adaptor into another
+application sever, please consult the other application server's
+instructions.
+
+A JCA Adapter basically controls the inflow of messages to
+Message-Driven Beans (MDBs) and the outflow of messages sent from other
+JEE components, e.g. EJBs and Servlets.
+
+This section explains the basics behind configuring the different JEE
+components in the AS.
+
+Configuring Message-Driven Beans
+================================
+
+The delivery of messages to an MDB using ActiveMQ is configured on the
+JCA Adapter via a configuration file `ra.xml` which can be found under
+the `jms-ra.rar` directory. By default this is configured to consume
+messages using an InVM connector from the instance of ActiveMQ running
+within the application server. The configuration properties are listed
+later in this chapter.
+
+All MDBs however need to have the destination type and the destination
+configured. The following example shows how this can be done using
+annotations:
+
+ @MessageDriven(name = "MDBExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
+ })
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDBExample implements MessageListener
+ {
+ public void onMessage(Message message)...
+ }
+
+In this example you can see that the MDB will consume messages from a
+queue that is mapped into JNDI with the binding `queue/testQueue`. This
+queue must be preconfigured in the usual way using the ActiveMQ
+configuration files.
+
+The `ResourceAdapter` annotation is used to specify which adaptor should
+be used. To use this you will need to import
+`org.jboss.ejb3.annotation.ResourceAdapter` for JBoss AS 5.X and later
+version which can be found in the `jboss-ejb3-ext-api.jar` which can be
+found in the JBoss repository. For JBoss AS 4.X, the annotation to use
+is `org.jboss.annotation.ejb.ResourceAdaptor`.
+
+Alternatively you can add use a deployment descriptor and add something
+like the following to `jboss.xml`
+
+ <message-driven>
+ <ejb-name>ExampleMDB</ejb-name>
+ <resource-adapter-name>activemq-ra.rar</resource-adapter-name>
+ </message-driven>
+
+You can also rename the activemq-ra.rar directory to jms-ra.rar and
+neither the annotation or the extra descriptor information will be
+needed. If you do this you will need to edit the `jms-ds.xml` datasource
+file and change `rar-name` element.
+
+> **Note**
+>
+> ActiveMQ is the default JMS provider for JBoss AS 6. Starting with
+> this AS version, ActiveMQ resource adapter is named `jms-ra.rar` and
+> you no longer need to annotate the MDB for the resource adapter name.
+
+All the examples shipped with the ActiveMQ distribution use the
+annotation.
+
+Using Container-Managed Transactions
+------------------------------------
+
+When an MDB is using Container-Managed Transactions (CMT), the delivery
+of the message is done within the scope of a JTA transaction. The commit
+or rollback of this transaction is controlled by the container itself.
+If the transaction is rolled back then the message delivery semantics
+will kick in (by default, it will try to redeliver the message up to 10
+times before sending to a DLQ). Using annotations this would be
+configured as follows:
+
+ @MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
+ })
+ @TransactionManagement(value= TransactionManagementType.CONTAINER)
+ @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDB_CMP_TxRequiredExample implements MessageListener
+ {
+ public void onMessage(Message message)...
+ }
+
+The `TransactionManagement` annotation tells the container to manage the
+transaction. The `TransactionAttribute` annotation tells the container
+that a JTA transaction is required for this MDB. Note that the only
+other valid value for this is `TransactionAttributeType.NOT_SUPPORTED`
+which tells the container that this MDB does not support JTA
+transactions and one should not be created.
+
+It is also possible to inform the container that it must rollback the
+transaction by calling `setRollbackOnly` on the `MessageDrivenContext`.
+The code for this would look something like:
+
+ @Resource
+ MessageDrivenContextContext ctx;
+
+ public void onMessage(Message message)
+ {
+ try
+ {
+ //something here fails
+ }
+ catch (Exception e)
+ {
+ ctx.setRollbackOnly();
+ }
+ }
+
+If you do not want the overhead of an XA transaction being created every
+time but you would still like the message delivered within a transaction
+(i.e. you are only using a JMS resource) then you can configure the MDB
+to use a local transaction. This would be configured as such:
+
+ @MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
+ @ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
+ })
+ @TransactionManagement(value = TransactionManagementType.CONTAINER)
+ @TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDB_CMP_TxLocalExample implements MessageListener
+ {
+ public void onMessage(Message message)...
+ }
+
+Using Bean-Managed Transactions
+-------------------------------
+
+Message-driven beans can also be configured to use Bean-Managed
+Transactions (BMT). In this case a User Transaction is created. This
+would be configured as follows:
+
+ @MessageDriven(name = "MDB_BMPExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
+ @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
+ })
+ @TransactionManagement(value= TransactionManagementType.BEAN)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDB_BMPExample implements MessageListener
+ {
+ public void onMessage(Message message)
+ }
+
+When using Bean-Managed Transactions the message delivery to the MDB
+will occur outside the scope of the user transaction and use the
+acknowledge mode specified by the user with the `acknowledgeMode`
+property. There are only 2 acceptable values for this `Auto-acknowledge`
+and `Dups-ok-acknowledge`. Please note that because the message delivery
+is outside the scope of the transaction a failure within the MDB will
+not cause the message to be redelivered.
+
+A user would control the life-cycle of the transaction something like
+the following:
+
+ @Resource
+ MessageDrivenContext ctx;
+
+ public void onMessage(Message message)
+ {
+ UserTransaction tx;
+ try
+ {
+ TextMessage textMessage = (TextMessage)message;
+
+ String text = textMessage.getText();
+
+ UserTransaction tx = ctx.getUserTransaction();
+
+ tx.begin();
+
+ //do some stuff within the transaction
+
+ tx.commit();
+
+ }
+ catch (Exception e)
+ {
+ tx.rollback();
+ }
+ }
+
+Using Message Selectors with Message-Driven Beans
+-------------------------------------------------
+
+It is also possible to use MDBs with message selectors. To do this
+simple define your message selector as follows:
+
+ @MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
+ @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
+ })
+ @TransactionManagement(value= TransactionManagementType.CONTAINER)
+ @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDBMessageSelectorExample implements MessageListener
+ {
+ public void onMessage(Message message)....
+ }
+
+Sending Messages from within JEE components
+===========================================
+
+The JCA adapter can also be used for sending messages. The Connection
+Factory to use is configured by default in the `jms-ds.xml` file and is
+mapped to `java:/JmsXA`. Using this from within a JEE component will
+mean that the sending of the message will be done as part of the JTA
+transaction being used by the component.
+
+This means that if the sending of the message fails the overall
+transaction would rollback and the message be re-sent. Heres an example
+of this from within an MDB:
+
+ @MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
+ })
+ @TransactionManagement(value= TransactionManagementType.CONTAINER)
+ @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MDBMessageSendTxExample implements MessageListener
+ {
+ @Resource(mappedName = "java:/JmsXA")
+ ConnectionFactory connectionFactory;
+
+ @Resource(mappedName = "queue/replyQueue")
+ Queue replyQueue;
+
+ public void onMessage(Message message)
+ {
+ Connection conn = null;
+ try
+ {
+ //Step 9. We know the client is sending a text message so we cast
+ TextMessage textMessage = (TextMessage)message;
+
+ //Step 10. get the text from the message.
+ String text = textMessage.getText();
+
+ System.out.println("message " + text);
+
+ conn = connectionFactory.createConnection();
+
+ Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ MessageProducer producer = sess.createProducer(replyQueue);
+
+ producer.send(sess.createTextMessage("this is a reply"));
+
+ }
+ catch (Exception e)
+ {
+ e.printStackTrace();
+ }
+ finally
+ {
+ if(conn != null)
+ {
+ try
+ {
+ conn.close();
+ }
+ catch (JMSException e)
+ {
+ }
+ }
+ }
+ }
+ }
+
+In JBoss Application Server you can use the JMS JCA adapter for sending
+messages from EJBs (including Session, Entity and Message-Driven Beans),
+Servlets (including jsps) and custom MBeans.
+
+MDB and Consumer pool size
+==========================
+
+Most application servers, including JBoss, allow you to configure how
+many MDB's there are in a pool. In JBoss this is configured via the
+`MaxPoolSize` parameter in the ejb3-interceptors-aop.xml file.
+Configuring this has no actual effect on how many sessions/consumers
+there actually are created. This is because the Resource Adaptor
+implementation knows nothing about the application servers MDB
+implementation. So even if you set the MDB pool size to 1, 15
+sessions/consumers will be created (this is the default). If you want to
+limit how many sessions/consumers are created then you need to set the
+`maxSession` parameter either on the resource adapter itself or via an
+an Activation Config Property on the MDB itself
+
+ @MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
+ {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
+ @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
+ })
+ @TransactionManagement(value= TransactionManagementType.CONTAINER)
+ @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
+ @ResourceAdapter("activemq-ra.rar")
+ public class MyMDB implements MessageListener
+ { ....}
+
+
+Configuring the JCA Adaptor
+===========================
+
+The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to
+be integrated with JEE components such as MDBs and EJBs. It configures
+how components such as MDBs consume messages from the ActiveMQ server
+and also how components such as EJBs or Servlets can send messages.
+
+The ActiveMQ JCA adapter is deployed via the `jms-ra.rar` archive. The
+configuration of the adapter is found in this archive under
+`META-INF/ra.xml`.
+
+The configuration will look something like the following:
+
+ <resourceadapter>
+ <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport type. Multiple connectors can be configured by using a comma separated list,
+ i.e. org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory,org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory.</description>
+ <config-property-name>ConnectorClassName</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration. These values must be in the form of key=val;key=val;,
+ if multiple connectors are used then each set must be separated by a comma i.e. host=host1;port=5445,host=host2;port=5446.
+ Each set of parameters maps to the connector classname specified.</description>
+ <config-property-name>ConnectionParameters</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>server-id=0</config-property-value>
+ </config-property>
+
+ <outbound-resourceadapter>
+ <connection-definition>
+ <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnection
+ Factory</managedconnectionfactory-class>
+
+ <config-property>
+ <description>The default session type</description>
+ <config-property-name>SessionDefaultType</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>javax.jms.Queue</config-property-value>
+ </config-property>
+ <config-property>
+ <description>Try to obtain a lock within specified number of seconds; less
+ than or equal to 0 disable this functionality</description>
+ <config-property-name>UseTryLock</config-property-name>
+ <config-property-type>java.lang.Integer</config-property-type>
+ <config-property-value>0</config-property-value>
+ </config-property>
+
+ <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory
+ </connectionfactory-interface>
+ <connectionfactororg.apache.activemq.ra.ActiveMQConnectionFactoryImplonFactoryImpl
+ </connectionfactory-impl-class>
+ <connection-interface>javax.jms.Session</connection-interface>
+ <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession
+ </connection-impl-class>
+ </connection-definition>
+ <transaction-support>XATransaction</transaction-support>
+ <authentication-mechanism>
+ <authentication-mechanism-type>BasicPassword
+ </authentication-mechanism-type>
+ <credential-interface>javax.resource.spi.security.PasswordCredential
+ </credential-interface>
+ </authentication-mechanism>
+ <reauthentication-support>false</reauthentication-support>
+ </outbound-resourceadapter>
+
+ <inbound-resourceadapter>
+ <messageadapter>
+ <messagelistener>
+ <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
+ <activationspec>
+ <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec
+ </activationspec-class>
+ <required-config-property>
+ <config-property-name>destination</config-property-name>
+ </required-config-property>
+ </activationspec>
+ </messagelistener>
+ </messageadapter>
+ </inbound-resourceadapter>
+ </resourceadapter>
+
+There are three main parts to this configuration.
+
+1. A set of global properties for the adapter
+
+2. The configuration for the outbound part of the adapter. This is used
+ for creating JMS resources within EE components.
+
+3. The configuration of the inbound part of the adapter. This is used
+ for controlling the consumption of messages via MDBs.
+
+Global Properties
+-----------------
+
+The first element you see is `resourceadapter-class` which should be
+left unchanged. This is the ActiveMQ resource adapter class.
+
+After that there is a list of configuration properties. This will be
+where most of the configuration is done. The first two properties
+configure the transport used by the adapter and the rest configure the
+connection factory itself.
+
+> **Note**
+>
+> All connection factory properties will use the defaults if they are
+> not provided, except for the `reconnectAttempts` which will default to
+> -1. This signifies that the connection should attempt to reconnect on
+> connection failure indefinitely. This is only used when the adapter is
+> configured to connect to a remote server as an InVM connector can
+> never fail.
+
+The following table explains what each property is for.
+
+ Property Name Property Type Property Description
+ --------------------------------------------------------------------------- --------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ ConnectorClassName String The Connector class name (see ? for more information). If multiple connectors are needed this should be provided as a comma separated list.
+ ConnectionParameters String The transport configuration. These parameters must be in the form of `key1=val1;key2=val2;` and will be specific to the connector used. If multiple connectors are configured then parameters should be supplied for each connector separated by a comma.
+ ha boolean True if high availability is needed.
+ useLocalTx boolean True will enable local transaction optimisation.
+ UserName String The user name to use when making a connection
+ Password String The password to use when making a connection
+ [DiscoveryAddress](#configuration.discovery-group.group-address) String The discovery group address to use to auto-detect a server
+ [DiscoveryPort](#configuration.discovery-group.group-port) Integer The port to use for discovery
+ [DiscoveryRefreshTimeout](#configuration.discovery-group.refresh-timeout) Long The timeout, in milliseconds, to refresh.
+ DiscoveryInitialWaitTimeout Long The initial time to wait for discovery.
+ ConnectionLoadBalancingPolicyClassName String The load balancing policy class to use.
+ ConnectionTTL Long The time to live (in milliseconds) for the connection.
+ CallTimeout Long the call timeout (in milliseconds) for each packet sent.
+ DupsOKBatchSize Integer the batch size (in bytes) between acknowledgements when using DUPS\_OK\_ACKNOWLEDGE mode
+ TransactionBatchSize Integer the batch size (in bytes) between acknowledgements when using a transactional session
+ ConsumerWindowSize Integer the window size (in bytes) for consumer flow control
+ ConsumerMaxRate Integer the fastest rate a consumer may consume messages per second
+ ConfirmationWindowSize Integer the window size (in bytes) for reattachment confirmations
+ ProducerMaxRate Integer the maximum rate of messages per second that can be sent
+ MinLargeMessageSize Integer the size (in bytes) before a message is treated as large
+ BlockOnAcknowledge Boolean whether or not messages are acknowledged synchronously
+ BlockOnNonDurableSend Boolean whether or not non-durable messages are sent synchronously
+ BlockOnDurableSend Boolean whether or not durable messages are sent synchronously
+ AutoGroup Boolean whether or not message grouping is automatically used
+ PreAcknowledge Boolean whether messages are pre acknowledged by the server before sending
+ ReconnectAttempts Integer maximum number of retry attempts, default for the resource adapter is -1 (infinite attempts)
+ RetryInterval Long the time (in milliseconds) to retry a connection after failing
+ RetryIntervalMultiplier Double multiplier to apply to successive retry intervals
+ FailoverOnServerShutdown Boolean If true client will reconnect to another server if available
+ ClientID String the pre-configured client ID for the connection factory
+ ClientFailureCheckPeriod Long the period (in ms) after which the client will consider the connection failed after not receiving packets from the server
+ UseGlobalPools Boolean whether or not to use a global thread pool for threads
+ ScheduledThreadPoolMaxSize Integer the size of the *scheduled thread* pool
+ ThreadPoolMaxSize Integer the size of the thread pool
+ SetupAttempts Integer Number of attempts to setup a JMS connection (default is 10, -1 means to attempt infinitely). It is possible that the MDB is deployed before the JMS resources are available. In that case, the resource adapter will try to setup several times until the resources are available. This applies only for inbound connections
+ SetupInterval Long Interval in milliseconds between consecutive attempts to setup a JMS connection (default is 2000m). This applies only for inbound connections
+
+ : Global Configuration Properties
+
+Adapter Outbound Configuration
+------------------------------
+
+The outbound configuration should remain unchanged as they define
+connection factories that are used by Java EE components. These
+Connection Factories can be defined inside a configuration file that
+matches the name `*-ds.xml`. You'll find a default `jms-ds.xml`
+configuration under the `activemq` directory in the JBoss AS deployment.
+The connection factories defined in this file inherit their properties
+from the main `ra.xml` configuration but can also be overridden. The
+following example shows how to override them.
+
+> **Note**
+>
+> Please note that this configuration only applies when ActiveMQ
+> resource adapter is installed in JBoss Application Server. If you are
+> using another JEE application server please refer to your application
+> servers documentation for how to do this.
+
+ <tx-connection-factory>
+ <jndi-name>RemoteJmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>jms-ra.rar</rar-name>
+ <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory
+ </connection-definition>
+ <config-property name="SessionDefaultType" type="String">javax.jms.Topic</config-property>
+ <config-property name="ConnectorClassName" type="String">
+ org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
+ </config-property>
+ <config-property name="ConnectionParameters" type="String">
+ port=5445</config-property>
+ <max-pool-size>20</max-pool-size>
+ </tx-connection-factory>
+
+> **Warning**
+>
+> If the connector class name is overridden the all parameters must also
+> be supplied.
+
+In this example the connection factory will be bound to JNDI with the
+name `RemoteJmsXA` and can be looked up in the usual way using JNDI or
+defined within the EJB or MDB as such:
+
+ @Resource(mappedName="java:/RemoteJmsXA")
+ private ConnectionFactory connectionFactory;
+
+The `config-property` elements are what overrides those in the `ra.xml`
+configuration file. Any of the elements pertaining to the connection
+factory can be overridden here.
+
+The outbound configuration also defines additional properties in
+addition to the global configuration properties.
+
+ Property Name Property Type Property Description
+ -------------------- --------------- -------------------------------------------------------------------------------------------------------------
+ SessionDefaultType String the default session type
+ UseTryLock Integer try to obtain a lock within specified number of seconds. less than or equal to 0 disable this functionality
+
+ : Outbound Configuration Properties
+
+Adapter Inbound Configuration
+-----------------------------
+
+The inbound configuration should again remain unchanged. This controls
+what forwards messages onto MDBs. It is possible to override properties
+on the MDB by adding an activation configuration to the MDB itself. This
+could be used to configure the MDB to consume from a different server.
+
+The inbound configuration also defines additional properties in addition
+to the global configuration properties.
+
+ Property Name Property Type Property Description
+ ------------------------ --------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ Destination String JNDI name of the destination
+ DestinationType String type of the destination, either `javax.jms.Queue` or `javax.jms.Topic` (default is javax.jms.Queue)
+ AcknowledgeMode String The Acknowledgment mode, either `Auto-acknowledge` or `Dups-ok-acknowledge` (default is Auto-acknowledge). `AUTO_ACKNOWLEDGE` and `DUPS_OK_ACKNOWLEDGE` are acceptable values.
+ JndiParams String A semicolon (';') delimited string of name=value pairs which represent the properties to be used for the destination JNDI look up. The properties depends on the JNDI implementation of the server hosting ActiveMQ. Typically only be used when the MDB is configured to consume from a remote destination and needs to look up a JNDI reference rather than the ActiveMQ name of the destination. Only relevant when `useJNDI` is `true` (default is an empty string).
+ MaxSession Integer Maximum number of session created by this inbound configuration (default is 15)
+ MessageSelector String the message selector of the consumer
+ SubscriptionDurability String Type of the subscription, either `Durable` or `NonDurable`
+ ShareSubscriptions Boolean When true, multiple MDBs can share the same `Durable` subscription
+ SubscriptionName String Name of the subscription
+ TransactionTimeout Long The transaction timeout in milliseconds (default is 0, the transaction does not timeout)
+ UseJNDI Boolean Whether or not use JNDI to look up the destination (default is true)
+
+ : Inbound Configuration Properties
+
+Configuring the adapter to use a standalone ActiveMQ Server
+-----------------------------------------------------------
+
+Sometime you may want your messaging server on a different machine or
+separate from the application server. If this is the case you will only
+need the activemq client libs installed. This section explains what
+config to create and what jar dependencies are needed.
+
+###
+
+There are two configuration files needed to do this, one for the
+incoming adapter used for MDB's and one for outgoing connections managed
+by the JCA managed connection pool used by outgoing JEE components
+wanting outgoing connections.
+
+#### Configuring the Incoming Adaptor
+
+Firstly you will need to create directory under the `deploy` directory
+ending in `.rar.` For this example we will name the directory
+`activemq-ra.rar`. This detail is important as the name of directory is
+referred to by the MDB's and the outgoing configuration.
+
+> **Note**
+>
+> The jboss default for this is `jms-ra.rar`, If you don't want to have
+> to configure your MDB's you can use this but you may need to remove
+> the generic adaptor that uses this.
+
+Under the `activemq-ra.rar` directory you will need to create a
+`META-INF` directory into which you should create an `ra.xml`
+configuration file. You can find a template for the `ra.xml` under the
+config directory of the ActiveMQ distribution.
+
+To configure MDB's to consume messages from a remote ActiveMQ server you
+need to edit the `ra.xml` file under `deploy/activemq-ra.rar/META-INF`
+and change the transport type to use a netty connector (instead of the
+invm connector that is defined) and configure its transport parameters.
+Heres an example of what this would look like:
+
+ <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport type</description>
+ <config-property-name>ConnectorClassName</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
+ <config-property-name>ConnectionParameters</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>host=127.0.0.1;port=5446</config-property-value>
+ </config-property>
+
+If you want to provide a list of servers that the adapter can connect to
+you can provide a list of connectors, each separated by a comma.
+
+ <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport type</description>
+ <config-property-name>ConnectorClassName</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory,org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
+ <config-property-name>ConnectionParameters</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>host=127.0.0.1;port=5446,host=127.0.0.2;port=5447</config-property-value>
+ </config-property>
+
+> **Warning**
+>
+> Make sure you provide parameters for each connector configured. The
+> position of the parameters in the list maps to each connector
+> provided.
+
+This configures the resource adapter to connect to a server running on
+localhost listening on port 5446
+
+#### Configuring the outgoing adaptor
+
+You will also need to configure the outbound connection by creating a
+`activemq-ds.xml` and placing it under any directory that will be
+deployed under the `deploy` directory. In a standard ActiveMQ jboss
+configuration this would be under `activemq` or `activemq.sar` but you
+can place it where ever you like. Actually as long as it ends in
+`-ds.xml` you can call it anything you like. You can again find a
+template for this file under the config directory of the ActiveMQ
+distribution but called `jms-ds.xml` which is the jboss default.
+
+The following example shows a sample configuration
+
+ <tx-connection-factory>
+ <jndi-name>RemoteJmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>activemq-ra.rar</rar-name>
+ <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
+ <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
+ <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
+ <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446</config-property>
+ <max-pool-size>20</max-pool-size>
+ </tx-connection-factory>
+
+Again you will see that this uses the netty connector type and will
+connect to the ActiveMQ server running on localhost and listening on
+port 5446. JEE components can access this by using JNDI and looking up
+the connection factory using JNDI using `java:/RemoteJmsXA`, you can see
+that this is defined under the`jndi-name` attribute. You will also note
+that the outgoing connection will be created by the resource adaptor
+configured under the directory `activemq-ra.rar` as explained in the
+last section.
+
+Also if you want to configure multiple connectors do this as a comma
+separated list as in the ra configuration.
+
+#### Jar dependencies
+
+This is a list of the ActiveMQ and third party jars needed
+
+ Jar Name Description Location
+ -------------------------- --------------------------------------- -------------------------------------------------------------------------------------------------
+ activemq-ra.jar The ActiveMQ resource adaptor classes deploy/activemq-ra.rar or equivalent
+ activemq-core-client.jar The ActiveMQ core client classes either in the config lib, i.e. default/lib or the common lib dir, i.e. \$JBOSS\_HOME/common lib
+ activemq-jms-client.jar The ActiveMQ JMS classes as above
+ netty.jar The Netty transport classes as above
+
+ : Jar Dependencies
+
+Configuring the JBoss Application Server to connect to Remote ActiveMQ Server
+=============================================================================
+
+This is a step by step guide on how to configure a JBoss application
+server that doesn't have ActiveMQ installed to use a remote instance of
+ActiveMQ
+
+Configuring JBoss 5
+-------------------
+
+Firstly download and install JBoss AS 5 as per the JBoss installation
+guide and ActiveMQ as per the ActiveMQ installation guide. After that
+the following steps are required
+
+- Copy the following jars from the ActiveMQ distribution to the `lib`
+ directory of which ever JBossAs configuration you have chosen, i.e.
+ `default`.
+
+ - activemq-core-client.jar
+
+ - activemq-jms-client.jar
+
+ - activemq-ra.jar (this can be found inside the `activemq-ra.rar`
+ archive)
+
+ - netty.jar
+
+- create the directories `activemq-ra.rar` and
+ `activemq-ra.rar/META-INF` under the `deploy` directory in your
+ JBoss config directory
+
+- under the `activemq-ra.rar/META-INF` create a `ra.xml` file or copy
+ it from the ActiveMQ distribution (again it can be found in the
+ `activemq-ra.rar` archive) and configure it as follows
+
+ <?xml version="1.0" encoding="UTF-8"?>
+
+ <connector xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+ http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
+ version="1.5">
+
+ <description>ActiveMQ 2.0 Resource Adapter Alternate Configuration</description>
+ <display-name>ActiveMQ 2.0 Resource Adapter Alternate Configuration</display-name>
+
+ <vendor-name>Red Hat Middleware LLC</vendor-name>
+ <eis-type>JMS 1.1 Server</eis-type>
+ <resourceadapter-version>1.0</resourceadapter-version>
+
+ <license>
+ <description>
+ Copyright 2009 Red Hat, Inc.
+ Red Hat 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.
+ </description>
+ <license-required>true</license-required>
+ </license>
+
+ <resourceadapter>
+ <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport type</description>
+ <config-property-name>ConnectorClassName</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
+ <config-property-name>ConnectionParameters</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+
+ </config-property>
+
+ <outbound-resourceadapter>
+ <connection-definition>
+ <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnectionFactory</managedconnectionfactory-class>
+
+ <config-property>
+ <description>The default session type</description>
+ <config-property-name>SessionDefaultType</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>javax.jms.Queue</config-property-value>
+ </config-property>
+ <config-property>
+ <description>Try to obtain a lock within specified number of seconds; less than or equal to 0 disable this functionality</description>
+ <config-property-name>UseTryLock</config-property-name>
+ <config-property-type>java.lang.Integer</config-property-type>
+ <config-property-value>0</config-property-value>
+ </config-property>
+
+ <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connectionfactory-interface>
+ <connectionfactory-impl-class>org.apache.activemq.ra.ActiveMQRAConnectionFactoryImpl</connectionfactory-impl-class>
+ <connection-interface>javax.jms.Session</connection-interface>
+ <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession</connection-impl-class>
+ </connection-definition>
+ <transaction-support>XATransaction</transaction-support>
+ <authentication-mechanism>
+ <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
+ <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
+ </authentication-mechanism>
+ <reauthentication-support>false</reauthentication-support>
+ </outbound-resourceadapter>
+
+ <inbound-resourceadapter>
+ <messageadapter>
+ <messagelistener>
+ <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
+ <activationspec>
+ <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec</activationspec-class>
+ <required-config-property>
+ <config-property-name>destination</config-property-name>
+ </required-config-property>
+ </activationspec>
+ </messagelistener>
+ </messageadapter>
+ </inbound-resourceadapter>
+
+ </resourceadapter>
+ </connector>
+
+ The important part of this configuration is the part in bold, i.e.
+ \<config-property-value\>host=127.0.0.1;port=5445\</config-property-value\>.
+ This should be configured to the host and port of the remote
+ ActiveMQ server.
+
+At this point you should be able to now deploy MDB's that consume from
+the remote server. You will however, have to make sure that your MDB's
+have the annotation `@ResourceAdapter("activemq-ra.rar")` added, this is
+illustrated in the ? section. If you don't want to add this annotation
+then you can delete the generic resource adapter `jms-ra.rar` and rename
+the `activemq-ra.rar` to this.
+
+If you also want to use the remote ActiveMQ server for outgoing
+connections, i.e. sending messages, then do the following:
+
+- Create a file called `activemq-ds.xml` in the `deploy` directory (in
+ fact you can call this anything you want as long as it ends in
+ `-ds.xml`). Then add the following:
+
+ <connection-factories>
+ <!--
+ JMS XA Resource adapter, use this for outbound JMS connections.
+ Inbound connections are defined at the @MDB activation or at the resource-adapter properties.
+ -->
+ <tx-connection-factory>
+ <jndi-name>RemoteJmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>activemq-ra.rar</rar-name>
+ <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
+ <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
+ <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
+ <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5445</config-property>
+ <max-pool-size>20</max-pool-size>
+ </tx-connection-factory>
+
+
+ </connection-factories>
+
+ Again you will see that the host and port are configured here to
+ match the remote ActiveMQ servers configuration. The other important
+ attributes are:
+
+ - jndi-name - This is the name used to look up the JMS connection
+ factory from within your JEE client
+
+ - rar-name - This should match the directory that you created to
+ hold the Resource Adapter configuration
+
+Now you should be able to send messages using the JCA JMS connection
+pooling within an XA transaction.
+
+Configuring JBoss 5
+-------------------
+
+The steps to do this are exactly the same as for JBoss 4, you will have
+to create a jboss.xml definition file for your MDB with the following
+entry
+
+ <message-driven>
+ <ejb-name>MyMDB</ejb-name>
+ <resource-adapter-name>jms-ra.rar</resource-adapter-name>
+ </message-driven>
+
+Also you will need to edit the `standardjboss.xml` and uncomment the
+section with the following 'Uncomment to use JMS message inflow from
+jmsra.rar' and then comment out the invoker-proxy-binding called
+'message-driven-bean'
+
+High Availability JNDI (HA-JNDI)
+================================
+
+If you are using JNDI to look-up JMS queues, topics and connection
+factories from a cluster of servers, it is likely you will want to use
+HA-JNDI so that your JNDI look-ups will continue to work if one or more
+of the servers in the cluster fail.
+
+HA-JNDI is a JBoss Application Server service which allows you to use
+JNDI from clients without them having to know the exact JNDI connection
+details of every server in the cluster. This service is only available
+if using a cluster of JBoss Application Server instances.
+
+To use it use the following properties when connecting to JNDI.
+
+ Hashtable<String, String> jndiParameters = new Hashtable<String, String>();
+ jndiParameters.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
+ jndiParameters.put("java.naming.factory.url.pkgs=", "org.jboss.naming:org.jnp.interfaces");
+
+ initialContext = new InitialContext(jndiParameters);
+
+For more information on using HA-JNDI see the [JBoss Application Server
+clustering
+documentation](http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html)
+
+XA Recovery
+===========
+
+*XA recovery* deals with system or application failures to ensure that
+of a transaction are applied consistently to all resources affected by
+the transaction, even if any of the application processes or the machine
+hosting them crash or lose network connectivity. For more information on
+XA Recovery,please refer to [JBoss
+Transactions](http://www.jboss.org/community/wiki/JBossTransactions).
+
+When ActiveMQ is integrated with JBoss AS, it can take advantage of
+JBoss Transactions to provide recovery of messaging resources. If
+messages are involved in a XA transaction, in the event of a server
+crash, the recovery manager will ensure that the transactions are
+recovered and the messages will either be committed or rolled back
+(depending on the transaction outcome) when the server is restarted.
+
+XA Recovery Configuration
+-------------------------
+
+To enable ActiveMQ's XA Recovery, the Recovery Manager must be
+configured to connect to ActiveMQ to recover its resources. The
+following property must be added to the `jta` section of
+`conf/jbossts-properties.xml` of JBoss AS profiles:
+
+ <properties depends="arjuna" name="jta">
+ ...
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ActiveMQ1"
+ value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;[connection configuration]"/>
+ <property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
+ </properties>
+
+The `[connection configuration]` contains all the information required
+to connect to ActiveMQ node under the form `[connector factory class
+ name],[user name], [password], [connector parameters]`.
+
+- `[connector factory class name]` corresponds to the name of the
+ `ConnectorFactory` used to connect to ActiveMQ. Values can be
+ `org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory`
+ or
+ `org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory`
+
+- `[user name]` is the user name to create a client session. It is
+ optional
+
+- `[password]` is the password to create a client session. It is
+ mandatory only if the user name is specified
+
+- `[connector parameters]` is a list of comma-separated key=value pair
+ which are passed to the connector factory (see ? for a list of the
+ transport parameters).
+
+Also note the `com.arjuna.ats.jta.xaRecoveryNode` parameter. If you want
+recovery enabled then this must be configured to what ever the tx node
+id is set to, this is configured in the same file by the
+`com.arjuna.ats.arjuna.xa.nodeIdentifier` property.
+
+> **Note**
+>
+> ActiveMQ must have a valid acceptor which corresponds to the connector
+> specified in `conf/jbossts-properties.xml`.
+
+### Configuration Settings
+
+If ActiveMQ is configured with a default in-vm acceptor:
+
+ <acceptor name="in-vm">
+ <factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory</factory-class>
+ </acceptor>
+
+the corresponding configuration in `conf/jbossts-properties.xml` is:
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
+ value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory"/>
+
+If it is now configured with a netty acceptor on a non-default port:
+
+ <acceptor name="netty">
+ <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
+ <param key="port" value="8888"/>
+ </acceptor>
+
+the corresponding configuration in `conf/jbossts-properties.xml` is:
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
+ value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/>
+
+> **Note**
+>
+> Note the additional commas to skip the user and password before
+> connector parameters
+
+If the recovery must use `admin, adminpass`, the configuration would
+have been:
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
+ value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/>
+
+Configuring ActiveMQ with an invm acceptor and configuring the Recovery
+Manager with an invm connector is the recommended way to enable XA
+Recovery.
+
+Example
+-------
+
+See ? which shows how to configure XA Recovery and recover messages
+after a server crash.
[04/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/scheduled-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/scheduled-messages.md b/docs/user-manual/en/scheduled-messages.md
new file mode 100644
index 0000000..e8f4cad
--- /dev/null
+++ b/docs/user-manual/en/scheduled-messages.md
@@ -0,0 +1,36 @@
+Scheduled Messages
+==================
+
+Scheduled messages differ from normal messages in that they won't be
+delivered until a specified time in the future, at the earliest.
+
+To do this, a special property is set on the message before sending it.
+
+Scheduled Delivery Property
+===========================
+
+The property name used to identify a scheduled message is
+`"_HQ_SCHED_DELIVERY"` (or the constant
+`Message.HDR_SCHEDULED_DELIVERY_TIME`).
+
+The specified value must be a positive `long` corresponding to the time
+the message must be delivered (in milliseconds). An example of sending a
+scheduled message using the JMS API is as follows.
+
+ TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
+ message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
+ producer.send(message);
+
+ ...
+
+ // message will not be received immediately but 5 seconds later
+ TextMessage messageReceived = (TextMessage) consumer.receive();
+
+Scheduled messages can also be sent using the core API, by setting the
+same property on the core message before sending.
+
+Example
+=======
+
+See ? for an example which shows how scheduled messages can be used with
+JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/scheduled-messages.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/scheduled-messages.xml b/docs/user-manual/en/scheduled-messages.xml
deleted file mode 100644
index 6277e9a..0000000
--- a/docs/user-manual/en/scheduled-messages.xml
+++ /dev/null
@@ -1,53 +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="scheduled-messages">
- <title>Scheduled Messages</title>
- <para>Scheduled messages differ from normal messages in that they won't be delivered until a
- specified time in the future, at the earliest.</para>
- <para>To do this, a special property is set on the message before sending it.</para>
- <section>
- <title>Scheduled Delivery Property</title>
- <para>The property name used to identify a scheduled message is <literal
- >"_HQ_SCHED_DELIVERY"</literal> (or the constant <literal
- >Message.HDR_SCHEDULED_DELIVERY_TIME</literal>).</para>
- <para>The specified value must be a positive <literal>long</literal> corresponding to the time the
- message must be delivered (in milliseconds). An example of sending a scheduled message
- using the JMS API is as follows.</para>
- <programlisting>
-TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
-message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
-producer.send(message);
-
-...
-
-// message will not be received immediately but 5 seconds later
-TextMessage messageReceived = (TextMessage) consumer.receive();</programlisting>
- <para>Scheduled messages can also be sent using the core API, by setting the same property on
- the core message before sending.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.scheduled-message"/> for an example which shows how
- scheduled messages can be used with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/security.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
new file mode 100644
index 0000000..6871334
--- /dev/null
+++ b/docs/user-manual/en/security.md
@@ -0,0 +1,306 @@
+Security
+========
+
+This chapter describes how security works with ActiveMQ and how you can
+configure it. To disable security completely simply set the
+`security-enabled` property to false in the `activemq-configuration.xml`
+file.
+
+For performance reasons security is cached and invalidated every so
+long. To change this period set the property
+`security-invalidation-interval`, which is in milliseconds. The default
+is `10000` ms.
+
+Role based security for addresses
+=================================
+
+ActiveMQ contains a flexible role-based security model for applying
+security to queues, based on their addresses.
+
+As explained in ?, ActiveMQ core consists mainly of sets of queues bound
+to addresses. A message is sent to an address and the server looks up
+the set of queues that are bound to that address, the server then routes
+the message to those set of queues.
+
+ActiveMQ allows sets of permissions to be defined against the queues
+based on their address. An exact match on the address can be used or a
+wildcard match can be used using the wildcard characters '`#`' and
+'`*`'.
+
+Seven different permissions can be given to the set of queues which
+match the address. Those permissions are:
+
+- `createDurableQueue`. This permission allows the user to create a
+ durable queue under matching addresses.
+
+- `deleteDurableQueue`. This permission allows the user to delete a
+ durable queue under matching addresses.
+
+- `createNonDurableQueue`. This permission allows the user to create a
+ non-durable queue under matching addresses.
+
+- `deleteNonDurableQueue`. This permission allows the user to delete a
+ non-durable queue under matching addresses.
+
+- `send`. This permission allows the user to send a message to
+ matching addresses.
+
+- `consume`. This permission allows the user to consume a message from
+ a queue bound to matching addresses.
+
+- `manage`. This permission allows the user to invoke management
+ operations by sending management messages to the management address.
+
+For each permission, a list of roles who are granted that permission is
+specified. If the user has any of those roles, he/she will be granted
+that permission for that set of addresses.
+
+Let's take a simple example, here's a security block from
+`activemq-configuration.xml` or `activemq-queues.xml` file:
+
+ <security-setting match="globalqueues.europe.#">
+ <permission type="createDurableQueue" roles="admin"/>
+ <permission type="deleteDurableQueue" roles="admin"/>
+ <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
+ <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
+ <permission type="send" roles="admin, europe-users"/>
+ <permission type="consume" roles="admin, europe-users"/>
+ </security-setting>
+
+The '`#`' character signifies "any sequence of words". Words are
+delimited by the '`.`' character. For a full description of the wildcard
+syntax please see ?. The above security block applies to any address
+that starts with the string "globalqueues.europe.":
+
+Only users who have the `admin` role can create or delete durable queues
+bound to an address that starts with the string "globalqueues.europe."
+
+Any users with the roles `admin`, `guest`, or `europe-users` can create
+or delete temporary queues bound to an address that starts with the
+string "globalqueues.europe."
+
+Any users with the roles `admin` or `europe-users` can send messages to
+these addresses or consume messages from queues bound to an address that
+starts with the string "globalqueues.europe."
+
+The mapping between a user and what roles they have is handled by the
+security manager. ActiveMQ ships with a user manager that reads user
+credentials from a file on disk, and can also plug into JAAS or JBoss
+Application Server security.
+
+For more information on configuring the security manager, please see ?.
+
+There can be zero or more `security-setting` elements in each xml file.
+Where more than one match applies to a set of addresses the *more
+specific* match takes precedence.
+
+Let's look at an example of that, here's another `security-setting`
+block:
+
+ <security-setting match="globalqueues.europe.orders.#">
+ <permission type="send" roles="europe-users"/>
+ <permission type="consume" roles="europe-users"/>
+ </security-setting>
+
+In this `security-setting` block the match
+'globalqueues.europe.orders.\#' is more specific than the previous match
+'globalqueues.europe.\#'. So any addresses which match
+'globalqueues.europe.orders.\#' will take their security settings *only*
+from the latter security-setting block.
+
+Note that settings are not inherited from the former block. All the
+settings will be taken from the more specific matching block, so for the
+address 'globalqueues.europe.orders.plastics' the only permissions that
+exist are `send` and `consume` for the role europe-users. The
+permissions `createDurableQueue`, `deleteDurableQueue`,
+`createNonDurableQueue`, `deleteNonDurableQueue` are not inherited from
+the other security-setting block.
+
+By not inheriting permissions, it allows you to effectively deny
+permissions in more specific security-setting blocks by simply not
+specifying them. Otherwise it would not be possible to deny permissions
+in sub-groups of addresses.
+
+Secure Sockets Layer (SSL) Transport
+====================================
+
+When messaging clients are connected to servers, or servers are
+connected to other servers (e.g. via bridges) over an untrusted network
+then ActiveMQ allows that traffic to be encrypted using the Secure
+Sockets Layer (SSL) transport.
+
+For more information on configuring the SSL transport, please see ?.
+
+Basic user credentials
+======================
+
+ActiveMQ ships with a security manager implementation that reads user
+credentials, i.e. user names, passwords and role information from an xml
+file on the classpath called `activemq-users.xml`. This is the default
+security manager.
+
+If you wish to use this security manager, then users, passwords and
+roles can easily be added into this file.
+
+Let's take a look at an example file:
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
+
+ <defaultuser name="guest" password="guest">
+ <role name="guest"/>
+ </defaultuser>
+
+ <user name="tim" password="marmite">
+ <role name="admin"/>
+ </user>
+
+ <user name="andy" password="doner_kebab">
+ <role name="admin"/>
+ <role name="guest"/>
+ </user>
+
+ <user name="jeff" password="camembert">
+ <role name="europe-users"/>
+ <role name="guest"/>
+ </user>
+
+ </configuration>
+
+The first thing to note is the element `defaultuser`. This defines what
+user will be assumed when the client does not specify a
+username/password when creating a session. In this case they will be the
+user `guest` and have the role also called `guest`. Multiple roles can
+be specified for a default user.
+
+We then have three more users, the user `tim` has the role `admin`. The
+user `andy` has the roles `admin` and `guest`, and the user `jeff` has
+the roles `europe-users` and `guest`.
+
+Changing the security manager
+=============================
+
+If you do not want to use the default security manager then you can
+specify a different one by editing the file `activemq-beans.xml` (or
+`activemq-jboss-beans.xml` if you're running JBoss Application Server)
+and changing the class for the `ActiveMQSecurityManager` bean.
+
+Let's take a look at a snippet from the default beans file:
+
+
+ <bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ </bean>
+
+The class
+`org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl` is
+the default security manager that is used by the standalone server.
+
+ActiveMQ ships with two other security manager implementations you can
+use off-the-shelf; one a JAAS security manager and another for
+integrating with JBoss Application Sever security, alternatively you
+could write your own implementation by implementing the
+`org.apache.activemq.spi.core.security.ActiveMQSecurityManager`
+interface, and specifying the classname of your implementation in the
+file `activemq-beans.xml` (or `activemq-jboss-beans.xml` if you're
+running JBoss Application Server).
+
+These two implementations are discussed in the next two sections.
+
+JAAS Security Manager
+=====================
+
+JAAS stands for 'Java Authentication and Authorization Service' and is a
+standard part of the Java platform. It provides a common API for
+security authentication and authorization, allowing you to plugin your
+pre-built implementations.
+
+To configure the JAAS security manager to work with your pre-built JAAS
+infrastructure you need to specify the security manager as a
+`JAASSecurityManager` in the beans file. Here's an example:
+
+ <bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+
+ <property name="ConfigurationName">org.apache.activemq.jms.example.ExampleLoginModule</property>
+ <property name="Configuration">
+ <inject bean="ExampleConfiguration"/>
+ </property>
+ <property name="CallbackHandler">
+ <inject bean="ExampleCallbackHandler"/>
+ </property>
+ </bean>
+
+Note that you need to feed the JAAS security manager with three
+properties:
+
+- ConfigurationName: the name of the `LoginModule` implementation that
+ JAAS must use
+
+- Configuration: the `Configuration` implementation used by JAAS
+
+- CallbackHandler: the `CallbackHandler` implementation to use if user
+ interaction are required
+
+Example
+-------
+
+See ? for an example which shows how ActiveMQ can be configured to use
+JAAS.
+
+JBoss AS Security Manager
+=========================
+
+The JBoss AS security manager is used when running ActiveMQ inside the
+JBoss Application server. This allows tight integration with the JBoss
+Application Server's security model.
+
+The class name of this security manager is
+`org.apache.activemq.integration.jboss.security.JBossASSecurityManager`
+
+Take a look at one of the default `activemq-jboss-beans.xml` files for
+JBoss Application Server that are bundled in the distribution for an
+example of how this is configured.
+
+Configuring Client Login
+------------------------
+
+JBoss can be configured to allow client login, basically this is when a
+JEE component such as a Servlet or EJB sets security credentials on the
+current security context and these are used throughout the call. If you
+would like these credentials to be used by ActiveMQ when sending or
+consuming messages then set `allowClientLogin` to true. This will bypass
+ActiveMQ authentication and propagate the provided Security Context. If
+you would like ActiveMQ to authenticate using the propagated security
+then set the `authoriseOnClientLogin` to true also.
+
+There is more info on using the JBoss client login module
+[here](http://community.jboss.org/wiki/ClientLoginModule)
+
+> **Note**
+>
+> If messages are sent non blocking then there is a chance that these
+> could arrive on the server after the calling thread has completed
+> meaning that the security context has been cleared. If this is the
+> case then messages will need to be sent blocking
+
+Changing the Security Domain
+----------------------------
+
+The name of the security domain used by the JBoss AS security manager
+defaults to `java:/jaas/activemq
+ `. This can be changed by specifying `securityDomainName`
+(e.g. java:/jaas/myDomain).
+
+Changing the username/password for clustering
+=============================================
+
+In order for cluster connections to work correctly, each node in the
+cluster must make connections to the other nodes. The username/password
+they use for this should always be changed from the installation default
+to prevent a security risk.
+
+Please see ? for instructions on how to do this.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/security.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/security.xml b/docs/user-manual/en/security.xml
deleted file mode 100644
index 1c287b1..0000000
--- a/docs/user-manual/en/security.xml
+++ /dev/null
@@ -1,287 +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="security">
- <title>Security</title>
- <para>This chapter describes how security works with ActiveMQ and how you can configure it. To
- disable security completely simply set the <literal>security-enabled</literal> property to
- false in the <literal>activemq-configuration.xml</literal> file.</para>
- <para>For performance reasons security is cached and invalidated every so long. To change this
- period set the property <literal>security-invalidation-interval</literal>, which is in
- milliseconds. The default is <literal>10000</literal> ms.</para>
- <section id="security.settings.roles">
- <title>Role based security for addresses</title>
- <para>ActiveMQ contains a flexible role-based security model for applying security to queues,
- based on their addresses.</para>
- <para>As explained in <xref linkend="using-core"/>, ActiveMQ core consists mainly of sets of
- queues bound to addresses. A message is sent to an address and the server looks up the
- set of queues that are bound to that address, the server then routes the message to
- those set of queues.</para>
- <para>ActiveMQ allows sets of permissions to be defined against the queues based on their
- address. An exact match on the address can be used or a wildcard match can be used using
- the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
- <para>Seven different permissions can be given to the set of queues which match the address.
- Those permissions are:</para>
- <itemizedlist>
- <listitem>
- <para><literal>createDurableQueue</literal>. This permission allows the user to
- create a durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>deleteDurableQueue</literal>. This permission allows the user to
- delete a durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>createNonDurableQueue</literal>. This permission allows the user to create
- a non-durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>deleteNonDurableQueue</literal>. This permission allows the user to delete
- a non-durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>send</literal>. This permission allows the user to send a message to
- matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>consume</literal>. This permission allows the user to consume a
- message from a queue bound to matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>manage</literal>. This permission allows the user to invoke
- management operations by sending management messages to the management
- address.</para>
- </listitem>
- </itemizedlist>
- <para>For each permission, a list of roles who are granted that permission is specified. If
- the user has any of those roles, he/she will be granted that permission for that set of
- addresses.</para>
- <para>Let's take a simple example, here's a security block from <literal
- >activemq-configuration.xml</literal> or <literal>activemq-queues.xml</literal>
- file:</para>
- <programlisting>
-<security-setting match="globalqueues.europe.#">
- <permission type="createDurableQueue" roles="admin"/>
- <permission type="deleteDurableQueue" roles="admin"/>
- <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
- <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
- <permission type="send" roles="admin, europe-users"/>
- <permission type="consume" roles="admin, europe-users"/>
-</security-setting></programlisting>
- <para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
- delimited by the '<literal>.</literal>' character. For a full description of the
- wildcard syntax please see <xref linkend="wildcard-syntax"/>. The above security block
- applies to any address that starts with the string "globalqueues.europe.":</para>
- <para>Only users who have the <literal>admin</literal> role can create or delete durable
- queues bound to an address that starts with the string "globalqueues.europe."</para>
- <para>Any users with the roles <literal>admin</literal>, <literal>guest</literal>, or
- <literal>europe-users</literal> can create or delete temporary queues bound to an
- address that starts with the string "globalqueues.europe."</para>
- <para>Any users with the roles <literal>admin</literal> or <literal>europe-users</literal>
- can send messages to these addresses or consume messages from queues bound to an address
- that starts with the string "globalqueues.europe."</para>
- <para>The mapping between a user and what roles they have is handled by the security
- manager. ActiveMQ ships with a user manager that reads user credentials from a file on
- disk, and can also plug into JAAS or JBoss Application Server security.</para>
- <para>For more information on configuring the security manager, please see <xref
- linkend="change-security-manager"/>.</para>
- <para>There can be zero or more <literal>security-setting</literal> elements in each xml
- file. Where more than one match applies to a set of addresses the <emphasis>more
- specific</emphasis> match takes precedence.</para>
- <para>Let's look at an example of that, here's another <literal>security-setting</literal>
- block:</para>
- <programlisting>
-<security-setting match="globalqueues.europe.orders.#">
- <permission type="send" roles="europe-users"/>
- <permission type="consume" roles="europe-users"/>
-</security-setting></programlisting>
- <para>In this <literal>security-setting</literal> block the match
- 'globalqueues.europe.orders.#' is more specific than the previous match
- 'globalqueues.europe.#'. So any addresses which match 'globalqueues.europe.orders.#'
- will take their security settings <emphasis>only</emphasis> from the latter
- security-setting block.</para>
- <para>Note that settings are not inherited from the former block. All the settings will be
- taken from the more specific matching block, so for the address
- 'globalqueues.europe.orders.plastics' the only permissions that exist are <literal
- >send</literal> and <literal>consume</literal> for the role europe-users. The
- permissions <literal>createDurableQueue</literal>, <literal
- >deleteDurableQueue</literal>, <literal>createNonDurableQueue</literal>, <literal
- >deleteNonDurableQueue</literal> are not inherited from the other security-setting
- block.</para>
- <para>By not inheriting permissions, it allows you to effectively deny permissions in more
- specific security-setting blocks by simply not specifying them. Otherwise it would not
- be possible to deny permissions in sub-groups of addresses.</para>
- </section>
- <section>
- <title>Secure Sockets Layer (SSL) Transport</title>
- <para>When messaging clients are connected to servers, or servers are connected to other
- servers (e.g. via bridges) over an untrusted network then ActiveMQ allows that traffic to
- be encrypted using the Secure Sockets Layer (SSL) transport.</para>
- <para>For more information on configuring the SSL transport, please see <xref
- linkend="configuring-transports"/>.</para>
- </section>
- <section>
- <title>Basic user credentials</title>
- <para>ActiveMQ ships with a security manager implementation that reads user credentials, i.e.
- user names, passwords and role information from an xml file on the classpath called
- <literal>activemq-users.xml</literal>. This is the default security manager.</para>
- <para>If you wish to use this security manager, then users, passwords and roles can easily
- be added into this file.</para>
- <para>Let's take a look at an example file:</para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
-
- <defaultuser name="guest" password="guest">
- <role name="guest"/>
- </defaultuser>
-
- <user name="tim" password="marmite">
- <role name="admin"/>
- </user>
-
- <user name="andy" password="doner_kebab">
- <role name="admin"/>
- <role name="guest"/>
- </user>
-
- <user name="jeff" password="camembert">
- <role name="europe-users"/>
- <role name="guest"/>
- </user>
-
-</configuration></programlisting>
- <para>The first thing to note is the element <literal>defaultuser</literal>. This defines
- what user will be assumed when the client does not specify a username/password when
- creating a session. In this case they will be the user <literal>guest</literal> and have
- the role also called <literal>guest</literal>. Multiple roles can be specified for a
- default user.</para>
- <para>We then have three more users, the user <literal>tim</literal> has the role <literal
- >admin</literal>. The user <literal>andy</literal> has the roles <literal
- >admin</literal> and <literal>guest</literal>, and the user <literal>jeff</literal>
- has the roles <literal>europe-users</literal> and <literal>guest</literal>.</para>
- </section>
- <section id="change-security-manager">
- <title>Changing the security manager</title>
- <para>If you do not want to use the default security manager then you can specify a
- different one by editing the file <literal>activemq-beans.xml</literal> (or <literal
- >activemq-jboss-beans.xml</literal> if you're running JBoss Application Server) and
- changing the class for the <literal>ActiveMQSecurityManager</literal> bean.</para>
- <para>Let's take a look at a snippet from the default beans file:</para>
- <programlisting>
-<bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
- <start ignored="true"/>
- <stop ignored="true"/>
-</bean></programlisting>
- <para>The class <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl</literal>
- is the default security manager that is used by the standalone server.</para>
- <para>ActiveMQ ships with two other security manager implementations you can use
- off-the-shelf; one a JAAS security manager and another for integrating with JBoss
- Application Sever security, alternatively you could write your own implementation by
- implementing the <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManager</literal>
- interface, and specifying the classname of your implementation in the file <literal
- >activemq-beans.xml</literal> (or <literal>activemq-jboss-beans.xml</literal> if
- you're running JBoss Application Server).</para>
- <para>These two implementations are discussed in the next two sections.</para>
- </section>
- <section>
- <title>JAAS Security Manager</title>
- <para>JAAS stands for 'Java Authentication and Authorization Service' and is a standard part
- of the Java platform. It provides a common API for security authentication and
- authorization, allowing you to plugin your pre-built implementations.</para>
- <para>To configure the JAAS security manager to work with your pre-built JAAS infrastructure
- you need to specify the security manager as a <literal>JAASSecurityManager</literal> in
- the beans file. Here's an example:</para>
- <programlisting>
-<bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
- <start ignored="true"/>
- <stop ignored="true"/>
-
- <property name="ConfigurationName">org.apache.activemq.jms.example.ExampleLoginModule</property>
- <property name="Configuration">
- <inject bean="ExampleConfiguration"/>
- </property>
- <property name="CallbackHandler">
- <inject bean="ExampleCallbackHandler"/>
- </property>
-</bean></programlisting>
- <para>Note that you need to feed the JAAS security manager with three properties:</para>
- <itemizedlist>
- <listitem>
- <para>ConfigurationName: the name of the <literal>LoginModule</literal>
- implementation that JAAS must use</para>
- </listitem>
- <listitem>
- <para>Configuration: the <literal>Configuration</literal> implementation used by
- JAAS</para>
- </listitem>
- <listitem>
- <para>CallbackHandler: the <literal>CallbackHandler</literal> implementation to use
- if user interaction are required</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.jaas"/> for an example which shows how ActiveMQ can be
- configured to use JAAS.</para>
- </section>
- </section>
- <section>
- <title>JBoss AS Security Manager</title>
- <para>The JBoss AS security manager is used when running ActiveMQ inside the JBoss
- Application server. This allows tight integration with the JBoss Application Server's
- security model.</para>
- <para>The class name of this security manager is <literal
- >org.apache.activemq.integration.jboss.security.JBossASSecurityManager</literal></para>
- <para>Take a look at one of the default <literal>activemq-jboss-beans.xml</literal> files for
- JBoss Application Server that are bundled in the distribution for an example of how this
- is configured.</para>
- <section>
- <title>Configuring Client Login</title>
- <para>JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet
- or EJB sets security credentials on the current security context and these are used throughout the call.
- If you would like these credentials to be used by ActiveMQ when sending or consuming messages then
- set <literal>allowClientLogin</literal> to true. This will bypass ActiveMQ authentication and propagate the
- provided Security Context. If you would like ActiveMQ to authenticate using the propagated security then set the
- <literal>authoriseOnClientLogin</literal> to true also.</para>
- <para>There is more info on using the JBoss client login module <ulink
- url="http://community.jboss.org/wiki/ClientLoginModule">here</ulink> </para>
- <note><para>If messages are sent non blocking then there is a chance that these could arrive on the server after
- the calling thread has completed meaning that the security context has been cleared. If this is the case then messages
- will need to be sent blocking</para></note>
- </section>
- <section>
- <title>Changing the Security Domain</title>
- <para>The name of the security domain used by the JBoss AS security manager defaults to <literal>java:/jaas/activemq
- </literal>. This can be changed by specifying <literal>securityDomainName</literal> (e.g. java:/jaas/myDomain).
- </para>
- </section>
- </section>
- <section>
- <title>Changing the username/password for clustering</title>
- <para>In order for cluster connections to work correctly, each node in the cluster must make
- connections to the other nodes. The username/password they use for this should always be
- changed from the installation default to prevent a security risk.</para>
- <para>Please see <xref linkend="management"/> for instructions on how to do this.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/send-guarantees.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/send-guarantees.md b/docs/user-manual/en/send-guarantees.md
new file mode 100644
index 0000000..439f70e
--- /dev/null
+++ b/docs/user-manual/en/send-guarantees.md
@@ -0,0 +1,151 @@
+Guarantees of sends and commits
+===============================
+
+Guarantees of Transaction Completion
+====================================
+
+When committing or rolling back a transaction with ActiveMQ, the request
+to commit or rollback is sent to the server, and the call will block on
+the client side until a response has been received from the server that
+the commit or rollback was executed.
+
+When the commit or rollback is received on the server, it will be
+committed to the journal, and depending on the value of the parameter
+`journal-sync-transactional` the server will ensure that the commit or
+rollback is durably persisted to storage before sending the response
+back to the client. If this parameter has the value `false` then commit
+or rollback may not actually get persisted to storage until some time
+after the response has been sent to the client. In event of server
+failure this may mean the commit or rollback never gets persisted to
+storage. The default value of this parameter is `true` so the client can
+be sure all transaction commits or rollbacks have been persisted to
+storage by the time the call to commit or rollback returns.
+
+Setting this parameter to `false` can improve performance at the expense
+of some loss of transaction durability.
+
+This parameter is set in `activemq-configuration.xml`
+
+Guarantees of Non Transactional Message Sends
+=============================================
+
+If you are sending messages to a server using a non transacted session,
+ActiveMQ can be configured to block the call to send until the message
+has definitely reached the server, and a response has been sent back to
+the client. This can be configured individually for durable and
+non-durable messages, and is determined by the following two parameters:
+
+- `BlockOnDurableSend`. If this is set to `true` then all calls to
+ send for durable messages on non transacted sessions will block
+ until the message has reached the server, and a response has been
+ sent back. The default value is `true`.
+
+- `BlockOnNonDurableSend`. If this is set to `true` then all calls to
+ send for non-durable messages on non transacted sessions will block
+ until the message has reached the server, and a response has been
+ sent back. The default value is `false`.
+
+Setting block on sends to `true` can reduce performance since each send
+requires a network round trip before the next send can be performed.
+This means the performance of sending messages will be limited by the
+network round trip time (RTT) of your network, rather than the bandwidth
+of your network. For better performance we recommend either batching
+many messages sends together in a transaction since with a transactional
+session, only the commit / rollback blocks not every send, or, using
+ActiveMQ's advanced *asynchronous send acknowledgements feature*
+described in ?.
+
+If you are using JMS and you're using the JMS service on the server to
+load your JMS connection factory instances into JNDI then these
+parameters can be configured in `activemq-jms.xml` using the elements
+`block-on-durable-send` and `block-on-non-durable-send`. If you're using
+JMS but not using JNDI then you can set these values directly on the
+`ActiveMQConnectionFactory` instance using the appropriate setter
+methods.
+
+If you're using core you can set these values directly on the
+`ClientSessionFactory` instance using the appropriate setter methods.
+
+When the server receives a message sent from a non transactional
+session, and that message is durable and the message is routed to at
+least one durable queue, then the server will persist the message in
+permanent storage. If the journal parameter
+`journal-sync-non-transactional` is set to `true` the server will not
+send a response back to the client until the message has been persisted
+and the server has a guarantee that the data has been persisted to disk.
+The default value for this parameter is `true`.
+
+Guarantees of Non Transactional Acknowledgements
+================================================
+
+If you are acknowledging the delivery of a message at the client side
+using a non transacted session, ActiveMQ can be configured to block the
+call to acknowledge until the acknowledge has definitely reached the
+server, and a response has been sent back to the client. This is
+configured with the parameter `BlockOnAcknowledge`. If this is set to
+`true` then all calls to acknowledge on non transacted sessions will
+block until the acknowledge has reached the server, and a response has
+been sent back. You might want to set this to `true` if you want to
+implement a strict *at most once* delivery policy. The default value is
+`false`
+
+Asynchronous Send Acknowledgements
+==================================
+
+If you are using a non transacted session but want a guarantee that
+every message sent to the server has reached it, then, as discussed in
+?, you can configure ActiveMQ to block the call to send until the server
+has received the message, persisted it and sent back a response. This
+works well but has a severe performance penalty - each call to send
+needs to block for at least the time of a network round trip (RTT) - the
+performance of sending is thus limited by the latency of the network,
+*not* limited by the network bandwidth.
+
+Let's do a little bit of maths to see how severe that is. We'll consider
+a standard 1Gib ethernet network with a network round trip between the
+server and the client of 0.25 ms.
+
+With a RTT of 0.25 ms, the client can send *at most* 1000/ 0.25 = 4000
+messages per second if it blocks on each message send.
+
+If each message is \< 1500 bytes and a standard 1500 bytes MTU size is
+used on the network, then a 1GiB network has a *theoretical* upper limit
+of (1024 \* 1024 \* 1024 / 8) / 1500 = 89478 messages per second if
+messages are sent without blocking! These figures aren't an exact
+science but you can clearly see that being limited by network RTT can
+have serious effect on performance.
+
+To remedy this, ActiveMQ provides an advanced new feature called
+*asynchronous send acknowledgements*. With this feature, ActiveMQ can be
+configured to send messages without blocking in one direction and
+asynchronously getting acknowledgement from the server that the messages
+were received in a separate stream. By de-coupling the send from the
+acknowledgement of the send, the system is not limited by the network
+RTT, but is limited by the network bandwidth. Consequently better
+throughput can be achieved than is possible using a blocking approach,
+while at the same time having absolute guarantees that messages have
+successfully reached the server.
+
+The window size for send acknowledgements is determined by the
+confirmation-window-size parameter on the connection factory or client
+session factory. Please see ? for more info on this.
+
+Asynchronous Send Acknowledgements
+----------------------------------
+
+To use the feature using the core API, you implement the interface
+`org.apache.activemq.api.core.client.SendAcknowledgementHandler` and set
+a handler instance on your `ClientSession`.
+
+Then, you just send messages as normal using your `ClientSession`, and
+as messages reach the server, the server will send back an
+acknowledgement of the send asynchronously, and some time later you are
+informed at the client side by ActiveMQ calling your handler's
+`sendAcknowledged(ClientMessage message)` method, passing in a reference
+to the message that was sent.
+
+To enable asynchronous send acknowledgements you must make sure
+`confirmation-window-size` is set to a positive integer value, e.g.
+10MiB
+
+Please see ? for a full working example.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/send-guarantees.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/send-guarantees.xml b/docs/user-manual/en/send-guarantees.xml
deleted file mode 100644
index a572e14..0000000
--- a/docs/user-manual/en/send-guarantees.xml
+++ /dev/null
@@ -1,152 +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="send-guarantees">
- <title>Guarantees of sends and commits</title>
- <section>
- <title>Guarantees of Transaction Completion</title>
- <para>When committing or rolling back a transaction with ActiveMQ, the request to commit or
- rollback is sent to the server, and the call will block on the client side until a
- response has been received from the server that the commit or rollback was
- executed.</para>
- <para>When the commit or rollback is received on the server, it will be committed to the
- journal, and depending on the value of the parameter <literal
- >journal-sync-transactional</literal> the server will ensure that the commit or
- rollback is durably persisted to storage before sending the response back to the client.
- If this parameter has the value <literal>false</literal> then commit or rollback may not
- actually get persisted to storage until some time after the response has been sent to
- the client. In event of server failure this may mean the commit or rollback never gets
- persisted to storage. The default value of this parameter is <literal>true</literal> so
- the client can be sure all transaction commits or rollbacks have been persisted to
- storage by the time the call to commit or rollback returns.</para>
- <para>Setting this parameter to <literal>false</literal> can improve performance at the
- expense of some loss of transaction durability.</para>
- <para>This parameter is set in <literal>activemq-configuration.xml</literal></para>
- </section>
- <section id="non-transactional-sends">
- <title>Guarantees of Non Transactional Message Sends</title>
- <para>If you are sending messages to a server using a non transacted session, ActiveMQ can be
- configured to block the call to send until the message has definitely reached the
- server, and a response has been sent back to the client. This can be configured
- individually for durable and non-durable messages, and is determined by the
- following two parameters:</para>
- <itemizedlist>
- <listitem>
- <para><literal>BlockOnDurableSend</literal>. If this is set to <literal
- >true</literal> then all calls to send for durable messages on non
- transacted sessions will block until the message has reached the server, and a
- response has been sent back. The default value is <literal>true</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>BlockOnNonDurableSend</literal>. If this is set to <literal
- >true</literal> then all calls to send for non-durable messages on non
- transacted sessions will block until the message has reached the server, and a
- response has been sent back. The default value is <literal
- >false</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>Setting block on sends to <literal>true</literal> can reduce performance since each
- send requires a network round trip before the next send can be performed. This means the
- performance of sending messages will be limited by the network round trip time (RTT) of
- your network, rather than the bandwidth of your network. For better performance we
- recommend either batching many messages sends together in a transaction since with a
- transactional session, only the commit / rollback blocks not every send, or, using
- ActiveMQ's advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
- described in <xref linkend="asynchronous-send-acknowledgements"/>.</para>
- <para>If you are using JMS and you're using the JMS service on the server to load your JMS
- connection factory instances into JNDI then these parameters can be configured in
- <literal>activemq-jms.xml</literal> using the elements <literal
- >block-on-durable-send</literal> and <literal
- >block-on-non-durable-send</literal>. If you're using JMS but not using JNDI then
- you can set these values directly on the <literal>ActiveMQConnectionFactory</literal>
- instance using the appropriate setter methods.</para>
- <para>If you're using core you can set these values directly on the <literal
- >ClientSessionFactory</literal> instance using the appropriate setter
- methods.</para>
- <para>When the server receives a message sent from a non transactional session, and that
- message is durable and the message is routed to at least one durable queue, then the
- server will persist the message in permanent storage. If the journal parameter <literal
- >journal-sync-non-transactional</literal> is set to <literal>true</literal> the
- server will not send a response back to the client until the message has been persisted
- and the server has a guarantee that the data has been persisted to disk. The default
- value for this parameter is <literal>true</literal>.</para>
- </section>
- <section id="send-guarantees.nontrans.acks">
- <title>Guarantees of Non Transactional Acknowledgements</title>
- <para>If you are acknowledging the delivery of a message at the client side using a non
- transacted session, ActiveMQ can be configured to block the call to acknowledge until the
- acknowledge has definitely reached the server, and a response has been sent back to the
- client. This is configured with the parameter <literal>BlockOnAcknowledge</literal>. If
- this is set to <literal>true</literal> then all calls to acknowledge on non transacted
- sessions will block until the acknowledge has reached the server, and a response has
- been sent back. You might want to set this to <literal>true</literal> if you want to
- implement a strict <emphasis>at most once</emphasis> delivery policy. The default value
- is <literal>false</literal></para>
- </section>
- <section id="asynchronous-send-acknowledgements">
- <title>Asynchronous Send Acknowledgements</title>
- <para>If you are using a non transacted session but want a guarantee that every message sent
- to the server has reached it, then, as discussed in <xref
- linkend="non-transactional-sends"/>, you can configure ActiveMQ to block the call to
- send until the server has received the message, persisted it and sent back a response.
- This works well but has a severe performance penalty - each call to send needs to block
- for at least the time of a network round trip (RTT) - the performance of sending is thus
- limited by the latency of the network, <emphasis>not</emphasis> limited by the network
- bandwidth.</para>
- <para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
- 1Gib ethernet network with a network round trip between the server and the client of
- 0.25 ms.</para>
- <para>With a RTT of 0.25 ms, the client can send <emphasis>at most</emphasis> 1000/ 0.25 =
- 4000 messages per second if it blocks on each message send.</para>
- <para>If each message is < 1500 bytes and a standard 1500 bytes MTU size is used on the
- network, then a 1GiB network has a <emphasis>theoretical</emphasis> upper limit of (1024
- * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
- blocking! These figures aren't an exact science but you can clearly see that being
- limited by network RTT can have serious effect on performance.</para>
- <para>To remedy this, ActiveMQ provides an advanced new feature called <emphasis>asynchronous
- send acknowledgements</emphasis>. With this feature, ActiveMQ can be configured to
- send messages without blocking in one direction and asynchronously getting
- acknowledgement from the server that the messages were received in a separate stream. By
- de-coupling the send from the acknowledgement of the send, the system is not limited by
- the network RTT, but is limited by the network bandwidth. Consequently better throughput
- can be achieved than is possible using a blocking approach, while at the same time
- having absolute guarantees that messages have successfully reached the server.</para>
- <para>The window size for send acknowledgements is determined by the confirmation-window-size parameter on
- the connection factory or client session factory. Please see <xref linkend="client-reconnection"/> for more info on this.</para>
- <section>
- <title>Asynchronous Send Acknowledgements</title>
- <para>To use the feature using the core API, you implement the interface <literal
- >org.apache.activemq.api.core.client.SendAcknowledgementHandler</literal> and set a handler
- instance on your <literal>ClientSession</literal>.</para>
- <para>Then, you just send messages as normal using your <literal
- >ClientSession</literal>, and as messages reach the server, the server will send
- back an acknowledgement of the send asynchronously, and some time later you are
- informed at the client side by ActiveMQ calling your handler's <literal
- >sendAcknowledged(ClientMessage message)</literal> method, passing in a
- reference to the message that was sent.</para>
- <para>To enable asynchronous send acknowledgements you must make sure <literal>confirmation-window-size</literal> is set to a positive integer value, e.g. 10MiB</para>
- <para>Please see <xref linkend="asynchronous-send-acknowledgements-example"/> for a full
- working example.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/slow-consumers.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/slow-consumers.md b/docs/user-manual/en/slow-consumers.md
new file mode 100644
index 0000000..ae03d30
--- /dev/null
+++ b/docs/user-manual/en/slow-consumers.md
@@ -0,0 +1,36 @@
+Detecting Slow Consumers
+========================
+
+In this section we will discuss how ActiveMQ can be configured to deal
+with slow consumers. A slow consumer with a server-side queue (e.g. JMS
+topic subscriber) can pose a significant problem for broker performance.
+If messages build up in the consumer's server-side queue then memory
+will begin filling up and the broker may enter paging mode which would
+impact performance negatively. However, criteria can be set so that
+consumers which don't acknowledge messages quickly enough can
+potentially be disconnected from the broker which in the case of a
+non-durable JMS subscriber would allow the broker to remove the
+subscription and all of its messages freeing up valuable server
+resources.
+
+Configuration required for detecting slow consumers
+===================================================
+
+By default the server will not detect slow consumers. If slow consumer
+detection is desired then see ? for more details.
+
+The calculation to determine whether or not a consumer is slow only
+inspects the number of messages a particular consumer has
+*acknowledged*. It doesn't take into account whether or not flow control
+has been enabled on the consumer, whether or not the consumer is
+streaming a large message, etc. Keep this in mind when configuring slow
+consumer detection.
+
+Please note that slow consumer checks are performed using the scheduled
+thread pool and that each queue on the broker with slow consumer
+detection enabled will cause a new entry in the internal
+`java.util.concurrent.ScheduledThreadPoolExecutor` instance. If there
+are a high number of queues and the `slow-consumer-check-period` is
+relatively low then there may be delays in executing some of the checks.
+However, this will not impact the accuracy of the calculations used by
+the detection algorithm. See ? for more details about this pool.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/slow-consumers.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/slow-consumers.xml b/docs/user-manual/en/slow-consumers.xml
deleted file mode 100644
index 227fa22..0000000
--- a/docs/user-manual/en/slow-consumers.xml
+++ /dev/null
@@ -1,52 +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="slow-consumers">
- <title>Detecting Slow Consumers</title>
- <para>In this section we will discuss how ActiveMQ can be configured to deal with slow consumers. A slow consumer with
- a server-side queue (e.g. JMS topic subscriber) can pose a significant problem for broker performance. If messages
- build up in the consumer's server-side queue then memory will begin filling up and the broker may enter paging
- mode which would impact performance negatively. However, criteria can be set so that consumers which don't
- acknowledge messages quickly enough can potentially be disconnected from the broker which in the case of a
- non-durable JMS subscriber would allow the broker to remove the subscription and all of its messages freeing up
- valuable server resources.
- </para>
- <section id="slow.consumer.configuration">
- <title>Configuration required for detecting slow consumers</title>
- <para>By default the server will not detect slow consumers. If slow consumer detection is desired then see
- <xref linkend="queue-attributes.address-settings"/>
- for more details.
- </para>
- <para>The calculation to determine whether or not a consumer is slow only inspects the number of messages a
- particular consumer has <emphasis>acknowledged</emphasis>. It doesn't take into account whether or not flow
- control has been enabled on the consumer, whether or not the consumer is streaming a large message, etc. Keep
- this in mind when configuring slow consumer detection.
- </para>
- <para>Please note that slow consumer checks are performed using the scheduled thread pool and that each queue on
- the broker with slow consumer detection enabled will cause a new entry in the internal
- <literal>java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance. If there are a high number of
- queues and the <literal>slow-consumer-check-period</literal> is relatively low then there may be delays in
- executing some of the checks. However, this will not impact the accuracy of the calculations used by the
- detection algorithm. See <xref linkend="server.scheduled.thread.pool"/> for more details about this pool.
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/spring-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/spring-integration.md b/docs/user-manual/en/spring-integration.md
new file mode 100644
index 0000000..570eac5
--- /dev/null
+++ b/docs/user-manual/en/spring-integration.md
@@ -0,0 +1,50 @@
+Spring Integration
+==================
+
+ActiveMQ provides a simple bootstrap class,
+`org.apache.activemq.integration.spring.SpringJmsBootstrap`, for
+integration with Spring. To use it, you configure ActiveMQ as you always
+would, through its various configuration files like
+`activemq-configuration.xml`, `activemq-jms.xml`, and
+`activemq-users.xml`. The Spring helper class starts the ActiveMQ server
+and adds any factories or destinations configured within
+`activemq-jms.xml` directly into the namespace of the Spring context.
+Let's take this `activemq-jms.xml` file for instance:
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq /schema/activemq-jms.xsd">
+
+ <!--the queue used by the example-->
+ <queue name="exampleQueue"/>
+ </configuration>
+
+Here we've specified a `javax.jms.ConnectionFactory` we want bound to a
+`ConnectionFactory` entry as well as a queue destination bound to a
+`/queue/exampleQueue` entry. Using the `SpringJmsBootStrap` bean will
+automatically populate the Spring context with references to those beans
+so that you can use them. Below is an example Spring JMS bean file
+taking advantage of this feature:
+
+ <beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
+
+ <bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
+
+ <bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
+
+ <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
+ <property name="connectionFactory" ref="ConnectionFactory"/>
+ <property name="destination" ref="/queue/exampleQueue"/>
+ <property name="messageListener" ref="listener"/>
+ </bean>
+ </beans>
+
+As you can see, the `listenerContainer` bean references the components
+defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class
+extends the EmbeddedJMS class talked about in ? and the same defaults
+and configuration options apply. Also notice that an `init-method` must
+be declared with a start value so that the bean's lifecycle is executed.
+See the javadocs for more details on other properties of the bean class.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/spring-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/spring-integration.xml b/docs/user-manual/en/spring-integration.xml
deleted file mode 100644
index b516871..0000000
--- a/docs/user-manual/en/spring-integration.xml
+++ /dev/null
@@ -1,81 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd"> -->
-<!-- ============================================================================= -->
-<!-- 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="spring.integration">
- <title>Spring Integration</title>
-
- <para>ActiveMQ provides a simple bootstrap class,
- <literal>org.apache.activemq.integration.spring.SpringJmsBootstrap</literal>, for
- integration with Spring. To use it, you configure ActiveMQ as you always
- would, through its various configuration files like
- <literal>activemq-configuration.xml</literal>,
- <literal>activemq-jms.xml</literal>, and
- <literal>activemq-users.xml</literal>. The Spring helper class starts the
- ActiveMQ server and adds any factories or destinations configured within
- <literal>activemq-jms.xml</literal> directly into the namespace of the Spring
- context. Let's take this <literal>activemq-jms.xml</literal> file for
- instance: </para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq /schema/activemq-jms.xsd">
-
- <!--the queue used by the example-->
- <queue name="exampleQueue"/>
-</configuration></programlisting>
- <para>Here we've specified a
- <literal>javax.jms.ConnectionFactory</literal> we want bound to a
- <literal>ConnectionFactory</literal> entry as well as a queue destination
- bound to a <literal>/queue/exampleQueue</literal> entry. Using the
- <literal>SpringJmsBootStrap</literal> bean will automatically populate the
- Spring context with references to those beans so that you can use them.
- Below is an example Spring JMS bean file taking advantage of this
- feature:</para>
- <programlisting>
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
-
- <bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
-
- <bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
-
- <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
- <property name="connectionFactory" ref="ConnectionFactory"/>
- <property name="destination" ref="/queue/exampleQueue"/>
- <property name="messageListener" ref="listener"/>
- </bean>
-</beans></programlisting>
- <para>As you can see, the
- <literal>listenerContainer</literal> bean references the components defined
- in the <literal>activemq-jms.xml</literal> file. The
- <literal>SpringJmsBootstrap</literal> class extends the EmbeddedJMS class
- talked about in <xref
- linkend="simple.embedded.jms" /> and the same defaults and
- configuration options apply. Also notice that an
- <literal>init-method</literal> must be declared with a start value so that
- the bean's lifecycle is executed. See the javadocs for more details on other
- properties of the bean class.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/thread-pooling.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/thread-pooling.md b/docs/user-manual/en/thread-pooling.md
new file mode 100644
index 0000000..3dee1ea
--- /dev/null
+++ b/docs/user-manual/en/thread-pooling.md
@@ -0,0 +1,154 @@
+Thread management
+=================
+
+This chapter describes how ActiveMQ uses and pools threads and how you
+can manage them.
+
+First we'll discuss how threads are managed and used on the server side,
+then we'll look at the client side.
+
+Server-Side Thread Management
+=============================
+
+Each ActiveMQ Server maintains a single thread pool for general use, and
+a scheduled thread pool for scheduled use. A Java scheduled thread pool
+cannot be configured to use a standard thread pool, otherwise we could
+use a single thread pool for both scheduled and non scheduled activity.
+
+A separate thread pool is also used to service connections. ActiveMQ can
+use "old" (blocking) IO or "new" (non-blocking) IO also called NIO. Both
+of these options use a separate thread pool, but each of them behaves
+uniquely.
+
+Since old IO requires a thread per connection its thread pool is
+unbounded. The thread pool is created via `
+ java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)`.
+As the JavaDoc for this method states: “Creates a thread pool that
+creates new threads as needed, but will reuse previously constructed
+threads when they are available, and uses the provided ThreadFactory to
+create new threads when needed.” Threads from this pool which are idle
+for more than 60 seconds will time out and be removed. If old IO
+connections were serviced from the standard pool the pool would easily
+get exhausted if too many connections were made, resulting in the server
+"hanging" since it has no remaining threads to do anything else.
+However, even an unbounded thread pool can run into trouble if it
+becomes too large. If you require the server to handle many concurrent
+connections you should use NIO, not old IO.
+
+When using new IO (NIO), ActiveMQ will, by default, cap its thread pool
+at three times the number of cores (or hyper-threads) as reported by `
+ Runtime.getRuntime().availableProcessors()` for processing
+incoming packets. To override this value, you can set the number of
+threads by specifying the parameter `nio-remoting-threads` in the
+transport configuration. See the ? for more information on this.
+
+There are also a small number of other places where threads are used
+directly, we'll discuss each in turn.
+
+Server Scheduled Thread Pool
+----------------------------
+
+The server scheduled thread pool is used for most activities on the
+server side that require running periodically or with delays. It maps
+internally to a `java.util.concurrent.ScheduledThreadPoolExecutor`
+instance.
+
+The maximum number of thread used by this pool is configure in
+`activemq-configuration.xml` with the `scheduled-thread-pool-max-size`
+parameter. The default value is `5` threads. A small number of threads
+is usually sufficient for this pool.
+
+General Purpose Server Thread Pool
+----------------------------------
+
+This general purpose thread pool is used for most asynchronous actions
+on the server side. It maps internally to a
+`java.util.concurrent.ThreadPoolExecutor` instance.
+
+The maximum number of thread used by this pool is configure in
+`activemq-configuration.xml` with the `thread-pool-max-size` parameter.
+
+If a value of `-1` is used this signifies that the thread pool has no
+upper bound and new threads will be created on demand if there are not
+enough threads available to satisfy a request. If activity later
+subsides then threads are timed-out and closed.
+
+If a value of `n` where `n`is a positive integer greater than zero is
+used this signifies that the thread pool is bounded. If more requests
+come in and there are no free threads in the pool and the pool is full
+then requests will block until a thread becomes available. It is
+recommended that a bounded thread pool is used with caution since it can
+lead to dead-lock situations if the upper bound is chosen to be too low.
+
+The default value for `thread-pool-max-size` is `30`.
+
+See the [J2SE
+javadoc](http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.htm)
+for more information on unbounded (cached), and bounded (fixed) thread
+pools.
+
+Expiry Reaper Thread
+--------------------
+
+A single thread is also used on the server side to scan for expired
+messages in queues. We cannot use either of the thread pools for this
+since this thread needs to run at its own configurable priority.
+
+For more information on configuring the reaper, please see ?.
+
+Asynchronous IO
+---------------
+
+Asynchronous IO has a thread pool for receiving and dispatching events
+out of the native layer. You will find it on a thread dump with the
+prefix ActiveMQ-AIO-poller-pool. ActiveMQ uses one thread per opened
+file on the journal (there is usually one).
+
+There is also a single thread used to invoke writes on libaio. We do
+that to avoid context switching on libaio that would cause performance
+issues. You will find this thread on a thread dump with the prefix
+ActiveMQ-AIO-writer-pool.
+
+Client-Side Thread Management
+=============================
+
+On the client side, ActiveMQ maintains a single static scheduled thread
+pool and a single static general thread pool for use by all clients
+using the same classloader in that JVM instance.
+
+The static scheduled thread pool has a maximum size of `5` threads, and
+the general purpose thread pool has an unbounded maximum size.
+
+If required ActiveMQ can also be configured so that each
+`ClientSessionFactory` instance does not use these static pools but
+instead maintains its own scheduled and general purpose pool. Any
+sessions created from that `ClientSessionFactory` will use those pools
+instead.
+
+To configure a `ClientSessionFactory` instance to use its own pools,
+simply use the appropriate setter methods immediately after creation,
+for example:
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
+ ClientSessionFactory myFactory = locator.createClientSessionFactory();
+ myFactory.setUseGlobalPools(false);
+ myFactory.setScheduledThreadPoolMaxSize(10);
+ myFactory.setThreadPoolMaxSize(-1);
+
+If you're using the JMS API, you can set the same parameters on the
+ClientSessionFactory and use it to create the `ConnectionFactory`
+instance, for example:
+
+ ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
+
+If you're using JNDI to instantiate `ActiveMQConnectionFactory`
+instances, you can also set these parameters in the JNDI context
+environment, e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.useGlobalPools=false
+ connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
+ connection.ConnectionFactory.threadPoolMaxSize=-1
[24/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
ACTIVEMQ6-9 - port to markdown
https://issues.apache.org/jira/browse/ACTIVEMQ6-9
remove the jboss jdocbook build and style and replace using plane markdown
Project: http://git-wip-us.apache.org/repos/asf/activemq-6/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-6/commit/4245a6b4
Tree: http://git-wip-us.apache.org/repos/asf/activemq-6/tree/4245a6b4
Diff: http://git-wip-us.apache.org/repos/asf/activemq-6/diff/4245a6b4
Branch: refs/heads/master
Commit: 4245a6b4fe667021eb791543577ea9a4c99155a1
Parents: d42481d
Author: Andy Taylor <an...@apache.org>
Authored: Thu Dec 4 15:25:29 2014 +0000
Committer: Andy Taylor <an...@apache.org>
Committed: Mon Dec 8 13:23:24 2014 +0000
----------------------------------------------------------------------
distribution/activemq/src/main/assembly/dep.xml | 12 -
docs/design-guide/en/Author_Group.xml | 34 -
docs/design-guide/en/Book_Info.xml | 48 -
docs/design-guide/en/HornetQ_Design_Guide.ent | 5 -
docs/design-guide/en/HornetQ_Design_Guide.xml | 30 -
docs/design-guide/en/about.md | 4 +
docs/design-guide/en/about.xml | 28 -
docs/design-guide/en/clustering.md | 23 +
docs/design-guide/en/clustering.xml | 42 -
docs/design-guide/en/notice.md | 17 +
docs/design-guide/en/notice.xml | 41 -
docs/design-guide/pom.xml | 310 ---
docs/diagrams/standard_image.odg | Bin 11094 -> 0 bytes
docs/eap-manual/en/Author_Group.xml | 35 -
docs/eap-manual/en/Book_Info.xml | 49 -
docs/eap-manual/en/HornetQ_EAP_Manual.ent | 7 -
docs/eap-manual/en/HornetQ_EAP_Manual.xml | 29 -
docs/eap-manual/en/clusters.xml | 573 -----
docs/eap-manual/en/diagrams/ha-topologies1.odg | Bin 14529 -> 0 bytes
docs/eap-manual/en/images/simple-colocated.jpg | Bin 94996 -> 0 bytes
docs/eap-manual/en/images/simple-colocated2.jpg | Bin 124592 -> 0 bytes
docs/eap-manual/en/images/simple-colocated3.jpg | Bin 162357 -> 0 bytes
.../en/images/simple-dedicated-jca-remote.jpg | Bin 65959 -> 0 bytes
.../en/images/simple-dedicated-jca.jpg | Bin 100349 -> 0 bytes
docs/eap-manual/en/images/simple-dedicated.jpg | Bin 49812 -> 0 bytes
docs/eap-manual/en/master.xml | 0
docs/eap-manual/pom.xml | 309 ---
docs/pom.xml | 55 -
.../en/ActiveMQ_QuickStart_Guide.ent | 5 -
.../en/ActiveMQ_QuickStart_Guide.xml | 17 -
docs/quickstart-guide/en/Author_Group.xml | 45 -
docs/quickstart-guide/en/Book_Info.xml | 31 -
docs/quickstart-guide/en/README.md | 4 +
docs/quickstart-guide/en/SUMMARY.md | 7 +
docs/quickstart-guide/en/about.md | 49 +
docs/quickstart-guide/en/about.xml | 83 -
docs/quickstart-guide/en/download.md | 36 +
docs/quickstart-guide/en/download.xml | 74 -
docs/quickstart-guide/en/examples.md | 314 +++
docs/quickstart-guide/en/examples.xml | 329 ---
.../en/images/hornetQ_logo_600px.png | Bin 23866 -> 0 bytes
docs/quickstart-guide/en/installation.md | 85 +
docs/quickstart-guide/en/installation.xml | 101 -
docs/quickstart-guide/en/introduction.md | 13 +
docs/quickstart-guide/en/introduction.xml | 32 -
docs/quickstart-guide/en/master.xml | 0
docs/quickstart-guide/en/migrate.sh | 6 +
docs/quickstart-guide/en/notice.md | 17 +
docs/quickstart-guide/en/notice.xml | 40 -
docs/quickstart-guide/en/running.md | 106 +
docs/quickstart-guide/en/running.xml | 124 -
docs/quickstart-guide/pom.xml | 300 ---
docs/user-manual/en/ActiveMQ_User_Manual.ent | 22 -
docs/user-manual/en/ActiveMQ_User_Manual.xml | 79 -
docs/user-manual/en/Author_Group.xml | 86 -
docs/user-manual/en/Book_Info.xml | 48 -
docs/user-manual/en/README.md | 7 +
docs/user-manual/en/SUMMARY.md | 53 +
docs/user-manual/en/aerogear-integration.md | 101 +
docs/user-manual/en/aerogear-integration.xml | 115 -
docs/user-manual/en/appserver-integration.md | 1031 +++++++++
docs/user-manual/en/appserver-integration.xml | 1338 -----------
docs/user-manual/en/architecture.md | 159 ++
docs/user-manual/en/architecture.xml | 151 --
docs/user-manual/en/book.json | 12 +
docs/user-manual/en/client-classpath.md | 32 +
docs/user-manual/en/client-classpath.xml | 51 -
docs/user-manual/en/client-reconnection.md | 149 ++
docs/user-manual/en/client-reconnection.xml | 147 --
docs/user-manual/en/clusters.md | 1059 +++++++++
docs/user-manual/en/clusters.xml | 998 --------
docs/user-manual/en/configuration-index.md | 273 +++
docs/user-manual/en/configuration-index.xml | 396 ----
docs/user-manual/en/configuring-transports.md | 462 ++++
docs/user-manual/en/configuring-transports.xml | 443 ----
docs/user-manual/en/connection-ttl.md | 198 ++
docs/user-manual/en/connection-ttl.xml | 202 --
docs/user-manual/en/core-bridges.md | 225 ++
docs/user-manual/en/core-bridges.xml | 241 --
docs/user-manual/en/diverts.md | 114 +
docs/user-manual/en/diverts.xml | 113 -
docs/user-manual/en/duplicate-detection.md | 161 ++
docs/user-manual/en/duplicate-detection.xml | 148 --
docs/user-manual/en/embedding-activemq.md | 225 ++
docs/user-manual/en/embedding-activemq.xml | 270 ---
docs/user-manual/en/examples.md | 826 +++++++
docs/user-manual/en/examples.xml | 693 ------
docs/user-manual/en/filter-expressions.md | 52 +
docs/user-manual/en/filter-expressions.xml | 86 -
docs/user-manual/en/flow-control.md | 304 +++
docs/user-manual/en/flow-control.xml | 290 ---
docs/user-manual/en/ha.md | 892 ++++++++
docs/user-manual/en/ha.xml | 985 --------
docs/user-manual/en/images/activemq-logo.jpg | Bin 0 -> 6819 bytes
docs/user-manual/en/intercepting-operations.md | 84 +
docs/user-manual/en/intercepting-operations.xml | 99 -
docs/user-manual/en/interoperability.md | 365 +++
docs/user-manual/en/interoperability.xml | 305 ---
docs/user-manual/en/jms-bridge.md | 460 ++++
docs/user-manual/en/jms-bridge.xml | 449 ----
docs/user-manual/en/jms-core-mapping.md | 39 +
docs/user-manual/en/jms-core-mapping.xml | 50 -
docs/user-manual/en/large-messages.md | 275 +++
docs/user-manual/en/large-messages.xml | 285 ---
docs/user-manual/en/last-value-queues.md | 55 +
docs/user-manual/en/last-value-queues.xml | 70 -
docs/user-manual/en/libaio.md | 109 +
docs/user-manual/en/libaio.xml | 129 --
docs/user-manual/en/logging.md | 93 +
docs/user-manual/en/logging.xml | 138 --
docs/user-manual/en/management.md | 1094 +++++++++
docs/user-manual/en/management.xml | 1117 ---------
docs/user-manual/en/message-expiry.md | 85 +
docs/user-manual/en/message-expiry.xml | 100 -
docs/user-manual/en/message-grouping.md | 198 ++
docs/user-manual/en/message-grouping.xml | 195 --
docs/user-manual/en/messaging-concepts.md | 312 +++
docs/user-manual/en/messaging-concepts.xml | 267 ---
docs/user-manual/en/notice.md | 17 +
docs/user-manual/en/notice.xml | 39 -
docs/user-manual/en/paging.md | 160 ++
docs/user-manual/en/paging.xml | 215 --
docs/user-manual/en/perf-tuning.md | 255 +++
docs/user-manual/en/perf-tuning.xml | 304 ---
docs/user-manual/en/persistence.md | 392 ++++
docs/user-manual/en/persistence.xml | 356 ---
docs/user-manual/en/pre-acknowledge.md | 92 +
docs/user-manual/en/pre-acknowledge.xml | 92 -
docs/user-manual/en/preface.md | 52 +
docs/user-manual/en/preface.xml | 86 -
docs/user-manual/en/project-info.md | 50 +
docs/user-manual/en/queue-attributes.md | 182 ++
docs/user-manual/en/queue-attributes.xml | 171 --
docs/user-manual/en/rest.md | 1570 +++++++++++++
docs/user-manual/en/rest.xml | 2150 ------------------
docs/user-manual/en/scheduled-messages.md | 36 +
docs/user-manual/en/scheduled-messages.xml | 53 -
docs/user-manual/en/security.md | 306 +++
docs/user-manual/en/security.xml | 287 ---
docs/user-manual/en/send-guarantees.md | 151 ++
docs/user-manual/en/send-guarantees.xml | 152 --
docs/user-manual/en/slow-consumers.md | 36 +
docs/user-manual/en/slow-consumers.xml | 52 -
docs/user-manual/en/spring-integration.md | 50 +
docs/user-manual/en/spring-integration.xml | 81 -
docs/user-manual/en/thread-pooling.md | 154 ++
docs/user-manual/en/thread-pooling.xml | 150 --
docs/user-manual/en/tools.md | 88 +
docs/user-manual/en/tools.xml | 116 -
docs/user-manual/en/transaction-config.md | 22 +
docs/user-manual/en/transaction-config.xml | 38 -
docs/user-manual/en/undelivered-messages.md | 166 ++
docs/user-manual/en/undelivered-messages.xml | 159 --
docs/user-manual/en/using-core.md | 222 ++
docs/user-manual/en/using-core.xml | 223 --
docs/user-manual/en/using-jms.md | 410 ++++
docs/user-manual/en/using-jms.xml | 364 ---
docs/user-manual/en/using-server.md | 204 ++
docs/user-manual/en/using-server.xml | 208 --
docs/user-manual/en/vertx-integration.md | 91 +
docs/user-manual/en/vertx-integration.xml | 114 -
docs/user-manual/en/wildcard-routing.md | 21 +
docs/user-manual/en/wildcard-routing.xml | 42 -
docs/user-manual/en/wildcard-syntax.md | 28 +
docs/user-manual/en/wildcard-syntax.xml | 43 -
docs/user-manual/pom.xml | 365 ---
docs/user-manual/publican.cfg | 7 -
.../src/main/resources/schemaToTable.xsl | 374 ---
pom.xml | 1 -
169 files changed, 14940 insertions(+), 19136 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/distribution/activemq/src/main/assembly/dep.xml
----------------------------------------------------------------------
diff --git a/distribution/activemq/src/main/assembly/dep.xml b/distribution/activemq/src/main/assembly/dep.xml
index 088ae95..270c239 100644
--- a/distribution/activemq/src/main/assembly/dep.xml
+++ b/distribution/activemq/src/main/assembly/dep.xml
@@ -124,17 +124,5 @@
<exclude>**/**/*.dat</exclude>
</excludes>
</fileSet>
- <!-- docs -->
- <!--todo, this is crap, there must be better jdocbook assembly integration-->
- <fileSet>
- <directory>../../docs/user-manual/target/docbook/publish/en/html/</directory>
- <outputDirectory>web/user-manual</outputDirectory>
- <lineEnding>keep</lineEnding>
- </fileSet>
- <fileSet>
- <directory>../../docs/rest-manual/target/docbook/publish/en</directory>
- <outputDirectory>docs/rest-manual</outputDirectory>
- <lineEnding>keep</lineEnding>
- </fileSet>
</fileSets>
</assembly>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/Author_Group.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/Author_Group.xml b/docs/design-guide/en/Author_Group.xml
deleted file mode 100644
index cc80d8b..0000000
--- a/docs/design-guide/en/Author_Group.xml
+++ /dev/null
@@ -1,34 +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 authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_Design_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<authorgroup>
- <author>
- <firstname>Andy</firstname>
- <surname>Taylor</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ataylor@redhat.com</email>
- </author>
-</authorgroup>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/Book_Info.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/Book_Info.xml b/docs/design-guide/en/Book_Info.xml
deleted file mode 100644
index 4d4a08f..0000000
--- a/docs/design-guide/en/Book_Info.xml
+++ /dev/null
@@ -1,48 +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.
- -->
-
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_Design_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<bookinfo id="ActiveMQ_QuickStart_Guide">
- <title>ActiveMQ Design Guide</title>
- <subtitle>Putting the buzz in messaging</subtitle>
- <productname>ActiveMQ</productname>
- <edition>2.1.0</edition>
- <pubsnumber>1</pubsnumber>
- <abstract>
- <para>This Design guide is to help current and future developers how ActiveMQ's architectures are designed to
- help the future development and maintenance of the project</para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>ActiveMQ Logo</phrase>
- </textobject>
- </inlinemediaobject>
- </corpauthor>
- <copyright>
- <year>&YEAR;</year>
- <holder>&HOLDER;</holder>
- </copyright>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
-</bookinfo>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/HornetQ_Design_Guide.ent
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/HornetQ_Design_Guide.ent b/docs/design-guide/en/HornetQ_Design_Guide.ent
deleted file mode 100644
index 004902c..0000000
--- a/docs/design-guide/en/HornetQ_Design_Guide.ent
+++ /dev/null
@@ -1,5 +0,0 @@
-<!ENTITY PRODUCT "ActiveMQ">
-<!ENTITY BOOKID "ActiveMQ_Design_Guide">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "Red Hat Inc.">
-<!ENTITY semi ";">
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/HornetQ_Design_Guide.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/HornetQ_Design_Guide.xml b/docs/design-guide/en/HornetQ_Design_Guide.xml
deleted file mode 100644
index 50961be..0000000
--- a/docs/design-guide/en/HornetQ_Design_Guide.xml
+++ /dev/null
@@ -1,30 +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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_Design_Guide.ent">
-%BOOK_ENTITIES;
-
-]>
-<book>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="notice.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="about.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="clustering.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/about.md
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/about.md b/docs/design-guide/en/about.md
new file mode 100644
index 0000000..184d493
--- /dev/null
+++ b/docs/design-guide/en/about.md
@@ -0,0 +1,4 @@
+About ActiveMQ
+==============
+
+What is ActiveMQ?
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/about.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/about.xml b/docs/design-guide/en/about.xml
deleted file mode 100644
index ca8df7a..0000000
--- a/docs/design-guide/en/about.xml
+++ /dev/null
@@ -1,28 +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_Design_Guide.ent">
-%BOOK_ENTITIES;
-]>
-
-<chapter id="about">
- <title>About ActiveMQ</title>
- <para>What is ActiveMQ?</para>
-</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/clustering.md
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/clustering.md b/docs/design-guide/en/clustering.md
new file mode 100644
index 0000000..235c0d9
--- /dev/null
+++ b/docs/design-guide/en/clustering.md
@@ -0,0 +1,23 @@
+Getting Started
+===============
+
+This chapter discusses the architecture behind clustering
+
+Discovery
+=========
+
+Discovery is done in 2 steps, initial discovery where the server locates
+another node in the cluster and topology discovery where the node finds
+out about all other nodes in the cluster
+
+Initial Discovery
+-----------------
+
+blah blah blah, UDP, static connectors etc etc
+
+Topology Discovery
+------------------
+
+blah blah blah, topology etc
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/clustering.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/clustering.xml b/docs/design-guide/en/clustering.xml
deleted file mode 100644
index 9bc19ca..0000000
--- a/docs/design-guide/en/clustering.xml
+++ /dev/null
@@ -1,42 +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_Design_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="introduction">
- <title>Getting Started</title>
- <para>This chapter discusses the architecture behind clustering</para>
- <section>
- <title>Discovery</title>
- <para>Discovery is done in 2 steps, initial discovery where the server locates another node in the cluster and
- topology discovery where the node finds out about all other nodes in the cluster</para>
- <section>
- <title>Initial Discovery</title>
- <para>blah blah blah, UDP, static connectors etc etc</para>
- </section>
- <section>
- <title>Topology Discovery</title>
- <para>blah blah blah, topology etc</para>
- <para>
- <graphic fileref="images/topology-update.jpg" align="center" format="JPEG" scale="30"/>
- </para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/notice.md
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/notice.md b/docs/design-guide/en/notice.md
new file mode 100644
index 0000000..2b2cdc2
--- /dev/null
+++ b/docs/design-guide/en/notice.md
@@ -0,0 +1,17 @@
+Legal Notice
+============
+
+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.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/en/notice.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/en/notice.xml b/docs/design-guide/en/notice.xml
deleted file mode 100644
index dfc2acb..0000000
--- a/docs/design-guide/en/notice.xml
+++ /dev/null
@@ -1,41 +0,0 @@
-<!--
- ~ 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_Design_Guide.ent">
-%BOOK_ENTITIES;
-]>
-
-<chapter id="notice">
- <title>Legal Notice</title>
-
- <para>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</para>
- <para></para>
- <para>http://www.apache.org/licenses/LICENSE-2.0</para>
- <para></para>
- <para>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.</para>
-
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/design-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/design-guide/pom.xml b/docs/design-guide/pom.xml
deleted file mode 100644
index ca7729e..0000000
--- a/docs/design-guide/pom.xml
+++ /dev/null
@@ -1,310 +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.
- -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.jboss.project</groupId>
- <artifactId>${docname}-${translation}</artifactId>
- <version>1.0</version>
- <packaging>jdocbook</packaging>
- <name>${bookname}-(${translation})</name>
-
- <properties>
- <translation>en</translation>
- <docname>ActiveMQ_Design_Guide</docname>
- <bookname>ActiveMQ Design Guide</bookname>
- </properties>
-
- <repositories>
- <repository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </snapshots>
- </repository>
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository>
- <!--pluginRepository>
- <id>jboss-snapshot-repository-group</id>
- <name>JBoss Snapshot Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/snapshot/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository-->
- </pluginRepositories>
-
- <profiles>
-
- <!-- mvn compile -->
- <profile>
- <id>all</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml -->
- <profile>
- <id>html</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml-single -->
- <profile>
- <id>html-single</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Ppdf -->
- <profile>
- <id>pdf</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.1.0</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- </profiles>
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDirectory>${project.basedir}</sourceDirectory>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <masterTranslation>en</masterTranslation>
- <imageResource>
- <directory>${project.basedir}/en</directory>
- <includes>
- <include>images/*.png</include>
- <include>images/*.jpg</include>
- </includes>
- </imageResource>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${pdf.name}</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <docbookVersion>1.72.0</docbookVersion>
- <localeSeparator>-</localeSeparator>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </pluginManagement>
- </build>
- <!--<build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <sourceDirectory>.</sourceDirectory>
- <imageResource>
- <directory>${translation}</directory>
- <includes>
- <include>images/*</include>
- </includes>
- </imageResource>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
-
- </plugins>
- </build>-->
-
-</project>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/diagrams/standard_image.odg
----------------------------------------------------------------------
diff --git a/docs/diagrams/standard_image.odg b/docs/diagrams/standard_image.odg
deleted file mode 100644
index ecab22a..0000000
Binary files a/docs/diagrams/standard_image.odg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/Author_Group.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/Author_Group.xml b/docs/eap-manual/en/Author_Group.xml
deleted file mode 100644
index 7b2e395..0000000
--- a/docs/eap-manual/en/Author_Group.xml
+++ /dev/null
@@ -1,35 +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 authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_EAP_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<authorgroup>
- <author>
- <firstname>Andy</firstname>
- <surname>Taylor</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ataylor@redhat.com</email>
- </author>
-</authorgroup>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/Book_Info.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/Book_Info.xml b/docs/eap-manual/en/Book_Info.xml
deleted file mode 100644
index 96a48f3..0000000
--- a/docs/eap-manual/en/Book_Info.xml
+++ /dev/null
@@ -1,49 +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.
- -->
-
-
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_EAP_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<bookinfo id="ActiveMQ_EAP_Manual">
- <title>ActiveMQ Eap Manual</title>
- <subtitle>Putting the buzz in messaging</subtitle>
- <productname>ActiveMQ</productname>
- <edition>2.1.0</edition>
- <pubsnumber>1</pubsnumber>
- <abstract>
- <para>This is a guide to using ActiveMQ within EAP</para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>ActiveMQ Logo</phrase>
- </textobject>
- </inlinemediaobject>
- </corpauthor>
- <copyright>
- <year>&YEAR;</year>
- <holder>&HOLDER;</holder>
- </copyright>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
-</bookinfo>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/HornetQ_EAP_Manual.ent
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/HornetQ_EAP_Manual.ent b/docs/eap-manual/en/HornetQ_EAP_Manual.ent
deleted file mode 100644
index c757b83..0000000
--- a/docs/eap-manual/en/HornetQ_EAP_Manual.ent
+++ /dev/null
@@ -1,7 +0,0 @@
-<!ENTITY PRODUCT "ActiveMQ">
-<!ENTITY BOOKID "ActiveMQ_EAP_Manual">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "Red Hat Inc.">
-<!ENTITY semi ";">
-
-
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/HornetQ_EAP_Manual.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/HornetQ_EAP_Manual.xml b/docs/eap-manual/en/HornetQ_EAP_Manual.xml
deleted file mode 100644
index 675c6cc..0000000
--- a/docs/eap-manual/en/HornetQ_EAP_Manual.xml
+++ /dev/null
@@ -1,29 +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.
- -->
-
-
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_EAP_Manual.ent">
-%BOOK_ENTITIES;
-
-]>
-<book>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="clusters.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/clusters.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/clusters.xml b/docs/eap-manual/en/clusters.xml
deleted file mode 100644
index daacc4c..0000000
--- a/docs/eap-manual/en/clusters.xml
+++ /dev/null
@@ -1,573 +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.
- -->
-
-<chapter id="clusters">
- <title>ActiveMQ and EAP Cluster Configuration</title>
- <section>
- <title>Configuring Failover</title>
- <para>
- This chapter explains how to configure ActiveMQ within EAP with live backup-groups. Currently in this version
- ActiveMQ only supports shared store for backup nodes so we assume that in the rest of this chapter.
- </para>
- <para>There are 2 main ways to configure ActiveMQ servers to have a backup server:</para>
- <itemizedlist>
- <listitem>
- <para>Colocated. This is when an EAP instance has both a live and backup(s) running.</para>
- </listitem>
- <listitem>
- <para>Dedicated. This is when an EAP instance has either a live or backup running but never both.</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Colocated Live and Backup in Symmetrical cluster</title>
- <para>
- The colocated symmetrical topology will be the most widely used topology, this is where an EAP instance has
- a live node running plus 1 or more backup node. Each backup node will belong to a live node on another EAP
- instance. In a simple cluster of 2
- EAP instances this would mean that each EAP instance would have a live server and 1 backup server as in
- diagram1.
- </para>
- <para>
- <graphic fileref="images/simple-colocated.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <para>
- Here the continuous lines show before failover and the dotted lines show the state of the cluster after
- failover has occurred. To start with the 2 live servers are connected forming a cluster with each live server
- connected to its local applications (via JCA). Also remote clients are connected to the live servers. After
- failover the backup connects to the still available live server (which happens to be in the same vm) and takes
- over as the live server in the cluster. Any remote clients also failover.
- </para>
- <para>
- One thing to mention is that in that depending on what consumers/producers and MDB's etc are available messages
- will be distributed between the nodes to make sure that all clients are satisfied from a JMS perspective. That is
- if a producer is sending messages to a queue on a backup server that has no consumers, the messages will be
- distributed to a live node elsewhere.
- </para>
- <para>
- The following diagram is slightly more complex but shows the same configuration with 3 servers. Note that the
- cluster connections ave been removed to make the configuration clearer but in reality all live servers will
- form a cluster.
- </para>
- <para>
- <graphic fileref="images/simple-colocated2.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <para>
- With more than 2 servers it is up to the user as to how many backups per live server are configured, you can
- have
- as many backups as required but usually 1 would suffice. In 3 node topology you may have each EAP instance
- configured
- with 2 backups in a 4 node 3 backups and so on. The following diagram demonstrates this.
- </para>
- <para>
- <graphic fileref="images/simple-colocated3.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <section>
- <title>Configuration</title>
- <section>
- <title>Live Server Configuration</title>
- <para>
- First let's start with the configuration of the live server, we will use the EAP 'all' configuration as
- our starting point. Since this version only supports shared store for failover we need to configure
- this in the
- <literal>activemq-configuration.xml</literal>
- file like so:
- </para>
- <programlisting>
- <shared-store>true</shared-store>
- </programlisting>
- <para>
- Obviously this means that the location of the journal files etc will have to be configured to be some
- where
- where
- this lives backup can access. You may change the lives configuration in
- <literal>activemq-configuration.xml</literal>
- to
- something like:
- </para>
- <programlisting>
- <large-messages-directory>/media/shared/data/large-messages</large-messages-directory>
- <bindings-directory>/media/shared/data/bindings</bindings-directory>
- <journal-directory>/media/shared/data/journal</journal-directory>
- <paging-directory>/media/shared/data/paging</paging-directory>
- </programlisting>
- <para>
- How these paths are configured will of course depend on your network settings or file system.
- </para>
- <para>
- Now we need to configure how remote JMS clients will behave if the server is shutdown in a normal
- fashion.
- By
- default
- Clients will not failover if the live server is shutdown. Depending on there connection factory
- settings
- they will either fail or try to reconnect to the live server.
- </para>
- <para>If you want clients to failover on a normal server shutdown the you must configure the
- <literal>failover-on-shutdown</literal>
- flag to true in the
- <literal>activemq-configuration.xml</literal>
- file like so:
- </para>
- <programlisting>
- <failover-on-shutdown>false</failover-on-shutdown>
- </programlisting>
- <para>Don't worry if you have this set to false (which is the default) but still want failover to occur,
- simply
- kill
- the
- server process directly or call
- <literal>forceFailover</literal>
- via jmx or the admin console on the core server object.
- </para>
- <para>We also need to configure the connection factories used by the client to be HA. This is done by
- adding
- certain attributes to the connection factories in<literal>activemq-jms.xml</literal>. Let's look at an
- example:
- </para>
- <programlisting>
- <connection-factory name="NettyConnectionFactory">
- <xa>true</xa>
- <connectors>
- <connector-ref connector-name="netty"/>
- </connectors>
- <entries>
- <entry name="/ConnectionFactory"/>
- <entry name="/XAConnectionFactory"/>
- </entries>
-
- <ha>true</ha>
- <!-- Pause 1 second between connect attempts -->
- <retry-interval>1000</retry-interval>
-
- <!-- Multiply subsequent reconnect pauses by this multiplier. This can be used to
- implement an exponential back-off. For our purposes we just set to 1.0 so each reconnect
- pause is the same length -->
- <retry-interval-multiplier>1.0</retry-interval-multiplier>
-
- <!-- Try reconnecting an unlimited number of times (-1 means "unlimited") -->
- <reconnect-attempts>-1</reconnect-attempts>
- </connection-factory>
-
- </programlisting>
- <para>We have added the following attributes to the connection factory used by the client:</para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>ha</literal>
- - This tells the client it support HA and must always be true for failover
- to occur
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>retry-interval</literal>
- - this is how long the client will wait after each unsuccessful
- reconnect to the server
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>retry-interval-multiplier</literal>
- - is used to configure an exponential back off for
- reconnect attempts
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>reconnect-attempts</literal>
- - how many reconnect attempts should a client make before failing,
- -1 means unlimited.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Backup Server Configuration</title>
- <para>
- Now let's look at how to create and configure a backup server on the same eap instance. This is running
- on the same eap instance as the live server from the previous chapter but is configured as the backup
- for a live server running on a different eap instance.
- </para>
- <para>
- The first thing to mention is that the backup only needs a <literal>activemq-jboss-beans.xml</literal>
- and a <literal>activemq-configuration.xml</literal> configuration file. This is because any JMS components
- are created from the Journal when the backup server becomes live.
- </para>
- <para>
- Firstly we need to define a new ActiveMQ Server that EAP will deploy. We do this by creating a new
- <literal>activemq-jboss-beans.xml</literal>
- configuration. We will place this under a new directory
- <literal>activemq-backup1</literal>
- which will need creating
- in the
- <literal>deploy</literal>
- directory but in reality it doesn't matter where this is put. This will look like:
- </para>
- <programlisting>
- <?xml version="1.0" encoding="UTF-8"?>
-
- <deployment xmlns="urn:jboss:bean-deployer:2.0">
-
- <!-- The core configuration -->
- <bean name="BackupConfiguration" class="org.apache.activemq.core.config.impl.FileConfiguration">
- <property
- name="configurationUrl">${jboss.server.home.url}/deploy/activemq-backup1/activemq-configuration.xml</property>
- </bean>
-
-
- <!-- The core server -->
- <bean name="BackupActiveMQServer" class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
- <constructor>
- <parameter>
- <inject bean="BackupConfiguration"/>
- </parameter>
- <parameter>
- <inject bean="MBeanServer"/>
- </parameter>
- <parameter>
- <inject bean="ActiveMQSecurityManager"/>
- </parameter>
- </constructor>
- <start ignored="true"/>
- <stop ignored="true"/>
- </bean>
-
- <!-- The JMS server -->
- <bean name="BackupJMSServerManager" class="org.apache.activemq.jms.server.impl.JMSServerManagerImpl">
- <constructor>
- <parameter>
- <inject bean="BackupActiveMQServer"/>
- </parameter>
- </constructor>
- </bean>
-
- </deployment>
- </programlisting>
- <para>
- The first thing to notice is the BackupConfiguration bean. This is configured to pick up the
- configuration
- for
- the
- server which we will place in the same directory.
- </para>
- <para>
- After that we just configure a new ActiveMQ Server and JMS server.
- </para>
- <note>
- <para>
- Notice that the names of the beans have been changed from that of the live servers configuration.
- This
- is
- so
- there is no clash. Obviously if you add more backup servers you will need to rename those as well,
- backup1,
- backup2 etc.
- </para>
- </note>
- <para>
- Now let's add the server configuration in
- <literal>activemq-configuration.xml</literal>
- and add it to the same directory
- <literal>deploy/activemq-backup1</literal>
- and configure it like so:
- </para>
- <programlisting>
- <configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
-
- <jmx-domain>org.apache.activemq.backup1</jmx-domain>
-
- <clustered>true</clustered>
-
- <backup>true</backup>
-
- <shared-store>true</shared-store>
-
- <allow-failback>true</allow-failback>
-
- <bindings-directory>/media/shared/data/activemq-backup/bindings</bindings-directory>
-
- <journal-directory>/media/shared/data/activemq-backup/journal</journal-directory>
-
- <journal-min-files>10</journal-min-files>
-
- <large-messages-directory>/media/shared/data/activemq-backup/largemessages</large-messages-directory>
-
- <paging-directory>/media/shared/data/activemq-backup/paging</paging-directory>
-
- <connectors>
- <connector name="netty-connector">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
- <param key="host" value="${jboss.bind.address:localhost}"/>
- <param key="port" value="${activemq.remoting.backup.netty.port:5446}"/>
- </connector>
-
- <connector name="in-vm">
- <factory-class>org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</factory-class>
- <param key="server-id" value="${activemq.server-id:0}"/>
- </connector>
-
- </connectors>
-
- <acceptors>
- <acceptor name="netty">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
- <param key="host" value="${jboss.bind.address:localhost}"/>
- <param key="port" value="${activemq.remoting.backup.netty.port:5446}"/>
- </acceptor>
- </acceptors>
-
- <broadcast-groups>
- <broadcast-group name="bg-group1">
- <group-address>231.7.7.7</group-address>
- <group-port>9876</group-port>
- <broadcast-period>1000</broadcast-period>
- <connector-ref>netty-connector</connector-ref>
- </broadcast-group>
- </broadcast-groups>
-
- <discovery-groups>
- <discovery-group name="dg-group1">
- <group-address>231.7.7.7</group-address>
- <group-port>9876</group-port>
- <refresh-timeout>60000</refresh-timeout>
- </discovery-group>
- </discovery-groups>
-
- <cluster-connections>
- <cluster-connection name="my-cluster">
- <address>jms</address>
- <connector-ref>netty-connector</connector-ref>
- <discovery-group-ref discovery-group-name="dg-group1"/>
- <!--max hops defines how messages are redistributed, the default is 1 meaning only distribute to directly
- connected nodes, to disable set to 0-->
- <!--<max-hops>0</max-hops>-->
- </cluster-connection>
- </cluster-connections>
-
- <security-settings>
- <security-setting match="#">
- <permission type="createNonDurableQueue" roles="guest"/>
- <permission type="deleteNonDurableQueue" roles="guest"/>
- <permission type="consume" roles="guest"/>
- <permission type="send" roles="guest"/>
- </security-setting>
- </security-settings>
-
- <address-settings>
- <!--default for catch all-->
- <address-setting match="#">
- <dead-letter-address>jms.queue.DLQ</dead-letter-address>
- <expiry-address>jms.queue.ExpiryQueue</expiry-address>
- <redelivery-delay>0</redelivery-delay>
- <max-size-bytes>10485760</max-size-bytes>
- <message-counter-history-day-limit>10</message-counter-history-day-limit>
- <address-full-policy>BLOCK</address-full-policy>
- </address-setting>
- </address-settings>
-
- </configuration>
-
- </programlisting>
- <para>
- The second thing you can see is we have added a
- <literal>jmx-domain</literal>
- attribute, this is used when
- adding objects, such as the ActiveMQ server and JMS server to jmx, we change this from the default
- <literal>org.apache.activemq</literal>
- to avoid naming clashes with the live server
- </para>
- <para>
- The first important part of the configuration is to make sure that this server starts as a backup
- server not
- a live server, via the
- <literal>backup</literal>
- attribute.
- </para>
- <para>
- After that we have the same cluster configuration as live, that is
- <literal>clustered</literal>
- is true and
- <literal>shared-store</literal>
- is true. However you can see we have added a new configuration element
- <literal>allow-failback</literal>. When this is set to true then this backup server will automatically
- stop
- and fall back into backup node if failover occurs and the live server has become available. If false
- then
- the user will have to stop the server manually.
- </para>
- <para>
- Next we can see the configuration for the journal location, as in the live configuration this must
- point to
- the same directory as this backup's live server.
- </para>
- <para>
- Now we see the connectors configuration, we have 3 defined which are needed for the following
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>netty-connector.</literal>
- This is the connector used to connect to this backup server once live.
- </para>
- </listitem>
- </itemizedlist>
- <para>After that you will see the acceptors defined, This is the acceptor where clients will reconnect.
- </para>
- <para>
- The Broadcast groups, Discovery group and cluster configurations are as per normal, details of these
- can be found in the ActiveMQ user manual.
- </para>
- <note>
- <para>notice the commented out <literal>max-hops</literal> in the cluster connection, set this to 0 if
- you want to disable server side load balancing.</para>
- </note>
- <para>
- When the backup becomes it will be not be servicing any JEE components on this eap instance. Instead any
- existing messages will be redistributed around the cluster and new messages forwarded to and from the backup
- to service any remote clients it has (if it has any).
- </para>
- </section>
- <section>
- <title>Configuring multiple backups</title>
- <para>
- In this instance we have assumed that there are only 2 nodes where each node has a backup for the other
- node. However you may want to configure a server too have multiple backup nodes. For example you may want
- 3 nodes where each node has 2 backups, one for each of the other 2 live servers. For this you would simply
- copy the backup configuration and make sure you do the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Make sure that you give all the beans in the <literal>activemq-jboss-beans.xml</literal> configuration
- file a unique name, i.e.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Running the shipped example</title>
- <para>
- EAP ships with an example configuration for this topology. Look under <literal>extras/activemq/resources/examples/symmetric-cluster-with-backups-colocated</literal>
- and follow the read me
- </para>
- </section>
- </section>
- </section>
- <section>
- <title>Dedicated Live and Backup in Symmetrical cluster</title>
- <para>
- In reality the configuration for this is exactly the same as the backup server in the previous section, the only
- difference is that a backup will reside on an eap instance of its own rather than colocated with another live server.
- Of course this means that the eap instance is passive and not used until the backup comes live and is only
- really useful for pure JMS applications.
- </para>
- <para>The following diagram shows a possible configuration for this:</para>
- <para>
- <graphic fileref="images/simple-dedicated.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <para>
- Here you can see how this works with remote JMS clients. Once failover occurs the ActiveMQ backup Server takes
- running within another eap instance takes over as live.
- </para>
- <para>
- This is fine with applications that are pure JMS and have no JMS components such as MDB's. If you are using
- JMS components then there are 2 ways that this can be done. The first is shown in the following diagram:
- </para>
- <para>
- <graphic fileref="images/simple-dedicated-jca.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <para>
- Because there is no live activemq server running by default in the eap instance running the backup server it
- makes no sense to host any applications in it. However you can host applications on the server running the live
- activemq server. If failure occurs to an live activemq server then remote jms clients will failover as previously
- explained however what happens to any messages meant for or sent from JEE components. Well when the backup comes
- live, messages will be distributed to and from the backup server over ActiveMQ cluster connections and handled
- appropriately.
- </para>
- <para>
- The second way to do this is to have both live and backup server remote form the eap instance as shown in the
- following diagram.
- </para>
- <para>
- <graphic fileref="images/simple-dedicated-jca-remote.jpg" align="center" format="jpg" scale="30"/>
- </para>
- <para>
- Here you can see that all the Application (via JCA) will be serviced by a ActiveMQ server in its own eap instance.
- </para>
- <section>
- <title>Configuration of dedicated Live and backup</title>
- <para>
- The live server configuration is exactly the same as in the previous example. The only difference of course
- is that there is no backup in the eap instance.
- </para>
- <para>
- For the backup server the <literal>activemq-configuration.xml</literal> is unchanged, however since there is
- no live server we need to make sure that the <literal>activemq-jboss-beans.xml</literal> instantiates all
- the beans needed. For this simply use the same configuration as in the live server changing only the
- location of the <literal>activemq-configuration.xml</literal> parameter for the <literal>Configuration</literal>
- bean.
- </para>
- <para>
- As before there will be no <literal>activemq-jms.xml</literal> or <literal>jms-ds.xml</literal> configuration.
- </para>
- <para>
- If you want both activemq servers to be in there own dedicated server where they are remote to applications,
- as in the last diagram. Then simply edit the <literal>jms-ds.xml</literal> and change the following lines to
- </para>
- <programlisting>
- <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
- <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446</config-property>
- </programlisting>
- <para>
- This will change the outbound JCA connector, to configure the inbound connector for MDB's edit the
- <literal>ra.xml</literal> config file and change the following parameters.
- </para>
- <programlisting>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>host=127.0.0.1;port=5446</config-property-value>
- </config-property>
- </programlisting>
- <para>
- In both cases the host and port should match your live server. If you are using Discovery then set the
- appropriate parameters for <literal>DiscoveryAddress</literal> and <literal>DiscoveryPort</literal> to match
- your configured broadcast groups.
- </para>
- </section>
- <section>
- <title>Running the shipped example</title>
- <para>
- EAP ships with an example configuration for this topology. Look under
- <literal>extras/activemq/resources/examples/cluster-with-dedicated-backup</literal>
- and follow the read me
- </para>
- </section>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/diagrams/ha-topologies1.odg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/diagrams/ha-topologies1.odg b/docs/eap-manual/en/diagrams/ha-topologies1.odg
deleted file mode 100644
index f42e64f..0000000
Binary files a/docs/eap-manual/en/diagrams/ha-topologies1.odg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-colocated.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-colocated.jpg b/docs/eap-manual/en/images/simple-colocated.jpg
deleted file mode 100644
index ed998e5..0000000
Binary files a/docs/eap-manual/en/images/simple-colocated.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-colocated2.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-colocated2.jpg b/docs/eap-manual/en/images/simple-colocated2.jpg
deleted file mode 100644
index 76e6ee3..0000000
Binary files a/docs/eap-manual/en/images/simple-colocated2.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-colocated3.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-colocated3.jpg b/docs/eap-manual/en/images/simple-colocated3.jpg
deleted file mode 100644
index d07a9eb..0000000
Binary files a/docs/eap-manual/en/images/simple-colocated3.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-dedicated-jca-remote.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-dedicated-jca-remote.jpg b/docs/eap-manual/en/images/simple-dedicated-jca-remote.jpg
deleted file mode 100644
index 6a98b3a..0000000
Binary files a/docs/eap-manual/en/images/simple-dedicated-jca-remote.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-dedicated-jca.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-dedicated-jca.jpg b/docs/eap-manual/en/images/simple-dedicated-jca.jpg
deleted file mode 100644
index 4d6387f..0000000
Binary files a/docs/eap-manual/en/images/simple-dedicated-jca.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/images/simple-dedicated.jpg
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/images/simple-dedicated.jpg b/docs/eap-manual/en/images/simple-dedicated.jpg
deleted file mode 100644
index ea97b2c..0000000
Binary files a/docs/eap-manual/en/images/simple-dedicated.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/en/master.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/en/master.xml b/docs/eap-manual/en/master.xml
deleted file mode 100644
index e69de29..0000000
[11/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/large-messages.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/large-messages.xml b/docs/user-manual/en/large-messages.xml
deleted file mode 100644
index 43bc2a8..0000000
--- a/docs/user-manual/en/large-messages.xml
+++ /dev/null
@@ -1,285 +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="large-messages">
- <title>Large Messages</title>
- <para>ActiveMQ supports sending and receiving of huge messages, even when the client and server
- are running with limited memory. The only realistic limit to the size of a message that can
- be sent or consumed is the amount of disk space you have available. We have tested sending
- and consuming messages up to 8 GiB in size with a client and server running in just 50MiB of
- RAM!</para>
- <para>To send a large message, the user can set an <literal>InputStream</literal> on a message
- body, and when that message is sent, ActiveMQ will read the <literal>InputStream</literal>. A
- <literal>FileInputStream</literal> could be used for example to send a huge message from
- a huge file on disk.</para>
- <para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream
- of fragments. The server persists these fragments to disk as it receives them and when the
- time comes to deliver them to a consumer they are read back of the disk, also in fragments
- and sent down the wire. When the consumer receives a large message it initially receives
- just the message with an empty body, it can then set an <literal>OutputStream</literal> on
- the message to stream the huge message body to a file on disk or elsewhere. At no time is
- the entire message body stored fully in memory, either on the client or the server.</para>
- <section id="large.message.configuring">
- <title>Configuring the server</title>
- <para>Large messages are stored on a disk directory on the server side, as configured on the
- main configuration file.</para>
- <para>The configuration property <literal>large-messages-directory</literal> specifies where
- large messages are stored.</para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
-...
-<large-messages-directory>/data/large-messages</large-messages-directory>
-...
-</configuration</programlisting>
- <para>By default the large message directory is <literal>data/largemessages</literal></para>
- <para>For the best performance we recommend large messages directory is stored on a
- different physical volume to the message journal or paging directory.</para>
- </section>
- <section>
- <title>Configuring Parameters</title>
- <para>Any message larger than a certain size is considered a large message. Large messages
- will be split up and sent in fragments. This is determined by the parameter <literal
- >min-large-message-size</literal></para>
- <note>
- <para>ActiveMQ messages are encoded using 2 bytes per character so if the message data is filled
- with ASCII characters (which are 1 byte) the size of the resulting ActiveMQ message would roughly
- double. This is important when calculating the size of a "large" message as it may appear to be
- less than the <literal>min-large-message-size</literal> before it is sent, but it then turns into
- a "large" message once it is encoded.</para>
- </note>
- <para>The default value is 100KiB.</para>
- <section id="large-messages.core.config">
- <title>Using Core API</title>
- <para>If the ActiveMQ Core API is used, the minimal large message size is specified by
- <literal>ServerLocator.setMinLargeMessageSize</literal>.</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName()))
-
-locator.setMinLargeMessageSize(25 * 1024);
-
-ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory();</programlisting>
- <para><xref linkend="configuring-transports.client.side"/> will provide more information
- on how to instantiate the session factory.</para>
- </section>
- <section>
- <title>Using JMS</title>
- <para>If JNDI is used to instantiate and look up the connection factory, the minimum large message size
- is configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple
- example using the "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.minLargeMessageSize=250000
- </programlisting>
- <para>If the connection factory is being instantiated directly, the minimum large
- message size is specified by <literal
- >ActiveMQConnectionFactory.setMinLargeMessageSize</literal>.</para>
- </section>
- <section>
- <title>Compressed Large Messages</title>
- <para>
- You can choose to send large messages in compressed form using <literal>
- compress-large-messages</literal> attributes.
- </para>
- <section>
- <title><literal>compress-large-messages</literal></title>
- <para>If you specify the boolean property <literal>compress-large-messages</literal> on
- the <literal>server locator</literal> or <literal>ConnectionFactory</literal> as true, The
- system will use the ZIP algorithm to compress the message body as the message is
- transferred to the server's side. Notice that there's no special treatment at the
- server's side, all the compressing and uncompressing is done at the client.</para>
- <para>If the compressed size of a large message is below <literal>
- min-large-message-size</literal>, it is sent to server as regular messages. This means
- that the message won't be written into the server's large-message
- data directory, thus reducing the disk I/O.</para>
- </section>
- <section>
- <para>If JNDI is used to instantiate and look up the connection factory, large message compression can be
- configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple
- example using the "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.compressLargeMessages=true</programlisting>
- </section>
- </section>
- </section>
- <section>
- <title>Streaming large messages</title>
- <para>ActiveMQ supports setting the body of messages using input and output streams (<literal
- >java.lang.io</literal>)</para>
- <para>These streams are then used directly for sending (input streams) and receiving (output
- streams) messages.</para>
- <para>When receiving messages there are 2 ways to deal with the output stream; you may
- choose to block while the output stream is recovered using the method <literal
- >ClientMessage.saveOutputStream</literal> or alternatively using the method <literal
- >ClientMessage.setOutputstream</literal> which will asynchronously write the message
- to the stream. If you choose the latter the consumer must be kept alive until the
- message has been fully received.</para>
- <para>You can use any kind of stream you like. The most common use case is to send files
- stored in your disk, but you could also send things like JDBC Blobs, <literal
- >SocketInputStream</literal>, things you recovered from <literal
- >HTTPRequests</literal> etc. Anything as long as it implements <literal
- >java.io.InputStream</literal> for sending messages or <literal
- >java.io.OutputStream</literal> for receiving them.</para>
- <section>
- <title>Streaming over Core API</title>
- <para>The following table shows a list of methods available at <literal
- >ClientMessage</literal> which are also available through JMS by the use of
- object properties.</para>
- <table frame="topbot" id="large-messages.ClientMessageAPI">
- <title>org.apache.activemq.api.core.client.ClientMessage API</title>
- <tgroup cols="3">
- <colspec colname="Name" colnum="1"/>
- <colspec colname="Descr" colnum="2"/>
- <colspec colname="JMS" colnum="3"/>
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- <entry>JMS Equivalent Property</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>setBodyInputStream(InputStream)</entry>
- <entry>Set the InputStream used to read a message body when sending
- it.</entry>
- <entry>JMS_HQ_InputStream</entry>
- </row>
- <row>
- <entry>setOutputStream(OutputStream)</entry>
- <entry>Set the OutputStream that will receive the body of a message.
- This method does not block.</entry>
- <entry>JMS_HQ_OutputStream</entry>
- </row>
- <row>
- <entry>saveOutputStream(OutputStream)</entry>
- <entry>Save the body of the message to the <literal
- >OutputStream</literal>. It will block until the entire content
- is transferred to the <literal>OutputStream</literal>.</entry>
- <entry>JMS_HQ_SaveStream</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>To set the output stream when receiving a core message: </para>
- <programlisting>
-...
-ClientMessage msg = consumer.receive(...);
-
-
-// This will block here until the stream was transferred
-msg.saveOutputStream(someOutputStream);
-
-ClientMessage msg2 = consumer.receive(...);
-
-// This will not wait the transfer to finish
-msg.setOutputStream(someOtherOutputStream);
-...</programlisting>
- <para> Set the input stream when sending a core message: </para>
- <programlisting>
-...
-ClientMessage msg = session.createMessage();
-msg.setInputStream(dataInputStream);
-...</programlisting>
- <para>Notice also that for messages with more than 2GiB the getBodySize() will return
- invalid values since this is an integer (which is also exposed to the JMS API). On
- those cases you can use the message property _HQ_LARGE_SIZE.</para>
- </section>
- <section id="large-messages.streaming.over.jms">
- <title>Streaming over JMS</title>
- <para>When using JMS, ActiveMQ maps the streaming methods on the core API (see <xref
- linkend="large-messages.ClientMessageAPI"/>) by setting object properties . You
- can use the method <literal>Message.setObjectProperty</literal> to set the input and
- output streams.</para>
- <para>The <literal>InputStream</literal> can be defined through the JMS Object Property
- JMS_HQ_InputStream on messages being sent:</para>
- <programlisting>
-BytesMessage message = session.createBytesMessage();
-
-FileInputStream fileInputStream = new FileInputStream(fileInput);
-
-BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
-
-message.setObjectProperty("JMS_HQ_InputStream", bufferedInput);
-
-someProducer.send(message);</programlisting>
- <para>The <literal>OutputStream</literal> can be set through the JMS Object Property
- JMS_HQ_SaveStream on messages being received in a blocking way.</para>
- <programlisting>
-BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
-
-File outputFile = new File("huge_message_received.dat");
-
-FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
-
-BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
-
-// This will block until the entire content is saved on disk
-messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);</programlisting>
- <para>Setting the <literal>OutputStream</literal> could also be done in a non blocking
- way using the property JMS_HQ_OutputStream.</para>
- <programlisting>
-// This won't wait the stream to finish. You need to keep the consumer active.
-messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);</programlisting>
- <note>
- <para>When using JMS, Streaming large messages are only supported on <literal
- >StreamMessage</literal> and <literal>BytesMessage</literal>.</para>
- </note>
- </section>
- </section>
- <section>
- <title>Streaming Alternative</title>
- <para>If you choose not to use the <literal>InputStream</literal> or <literal
- >OutputStream</literal> capability of ActiveMQ You could still access the data
- directly in an alternative fashion.</para>
- <para>On the Core API just get the bytes of the body as you normally would.</para>
- <programlisting>
-ClientMessage msg = consumer.receive();
-
-byte[] bytes = new byte[1024];
-for (int i = 0 ; i < msg.getBodySize(); i += bytes.length)
-{
- msg.getBody().readBytes(bytes);
- // Whatever you want to do with the bytes
-}</programlisting>
- <para>If using JMS API, <literal>BytesMessage</literal> and <literal>StreamMessage</literal>
- also supports it transparently.</para>
- <programlisting>
-BytesMessage rm = (BytesMessage)cons.receive(10000);
-
-byte data[] = new byte[1024];
-
-for (int i = 0; i < rm.getBodyLength(); i += 1024)
-{
- int numberOfBytes = rm.readBytes(data);
- // Do whatever you want with the data
-} </programlisting>
- </section>
- <section id="large-messages.example">
- <title>Large message example</title>
- <para>Please see <xref linkend="examples.large-message"/> for an example which shows how
- large message is configured and used with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/last-value-queues.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/last-value-queues.md b/docs/user-manual/en/last-value-queues.md
new file mode 100644
index 0000000..eca5eb5
--- /dev/null
+++ b/docs/user-manual/en/last-value-queues.md
@@ -0,0 +1,55 @@
+Last-Value Queues
+=================
+
+Last-Value queues are special queues which discard any messages when a
+newer message with the same value for a well-defined Last-Value property
+is put in the queue. In other words, a Last-Value queue only retains the
+last value.
+
+A typical example for Last-Value queue is for stock prices, where you
+are only interested by the latest value for a particular stock.
+
+Configuring Last-Value Queues
+=============================
+
+Last-value queues are defined in the address-setting configuration:
+
+ <address-setting match="jms.queue.lastValueQueue">
+ <last-value-queue>true</last-value-queue>
+ </address-setting>
+
+By default, `last-value-queue` is false. Address wildcards can be used
+to configure Last-Value queues for a set of addresses (see ?).
+
+Using Last-Value Property
+=========================
+
+The property name used to identify the last value is `"_HQ_LVQ_NAME"`
+(or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API).
+
+For example, if two messages with the same value for the Last-Value
+property are sent to a Last-Value queue, only the latest message will be
+kept in the queue:
+
+ // send 1st message with Last-Value property set to STOCK_NAME
+ TextMessage message = session.createTextMessage("1st message with Last-Value property set");
+ message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
+ producer.send(message);
+
+ // send 2nd message with Last-Value property set to STOCK_NAME
+ message = session.createTextMessage("2nd message with Last-Value property set");
+ message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
+ producer.send(message);
+
+ ...
+
+ // only the 2nd message will be received: it is the latest with
+ // the Last-Value property set
+ TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
+ System.out.format("Received message: %s\n", messageReceived.getText());
+
+Example
+=======
+
+See ? for an example which shows how last value queues are configured
+and used with JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/last-value-queues.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/last-value-queues.xml b/docs/user-manual/en/last-value-queues.xml
deleted file mode 100644
index f6f44b6..0000000
--- a/docs/user-manual/en/last-value-queues.xml
+++ /dev/null
@@ -1,70 +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="last-value-queues">
- <title>Last-Value Queues</title>
- <para>Last-Value queues are special queues which discard any messages when a newer message with
- the same value for a well-defined Last-Value property is put in the queue. In other words, a
- Last-Value queue only retains the last value.</para>
- <para>A typical example for Last-Value queue is for stock prices, where you are only interested
- by the latest value for a particular stock.</para>
- <section>
- <title>Configuring Last-Value Queues</title>
- <para>Last-value queues are defined in the address-setting configuration:</para>
- <programlisting>
-<address-setting match="jms.queue.lastValueQueue">
- <last-value-queue>true</last-value-queue>
-</address-setting></programlisting>
- <para>By default, <literal>last-value-queue</literal> is false. Address wildcards can be used
- to configure Last-Value queues for a set of addresses (see <xref linkend="wildcard-syntax"
- />).</para>
- </section>
- <section>
- <title>Using Last-Value Property</title>
- <para>The property name used to identify the last value is <literal>"_HQ_LVQ_NAME"</literal>
- (or the constant <literal>Message.HDR_LAST_VALUE_NAME</literal> from the Core API).</para>
- <para>For example, if two messages with the same value for the Last-Value property are sent to
- a Last-Value queue, only the latest message will be kept in the queue:</para>
- <programlisting>
-// send 1st message with Last-Value property set to STOCK_NAME
-TextMessage message = session.createTextMessage("1st message with Last-Value property set");
-message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
-producer.send(message);
-
-// send 2nd message with Last-Value property set to STOCK_NAME
-message = session.createTextMessage("2nd message with Last-Value property set");
-message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
-producer.send(message);
-
-...
-
-// only the 2nd message will be received: it is the latest with
-// the Last-Value property set
-TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
-System.out.format("Received message: %s\n", messageReceived.getText());</programlisting>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.last-value-queue"/> for an example which shows how last
- value queues are configured and used with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/libaio.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/libaio.md b/docs/user-manual/en/libaio.md
new file mode 100644
index 0000000..1e5f9ae
--- /dev/null
+++ b/docs/user-manual/en/libaio.md
@@ -0,0 +1,109 @@
+Libaio Native Libraries
+=======================
+
+ActiveMQ distributes a native library, used as a bridge between ActiveMQ
+and Linux libaio.
+
+`libaio` is a library, developed as part of the Linux kernel project.
+With `libaio` we submit writes to the operating system where they are
+processed asynchronously. Some time later the OS will call our code back
+when they have been processed.
+
+We use this in our high performance journal if configured to do so,
+please see ?.
+
+These are the native libraries distributed by ActiveMQ:
+
+- libActiveMQAIO32.so - x86 32 bits
+
+- libActiveMQAIO64.so - x86 64 bits
+
+When using libaio, ActiveMQ will always try loading these files as long
+as they are on the [library path](#using-server.library.path).
+
+Compiling the native libraries
+==============================
+
+In the case that you are using Linux on a platform other than x86\_32 or
+x86\_64 (for example Itanium 64 bits or IBM Power) you may need to
+compile the native library, since we do not distribute binaries for
+those platforms with the release.
+
+Install requirements
+--------------------
+
+> **Note**
+>
+> At the moment the native layer is only available on Linux. If you are
+> in a platform other than Linux the native compilation will not work
+
+The native library uses
+[autoconf](http://en.wikipedia.org/wiki/Autoconf) what makes the
+compilation process easy, however you need to install extra packages as
+a requirement for compilation:
+
+- gcc - C Compiler
+
+- gcc-c++ or g++ - Extension to gcc with support for C++
+
+- autoconf - Tool for automating native build process
+
+- make - Plain old make
+
+- automake - Tool for automating make generation
+
+- libtool - Tool for link editing native libraries
+
+- libaio - library to disk asynchronous IO kernel functions
+
+- libaio-dev - Compilation support for libaio
+
+- A full JDK installed with the environment variable JAVA\_HOME set to
+ its location
+
+To perform this installation on RHEL or Fedora, you can simply type this
+at a command line:
+
+ sudo yum install automake libtool autoconf gcc-c++ gcc libaio libaio-devel make
+
+Or on Debian systems:
+
+ sudo apt-get install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make
+
+> **Note**
+>
+> You could find a slight variation of the package names depending on
+> the version and Linux distribution. (for example gcc-c++ on Fedora
+> versus g++ on Debian systems)
+
+Invoking the compilation
+------------------------
+
+In the distribution, in the `native-src` directory, execute the shell
+script `bootstrap`. This script will invoke `automake` and `make` what
+will create all the make files and the native library.
+
+ someUser@someBox:/messaging-distribution/native-src$ ./bootstrap
+ checking for a BSD-compatible install... /usr/bin/install -c
+ checking whether build environment is sane... yes
+ checking for a thread-safe mkdir -p... /bin/mkdir -p
+
+ ...
+
+ configure: creating ./config.status
+ config.status: creating Makefile
+ config.status: creating ./src/Makefile
+ config.status: creating config.h
+ config.status: config.h is unchanged
+ config.status: executing depfiles commands
+ config.status: executing libtool commands
+
+ ...
+
+The produced library will be at
+`./native-src/src/.libs/libActiveMQAIO.so`. Simply move that file over
+`bin` on the distribution or the place you have chosen on the [library
+path](#using-server.library.path).
+
+If you want to perform changes on the ActiveMQ libaio code, you could
+just call make directly at the `native-src` directory.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/libaio.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/libaio.xml b/docs/user-manual/en/libaio.xml
deleted file mode 100644
index 75007ed..0000000
--- a/docs/user-manual/en/libaio.xml
+++ /dev/null
@@ -1,129 +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="libaio">
- <title>Libaio Native Libraries</title>
- <para>ActiveMQ distributes a native library, used as a bridge between ActiveMQ and Linux
- libaio.</para>
- <para><literal>libaio</literal> is a library, developed as part of the Linux kernel project.
- With <literal>libaio</literal> we submit writes to the operating system where they are
- processed asynchronously. Some time later the OS will call our code back when they have been
- processed.</para>
- <para>We use this in our high performance journal if configured to do so, please see <xref
- linkend="persistence"/>.</para>
- <para>These are the native libraries distributed by ActiveMQ:</para>
- <itemizedlist>
- <listitem>
- <para>libActiveMQAIO32.so - x86 32 bits</para>
- </listitem>
- <listitem>
- <para>libActiveMQAIO64.so - x86 64 bits</para>
- </listitem>
- </itemizedlist>
- <para>When using libaio, ActiveMQ will always try loading these files as long as they are on the
- <link linkend="using-server.library.path">library path</link>.</para>
- <section>
- <title>Compiling the native libraries</title>
- <para>In the case that you are using Linux on a platform other than x86_32 or x86_64
- (for example Itanium 64 bits or IBM Power) you may need to compile the native library, since we
- do not distribute binaries for those platforms with the release.</para>
- <section>
- <title>Install requirements</title>
- <note>
- <para>At the moment the native layer is only available on Linux. If you are in a
- platform other than Linux the native compilation will not work</para>
- </note>
- <para>The native library uses <ulink url="http://en.wikipedia.org/wiki/Autoconf"
- >autoconf</ulink> what makes the compilation process easy, however you need to
- install extra packages as a requirement for compilation:</para>
- <itemizedlist>
- <listitem>
- <para>gcc - C Compiler</para>
- </listitem>
- <listitem>
- <para>gcc-c++ or g++ - Extension to gcc with support for C++</para>
- </listitem>
- <listitem>
- <para>autoconf - Tool for automating native build process</para>
- </listitem>
- <listitem>
- <para>make - Plain old make</para>
- </listitem>
- <listitem>
- <para>automake - Tool for automating make generation</para>
- </listitem>
- <listitem>
- <para>libtool - Tool for link editing native libraries</para>
- </listitem>
- <listitem>
- <para>libaio - library to disk asynchronous IO kernel functions</para>
- </listitem>
- <listitem>
- <para>libaio-dev - Compilation support for libaio</para>
- </listitem>
- <listitem>
- <para>A full JDK installed with the environment variable JAVA_HOME set to its
- location</para>
- </listitem>
- </itemizedlist>
- <para>To perform this installation on RHEL or Fedora, you can simply type this at a
- command line:</para>
- <programlisting>sudo yum install automake libtool autoconf gcc-c++ gcc libaio libaio-devel make</programlisting>
- <para>Or on Debian systems:</para>
- <programlisting>sudo apt-get install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make</programlisting>
- <note>
- <para>You could find a slight variation of the package names depending on the
- version and Linux distribution. (for example gcc-c++ on Fedora versus g++ on
- Debian systems)</para>
- </note>
- </section>
- <section>
- <title>Invoking the compilation</title>
- <para>In the distribution, in the <literal>native-src</literal> directory, execute the
- shell script <literal>bootstrap</literal>. This script will invoke <literal
- >automake</literal> and <literal>make</literal> what will create all the make
- files and the native library.</para>
- <programlisting>someUser@someBox:/messaging-distribution/native-src$ ./bootstrap
-checking for a BSD-compatible install... /usr/bin/install -c
-checking whether build environment is sane... yes
-checking for a thread-safe mkdir -p... /bin/mkdir -p
-
-...
-
-configure: creating ./config.status
-config.status: creating Makefile
-config.status: creating ./src/Makefile
-config.status: creating config.h
-config.status: config.h is unchanged
-config.status: executing depfiles commands
-config.status: executing libtool commands
-
-...</programlisting>
- <para>The produced library will be at <literal
- >./native-src/src/.libs/libActiveMQAIO.so</literal>. Simply move that file over
- <literal>bin</literal> on the distribution or the place you have chosen on the
- <link linkend="using-server.library.path">library path</link>.</para>
- <para>If you want to perform changes on the ActiveMQ libaio code, you could just call
- make directly at the <literal>native-src</literal> directory.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/logging.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/logging.md b/docs/user-manual/en/logging.md
new file mode 100644
index 0000000..32ef718
--- /dev/null
+++ b/docs/user-manual/en/logging.md
@@ -0,0 +1,93 @@
+Logging
+=======
+
+ActiveMQ uses the JBoss Logging framework to do its logging and is
+configurable via the `logging.properties` file found in the
+configuration directories. This is configured by Default to log to both
+the console and to a file.
+
+There are 6 loggers available which are as follows:
+
+ Logger Logger Description
+ ------------------------------------------- ----------------------------------------------------
+ org.jboss.logging Logs any calls not handled by the ActiveMQ loggers
+ org.apache.activemq.core.server Logs the core server
+ org.apache.activemq.utils Logs utility calls
+ org.apache.activemq.journal Logs Journal calls
+ org.apache.activemq.jms Logs JMS calls
+ org.apache.activemq.integration.bootstrap Logs bootstrap calls
+
+ : Global Configuration Properties
+
+Logging in a client or with an Embedded server
+==============================================
+
+Firstly, if you want to enable logging on the client side you need to
+include the JBoss logging jars in your library. If you are using maven
+add the following dependencies.
+
+ <dependency>
+ <groupId>org.jboss.logmanager</groupId>
+ <artifactId>jboss-logmanager</artifactId>
+ <version>1.3.1.Final</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.activemq</groupId>
+ <artifactId>activemq-core-client</artifactId>
+ <version>2.3.0.Final</version>
+ </dependency>
+
+There are 2 properties you need to set when starting your java program,
+the first is to set the Log Manager to use the JBoss Log Manager, this
+is done by setting the `-Djava.util.logging.manager` property i.e.
+`-Djava.util.logging.manager=org.jboss.logmanager.LogManager`
+
+The second is to set the location of the logging.properties file to use,
+this is done via the `-Dlogging.configuration` for instance
+`-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties`.
+
+> **Note**
+>
+> The value for this needs to be valid URL
+
+The following is a typical `logging.properties for a client`
+
+ # Root logger option
+ loggers=org.jboss.logging,org.apache.activemq.core.server,org.apache.activemq.utils,org.apache.activemq.journal,org.apache.activemq.jms,org.apache.activemq.ra
+
+ # Root logger level
+ logger.level=INFO
+ # ActiveMQ logger levels
+ logger.org.apache.activemq.core.server.level=INFO
+ logger.org.apache.activemq.utils.level=INFO
+ logger.org.apache.activemq.jms.level=DEBUG
+
+ # Root logger handlers
+ logger.handlers=FILE,CONSOLE
+
+ # Console handler configuration
+ handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
+ handler.CONSOLE.properties=autoFlush
+ handler.CONSOLE.level=FINE
+ handler.CONSOLE.autoFlush=true
+ handler.CONSOLE.formatter=PATTERN
+
+ # File handler configuration
+ handler.FILE=org.jboss.logmanager.handlers.FileHandler
+ handler.FILE.level=FINE
+ handler.FILE.properties=autoFlush,fileName
+ handler.FILE.autoFlush=true
+ handler.FILE.fileName=activemq.log
+ handler.FILE.formatter=PATTERN
+
+ # Formatter pattern configuration
+ formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
+ formatter.PATTERN.properties=pattern
+ formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n
+
+Logging With The JBoss Application Server
+=========================================
+
+When ActiveMQ is deployed within the JBoss Application Server version
+7.x or above then it will still use JBoss Logging, refer to the AS7
+documentation on how to configure AS7 logging.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/logging.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/logging.xml b/docs/user-manual/en/logging.xml
deleted file mode 100644
index 8277b55..0000000
--- a/docs/user-manual/en/logging.xml
+++ /dev/null
@@ -1,138 +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="logging">
- <title>Logging</title>
- <para>ActiveMQ uses the JBoss Logging framework to do its logging and is configurable via the <literal>logging.properties</literal>
- file found in the configuration directories. This is configured by Default to log to both the console and to a file.</para>
- <para>There are 6 loggers available which are as follows:</para>
- <table frame="topbot" border="2">
- <title>Global Configuration Properties</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <thead>
- <row>
- <entry>Logger</entry>
- <entry>Logger Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>org.jboss.logging</entry>
- <entry>Logs any calls not handled by the ActiveMQ loggers</entry>
- </row>
- <row>
- <entry>org.apache.activemq.core.server</entry>
- <entry>Logs the core server</entry>
- </row>
- <row>
- <entry>org.apache.activemq.utils</entry>
- <entry>Logs utility calls</entry>
- </row>
- <row>
- <entry>org.apache.activemq.journal</entry>
- <entry>Logs Journal calls</entry>
- </row>
- <row>
- <entry>org.apache.activemq.jms</entry>
- <entry>Logs JMS calls</entry>
- </row>
- <row>
- <entry>org.apache.activemq.integration.bootstrap</entry>
- <entry>Logs bootstrap calls</entry>
- </row>
- </tbody>
- </tgroup>
- <para>you can configure the levels on these loggers independently in the appropriate <literal>logging.properties</literal>
- file</para>
- </table>
- <section>
- <title>Logging in a client or with an Embedded server</title>
- <para>
- Firstly, if you want to enable logging on the client side you need to include the JBoss logging jars in your library.
- If you are using maven add the following dependencies.
- <programlisting>
-<dependency>
- <groupId>org.jboss.logmanager</groupId>
- <artifactId>jboss-logmanager</artifactId>
- <version>1.3.1.Final</version>
-</dependency>
-<dependency>
- <groupId>org.apache.activemq</groupId>
- <artifactId>activemq-core-client</artifactId>
- <version>2.3.0.Final</version>
-</dependency></programlisting>
- </para>
- <para>
- There are 2 properties you need to set when starting your java program, the first is to set the Log Manager to use
- the JBoss Log Manager, this is done by setting the <literal>-Djava.util.logging.manager</literal> property i.e.
- <literal>-Djava.util.logging.manager=org.jboss.logmanager.LogManager</literal>
- </para>
- <para>
- The second is to set the location of the logging.properties file to use, this is done via the <literal>-Dlogging.configuration</literal>
- for instance <literal>-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties</literal>.
- <note>The value for this needs to be valid URL</note>
- </para>
- <para>
- The following is a typical <literal>logging.properties for a client</literal>
- <programlisting>
-# Root logger option
-loggers=org.jboss.logging,org.apache.activemq.core.server,org.apache.activemq.utils,org.apache.activemq.journal,org.apache.activemq.jms,org.apache.activemq.ra
-
-# Root logger level
-logger.level=INFO
-# ActiveMQ logger levels
-logger.org.apache.activemq.core.server.level=INFO
-logger.org.apache.activemq.utils.level=INFO
-logger.org.apache.activemq.jms.level=DEBUG
-
-# Root logger handlers
-logger.handlers=FILE,CONSOLE
-
-# Console handler configuration
-handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
-handler.CONSOLE.properties=autoFlush
-handler.CONSOLE.level=FINE
-handler.CONSOLE.autoFlush=true
-handler.CONSOLE.formatter=PATTERN
-
-# File handler configuration
-handler.FILE=org.jboss.logmanager.handlers.FileHandler
-handler.FILE.level=FINE
-handler.FILE.properties=autoFlush,fileName
-handler.FILE.autoFlush=true
-handler.FILE.fileName=activemq.log
-handler.FILE.formatter=PATTERN
-
-# Formatter pattern configuration
-formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
-formatter.PATTERN.properties=pattern
-formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n</programlisting>
- </para>
- </section>
- <section>
- <title>Logging With The JBoss Application Server</title>
- <para>When ActiveMQ is deployed within the JBoss Application Server version 7.x or above then
- it will still use JBoss Logging, refer to the AS7 documentation on how to configure AS7 logging.</para>
- </section>
-</chapter>
[23/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/eap-manual/pom.xml
----------------------------------------------------------------------
diff --git a/docs/eap-manual/pom.xml b/docs/eap-manual/pom.xml
deleted file mode 100644
index d586aeb..0000000
--- a/docs/eap-manual/pom.xml
+++ /dev/null
@@ -1,309 +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.
- -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.jboss.project</groupId>
- <artifactId>${docname}-${translation}</artifactId>
- <version>1.0</version>
- <packaging>jdocbook</packaging>
- <name>${bookname}-(${translation})</name>
-
- <properties>
- <translation>en</translation>
- <docname>ActiveMQ_EAP_Manual</docname>
- <bookname>ActiveMQ EAP Manual</bookname>
- </properties>
-
- <repositories>
- <repository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </snapshots>
- </repository>
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository>
- <!--pluginRepository>
- <id>jboss-snapshot-repository-group</id>
- <name>JBoss Snapshot Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/snapshot/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository-->
- </pluginRepositories>
-
- <profiles>
-
- <!-- mvn compile -->
- <profile>
- <id>all</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml -->
- <profile>
- <id>html</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml-single -->
- <profile>
- <id>html-single</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Ppdf -->
- <profile>
- <id>pdf</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.1.0</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- </profiles>
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDirectory>${project.basedir}</sourceDirectory>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <masterTranslation>en</masterTranslation>
- <imageResource>
- <directory>${project.basedir}/en</directory>
- <includes>
- <include>images/*.png</include>
- </includes>
- </imageResource>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${pdf.name}</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <docbookVersion>1.72.0</docbookVersion>
- <localeSeparator>-</localeSeparator>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </pluginManagement>
- </build>
- <!--<build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <sourceDirectory>.</sourceDirectory>
- <imageResource>
- <directory>${translation}</directory>
- <includes>
- <include>images/*</include>
- </includes>
- </imageResource>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
-
- </plugins>
- </build>-->
-
-</project>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/pom.xml
----------------------------------------------------------------------
diff --git a/docs/pom.xml b/docs/pom.xml
deleted file mode 100644
index 183b3ca..0000000
--- a/docs/pom.xml
+++ /dev/null
@@ -1,55 +0,0 @@
-<!--
- ~ 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.
- -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.activemq</groupId>
- <artifactId>activemq-pom</artifactId>
- <version>6.0.0-SNAPSHOT</version>
- </parent>
-
- <groupId>org.apache.activemq.docs</groupId>
- <artifactId>activemq-docs</artifactId>
- <packaging>pom</packaging>
- <name>ActiveMQ6 Documentation</name>
-
- <properties>
- <skipLicenseCheck>true</skipLicenseCheck>
- <skipStyleCheck>true</skipStyleCheck>
- </properties>
-
- <modules>
- <module>user-manual</module>
- <module>quickstart-guide</module>
- </modules>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-deploy-plugin</artifactId>
- <configuration>
- <skip>true</skip>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
-</project>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.ent
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.ent b/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.ent
deleted file mode 100644
index 2d68887..0000000
--- a/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.ent
+++ /dev/null
@@ -1,5 +0,0 @@
-<!ENTITY PRODUCT "ActiveMQ">
-<!ENTITY BOOKID "ActiveMQ_QuickStart_Guide">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "Red Hat Inc.">
-<!ENTITY semi ";">
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.xml b/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.xml
deleted file mode 100644
index 0dac31a..0000000
--- a/docs/quickstart-guide/en/ActiveMQ_QuickStart_Guide.xml
+++ /dev/null
@@ -1,17 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-
-]>
-<book>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="notice.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="about.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="download.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="running.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="examples.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/Author_Group.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/Author_Group.xml b/docs/quickstart-guide/en/Author_Group.xml
deleted file mode 100644
index 43a10c3..0000000
--- a/docs/quickstart-guide/en/Author_Group.xml
+++ /dev/null
@@ -1,45 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<authorgroup>
- <author>
- <firstname>Clebert</firstname>
- <surname>Suconic</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Project Lead</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>csuconic@redhat.com</email>
- </author>
- <author>
- <firstname>Andy</firstname>
- <surname>Taylor</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ataylor@redhat.com</email>
- </author>
- <author>
- <firstname>Tim</firstname>
- <surname>Fox</surname>
- </author>
- <author>
- <firstname>Jeff</firstname>
- <surname>Mesnil</surname>
- </author>
- <author>
- <firstname>Howard</firstname>
- <surname>Gao</surname>
- <affiliation>
- <shortaffil>Red Hat, Inc.</shortaffil>
- <jobtitle>Core Developer</jobtitle>
- <orgdiv>JBoss</orgdiv>
- </affiliation>
- <email>ghoward@redhat.com</email>
- </author>
-</authorgroup>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/Book_Info.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/Book_Info.xml b/docs/quickstart-guide/en/Book_Info.xml
deleted file mode 100644
index 22a9c62..0000000
--- a/docs/quickstart-guide/en/Book_Info.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<bookinfo id="ActiveMQ_QuickStart_Guide">
- <title>ActiveMQ QuickStart Guide</title>
- <subtitle>Putting the buzz in messaging</subtitle>
- <productname>ActiveMQ</productname>
- <edition>2.1.0</edition>
- <pubsnumber>1</pubsnumber>
- <abstract>
- <para>This Quickstart guide will help you get ActiveMQ up and running in a few minutes and will explain the basics needed
- to get started.</para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>ActiveMQ Logo</phrase>
- </textobject>
- </inlinemediaobject>
- </corpauthor>
- <copyright>
- <year>&YEAR;</year>
- <holder>&HOLDER;</holder>
- </copyright>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
-</bookinfo>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/README.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/README.md b/docs/quickstart-guide/en/README.md
new file mode 100644
index 0000000..d1b4e1f
--- /dev/null
+++ b/docs/quickstart-guide/en/README.md
@@ -0,0 +1,4 @@
+ActiveMQ Quick Start Manual
+====================
+
+How to get started with ActiveMQ
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/SUMMARY.md b/docs/quickstart-guide/en/SUMMARY.md
new file mode 100644
index 0000000..0740ee4
--- /dev/null
+++ b/docs/quickstart-guide/en/SUMMARY.md
@@ -0,0 +1,7 @@
+* [Legal Notice](notice.md)
+* [Introduction](introduction.md)
+* [About](about.md)
+* [Download](download.md)
+* [Installation](installation.md)
+* [Running](running.md)
+* [Examples](examples.md)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/about.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/about.md b/docs/quickstart-guide/en/about.md
new file mode 100644
index 0000000..4d25f94
--- /dev/null
+++ b/docs/quickstart-guide/en/about.md
@@ -0,0 +1,49 @@
+About ActiveMQ
+==============
+
+What is ActiveMQ?
+
+- ActiveMQ is an open source project to build a multi-protocol,
+ embeddable, very high performance, clustered, asynchronous messaging
+ system.
+
+- For answers to more questions about what ActiveMQ is and what it
+ isn't please visit the [FAQs wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs).
+
+Why use ActiveMQ? Here are just a few of the reasons:
+
+- 100% open source software. ActiveMQ is licenced using the Apache
+ Software License v2.0 to minimise barriers to adoption.
+
+- ActiveMQ is designed with usability in mind.
+
+- Written in Java. Runs on any platform with a Java 6+ runtime, that's
+ everything from Windows desktops to IBM mainframes.
+
+- Amazing performance. Our class beating high performance journal
+ provides persistent messaging performance at rates normally seen for
+ non persistent messaging, our non persistent messaging performance
+ rocks the boat too.
+
+- Full feature set. All the features you'd expect in any serious
+ messaging system, and others you won't find anywhere else.
+
+- Elegant, clean-cut design with minimal third party dependencies. Run
+ ActiveMQ stand-alone, run it in integrated in your favourite JEE
+ application server, or run it embedded inside your own product. It's
+ up to you.
+
+- Seamless high availability. We provide a HA solution with automatic
+ client failover so you can guarantee zero message loss or
+ duplication in event of server failure.
+
+- Hugely flexible clustering. Create clusters of servers that know how
+ to load balance messages. Link geographically distributed clusters
+ over unreliable connections to form a global network. Configure
+ routing of messages in a highly flexible way.
+
+- For a full list of features, please see the [features wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQFeatures) .
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/about.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/about.xml b/docs/quickstart-guide/en/about.xml
deleted file mode 100644
index 800c190..0000000
--- a/docs/quickstart-guide/en/about.xml
+++ /dev/null
@@ -1,83 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-
-<chapter id="about">
- <title>About ActiveMQ</title>
- <para>What is ActiveMQ?</para>
- <itemizedlist>
- <listitem>
- <para>ActiveMQ is an open source project to build a multi-protocol, embeddable, very high
- performance, clustered, asynchronous messaging system.</para>
- </listitem>
- <listitem>
- <para>For answers to more questions about what ActiveMQ is and what it isn't please visit
- the <ulink url="http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs">FAQs wiki
- page</ulink>.</para>
- </listitem>
- </itemizedlist>
- <para>Why use ActiveMQ? Here are just a few of the reasons:</para>
- <itemizedlist>
- <listitem>
- <para>100% open source software. ActiveMQ is licenced using the Apache Software License v2.0
- to minimise barriers to adoption.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ is designed with usability in mind.</para>
- </listitem>
- <listitem>
- <para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything
- from Windows desktops to IBM mainframes.</para>
- </listitem>
- <listitem>
- <para>Amazing performance. Our class beating high performance journal provides persistent
- messaging performance at rates normally seen for non persistent messaging, our non
- persistent messaging performance rocks the boat too.</para>
- </listitem>
- <listitem>
- <para>Full feature set. All the features you'd expect in any serious messaging system,
- and others you won't find anywhere else.</para>
- </listitem>
- <listitem>
- <para>Elegant, clean-cut design with minimal third party dependencies. Run ActiveMQ
- stand-alone, run it in integrated in your favourite JEE application server, or run
- it embedded inside your own product. It's up to you.</para>
- </listitem>
- <listitem>
- <para>Seamless high availability. We provide a HA solution with automatic client
- failover so you can guarantee zero message loss or duplication in event of server
- failure.</para>
- </listitem>
- <listitem>
- <para>Hugely flexible clustering. Create clusters of servers that know how to load
- balance messages. Link geographically distributed clusters over unreliable
- connections to form a global network. Configure routing of messages in a highly
- flexible way.</para>
- </listitem>
- <listitem>
- <para>For a full list of features, please see the <ulink
- url="http://www.jboss.org/community/wiki/ActiveMQFeatures">features wiki
- page</ulink> .</para>
- </listitem>
- </itemizedlist>
-</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/download.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/download.md b/docs/quickstart-guide/en/download.md
new file mode 100644
index 0000000..7b3c08f
--- /dev/null
+++ b/docs/quickstart-guide/en/download.md
@@ -0,0 +1,36 @@
+Download
+========
+
+The official ActiveMQ project page is <http://activemq.org/>.
+
+Software Download
+=================
+
+The software can be download from the Download
+page:<http://activemq.org/downloads.html>
+
+Project Information
+===================
+
+- Please take a look at our project
+ [wiki](http://www.jboss.org/community/wiki/ActiveMQ)
+
+- If you have any user questions please use our [user
+ forum](https://community.jboss.org/en/activemq)
+
+- If you have development related questions, please use our [developer
+ forum](http://www.jboss.org/index.html?module=bb&op=viewforum&f=313)
+
+- Pop in and chat to us in our [IRC
+ channel](irc://irc.freenode.net:6667/activemq)
+
+- Our project [blog](http://activemq.blogspot.com/)
+
+- Follow us on [twitter](http://twitter.com/activemq)
+
+- ActiveMQ Git repository is <https://github.com/activemq/activemq>
+
+- All release tags are available from
+ <https://github.com/activemq/activemq/tags>
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/download.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/download.xml b/docs/quickstart-guide/en/download.xml
deleted file mode 100644
index 6c8b9c2..0000000
--- a/docs/quickstart-guide/en/download.xml
+++ /dev/null
@@ -1,74 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="download">
- <title>Download</title>
- <para>The official ActiveMQ project page is <ulink url="http://activemq.org/"
- >http://activemq.org/</ulink>.</para>
- <section id="download.software">
- <title>Software Download</title>
- <para>The software can be download from the Download page:<ulink
- url="http://activemq.org/downloads.html"
- >http://activemq.org/downloads.html</ulink></para>
- </section>
- <section id="download.git">
- <title>Project Information</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>Please take a look at our project <ulink
- url="http://www.jboss.org/community/wiki/ActiveMQ">wiki</ulink></para>
- </listitem>
- <listitem>
- <para>If you have any user questions please use our <ulink
- url="https://community.jboss.org/en/activemq">user
- forum</ulink></para>
- </listitem>
- <listitem>
- <para>If you have development related questions, please use our <ulink
- url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=313"
- >developer forum</ulink></para>
- </listitem>
- <listitem>
- <para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/activemq"
- >IRC channel</ulink></para>
- </listitem>
- <listitem>
- <para>Our project <ulink url="http://activemq.blogspot.com/">blog</ulink></para>
- </listitem>
- <listitem>
- <para>Follow us on <ulink url="http://twitter.com/activemq">twitter</ulink></para>
- </listitem>
- <listitem>
- <para>ActiveMQ Git repository is <ulink
- url="https://github.com/activemq/activemq"
- >https://github.com/activemq/activemq</ulink></para>
- </listitem>
- <listitem>
- <para>All release tags are available from <ulink
- url="https://github.com/activemq/activemq/tags"
- >https://github.com/activemq/activemq/tags</ulink></para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/examples.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/examples.md b/docs/quickstart-guide/en/examples.md
new file mode 100644
index 0000000..5b84747
--- /dev/null
+++ b/docs/quickstart-guide/en/examples.md
@@ -0,0 +1,314 @@
+Running the Examples
+====================
+
+In the directory `examples` there are 2 sets of examples, these are
+
+- JMS Examples - these demonstrate functionality while sending and
+ consumng JMS messages.
+
+- Java EE Examples - these demonstrate application server integration,
+ e.g. MDBs, EJBs, Servlets, etc.
+
+The JMS examples
+================
+
+The JMS Examples all follow the same format. Each examples is contained
+in its own directory which contains the following.
+
+- `pom.xml`
+
+ This is the Maven build file used to run the example
+
+- `src` directory
+
+ This contains the source code for the example
+
+- `resources/activemq/server0` configuration directory
+
+ This contains the configuration files needed to run the server for
+ the example. There may be multiple configuration directories
+ `server0`, `server1` etc for clustered examples etc.
+
+Each example will start one or more stand-alone servers and stop them
+after the example has completed.
+
+As a quick start we'll run the queue example. For all other examples
+refer to the main user manual.
+
+Firstly open a Shell or a Command prompt and navigate to the
+`examples/jms/queue` directory.
+
+Type the command `mvn verify` and you should see the following output:
+
+
+ [INFO] Scanning for projects...
+ [INFO]
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building ActiveMQ JMS Queue Example 2.3.0.BETA-SNAPSHOT
+ [INFO] ------------------------------------------------------------------------
+ [INFO]
+ [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ activemq-jms-queue-example ---
+ [INFO] Using 'UTF-8' encoding to copy filtered resources.
+ [INFO] Copying 3 resources
+ [INFO]
+ [INFO] --- maven-compiler-plugin:3.0:compile (default-compile) @ activemq-jms-queue-example ---
+ [INFO] Nothing to compile - all classes are up to date
+ [INFO]
+ [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ activemq-jms-queue-example ---
+ [INFO] Using 'UTF-8' encoding to copy filtered resources.
+ [INFO] skip non existing resourceDirectory /home/andy/projects/activemq-master/examples/jms/queue/src/test/resources
+ [INFO]
+ [INFO] --- maven-compiler-plugin:3.0:testCompile (default-testCompile) @ activemq-jms-queue-example ---
+ [INFO] No sources to compile
+ [INFO]
+ [INFO] --- maven-surefire-plugin:2.13:test (default-test) @ activemq-jms-queue-example ---
+ [INFO]
+ [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ activemq-jms-queue-example ---
+ [INFO] Building jar: /home/andy/projects/activemq-master/examples/jms/queue/target/activemq-jms-queue-example-2.3.0.BETA-SNAPSHOT.jar
+ [INFO]
+ [INFO] >>> maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example >>>
+ [INFO]
+ [INFO] <<< maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example <<<
+ [INFO]
+ [INFO] --- maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example ---
+ [INFO] Building jar: /home/andy/projects/activemq-master/examples/jms/queue/target/activemq-jms-queue-example-2.3.0.BETA-SNAPSHOT-sources.jar
+ [INFO]
+ [INFO] >>> maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example >>>
+ [INFO]
+ [INFO] <<< maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example <<<
+ [INFO]
+ [INFO] --- maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example ---
+ [WARNING] Artifact org.apache.activemq.examples.jms:activemq-jms-queue-example:java-source:sources:2.3.0.BETA-SNAPSHOT already attached to project, ignoring duplicate
+ [INFO]
+ [INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:start (start) @ activemq-jms-queue-example ---
+ [file:/home/andy/projects/activemq-master/examples/jms/queue/target/classes/activemq/server0/]
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.deployers.impl.FileConfigurationParser parseMainConfig
+ WARN: HQ222018: AIO was not located on this platform, it will fall back to using pure Java NIO. If your platform is Linux, install LibAIO to enable the AIO journal
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl start
+ INFO: HQ221000: live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/journal,bindingsDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/bindings,largeMessagesDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/largemessages,pagingDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/paging)
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl$SharedStoreLiveActivation run
+ INFO: HQ221006: Waiting to obtain live lock
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.persistence.impl.journal.JournalStorageManager <init>
+ INFO: HQ221013: Using NIO Journal
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl initialisePart1
+ WARN: HQ222007: Security risk! ActiveMQ is running with the default cluster admin user and default password. Please see the ActiveMQ user guide, cluster chapter, for instructions on how to change this.
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.FileLockNodeManager startLiveNode
+ INFO: HQ221034: Waiting to obtain live lock
+ Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.FileLockNodeManager startLiveNode
+ INFO: HQ221035: Live Server Obtained live lock
+ Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl deployQueue
+ INFO: HQ221003: trying to deploy queue jms.queue.exampleQueue
+ Apr 17, 2013 10:51:02 AM org.apache.activemq.core.remoting.impl.netty.NettyAcceptor start
+ INFO: HQ221020: Started Netty Acceptor version 3.6.2.Final-c0d783c localhost:5445 for CORE protocol
+ Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl$SharedStoreLiveActivation run
+ INFO: HQ221007: Server is now live
+ Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl start
+ INFO: HQ221001: ActiveMQ Server version 2.3.0.SNAPSHOT (black'n'yellow, 123) [a57893ff-7783-11e2-9787-07ca142fc9f7]
+ [INFO]
+ [INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:runClient (runClient) @ activemq-jms-queue-example ---
+ Apr 17, 2013 10:51:02 AM org.apache.activemq.common.example.ActiveMQExample getContext
+ INFO: using jnp://localhost:1099 for jndi
+ Sent message: This is a text message
+ Received message: This is a text message
+ example complete
+
+ #####################
+ ### SUCCESS! ###
+ #####################
+ [INFO]
+ [INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:stop (stop) @ activemq-jms-queue-example ---
+ Apr 17, 2013 10:51:03 AM org.apache.activemq.core.server.management.impl.ManagementServiceImpl stop
+ WARN: HQ222113: On ManagementService stop, there are 1 unexpected registered MBeans: [core.acceptor.netty-acceptor]
+ Apr 17, 2013 10:51:03 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl stop
+ INFO: HQ221002: ActiveMQ Server version 2.3.0.SNAPSHOT (black'n'yellow, 123) [a57893ff-7783-11e2-9787-07ca142fc9f7] stopped
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESS
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Total time: 4.428s
+ [INFO] Finished at: Wed Apr 17 10:51:03 BST 2013
+ [INFO] Final Memory: 11M/456M
+ [INFO] ------------------------------------------------------------------------
+
+Congratulations! You have successfully run your first ActiveMQ example.
+Try some of the others.
+
+The Java EE Examples
+====================
+
+The Java EE Examples are examples that require a JEE application server
+to run. They include MDB, Servlet, EJB examples etc. For this you will
+need the JBoss Application Server 7.1.x installed and uses Arquillian to
+run the example. How to do this is explained in the previous chapters.
+
+We'll use the MDB example for the purposes of this guide. For the other
+examples refer to the user guide. Before going any further ensure that
+the JBoss Application Server is running.
+
+The first thing we need to do is set the `JBOSS_HOME` environment
+property to the location of the JBoss Application Server, in a Linux
+shell this would be something like:
+
+ export JBOSS_HOME=/home/jbossas7.1/build/output/jboss-7.1.0
+
+Yoy can then run the example via maven by running `mvn test`
+
+In the shell window you should see something like the following output:
+
+ [INFO] Scanning for projects...
+ [INFO]
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building ActiveMQ JEE MDB Example 2.3.0.BETA-SNAPSHOT
+ [INFO] ------------------------------------------------------------------------
+ [INFO]
+ [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Using 'UTF-8' encoding to copy filtered resources.
+ [INFO] skip non existing resourceDirectory /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/src/main/resources
+ [INFO]
+ [INFO] --- maven-compiler-plugin:3.0:compile (default-compile) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Nothing to compile - all classes are up to date
+ [INFO]
+ [INFO] --- maven-resources-plugin:2.6:copy-resources (as-node-0) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Using 'UTF-8' encoding to copy filtered resources.
+ [INFO] Copying 1112 resources
+ [INFO] Copying 5 resources
+ [INFO]
+ [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Using 'UTF-8' encoding to copy filtered resources.
+ [INFO] Copying 1 resource
+ [INFO]
+ [INFO] --- maven-compiler-plugin:3.0:testCompile (default-testCompile) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Changes detected - recompiling the module!
+ [INFO] Compiling 1 source file to /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/test-classes
+ [INFO]
+ [INFO] --- maven-surefire-plugin:2.12:test (default-test) @ activemq-jee-mdb-bmt-example ---
+ [INFO] Surefire report directory: /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/surefire-reports
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.apache.activemq.javaee.example.server.ExampleRunnerTest
+ log4j:WARN No appenders could be found for logger (org.jboss.logging).
+ log4j:WARN Please initialize the log4j system properly.
+ log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
+ Apr 17, 2013 10:58:04 AM org.jboss.arquillian.container.impl.MapObject populate
+ WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.managed.ManagedContainerConfiguration
+ Unused property entries: {waitForPortsTimeoutInSeconds=8, waitForPorts=8787 9999}
+ Supported property names: [jbossHome, outputToConsole, enableAssertions, password, managementPort, javaHome, javaVmArguments, username, serverConfig, allowConnectingToRunningServer, managementAddress, startupTimeoutInSeconds, modulePath]
+ Apr 17, 2013 10:58:04 AM org.jboss.as.arquillian.container.managed.ManagedDeployableContainer startInternal
+ INFO: Starting container with: [/home/andy/devtools/jdk1.6.0_25//bin/java, -Djboss.inst=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0, -ea, -Djboss.home.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0, -Dorg.jboss.boot.log.file=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/log/boot.log, -Dlogging.configuration=file:/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/configuration/logging.properties, -Djboss.modules.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/modules, -Djboss.bundles.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/bundles, -jar, /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/jboss-modules.jar, -mp, /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/modules, -jaxpmodule
, javax.xml.jaxp-provider, org.jboss.as.standalone, -server-config, standalone-example.xml]
+ 10:58:04,525 INFO [org.jboss.modules] JBoss Modules version 1.1.1.GA
+ 10:58:04,664 INFO [org.jboss.msc] JBoss MSC version 1.0.2.GA
+ 10:58:04,703 INFO [org.jboss.as] JBAS015899: JBoss AS 7.1.1.Final "Brontes" starting
+ 10:58:05,492 INFO [org.xnio] XNIO Version 3.0.3.GA
+ 10:58:05,494 INFO [org.jboss.as.server] JBAS015888: Creating http management service using socket-binding (management-http)
+ 10:58:05,502 INFO [org.xnio.nio] XNIO NIO Implementation Version 3.0.3.GA
+ 10:58:05,509 INFO [org.jboss.remoting] JBoss Remoting version 3.2.3.GA
+ 10:58:05,527 INFO [org.jboss.as.logging] JBAS011502: Removing bootstrap log handlers
+ 10:58:05,530 INFO [org.jboss.as.configadmin] (ServerService Thread Pool -- 32) JBAS016200: Activating ConfigAdmin Subsystem
+ 10:58:05,560 INFO [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 37) JBAS010280: Activating Infinispan subsystem.
+ 10:58:05,562 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 33) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
+ 10:58:05,573 INFO [org.jboss.as.jacorb] (ServerService Thread Pool -- 38) JBAS016300: Activating JacORB Subsystem
+ 10:58:05,595 INFO [org.jboss.as.connector] (MSC service thread 1-12) JBAS010408: Starting JCA Subsystem (JBoss IronJacamar 1.0.9.Final)
+ 10:58:05,612 INFO [org.jboss.as.naming] (ServerService Thread Pool -- 48) JBAS011800: Activating Naming Subsystem
+ 10:58:05,625 INFO [org.jboss.as.osgi] (ServerService Thread Pool -- 49) JBAS011940: Activating OSGi Subsystem
+ 10:58:05,649 INFO [org.jboss.as.security] (ServerService Thread Pool -- 54) JBAS013101: Activating Security Subsystem
+ 10:58:05,657 INFO [org.jboss.as.naming] (MSC service thread 1-8) JBAS011802: Starting Naming Service
+ 10:58:05,663 INFO [org.jboss.as.mail.extension] (MSC service thread 1-16) JBAS015400: Bound mail session [java:jboss/mail/Default]
+ 10:58:05,675 INFO [org.jboss.as.security] (MSC service thread 1-14) JBAS013100: Current PicketBox version=4.0.7.Final
+ 10:58:05,683 INFO [org.jboss.as.webservices] (ServerService Thread Pool -- 58) JBAS015537: Activating WebServices Extension
+ 10:58:05,705 INFO [org.jboss.jaxr] (MSC service thread 1-8) JBAS014000: Started JAXR subsystem, binding JAXR connection factory into JNDI as: java:jboss/jaxr/ConnectionFactory
+ 10:58:05,831 INFO [org.jboss.ws.common.management.AbstractServerConfig] (MSC service thread 1-4) JBoss Web Services - Stack CXF Server 4.0.2.GA
+ 10:58:05,943 INFO [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-6) Starting Coyote HTTP/1.1 on http-localhost.localdomain-127.0.0.1-8080
+ 10:58:05,966 INFO [org.jboss.as.jacorb] (MSC service thread 1-2) JBAS016330: CORBA ORB Service started
+ 10:58:05,988 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingjournal,bindingsDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingbindings,largeMessagesDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messaginglargemessages,pagingDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingpaging)
+ 10:58:05,996 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) Waiting to obtain live lock
+ 10:58:06,037 INFO [org.apache.activemq.core.persistence.impl.journal.JournalStorageManager] (MSC service thread 1-11) Using AIO Journal
+ 10:58:06,122 INFO [org.jboss.as.jacorb] (MSC service thread 1-14) JBAS016328: CORBA Naming Service started
+ 10:58:06,184 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-7) JBAS010400: Bound data source [java:jboss/datasources/ExampleDS]
+ 10:58:06,204 INFO [org.apache.activemq.core.server.impl.AIOFileLockNodeManager] (MSC service thread 1-11) Waiting to obtain live lock
+ 10:58:06,205 INFO [org.apache.activemq.core.server.impl.AIOFileLockNodeManager] (MSC service thread 1-11) Live Server Obtained live lock
+ 10:58:06,434 INFO [org.jboss.as.remoting] (MSC service thread 1-2) JBAS017100: Listening on localhost.localdomain/127.0.0.1:4447
+ 10:58:06,434 INFO [org.jboss.as.remoting] (MSC service thread 1-15) JBAS017100: Listening on /127.0.0.1:9999
+ 10:58:06,436 INFO [org.jboss.as.server.deployment.scanner] (MSC service thread 1-16) JBAS015012: Started FileSystemDeploymentService for directory /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/deployments
+ 10:58:08,790 INFO [org.apache.activemq.core.remoting.impl.netty.NettyAcceptor] (MSC service thread 1-11) Started Netty Acceptor version 3.2.5.Final-a96d88c localhost.localdomain:5445 for CORE protocol
+ 10:58:08,793 INFO [org.apache.activemq.core.remoting.impl.netty.NettyAcceptor] (MSC service thread 1-11) Started Netty Acceptor version 3.2.5.Final-a96d88c localhost.localdomain:5455 for CORE protocol
+ 10:58:08,795 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) Server is now live
+ 10:58:08,797 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) ActiveMQ Server version 2.2.13.Final (HQ_2_2_13_FINAL_AS7, 122) [5c499e88-9c63-11e2-bfa3-fe5400591699]) started
+ 10:58:08,822 INFO [org.jboss.as.messaging] (MSC service thread 1-4) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/RemoteConnectionFactory
+ 10:58:08,824 INFO [org.jboss.as.messaging] (MSC service thread 1-4) JBAS011601: Bound messaging object to jndi name java:/RemoteConnectionFactory
+ 10:58:08,825 INFO [org.jboss.as.messaging] (MSC service thread 1-10) JBAS011601: Bound messaging object to jndi name java:/ConnectionFactory
+ 10:58:08,830 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-3) trying to deploy queue jms.queue.testQueue
+ 10:58:08,836 INFO [org.jboss.as.messaging] (MSC service thread 1-3) JBAS011601: Bound messaging object to jndi name java:/queue/test
+ 10:58:08,840 INFO [org.jboss.as.messaging] (MSC service thread 1-3) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/queues/testQueue
+ 10:58:08,859 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-9) JBAS010406: Registered connection factory java:/JmsXA
+ 10:58:08,866 INFO [org.apache.activemq.ra.ActiveMQResourceAdapter] (MSC service thread 1-9) ActiveMQ resource adaptor started
+ 10:58:08,867 INFO [org.jboss.as.connector.services.ResourceAdapterActivatorService$ResourceAdapterActivator] (MSC service thread 1-9) IJ020002: Deployed: file://RaActivatoractivemq-ra
+ 10:58:08,870 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-5) JBAS010401: Bound JCA ConnectionFactory [java:/JmsXA]
+ 10:58:08,898 INFO [org.jboss.as.server.deployment] (MSC service thread 1-10) JBAS015876: Starting deployment of "ONT001-1.0.war"
+ 10:58:09,146 INFO [org.jboss.wsf.stack.cxf.metadata.MetadataBuilder] (MSC service thread 1-1) Add Service
+ id=com.hpm.webservices.BasicWSImpl
+ address=http://localhost:8080/hpm/BasicWService
+ implementor=com.hpm.webservices.BasicWSImpl
+ invoker=org.jboss.wsf.stack.cxf.JBossWSInvoker
+ serviceName={http://ont001-hpm.rhcloud.com/BasicWS}BasicWService
+ portName={http://ont001-hpm.rhcloud.com/BasicWS}BasicWS
+ wsdlLocation=null
+ mtomEnabled=false
+ 10:58:09,361 INFO [org.apache.cxf.service.factory.ReflectionServiceFactoryBean] (MSC service thread 1-1) Creating Service {http://ont001-hpm.rhcloud.com/BasicWS}BasicWService from WSDL: WEB-INF/wsdl/BasicWService.wsdl
+ 10:58:09,517 INFO [org.jboss.wsf.stack.cxf.transport.AddressRewritingEndpointInfo] (MSC service thread 1-1) Setting new service endpoint address in wsdl: http://ONT001-HPM.rhcloud.com:80/BasicWService
+ 10:58:09,656 INFO [org.jboss.wsf.stack.cxf.transport.AddressRewritingEndpointInfo] (MSC service thread 1-1) Setting new service endpoint address in wsdl: http://localhost:8080/hpm/BasicWService
+ 10:58:09,688 INFO [org.apache.cxf.endpoint.ServerImpl] (MSC service thread 1-1) Setting the server's publish address to be http://localhost:8080/hpm/BasicWService
+ 10:58:09,729 INFO [org.jboss.wsf.stack.cxf.deployment.WSDLFilePublisher] (MSC service thread 1-1) WSDL published to: file:/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/wsdl/ONT001-1.0.war/BasicWService.wsdl
+ 10:58:09,735 INFO [org.jboss.as.webservices] (MSC service thread 1-11) JBAS015539: Starting service jboss.ws.port-component-link
+ 10:58:09,748 INFO [org.jboss.as.webservices] (MSC service thread 1-10) JBAS015539: Starting service jboss.ws.endpoint."ONT001-1.0.war"."com.hpm.webservices.BasicWSImpl"
+ 10:58:09,753 INFO [org.jboss.ws.common.management.DefaultEndpointRegistry] (MSC service thread 1-10) register: jboss.ws:context=hpm,endpoint=com.hpm.webservices.BasicWSImpl
+ 10:58:09,829 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /hpm
+ 10:58:09,834 INFO [org.jboss.as] (MSC service thread 1-7) JBAS015951: Admin console listening on http://127.0.0.1:9990
+ 10:58:09,835 INFO [org.jboss.as] (MSC service thread 1-7) JBAS015874: JBoss AS 7.1.1.Final "Brontes" started in 5506ms - Started 216 of 296 services (79 services are passive or on-demand)
+ 10:58:09,979 INFO [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "ONT001-1.0.war"
+ mdb.jar:
+ /org/
+ /org.apache.activemq/
+ /org.apache.activemq/javaee/
+ /org.apache.activemq/javaee/example/
+ /org.apache.activemq/javaee/example/server/
+ /org.apache.activemq/javaee/example/server/MDB_BMTExample.class
+ 10:58:11,612 INFO [org.jboss.as.repository] (management-handler-thread - 2) JBAS014900: Content added at location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/f0/e2d589ab9490193e109c8bc833f725c87defae/content
+ 10:58:11,620 INFO [org.jboss.as.server.deployment] (MSC service thread 1-8) JBAS015876: Starting deployment of "arquillian-service"
+ 10:58:11,811 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.jmx:main") which may be changed or removed in future versions without notice.
+ 10:58:11,812 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.server:main") which may be changed or removed in future versions without notice.
+ 10:58:11,813 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.osgi:main") which may be changed or removed in future versions without notice.
+ 10:58:11,815 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.jandex:main") which may be changed or removed in future versions without notice.
+ 10:58:11,817 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.osgi.framework:main") which may be changed or removed in future versions without notice.
+ 10:58:11,953 INFO [org.jboss.as.server] (management-handler-thread - 2) JBAS018559: Deployed "arquillian-service"
+ 10:58:12,328 INFO [org.jboss.as.repository] (management-handler-thread - 3) JBAS014900: Content added at location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/59/7dcdb0f420ed57aea638b2599f7a86eecf6c85/content
+ 10:58:12,333 INFO [org.jboss.as.server.deployment] (MSC service thread 1-7) JBAS015876: Starting deployment of "mdb.jar"
+ 10:58:12,401 INFO [org.jboss.as.arquillian] (MSC service thread 1-14) Arquillian deployment detected: ArquillianConfig[service=jboss.arquillian.config."mdb.jar",unit=mdb.jar,tests=[org.apache.activemq.javaee.example.server.ExampleRunnerTest]]
+ 10:58:12,418 INFO [org.jboss.as.ejb3] (MSC service thread 1-15) JBAS014142: Started message driven bean 'MDB_BMTExample' with 'activemq-ra' resource adapter
+ 10:58:12,562 INFO [org.jboss.as.server] (management-handler-thread - 3) JBAS018559: Deployed "mdb.jar"
+ Sent message: This is a text message
+ 10:58:13,229 INFO [org.jboss.as.naming] (Remoting "localhost" task-3) JBAS011806: Channel end notification received, closing channel Channel ID 57be4578 (inbound) of Remoting connection 3ac552d5 to /127.0.0.1:58571
+ 10:58:13,255 INFO [stdout] (Thread-0 (ActiveMQ-client-global-threads-1402019528)) message This is a text message received
+ 10:58:13,257 INFO [stdout] (Thread-0 (ActiveMQ-client-global-threads-1402019528)) we're in the middle of a transaction: org.jboss.tm.usertx.client.ServerVMClientUserTransaction@6b04d3c8
+ 10:58:14,292 INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) JBAS015877: Stopped deployment mdb.jar in 33ms
+ 10:58:14,413 INFO [org.jboss.as.repository] (management-handler-thread - 1) JBAS014901: Content removed from location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/59/7dcdb0f420ed57aea638b2599f7a86eecf6c85/content
+ 10:58:14,415 INFO [org.jboss.as.server] (management-handler-thread - 1) JBAS018558: Undeployed "mdb.jar"
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 10.609 sec
+ 10:58:14,436 INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) JBAS015877: Stopped deployment arquillian-service in 6ms
+ 10:58:14,530 INFO [org.jboss.as.repository] (management-handler-thread - 2) JBAS014901: Content removed from location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/f0/e2d589ab9490193e109c8bc833f725c87defae/content
+ 10:58:14,532 INFO [org.jboss.as.server] (management-handler-thread - 2) JBAS018558: Undeployed "arquillian-service"
+
+ Results :
+
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESS
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Total time: 23.441s
+ [INFO] Finished at: Wed Apr 17 10:58:16 BST 2013
+ [INFO] Final Memory: 19M/361M
+ [INFO] ------------------------------------------------------------------------
+
+Congratulations! you have successfully deployed and run a Java EE
+example.
[13/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
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.
[19/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/architecture.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/architecture.xml b/docs/user-manual/en/architecture.xml
deleted file mode 100644
index ea21b47..0000000
--- a/docs/user-manual/en/architecture.xml
+++ /dev/null
@@ -1,151 +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="architecture">
- <title>Architecture</title>
- <para>In this section we will give an overview of the ActiveMQ high level architecture.</para>
- <section>
- <title>Core Architecture</title>
- <para>ActiveMQ core is designed simply as set of Plain Old Java Objects (POJOs) - we hope you
- like its clean-cut design.</para>
- <para>We've also designed it to have as few dependencies on external jars as possible. In
- fact, ActiveMQ core has only one jar dependency, netty.jar,
- other than the standard JDK classes! This is because we use some of the netty buffer classes
- internally.</para>
- <para>This allows ActiveMQ to be easily embedded in your own project, or instantiated in any
- dependency injection framework such as JBoss Microcontainer, Spring or Google
- Guice.</para>
- <para>Each ActiveMQ server has its own ultra high performance persistent journal, which it
- uses for message and other persistence.</para>
- <para>Using a high performance journal allows outrageous persistence message performance,
- something not achievable when using a relational database for persistence.</para>
- <para>ActiveMQ clients, potentially on different physical machines interact with the ActiveMQ
- server. ActiveMQ currently provides two APIs for messaging at the client side:</para>
- <para>
- <orderedlist>
- <listitem>
- <para>Core client API. This is a simple intuitive Java API that allows the full
- set of messaging functionality without some of the complexities of
- JMS.</para>
- </listitem>
- <listitem>
- <para>JMS client API. The standard JMS API is available at the client
- side.</para>
- </listitem>
- </orderedlist>
- </para>
- <para>JMS semantics are implemented by a thin JMS facade layer on the client side.</para>
- <para>The ActiveMQ server does not speak JMS and in fact does not know anything about JMS,
- it is a protocol agnostic messaging server designed to be used with multiple different
- protocols.</para>
- <para>When a user uses the JMS API on the client side, all JMS interactions are translated
- into operations on the ActiveMQ core client API before being transferred over the wire
- using the ActiveMQ wire format.</para>
- <para>The server always just deals with core API interactions.</para>
- <para>A schematic illustrating this relationship is shown in figure 3.1 below:</para>
- <para>
- <graphic fileref="images/architecture1.jpg" align="center"/>
- </para>
- <para>Figure 3.1 shows two user applications interacting with a ActiveMQ server. User
- Application 1 is using the JMS API, while User Application 2 is using the core client
- API directly.</para>
- <para>You can see from the diagram that the JMS API is implemented by a thin facade layer on
- the client side.</para>
- </section>
- <section>
- <title>ActiveMQ embedded in your own application</title>
- <para>ActiveMQ core is designed as a set of simple POJOs so if you have an application that
- requires messaging functionality internally but you don't want to expose that as a
- ActiveMQ server you can directly instantiate and embed ActiveMQ servers in your own
- application.</para>
- <para>For more information on embedding ActiveMQ, see <xref linkend="embedding-activemq"
- />.</para>
- </section>
- <section>
- <title>ActiveMQ integrated with a JEE application server</title>
- <para>ActiveMQ provides its own fully functional Java Connector Architecture (JCA) adaptor
- which enables it to be integrated easily into any JEE compliant application server or
- servlet engine.</para>
- <para>JEE application servers provide Message Driven Beans (MDBs), which are a special type
- of Enterprise Java Beans (EJBs) that can process messages from sources such as JMS
- systems or mail systems.</para>
- <para>Probably the most common use of an MDB is to consume messages from a JMS messaging
- system.</para>
- <para>According to the JEE specification, a JEE application server uses a JCA adapter to
- integrate with a JMS messaging system so it can consume messages for MDBs.</para>
- <para>However, the JCA adapter is not only used by the JEE application server for <emphasis
- role="italic">consuming</emphasis> messages via MDBs, it is also used when sending
- message to the JMS messaging system e.g. from inside an EJB or servlet.</para>
- <para>When integrating with a JMS messaging system from inside a JEE application server it
- is always recommended that this is done via a JCA adaptor. In fact, communicating with a
- JMS messaging system directly, without using JCA would be illegal according to the JEE
- specification.</para>
- <para>The application server's JCA service provides extra functionality such as connection
- pooling and automatic transaction enlistment, which are desirable when using messaging,
- say, from inside an EJB. It is possible to talk to a JMS messaging system directly from
- an EJB, MDB or servlet without going through a JCA adapter, but this is not recommended
- since you will not be able to take advantage of the JCA features, such as caching of JMS
- sessions, which can result in poor performance.</para>
- <para>Figure 3.2 below shows a JEE application server integrating with a ActiveMQ server via
- the ActiveMQ JCA adaptor. Note that all communication between EJB sessions or entity
- beans and Message Driven beans go through the adaptor and not directly to
- ActiveMQ.</para>
- <para>The large arrow with the prohibited sign shows an EJB session bean talking directly to
- the ActiveMQ server. This is not recommended as you'll most likely end up creating a new
- connection and session every time you want to interact from the EJB, which is an
- anti-pattern.</para>
- <para>
- <graphic fileref="images/architecture2.jpg"/>
- </para>
- <para>For more information on using the JCA adaptor, please see <xref
- linkend="appserver-integration"/>.</para>
- </section>
- <section>
- <title>ActiveMQ stand-alone server</title>
- <para>ActiveMQ can also be deployed as a stand-alone server. This means a fully independent
- messaging server not dependent on a JEE application server.</para>
- <para>The standard stand-alone messaging server configuration comprises a core messaging
- server, a JMS service and a JNDI service.</para>
- <para>The role of the JMS Service is to deploy any JMS Queue, Topic and ConnectionFactory
- instances from any server side <literal>activemq-jms.xml</literal> configuration files.
- It also provides a simple management API for creating and destroying Queues, Topics and
- ConnectionFactory instances which can be accessed via JMX or the connection. It is a
- separate service to the ActiveMQ core server, since the core server is JMS agnostic. If
- you don't want to deploy any JMS Queue, Topic or ConnectionFactory instances via server
- side XML configuration and don't require a JMS management API on the server side then
- you can disable this service.</para>
- <para>We also include a JNDI server since JNDI is a common requirement when using JMS to
- lookup Queues, Topics and ConnectionFactory instances. If you do not require JNDI then
- this service can also be disabled. ActiveMQ allows you to programmatically create JMS and
- core objects directly on the client side as opposed to looking them up from JNDI, so a
- JNDI server is not always a requirement.</para>
- <para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and
- enforce dependencies between the components. JBoss Microcontainer is a very lightweight
- POJO bootstrapper.</para>
- <para>The stand-alone server architecture is shown in figure 3.3 below:</para>
- <para>
- <graphic fileref="images/architecture3.jpg"/>
- </para>
- <para>For more information on server configuration files see <xref
- linkend="server.configuration"/>. $ </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/book.json
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/book.json b/docs/user-manual/en/book.json
new file mode 100644
index 0000000..7469213
--- /dev/null
+++ b/docs/user-manual/en/book.json
@@ -0,0 +1,12 @@
+{
+ "title": "ActiveMQ Documentation",
+ "description": "ActiveMQ User Guide and Reference Documentation",
+ "github": "apache/activemq-6",
+ "githubHost": "https://github.com/",
+
+ "links": {
+ "home": "http://activemq.apache.org/",
+ "issues": "http://activemq.apache.org/",
+ "contribute": "http://activemq.apache.org/contributing.html"
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/client-classpath.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-classpath.md b/docs/user-manual/en/client-classpath.md
new file mode 100644
index 0000000..7142958
--- /dev/null
+++ b/docs/user-manual/en/client-classpath.md
@@ -0,0 +1,32 @@
+The Client Classpath
+====================
+
+ActiveMQ requires several jars on the *Client Classpath* depending on
+whether the client uses ActiveMQ Core API, JMS, and JNDI.
+
+> **Warning**
+>
+> All the jars mentioned here can be found in the `lib` directory of the
+> ActiveMQ distribution. Be sure you only use the jars from the correct
+> version of the release, you *must not* mix and match versions of jars
+> from different ActiveMQ versions. Mixing and matching different jar
+> versions may cause subtle errors and failures to occur.
+
+ActiveMQ Core Client
+====================
+
+If you are using just a pure ActiveMQ Core client (i.e. no JMS) then you
+need `activemq-core-client.jar`, `activemq-commons.jar`, and `netty.jar`
+on your client classpath.
+
+JMS Client
+==========
+
+If you are using JMS on the client side, then you will also need to
+include `activemq-jms-client.jar` and `jboss-jms-api.jar`.
+
+> **Note**
+>
+> `jboss-jms-api.jar` just contains Java EE API interface classes needed
+> for the `javax.jms.*` classes. If you already have a jar with these
+> interface classes on your classpath, you will not need it.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/client-classpath.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-classpath.xml b/docs/user-manual/en/client-classpath.xml
deleted file mode 100644
index 2baafbd..0000000
--- a/docs/user-manual/en/client-classpath.xml
+++ /dev/null
@@ -1,51 +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="client-classpath">
- <title>The Client Classpath</title>
- <para>ActiveMQ requires several jars on the <emphasis>Client Classpath</emphasis> depending on
- whether the client uses ActiveMQ Core API, JMS, and JNDI.</para>
- <warning>
- <para>All the jars mentioned here can be found in the <literal>lib</literal> directory of
- the ActiveMQ distribution. Be sure you only use the jars from the correct version of the
- release, you <emphasis>must not</emphasis> mix and match versions of jars from different
- ActiveMQ versions. Mixing and matching different jar versions may cause subtle errors and
- failures to occur.</para>
- </warning>
- <section>
- <title>ActiveMQ Core Client</title>
- <para>If you are using just a pure ActiveMQ Core client (i.e. no JMS) then you need <literal
- >activemq-core-client.jar</literal>, <literal>activemq-commons.jar</literal>, and
- <literal>netty.jar</literal> on your client classpath.</para>
- </section>
- <section>
- <title>JMS Client</title>
- <para>If you are using JMS on the client side, then you will also need to include <literal
- >activemq-jms-client.jar</literal> and <literal>jboss-jms-api.jar</literal>.</para>
-
- <note>
- <para><literal>jboss-jms-api.jar</literal> just contains Java EE API interface classes
- needed for the <literal>javax.jms.*</literal> classes. If you already have a jar
- with these interface classes on your classpath, you will not need it.</para>
- </note>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/client-reconnection.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-reconnection.md b/docs/user-manual/en/client-reconnection.md
new file mode 100644
index 0000000..4ee441c
--- /dev/null
+++ b/docs/user-manual/en/client-reconnection.md
@@ -0,0 +1,149 @@
+Client Reconnection and Session Reattachment
+============================================
+
+ActiveMQ clients can be configured to automatically reconnect or
+re-attach to the server in the event that a failure is detected in the
+connection between the client and the server.
+
+100% Transparent session re-attachment
+======================================
+
+If the failure was due to some transient failure such as a temporary
+network failure, and the target server was not restarted, then the
+sessions will still be existent on the server, assuming the client
+hasn't been disconnected for more than connection-ttl ?.
+
+In this scenario, ActiveMQ will automatically re-attach the client
+sessions to the server sessions when the connection reconnects. This is
+done 100% transparently and the client can continue exactly as if
+nothing had happened.
+
+The way this works is as follows:
+
+As ActiveMQ clients send commands to their servers they store each sent
+command in an in-memory buffer. In the case that connection failure
+occurs and the client subsequently reattaches to the same server, as
+part of the reattachment protocol the server informs the client during
+reattachment with the id of the last command it successfully received
+from that client.
+
+If the client has sent more commands than were received before failover
+it can replay any sent commands from its buffer so that the client and
+server can reconcile their states.
+
+The size of this buffer is configured by the `ConfirmationWindowSize`
+parameter, when the server has received `ConfirmationWindowSize` bytes
+of commands and processed them it will send back a command confirmation
+to the client, and the client can then free up space in the buffer.
+
+If you are using JMS and you're using the JMS service on the server to
+load your JMS connection factory instances into JNDI then this parameter
+can be configured in `activemq-jms.xml` using the element
+`confirmation-window-size` a. If you're using JMS but not using JNDI
+then you can set these values directly on the
+`ActiveMQConnectionFactory` instance using the appropriate setter
+method.
+
+If you're using the core API you can set these values directly on the
+`ServerLocator` instance using the appropriate setter method.
+
+The window is specified in bytes.
+
+Setting this parameter to `-1` disables any buffering and prevents any
+re-attachment from occurring, forcing reconnect instead. The default
+value for this parameter is `-1`. (Which means by default no auto
+re-attachment will occur)
+
+Session reconnection
+====================
+
+Alternatively, the server might have actually been restarted after
+crashing or being stopped. In this case any sessions will no longer be
+existent on the server and it won't be possible to 100% transparently
+re-attach to them.
+
+In this case, ActiveMQ will automatically reconnect the connection and
+*recreate* any sessions and consumers on the server corresponding to the
+sessions and consumers on the client. This process is exactly the same
+as what happens during failover onto a backup server.
+
+Client reconnection is also used internally by components such as core
+bridges to allow them to reconnect to their target servers.
+
+Please see the section on failover ? to get a full understanding of how
+transacted and non-transacted sessions are reconnected during
+failover/reconnect and what you need to do to maintain *once and only
+once*delivery guarantees.
+
+Configuring reconnection/reattachment attributes
+================================================
+
+Client reconnection is configured using the following parameters:
+
+- `retry-interval`. This optional parameter determines the period in
+ milliseconds between subsequent reconnection attempts, if the
+ connection to the target server has failed. The default value is
+ `2000` milliseconds.
+
+- `retry-interval-multiplier`. This optional parameter determines
+ determines a multiplier to apply to the time since the last retry to
+ compute the time to the next retry.
+
+ This allows you to implement an *exponential backoff* between retry
+ attempts.
+
+ Let's take an example:
+
+ If we set `retry-interval` to `1000` ms and we set
+ `retry-interval-multiplier` to `2.0`, then, if the first reconnect
+ attempt fails, we will wait `1000` ms then `2000` ms then `4000` ms
+ between subsequent reconnection attempts.
+
+ The default value is `1.0` meaning each reconnect attempt is spaced
+ at equal intervals.
+
+- `max-retry-interval`. This optional parameter determines the maximum
+ retry interval that will be used. When setting
+ `retry-interval-multiplier` it would otherwise be possible that
+ subsequent retries exponentially increase to ridiculously large
+ values. By setting this parameter you can set an upper limit on that
+ value. The default value is `2000` milliseconds.
+
+- `reconnect-attempts`. This optional parameter determines the total
+ number of reconnect attempts to make before giving up and shutting
+ down. A value of `-1` signifies an unlimited number of attempts. The
+ default value is `0`.
+
+If you're using JMS and you're using JNDI on the client to look up your
+JMS connection factory instances then you can specify these parameters
+in the JNDI context environment in, e.g. `jndi.properties`:
+
+ java.naming.factory.initial = org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url = tcp://localhost:5445
+ connection.ConnectionFactory.retryInterval=1000
+ connection.ConnectionFactory.retryIntervalMultiplier=1.5
+ connection.ConnectionFactory.maxRetryInterval=60000
+ connection.ConnectionFactory.reconnectAttempts=1000
+
+If you're using JMS, but instantiating your JMS connection factory
+directly, you can specify the parameters using the appropriate setter
+methods on the `ActiveMQConnectionFactory` immediately after creating
+it.
+
+If you're using the core API and instantiating the `ServerLocator`
+instance directly you can also specify the parameters using the
+appropriate setter methods on the `ServerLocator` immediately after
+creating it.
+
+If your client does manage to reconnect but the session is no longer
+available on the server, for instance if the server has been restarted
+or it has timed out, then the client won't be able to re-attach, and any
+`ExceptionListener` or `FailureListener` instances registered on the
+connection or session will be called.
+
+ExceptionListeners and SessionFailureListeners
+==============================================
+
+Please note, that when a client reconnects or re-attaches, any
+registered JMS `ExceptionListener` or core API `SessionFailureListener`
+will be called.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/client-reconnection.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-reconnection.xml b/docs/user-manual/en/client-reconnection.xml
deleted file mode 100644
index 96a4534..0000000
--- a/docs/user-manual/en/client-reconnection.xml
+++ /dev/null
@@ -1,147 +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="client-reconnection">
- <title>Client Reconnection and Session Reattachment</title>
- <para>ActiveMQ clients can be configured to automatically reconnect or re-attach to the server in
- the event that a failure is detected in the connection between the client and the server. </para>
- <section>
- <title>100% Transparent session re-attachment</title>
- <para>If the failure was due to some transient failure such as a temporary network failure,
- and the target server was not restarted, then the sessions will still be existent on the
- server, assuming the client hasn't been disconnected for more than connection-ttl <xref
- linkend="connection-ttl"/>.</para>
- <para>In this scenario, ActiveMQ will automatically re-attach the client sessions to the
- server sessions when the connection reconnects. This is done 100% transparently and the
- client can continue exactly as if nothing had happened.</para>
- <para>The way this works is as follows:</para>
- <para>As ActiveMQ clients send commands to their servers they store each sent command in an
- in-memory buffer. In the case that connection failure occurs and the client subsequently
- reattaches to the same server, as part of the reattachment protocol the server informs
- the client during reattachment with the id of the last command it successfully received
- from that client.</para>
- <para>If the client has sent more commands than were received before failover it can replay
- any sent commands from its buffer so that the client and server can reconcile their
- states.</para>
- <para>The size of this buffer is configured by the <literal>ConfirmationWindowSize</literal>
- parameter, when the server has received <literal>ConfirmationWindowSize</literal> bytes
- of commands and processed them it will send back a command confirmation to the client,
- and the client can then free up space in the buffer.</para>
- <para>If you are using JMS and you're using the JMS service on the server to load your JMS
- connection factory instances into JNDI then this parameter can be configured in <literal
- >activemq-jms.xml</literal> using the element <literal
- >confirmation-window-size</literal> a. If you're using JMS but not using JNDI then
- you can set these values directly on the <literal>ActiveMQConnectionFactory</literal>
- instance using the appropriate setter method.</para>
- <para>If you're using the core API you can set these values directly on the <literal
- >ServerLocator</literal> instance using the appropriate setter method.</para>
- <para>The window is specified in bytes.</para>
- <para>Setting this parameter to <literal>-1</literal> disables any buffering and prevents
- any re-attachment from occurring, forcing reconnect instead. The default value for this
- parameter is <literal>-1</literal>. (Which means by default no auto re-attachment will occur)</para>
- </section>
- <section>
- <title>Session reconnection</title>
- <para>Alternatively, the server might have actually been restarted after crashing or being
- stopped. In this case any sessions will no longer be existent on the server and it won't
- be possible to 100% transparently re-attach to them.</para>
- <para>In this case, ActiveMQ will automatically reconnect the connection and <emphasis
- role="italic">recreate</emphasis> any sessions and consumers on the server
- corresponding to the sessions and consumers on the client. This process is exactly the
- same as what happens during failover onto a backup server.</para>
- <para>Client reconnection is also used internally by components such as core bridges to
- allow them to reconnect to their target servers.</para>
- <para>Please see the section on failover <xref linkend="ha.automatic.failover"/> to get a
- full understanding of how transacted and non-transacted sessions are reconnected during
- failover/reconnect and what you need to do to maintain <emphasis role="italic">once and
- only once </emphasis>delivery guarantees.</para>
- </section>
- <section>
- <title>Configuring reconnection/reattachment attributes</title>
- <para>Client reconnection is configured using the following parameters:</para>
- <itemizedlist>
- <listitem>
- <para><literal>retry-interval</literal>. This optional parameter determines the
- period in milliseconds between subsequent reconnection attempts, if the
- connection to the target server has failed. The default value is <literal
- >2000</literal> milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval-multiplier</literal>. This optional parameter
- determines determines a multiplier to apply to the time since the last retry to
- compute the time to the next retry.</para>
- <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
- between retry attempts.</para>
- <para>Let's take an example:</para>
- <para>If we set <literal>retry-interval</literal> to <literal>1000</literal> ms and
- we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
- then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
- ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
- subsequent reconnection attempts.</para>
- <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
- spaced at equal intervals.</para>
- </listitem>
- <listitem>
- <para><literal>max-retry-interval</literal>. This optional parameter determines the
- maximum retry interval that will be used. When setting <literal
- >retry-interval-multiplier</literal> it would otherwise be possible that
- subsequent retries exponentially increase to ridiculously large values. By
- setting this parameter you can set an upper limit on that value. The default
- value is <literal>2000</literal> milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>reconnect-attempts</literal>. This optional parameter determines the
- total number of reconnect attempts to make before giving up and shutting down. A
- value of <literal>-1</literal> signifies an unlimited number of attempts. The
- default value is <literal>0</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>If you're using JMS and you're using JNDI on the client to look up your JMS
- connection factory instances then you can specify these parameters
- in the JNDI context environment in, e.g. <literal>jndi.properties</literal>:</para>
- <programlisting>
-java.naming.factory.initial = org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url = tcp://localhost:5445
-connection.ConnectionFactory.retryInterval=1000
-connection.ConnectionFactory.retryIntervalMultiplier=1.5
-connection.ConnectionFactory.maxRetryInterval=60000
-connection.ConnectionFactory.reconnectAttempts=1000</programlisting>
- <para>If you're using JMS, but instantiating your JMS connection factory directly, you can
- specify the parameters using the appropriate setter methods on the <literal
- >ActiveMQConnectionFactory</literal> immediately after creating it.</para>
- <para>If you're using the core API and instantiating the <literal
- >ServerLocator</literal> instance directly you can also specify the
- parameters using the appropriate setter methods on the <literal
- >ServerLocator</literal> immediately after creating it.</para>
- <para>If your client does manage to reconnect but the session is no longer available on the
- server, for instance if the server has been restarted or it has timed out, then the
- client won't be able to re-attach, and any <literal>ExceptionListener</literal> or
- <literal>FailureListener</literal> instances registered on the connection or session
- will be called.</para>
- </section>
- <section id="client-reconnection.exceptionlistener">
- <title>ExceptionListeners and SessionFailureListeners</title>
- <para>Please note, that when a client reconnects or re-attaches, any registered JMS <literal
- >ExceptionListener</literal> or core API <literal>SessionFailureListener</literal>
- will be called.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/clusters.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/clusters.md b/docs/user-manual/en/clusters.md
new file mode 100644
index 0000000..6a1786c
--- /dev/null
+++ b/docs/user-manual/en/clusters.md
@@ -0,0 +1,1059 @@
+Clusters
+========
+
+Clusters Overview
+=================
+
+ActiveMQ clusters allow groups of ActiveMQ servers to be grouped
+together in order to share message processing load. Each active node in
+the cluster is an active ActiveMQ server which manages its own messages
+and handles its own connections.
+
+> **Note**
+>
+> The *clustered* parameter is deprecated and no longer needed for
+> setting up a cluster. If your configuration contains this parameter it
+> will be ignored and a message with the ID `HQ221038` will be logged.
+
+The cluster is formed by each node declaring *cluster connections* to
+other nodes in the core configuration file `activemq-configuration.xml`.
+When a node forms a cluster connection to another node, internally it
+creates a *core bridge* (as described in ?) connection between it and
+the other node, this is done transparently behind the scenes - you don't
+have to declare an explicit bridge for each node. These cluster
+connections allow messages to flow between the nodes of the cluster to
+balance load.
+
+Nodes can be connected together to form a cluster in many different
+topologies, we will discuss a couple of the more common topologies later
+in this chapter.
+
+We'll also discuss client side load balancing, where we can balance
+client connections across the nodes of the cluster, and we'll consider
+message redistribution where ActiveMQ will redistribute messages between
+nodes to avoid starvation.
+
+Another important part of clustering is *server discovery* where servers
+can broadcast their connection details so clients or other servers can
+connect to them with the minimum of configuration.
+
+> **Warning**
+>
+> Once a cluster node has been configured it is common to simply copy
+> that configuration to other nodes to produce a symmetric cluster.
+> However, care must be taken when copying the ActiveMQ files. Do not
+> copy the ActiveMQ *data* (i.e. the `bindings`, `journal`, and
+> `large-messages` directories) from one node to another. When a node is
+> started for the first time and initializes its journal files it also
+> persists a special identifier to the `journal` directory. This id
+> *must* be unique among nodes in the cluster or the cluster will not
+> form properly.
+
+Server discovery
+================
+
+Server discovery is a mechanism by which servers can propagate their
+connection details to:
+
+- Messaging clients. A messaging client wants to be able to connect to
+ the servers of the cluster without having specific knowledge of
+ which servers in the cluster are up at any one time.
+
+- Other servers. Servers in a cluster want to be able to create
+ cluster connections to each other without having prior knowledge of
+ all the other servers in the cluster.
+
+This information, let's call it the Cluster Topology, is actually sent
+around normal ActiveMQ connections to clients and to other servers over
+cluster connections. This being the case we need a way of establishing
+the initial first connection. This can be done using dynamic discovery
+techniques like
+[UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) and
+[JGroups](http://www.jgroups.org/), or by providing a list of initial
+connectors.
+
+Dynamic Discovery
+-----------------
+
+Server discovery uses
+[UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) multicast or
+[JGroups](http://www.jgroups.org/) to broadcast server connection
+settings.
+
+### Broadcast Groups
+
+A broadcast group is the means by which a server broadcasts connectors
+over the network. A connector defines a way in which a client (or other
+server) can make connections to the server. For more information on what
+a connector is, please see ?.
+
+The broadcast group takes a set of connector pairs, each connector pair
+contains connection settings for a live and backup server (if one
+exists) and broadcasts them on the network. Depending on which
+broadcasting technique you configure the cluster, it uses either UDP or
+JGroups to broadcast connector pairs information.
+
+Broadcast groups are defined in the server configuration file
+`activemq-configuration.xml`. There can be many broadcast groups per
+ActiveMQ server. All broadcast groups must be defined in a
+`broadcast-groups` element.
+
+Let's take a look at an example broadcast group from
+`activemq-configuration.xml` that defines a UDP broadcast group:
+
+ <broadcast-groups>
+ <broadcast-group name="my-broadcast-group">
+ <local-bind-address>172.16.9.3</local-bind-address>
+ <local-bind-port>5432</local-bind-port>
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <broadcast-period>2000</broadcast-period>
+ <connector-ref connector-name="netty-connector"/>
+ </broadcast-group>
+ </broadcast-groups>
+
+Some of the broadcast group parameters are optional and you'll normally
+use the defaults, but we specify them all in the above example for
+clarity. Let's discuss each one in turn:
+
+- `name` attribute. Each broadcast group in the server must have a
+ unique name.
+
+- `local-bind-address`. This is the local bind address that the
+ datagram socket is bound to. If you have multiple network interfaces
+ on your server, you would specify which one you wish to use for
+ broadcasts by setting this property. If this property is not
+ specified then the socket will be bound to the wildcard address, an
+ IP address chosen by the kernel. This is a UDP specific attribute.
+
+- `local-bind-port`. If you want to specify a local port to which the
+ datagram socket is bound you can specify it here. Normally you would
+ just use the default value of `-1` which signifies that an anonymous
+ port should be used. This parameter is always specified in
+ conjunction with `local-bind-address`. This is a UDP specific
+ attribute.
+
+- `group-address`. This is the multicast address to which the data
+ will be broadcast. It is a class D IP address in the range
+ `224.0.0.0` to `239.255.255.255`, inclusive. The address `224.0.0.0`
+ is reserved and is not available for use. This parameter is
+ mandatory. This is a UDP specific attribute.
+
+- `group-port`. This is the UDP port number used for broadcasting.
+ This parameter is mandatory. This is a UDP specific attribute.
+
+- `broadcast-period`. This is the period in milliseconds between
+ consecutive broadcasts. This parameter is optional, the default
+ value is `2000` milliseconds.
+
+- `connector-ref`. This specifies the connector and optional backup
+ connector that will be broadcasted (see ? for more information on
+ connectors). The connector to be broadcasted is specified by the
+ `connector-name` attribute.
+
+Here is another example broadcast group that defines a JGroups broadcast
+group:
+
+ <broadcast-groups>
+ <broadcast-group name="my-broadcast-group">
+ <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
+ <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
+ <broadcast-period>2000</broadcast-period>
+ <connector-ref connector-name="netty-connector"/>
+ </broadcast-group>
+ </broadcast-groups>
+
+To be able to use JGroups to broadcast, one must specify two attributes,
+i.e. `jgroups-file` and `jgroups-channel`, as discussed in details as
+following:
+
+- `jgroups-file` attribute. This is the name of JGroups configuration
+ file. It will be used to initialize JGroups channels. Make sure the
+ file is in the java resource path so that ActiveMQ can load it.
+
+- `jgroups-channel` attribute. The name that JGroups channels connect
+ to for broadcasting.
+
+> **Note**
+>
+> The JGroups attributes (`jgroups-file` and `jgroups-channel`) and UDP
+> specific attributes described above are exclusive of each other. Only
+> one set can be specified in a broadcast group configuration. Don't mix
+> them!
+
+The following is an example of a JGroups file
+
+ <config xmlns="urn:org:jgroups"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/JGroups-3.0.xsd">
+ <TCP loopback="true"
+ recv_buf_size="20000000"
+ send_buf_size="640000"
+ discard_incompatible_packets="true"
+ max_bundle_size="64000"
+ max_bundle_timeout="30"
+ enable_bundling="true"
+ use_send_queues="false"
+ sock_conn_timeout="300"
+
+ thread_pool.enabled="true"
+ thread_pool.min_threads="1"
+ thread_pool.max_threads="10"
+ thread_pool.keep_alive_time="5000"
+ thread_pool.queue_enabled="false"
+ thread_pool.queue_max_size="100"
+ thread_pool.rejection_policy="run"
+
+ oob_thread_pool.enabled="true"
+ oob_thread_pool.min_threads="1"
+ oob_thread_pool.max_threads="8"
+ oob_thread_pool.keep_alive_time="5000"
+ oob_thread_pool.queue_enabled="false"
+ oob_thread_pool.queue_max_size="100"
+ oob_thread_pool.rejection_policy="run"/>
+
+ <FILE_PING location="../file.ping.dir"/>
+ <MERGE2 max_interval="30000"
+ min_interval="10000"/>
+ <FD_SOCK/>
+ <FD timeout="10000" max_tries="5" />
+ <VERIFY_SUSPECT timeout="1500" />
+ <BARRIER />
+ <pbcast.NAKACK
+ use_mcast_xmit="false"
+ retransmit_timeout="300,600,1200,2400,4800"
+ discard_delivered_msgs="true"/>
+ <UNICAST timeout="300,600,1200" />
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
+ max_bytes="400000"/>
+ <pbcast.GMS print_local_addr="true" join_timeout="3000"
+ view_bundling="true"/>
+ <FC max_credits="2000000"
+ min_threshold="0.10"/>
+ <FRAG2 frag_size="60000" />
+ <pbcast.STATE_TRANSFER/>
+ <pbcast.FLUSH timeout="0"/>
+ </config>
+
+As it shows, the file content defines a jgroups protocol stacks. If you
+want activemq to use this stacks for channel creation, you have to make
+sure the value of `jgroups-file` in your broadcast-group/discovery-group
+configuration to be the name of this jgroups configuration file. For
+example if the above stacks configuration is stored in a file named
+"jgroups-stacks.xml" then your `jgroups-file` should be like
+
+ <jgroups-file>jgroups-stacks.xml</jgroups-file>
+
+### Discovery Groups
+
+While the broadcast group defines how connector information is
+broadcasted from a server, a discovery group defines how connector
+information is received from a broadcast endpoint (a UDP multicast
+address or JGroup channel).
+
+A discovery group maintains a list of connector pairs - one for each
+broadcast by a different server. As it receives broadcasts on the
+broadcast endpoint from a particular server it updates its entry in the
+list for that server.
+
+If it has not received a broadcast from a particular server for a length
+of time it will remove that server's entry from its list.
+
+Discovery groups are used in two places in ActiveMQ:
+
+- By cluster connections so they know how to obtain an initial
+ connection to download the topology
+
+- By messaging clients so they know how to obtain an initial
+ connection to download the topology
+
+Although a discovery group will always accept broadcasts, its current
+list of available live and backup servers is only ever used when an
+initial connection is made, from then server discovery is done over the
+normal ActiveMQ connections.
+
+> **Note**
+>
+> Each discovery group must be configured with broadcast endpoint (UDP
+> or JGroups) that matches its broadcast group counterpart. For example,
+> if broadcast is configured using UDP, the discovery group must also
+> use UDP, and the same multicast address.
+
+### Defining Discovery Groups on the Server
+
+For cluster connections, discovery groups are defined in the server side
+configuration file `activemq-configuration.xml`. All discovery groups
+must be defined inside a `discovery-groups` element. There can be many
+discovery groups defined by ActiveMQ server. Let's look at an example:
+
+ <discovery-groups>
+ <discovery-group name="my-discovery-group">
+ <local-bind-address>172.16.9.7</local-bind-address>
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <refresh-timeout>10000</refresh-timeout>
+ </discovery-group>
+ </discovery-groups>
+
+We'll consider each parameter of the discovery group:
+
+- `name` attribute. Each discovery group must have a unique name per
+ server.
+
+- `local-bind-address`. If you are running with multiple network
+ interfaces on the same machine, you may want to specify that the
+ discovery group listens only only a specific interface. To do this
+ you can specify the interface address with this parameter. This
+ parameter is optional. This is a UDP specific attribute.
+
+- `group-address`. This is the multicast IP address of the group to
+ listen on. It should match the `group-address` in the broadcast
+ group that you wish to listen from. This parameter is mandatory.
+ This is a UDP specific attribute.
+
+- `group-port`. This is the UDP port of the multicast group. It should
+ match the `group-port` in the broadcast group that you wish to
+ listen from. This parameter is mandatory. This is a UDP specific
+ attribute.
+
+- `refresh-timeout`. This is the period the discovery group waits
+ after receiving the last broadcast from a particular server before
+ removing that servers connector pair entry from its list. You would
+ normally set this to a value significantly higher than the
+ `broadcast-period` on the broadcast group otherwise servers might
+ intermittently disappear from the list even though they are still
+ broadcasting due to slight differences in timing. This parameter is
+ optional, the default value is `10000` milliseconds (10 seconds).
+
+Here is another example that defines a JGroups discovery group:
+
+ <discovery-groups>
+ <discovery-group name="my-broadcast-group">
+ <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
+ <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
+ <refresh-timeout>10000</refresh-timeout>
+ </discovery-group>
+ </discovery-groups>
+
+To receive broadcast from JGroups channels, one must specify two
+attributes, `jgroups-file` and `jgroups-channel`, as discussed in
+details as following:
+
+- `jgroups-file` attribute. This is the name of JGroups configuration
+ file. It will be used to initialize JGroups channels. Make sure the
+ file is in the java resource path so that ActiveMQ can load it.
+
+- `jgroups-channel` attribute. The name that JGroups channels connect
+ to for receiving broadcasts.
+
+> **Note**
+>
+> The JGroups attributes (`jgroups-file` and `jgroups-channel`) and UDP
+> specific attributes described above are exclusive of each other. Only
+> one set can be specified in a discovery group configuration. Don't mix
+> them!
+
+### Discovery Groups on the Client Side
+
+Let's discuss how to configure a ActiveMQ client to use discovery to
+discover a list of servers to which it can connect. The way to do this
+differs depending on whether you're using JMS or the core API.
+
+#### Configuring client discovery using JMS
+
+If you're using JMS and you're using JNDI on the client to look up your
+JMS connection factory instances then you can specify these parameters
+in the JNDI context environment. e.g. in `jndi.properties`. Simply
+ensure the host:port combination matches the group-address and
+group-port from the corresponding `broadcast-group` on the server. Let's
+take a look at an example:
+
+ java.naming.factory.initial = org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url = udp://231.7.7.7:9876
+
+The element `discovery-group-ref` specifies the name of a discovery
+group defined in `activemq-configuration.xml`.
+
+When this connection factory is downloaded from JNDI by a client
+application and JMS connections are created from it, those connections
+will be load-balanced across the list of servers that the discovery
+group maintains by listening on the multicast address specified in the
+discovery group configuration.
+
+If you're using JMS, but you're not using JNDI to lookup a connection
+factory - you're instantiating the JMS connection factory directly then
+you can specify the discovery group parameters directly when creating
+the JMS connection factory. Here's an example:
+
+ final String groupAddress = "231.7.7.7";
+
+ final int groupPort = 9876;
+
+ ConnectionFactory jmsConnectionFactory =
+ ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
+ new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF);
+
+ Connection jmsConnection1 = jmsConnectionFactory.createConnection();
+
+ Connection jmsConnection2 = jmsConnectionFactory.createConnection();
+
+The `refresh-timeout` can be set directly on the
+DiscoveryGroupConfiguration by using the setter method
+`setDiscoveryRefreshTimeout()` if you want to change the default value.
+
+There is also a further parameter settable on the
+DiscoveryGroupConfiguration using the setter method
+`setDiscoveryInitialWaitTimeout()`. If the connection factory is used
+immediately after creation then it may not have had enough time to
+received broadcasts from all the nodes in the cluster. On first usage,
+the connection factory will make sure it waits this long since creation
+before creating the first connection. The default value for this
+parameter is `10000` milliseconds.
+
+#### Configuring client discovery using Core
+
+If you're using the core API to directly instantiate
+`ClientSessionFactory` instances, then you can specify the discovery
+group parameters directly when creating the session factory. Here's an
+example:
+
+ final String groupAddress = "231.7.7.7";
+ final int groupPort = 9876;
+ ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
+ new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
+ ClientSessionFactory factory = locator.createSessionFactory();
+ ClientSession session1 = factory.createSession();
+ ClientSession session2 = factory.createSession();
+
+The `refresh-timeout` can be set directly on the
+DiscoveryGroupConfiguration by using the setter method
+`setDiscoveryRefreshTimeout()` if you want to change the default value.
+
+There is also a further parameter settable on the
+DiscoveryGroupConfiguration using the setter method
+`setDiscoveryInitialWaitTimeout()`. If the session factory is used
+immediately after creation then it may not have had enough time to
+received broadcasts from all the nodes in the cluster. On first usage,
+the session factory will make sure it waits this long since creation
+before creating the first session. The default value for this parameter
+is `10000` milliseconds.
+
+Discovery using static Connectors
+---------------------------------
+
+Sometimes it may be impossible to use UDP on the network you are using.
+In this case its possible to configure a connection with an initial list
+if possible servers. This could be just one server that you know will
+always be available or a list of servers where at least one will be
+available.
+
+This doesn't mean that you have to know where all your servers are going
+to be hosted, you can configure these servers to use the reliable
+servers to connect to. Once they are connected there connection details
+will be propagated via the server it connects to
+
+### Configuring a Cluster Connection
+
+For cluster connections there is no extra configuration needed, you just
+need to make sure that any connectors are defined in the usual manner,
+(see ? for more information on connectors). These are then referenced by
+the cluster connection configuration.
+
+### Configuring a Client Connection
+
+A static list of possible servers can also be used by a normal client.
+
+#### Configuring client discovery using JMS
+
+If you're using JMS and you're using JNDI on the client to look up your
+JMS connection factory instances then you can specify these parameters
+in the JNDI context environment in, e.g. `jndi.properties`:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445,myhost2:5445
+
+The `java.naming.provider.url` contains a list of servers to use for the
+connection factory. When this connection factory used client application
+and JMS connections are created from it, those connections will be
+load-balanced across the list of servers defined by the
+`java.naming.provider.url`.
+
+If you're using JMS, but you're not using JNDI to lookup a connection
+factory - you're instantiating the JMS connection factory directly then
+you can specify the connector list directly when creating the JMS
+connection factory. Here's an example:
+
+ HashMap<String, Object> map = new HashMap<String, Object>();
+ map.put("host", "myhost");
+ map.put("port", "5445");
+ TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
+ HashMap<String, Object> map2 = new HashMap<String, Object>();
+ map2.put("host", "myhost2");
+ map2.put("port", "5446");
+ TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
+
+ ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);
+
+#### Configuring client discovery using Core
+
+If you are using the core API then the same can be done as follows:
+
+ HashMap<String, Object> map = new HashMap<String, Object>();
+ map.put("host", "myhost");
+ map.put("port", "5445");
+ TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
+ HashMap<String, Object> map2 = new HashMap<String, Object>();
+ map2.put("host", "myhost2");
+ map2.put("port", "5446");
+ TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
+ ClientSessionFactory factory = locator.createSessionFactory();
+ ClientSession session = factory.createSession();
+
+Server-Side Message Load Balancing
+==================================
+
+If cluster connections are defined between nodes of a cluster, then
+ActiveMQ will load balance messages arriving at a particular node from a
+client.
+
+Let's take a simple example of a cluster of four nodes A, B, C, and D
+arranged in a *symmetric cluster* (described in ?). We have a queue
+called `OrderQueue` deployed on each node of the cluster.
+
+We have client Ca connected to node A, sending orders to the server. We
+have also have order processor clients Pa, Pb, Pc, and Pd connected to
+each of the nodes A, B, C, D. If no cluster connection was defined on
+node A, then as order messages arrive on node A they will all end up in
+the `OrderQueue` on node A, so will only get consumed by the order
+processor client attached to node A, Pa.
+
+If we define a cluster connection on node A, then as ordered messages
+arrive on node A instead of all of them going into the local
+`OrderQueue` instance, they are distributed in a round-robin fashion
+between all the nodes of the cluster. The messages are forwarded from
+the receiving node to other nodes of the cluster. This is all done on
+the server side, the client maintains a single connection to node A.
+
+For example, messages arriving on node A might be distributed in the
+following order between the nodes: B, D, C, A, B, D, C, A, B, D. The
+exact order depends on the order the nodes started up, but the algorithm
+used is round robin.
+
+ActiveMQ cluster connections can be configured to always blindly load
+balance messages in a round robin fashion irrespective of whether there
+are any matching consumers on other nodes, but they can be a bit
+cleverer than that and also be configured to only distribute to other
+nodes if they have matching consumers. We'll look at both these cases in
+turn with some examples, but first we'll discuss configuring cluster
+connections in general.
+
+Configuring Cluster Connections
+-------------------------------
+
+Cluster connections group servers into clusters so that messages can be
+load balanced between the nodes of the cluster. Let's take a look at a
+typical cluster connection. Cluster connections are always defined in
+`activemq-configuration.xml` inside a `cluster-connection` element.
+There can be zero or more cluster connections defined per ActiveMQ
+server.
+
+ <cluster-connections>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <connector-ref>netty-connector</connector-ref>
+ <check-period>1000</check-period>
+ <connection-ttl>5000</connection-ttl>
+ <min-large-message-size>50000</min-large-message-size>
+ <call-timeout>5000</call-timeout>
+ <retry-interval>500</retry-interval>
+ <retry-interval-multiplier>1.0</retry-interval-multiplier>
+ <max-retry-interval>5000</max-retry-interval>
+ <initial-connect-attempts>-1</initial-connect-attempts>
+ <reconnect-attempts>-1</reconnect-attempts>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>false</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <confirmation-window-size>32000</confirmation-window-size>
+ <call-failover-timeout>30000</call-failover-timeout>
+ <notification-interval>1000</notification-interval>
+ <notification-attempts>2</notification-attempts>
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ </cluster-connection>
+ </cluster-connections>
+
+In the above cluster connection all parameters have been explicitly
+specified. The following shows all the available configuration options
+
+- `address` Each cluster connection only applies to addresses that
+ match the specified address field. An address is matched on the
+ cluster connection when it begins with the string specified in this
+ field. The address field on a cluster connection also supports comma
+ separated lists and an exclude syntax '!'. To prevent an address
+ from being matched on this cluster connection, prepend a cluster
+ connection address string with '!'.
+
+ In the case shown above the cluster connection will load balance
+ messages sent to addresses that start with `jms`. This cluster
+ connection, will, in effect apply to all JMS queues and topics since
+ they map to core queues that start with the substring "jms".
+
+ The address can be any value and you can have many cluster
+ connections with different values of `address`, simultaneously
+ balancing messages for those addresses, potentially to different
+ clusters of servers. By having multiple cluster connections on
+ different addresses a single ActiveMQ Server can effectively take
+ part in multiple clusters simultaneously.
+
+ Be careful not to have multiple cluster connections with overlapping
+ values of `address`, e.g. "europe" and "europe.news" since this
+ could result in the same messages being distributed between more
+ than one cluster connection, possibly resulting in duplicate
+ deliveries.
+
+ Examples:
+
+ - 'jms.eu'
+ matches all addresses starting with 'jms.eu'
+ - '!jms.eu'
+ matches all address except for those starting with 'jms.eu'
+ - 'jms.eu.uk,jms.eu.de'
+ matches all addresses starting with either 'jms.eu.uk' or
+ 'jms.eu.de'
+ - 'jms.eu,!jms.eu.uk'
+ matches all addresses starting with 'jms.eu' but not those
+ starting with 'jms.eu.uk'
+
+ Notes:
+
+ - Address exclusion will always takes precedence over address
+ inclusion.
+ - Address matching on cluster connections does not support
+ wild-card matching.
+
+ This parameter is mandatory.
+
+- `connector-ref`. This is the connector which will be sent to other
+ nodes in the cluster so they have the correct cluster topology.
+
+ This parameter is mandatory.
+
+- `check-period`. The period (in milliseconds) used to check if the
+ cluster connection has failed to receive pings from another server.
+ Default is 30000.
+
+- `connection-ttl`. This is how long a cluster connection should stay
+ alive if it stops receiving messages from a specific node in the
+ cluster. Default is 60000.
+
+- `min-large-message-size`. If the message size (in bytes) is larger
+ than this value then it will be split into multiple segments when
+ sent over the network to other cluster members. Default is 102400.
+
+- `call-timeout`. When a packet is sent via a cluster connection and
+ is a blocking call, i.e. for acknowledgements, this is how long it
+ will wait (in milliseconds) for the reply before throwing an
+ exception. Default is 30000.
+
+- `retry-interval`. We mentioned before that, internally, cluster
+ connections cause bridges to be created between the nodes of the
+ cluster. If the cluster connection is created and the target node
+ has not been started, or say, is being rebooted, then the cluster
+ connections from other nodes will retry connecting to the target
+ until it comes back up, in the same way as a bridge does.
+
+ This parameter determines the interval in milliseconds between retry
+ attempts. It has the same meaning as the `retry-interval` on a
+ bridge (as described in ?).
+
+ This parameter is optional and its default value is `500`
+ milliseconds.
+
+- `retry-interval-multiplier`. This is a multiplier used to increase
+ the `retry-interval` after each reconnect attempt, default is 1.
+
+- `max-retry-interval`. The maximum delay (in milliseconds) for
+ retries. Default is 2000.
+
+- `initial-connect-attempts`. The number of times the system will try
+ to connect a node in the cluster initially. If the max-retry is
+ achieved this node will be considered permanently down and the
+ system will not route messages to this node. Default is -1 (infinite
+ retries).
+
+- `reconnect-attempts`. The number of times the system will try to
+ reconnect to a node in the cluster. If the max-retry is achieved
+ this node will be considered permanently down and the system will
+ stop routing messages to this node. Default is -1 (infinite
+ retries).
+
+- `use-duplicate-detection`. Internally cluster connections use
+ bridges to link the nodes, and bridges can be configured to add a
+ duplicate id property in each message that is forwarded. If the
+ target node of the bridge crashes and then recovers, messages might
+ be resent from the source node. By enabling duplicate detection any
+ duplicate messages will be filtered out and ignored on receipt at
+ the target node.
+
+ This parameter has the same meaning as `use-duplicate-detection` on
+ a bridge. For more information on duplicate detection, please see ?.
+ Default is true.
+
+- `forward-when-no-consumers`. This parameter determines whether
+ messages will be distributed round robin between other nodes of the
+ cluster *regardless* of whether or not there are matching or indeed
+ any consumers on other nodes.
+
+ If this is set to `true` then each incoming message will be round
+ robin'd even though the same queues on the other nodes of the
+ cluster may have no consumers at all, or they may have consumers
+ that have non matching message filters (selectors). Note that
+ ActiveMQ will *not* forward messages to other nodes if there are no
+ *queues* of the same name on the other nodes, even if this parameter
+ is set to `true`.
+
+ If this is set to `false` then ActiveMQ will only forward messages
+ to other nodes of the cluster if the address to which they are being
+ forwarded has queues which have consumers, and if those consumers
+ have message filters (selectors) at least one of those selectors
+ must match the message.
+
+ Default is false.
+
+- `max-hops`. When a cluster connection decides the set of nodes to
+ which it might load balance a message, those nodes do not have to be
+ directly connected to it via a cluster connection. ActiveMQ can be
+ configured to also load balance messages to nodes which might be
+ connected to it only indirectly with other ActiveMQ servers as
+ intermediates in a chain.
+
+ This allows ActiveMQ to be configured in more complex topologies and
+ still provide message load balancing. We'll discuss this more later
+ in this chapter.
+
+ The default value for this parameter is `1`, which means messages
+ are only load balanced to other ActiveMQ serves which are directly
+ connected to this server. This parameter is optional.
+
+- `confirmation-window-size`. The size (in bytes) of the window used
+ for sending confirmations from the server connected to. So once the
+ server has received `confirmation-window-size` bytes it notifies its
+ client, default is 1048576. A value of -1 means no window.
+
+- `call-failover-timeout`. Similar to `call-timeout` but used when a
+ call is made during a failover attempt. Default is -1 (no timeout).
+
+- `notification-interval`. How often (in milliseconds) the cluster
+ connection should broadcast itself when attaching to the cluster.
+ Default is 1000.
+
+- `notification-attempts`. How many times the cluster connection
+ should broadcast itself when connecting to the cluster. Default is
+ 2.
+
+- `discovery-group-ref`. This parameter determines which discovery
+ group is used to obtain the list of other servers in the cluster
+ that this cluster connection will make connections to.
+
+Alternatively if you would like your cluster connections to use a static
+list of servers for discovery then you can do it like this.
+
+ <cluster-connection name="my-cluster">
+ ...
+ <static-connectors>
+ <connector-ref>server0-connector</connector-ref>
+ <connector-ref>server1-connector</connector-ref>
+ </static-connectors>
+ </cluster-connection>
+
+Here we have defined 2 servers that we know for sure will that at least
+one will be available. There may be many more servers in the cluster but
+these will; be discovered via one of these connectors once an initial
+connection has been made.
+
+Cluster User Credentials
+------------------------
+
+When creating connections between nodes of a cluster to form a cluster
+connection, ActiveMQ uses a cluster user and cluster password which is
+defined in `activemq-configuration.xml`:
+
+ <cluster-user>ACTIVEMQ.CLUSTER.ADMIN.USER</cluster-user>
+ <cluster-password>CHANGE ME!!</cluster-password>
+
+> **Warning**
+>
+> It is imperative that these values are changed from their default, or
+> remote clients will be able to make connections to the server using
+> the default values. If they are not changed from the default, ActiveMQ
+> will detect this and pester you with a warning on every start-up.
+
+Client-Side Load balancing
+==========================
+
+With ActiveMQ client-side load balancing, subsequent sessions created
+using a single session factory can be connected to different nodes of
+the cluster. This allows sessions to spread smoothly across the nodes of
+a cluster and not be "clumped" on any particular node.
+
+The load balancing policy to be used by the client factory is
+configurable. ActiveMQ provides four out-of-the-box load balancing
+policies, and you can also implement your own and use that.
+
+The out-of-the-box policies are
+
+- Round Robin. With this policy the first node is chosen randomly then
+ each subsequent node is chosen sequentially in the same order.
+
+ For example nodes might be chosen in the order B, C, D, A, B, C, D,
+ A, B or D, A, B, C, D, A, B, C, D or C, D, A, B, C, D, A, B, C.
+
+ Use
+ `org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy`
+ as the `<connection-load-balancing-policy-class-name>`.
+
+- Random. With this policy each node is chosen randomly.
+
+ Use
+ `org.apache.activemq.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy`
+ as the `<connection-load-balancing-policy-class-name>`.
+
+- Random Sticky. With this policy the first node is chosen randomly
+ and then re-used for subsequent connections.
+
+ Use
+ `org.apache.activemq.api.core.client.loadbalance.RandomStickyConnectionLoadBalancingPolicy`
+ as the `<connection-load-balancing-policy-class-name>`.
+
+- First Element. With this policy the "first" (i.e. 0th) node is
+ always returned.
+
+ Use
+ `org.apache.activemq.api.core.client.loadbalance.FirstElementConnectionLoadBalancingPolicy`
+ as the `<connection-load-balancing-policy-class-name>`.
+
+You can also implement your own policy by implementing the interface
+`org.apache.activemq.api.core.client.loadbalance.ConnectionLoadBalancingPolicy`
+
+Specifying which load balancing policy to use differs whether you are
+using JMS or the core API. If you don't specify a policy then the
+default will be used which is
+`org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy`.
+
+If you're using JMS and you're using JNDI on the client to look up your
+JMS connection factory instances then you can specify these parameters
+in the JNDI context environment in, e.g. `jndi.properties`, to specify
+the load balancing policy directly:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.loadBalancingPolicyClassName=org.apache.activemq.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy
+
+The above example would instantiate a JMS connection factory that uses
+the random connection load balancing policy.
+
+If you're using JMS but you're instantiating your connection factory
+directly on the client side then you can set the load balancing policy
+using the setter on the `ActiveMQConnectionFactory` before using it:
+
+ ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
+ jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+
+If you're using the core API, you can set the load balancing policy
+directly on the `ServerLocator` instance you are using:
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
+ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+
+The set of servers over which the factory load balances can be
+determined in one of two ways:
+
+- Specifying servers explicitly
+
+- Using discovery.
+
+Specifying Members of a Cluster Explicitly
+==========================================
+
+Sometimes you want to explicitly define a cluster more explicitly, that
+is control which server connect to each other in the cluster. This is
+typically used to form non symmetrical clusters such as chain cluster or
+ring clusters. This can only be done using a static list of connectors
+and is configured as follows:
+
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <connector-ref>netty-connector</connector-ref>
+ <retry-interval>500</retry-interval>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>true</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <static-connectors allow-direct-connections-only="true">
+ <connector-ref>server1-connector</connector-ref>
+ </static-connectors>
+ </cluster-connection>
+
+In this example we have set the attribute
+`allow-direct-connections-only` which means that the only server that
+this server can create a cluster connection to is server1-connector.
+This means you can explicitly create any cluster topology you want.
+
+Message Redistribution
+======================
+
+Another important part of clustering is message redistribution. Earlier
+we learned how server side message load balancing round robins messages
+across the cluster. If `forward-when-no-consumers` is false, then
+messages won't be forwarded to nodes which don't have matching
+consumers, this is great and ensures that messages don't arrive on a
+queue which has no consumers to consume them, however there is a
+situation it doesn't solve: What happens if the consumers on a queue
+close after the messages have been sent to the node? If there are no
+consumers on the queue the message won't get consumed and we have a
+*starvation* situation.
+
+This is where message redistribution comes in. With message
+redistribution ActiveMQ can be configured to automatically
+*redistribute* messages from queues which have no consumers back to
+other nodes in the cluster which do have matching consumers.
+
+Message redistribution can be configured to kick in immediately after
+the last consumer on a queue is closed, or to wait a configurable delay
+after the last consumer on a queue is closed before redistributing. By
+default message redistribution is disabled.
+
+Message redistribution can be configured on a per address basis, by
+specifying the redistribution delay in the address settings, for more
+information on configuring address settings, please see ?.
+
+Here's an address settings snippet from `activemq-configuration.xml`
+showing how message redistribution is enabled for a set of queues:
+
+ <address-settings>
+ <address-setting match="jms.#">
+ <redistribution-delay>0</redistribution-delay>
+ </address-setting>
+ </address-settings>
+
+The above `address-settings` block would set a `redistribution-delay` of
+`0` for any queue which is bound to an address that starts with "jms.".
+All JMS queues and topic subscriptions are bound to addresses that start
+with "jms.", so the above would enable instant (no delay) redistribution
+for all JMS queues and topic subscriptions.
+
+The attribute `match` can be an exact match or it can be a string that
+conforms to the ActiveMQ wildcard syntax (described in ?).
+
+The element `redistribution-delay` defines the delay in milliseconds
+after the last consumer is closed on a queue before redistributing
+messages from that queue to other nodes of the cluster which do have
+matching consumers. A delay of zero means the messages will be
+immediately redistributed. A value of `-1` signifies that messages will
+never be redistributed. The default value is `-1`.
+
+It often makes sense to introduce a delay before redistributing as it's
+a common case that a consumer closes but another one quickly is created
+on the same queue, in such a case you probably don't want to
+redistribute immediately since the new consumer will arrive shortly.
+
+Cluster topologies
+==================
+
+ActiveMQ clusters can be connected together in many different
+topologies, let's consider the two most common ones here
+
+Symmetric cluster
+-----------------
+
+A symmetric cluster is probably the most common cluster topology, and
+you'll be familiar with if you've had experience of JBoss Application
+Server clustering.
+
+With a symmetric cluster every node in the cluster is connected to every
+other node in the cluster. In other words every node in the cluster is
+no more than one hop away from every other node.
+
+To form a symmetric cluster every node in the cluster defines a cluster
+connection with the attribute `max-hops` set to `1`. Typically the
+cluster connection will use server discovery in order to know what other
+servers in the cluster it should connect to, although it is possible to
+explicitly define each target server too in the cluster connection if,
+for example, UDP is not available on your network.
+
+With a symmetric cluster each node knows about all the queues that exist
+on all the other nodes and what consumers they have. With this knowledge
+it can determine how to load balance and redistribute messages around
+the nodes.
+
+Don't forget [this warning](#copy-warning) when creating a symmetric
+cluster.
+
+Chain cluster
+-------------
+
+With a chain cluster, each node in the cluster is not connected to every
+node in the cluster directly, instead the nodes form a chain with a node
+on each end of the chain and all other nodes just connecting to the
+previous and next nodes in the chain.
+
+An example of this would be a three node chain consisting of nodes A, B
+and C. Node A is hosted in one network and has many producer clients
+connected to it sending order messages. Due to corporate policy, the
+order consumer clients need to be hosted in a different network, and
+that network is only accessible via a third network. In this setup node
+B acts as a mediator with no producers or consumers on it. Any messages
+arriving on node A will be forwarded to node B, which will in turn
+forward them to node C where they can get consumed. Node A does not need
+to directly connect to C, but all the nodes can still act as a part of
+the cluster.
+
+To set up a cluster in this way, node A would define a cluster
+connection that connects to node B, and node B would define a cluster
+connection that connects to node C. In this case we only want cluster
+connections in one direction since we're only moving messages from node
+A-\>B-\>C and never from C-\>B-\>A.
+
+For this topology we would set `max-hops` to `2`. With a value of `2`
+the knowledge of what queues and consumers that exist on node C would be
+propagated from node C to node B to node A. Node A would then know to
+distribute messages to node B when they arrive, even though node B has
+no consumers itself, it would know that a further hop away is node C
+which does have consumers.
+
+Scaling Down
+============
+
+ActiveMQ supports scaling down a cluster with no message loss (even for
+non-durable messages). This is especially useful in certain environments
+(e.g. the cloud) where the size of a cluster may change relatively
+frequently. When scaling up a cluster (i.e. adding nodes) there is no
+risk of message loss, but when scaling down a cluster (i.e. removing
+nodes) the messages on those nodes would be lost unless the broker sent
+them to another node in the cluster. ActiveMQ can be configured to do
+just that.
+
+The simplest way to enable this behavior is to set `scale-down` to
+`true`. If the server is clustered and `scale-down` is `true` then when
+the server is shutdown gracefully (i.e. stopped without crashing) it
+will find another node in the cluster and send *all* of its messages
+(both durable and non-durable) to that node. The messages are processed
+in order and go to the *back* of the respective queues on the other node
+(just as if the messages were sent from an external client for the first
+time).
+
+If more control over where the messages go is required then specify
+`scale-down-group-name`. Messages will only be sent to another node in
+the cluster that uses the same `scale-down-group-name` as the server
+being shutdown.
+
+> **Warning**
+>
+> If cluster nodes are grouped together with different
+> `scale-down-group-name` values beware. If all the nodes in a single
+> group are shut down then the messages from that node/group will be
+> lost.
+
+If the server is using multiple `cluster-connection` then use
+`scale-down-clustername` to identify the name of the
+`cluster-connection` which should be used for scaling down.
[14/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/filter-expressions.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/filter-expressions.xml b/docs/user-manual/en/filter-expressions.xml
deleted file mode 100644
index b841ecb..0000000
--- a/docs/user-manual/en/filter-expressions.xml
+++ /dev/null
@@ -1,86 +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="filter-expressions">
- <title>Filter Expressions</title>
- <para>ActiveMQ provides a powerful filter language based on a subset of the SQL 92
- expression syntax.</para>
- <para>It is the same as the syntax used for JMS selectors, but the predefined identifiers are
- different. For documentation on JMS selector syntax please the JMS javadoc for <ulink
- url="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html"
- >javax.jms.Message</ulink>.</para>
- <para>Filter expressions are used in several places in ActiveMQ</para>
- <itemizedlist>
- <listitem>
- <para>Predefined Queues. When pre-defining a queue, either in <literal
- >activemq-configuration.xml</literal> or <literal>activemq-jms.xml</literal> a filter
- expression can be defined for a queue. Only messages that match the filter
- expression will enter the queue.</para>
- </listitem>
- <listitem>
- <para>Core bridges can be defined with an optional filter expression, only matching
- messages will be bridged (see <xref linkend="core-bridges"/>).</para>
- </listitem>
- <listitem>
- <para>Diverts can be defined with an optional filter expression, only matching messages
- will be diverted (see <xref linkend="diverts" />).</para>
- </listitem>
- <listitem>
- <para>Filter are also used programmatically when creating consumers, queues and in
- several places as described in <xref linkend="management"/>.</para>
- </listitem>
- </itemizedlist>
- <para>There are some differences between JMS selector expressions and ActiveMQ core
- filter expressions. Whereas JMS selector expressions operate on a JMS message, ActiveMQ
- core filter expressions operate on a core message.</para>
- <para>The following identifiers can be used in a core filter expressions to refer to attributes
- of the core message in an expression:</para>
- <itemizedlist>
- <listitem>
- <para><literal>HQPriority</literal>. To refer to the priority of a message. Message
- priorities are integers with valid values from <literal>0 - 9</literal>. <literal
- >0</literal> is the lowest priority and <literal>9</literal> is the highest.
- E.g. <literal>HQPriority = 3 AND animal = 'aardvark'</literal></para>
- </listitem>
- <listitem>
- <para><literal>HQExpiration</literal>. To refer to the expiration time of a message.
- The value is a long integer.</para>
- </listitem>
- <listitem>
- <para><literal>HQDurable</literal>. To refer to whether a message is durable or not.
- The value is a string with valid values: <literal>DURABLE</literal> or <literal
- >NON_DURABLE</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>HQTimestamp</literal>. The timestamp of when the message was created.
- The value is a long integer.</para>
- </listitem>
- <listitem>
- <para><literal>HQSize</literal>. The size of a message in bytes. The value is an
- integer.</para>
- </listitem>
- </itemizedlist>
- <para>Any other identifiers used in core filter expressions will be assumed to be properties of
- the message.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/flow-control.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/flow-control.md b/docs/user-manual/en/flow-control.md
new file mode 100644
index 0000000..bdaac25
--- /dev/null
+++ b/docs/user-manual/en/flow-control.md
@@ -0,0 +1,304 @@
+Flow Control
+============
+
+Flow control is used to limit the flow of data between a client and
+server, or a server and another server in order to prevent the client or
+server being overwhelmed with data.
+
+Consumer Flow Control
+=====================
+
+This controls the flow of data between the server and the client as the
+client consumes messages. For performance reasons clients normally
+buffer messages before delivering to the consumer via the `receive()`
+method or asynchronously via a message listener. If the consumer cannot
+process messages as fast as they are being delivered and stored in the
+internal buffer, then you could end up with a situation where messages
+would keep building up possibly causing out of memory on the client if
+they cannot be processed in time.
+
+Window-Based Flow Control
+-------------------------
+
+By default, ActiveMQ consumers buffer messages from the server in a
+client side buffer before the client consumes them. This improves
+performance: otherwise every time the client consumes a message,
+ActiveMQ would have to go the server to request the next message. In
+turn, this message would then get sent to the client side, if one was
+available.
+
+A network round trip would be involved for *every* message and
+considerably reduce performance.
+
+To prevent this, ActiveMQ pre-fetches messages into a buffer on each
+consumer. The total maximum size of messages (in bytes) that will be
+buffered on each consumer is determined by the `consumer-window-size`
+parameter.
+
+By default, the `consumer-window-size` is set to 1 MiB (1024 \* 1024
+bytes).
+
+The value can be:
+
+- `-1` for an *unbounded* buffer
+
+- `0` to not buffer any messages. See ? for working example of a
+ consumer with no buffering.
+
+- `>0` for a buffer with the given maximum size in bytes.
+
+Setting the consumer window size can considerably improve performance
+depending on the messaging use case. As an example, let's consider the
+two extremes:
+
+Fast consumers
+: Fast consumers can process messages as fast as they consume them (or
+ even faster)
+
+ To allow fast consumers, set the `consumer-window-size` to -1. This
+ will allow *unbounded* message buffering on the client side.
+
+ Use this setting with caution: it can overflow the client memory if
+ the consumer is not able to process messages as fast as it receives
+ them.
+
+Slow consumers
+: Slow consumers takes significant time to process each message and it
+ is desirable to prevent buffering messages on the client side so
+ that they can be delivered to another consumer instead.
+
+ Consider a situation where a queue has 2 consumers; 1 of which is
+ very slow. Messages are delivered in a round robin fashion to both
+ consumers, the fast consumer processes all of its messages very
+ quickly until its buffer is empty. At this point there are still
+ messages awaiting to be processed in the buffer of the slow consumer
+ thus preventing them being processed by the fast consumer. The fast
+ consumer is therefore sitting idle when it could be processing the
+ other messages.
+
+ To allow slow consumers, set the `consumer-window-size` to 0 (for no
+ buffer at all). This will prevent the slow consumer from buffering
+ any messages on the client side. Messages will remain on the server
+ side ready to be consumed by other consumers.
+
+ Setting this to 0 can give deterministic distribution between
+ multiple consumers on a queue.
+
+Most of the consumers cannot be clearly identified as fast or slow
+consumers but are in-between. In that case, setting the value of
+`consumer-window-size` to optimize performance depends on the messaging
+use case and requires benchmarks to find the optimal value, but a value
+of 1MiB is fine in most cases.
+
+### Using Core API
+
+If ActiveMQ Core API is used, the consumer window size is specified by
+`ServerLocator.setConsumerWindowSize()` method and some of the
+`ClientSession.createConsumer()` methods.
+
+### Using JMS
+
+If JNDI is used on the client to instantiate and look up the connection
+factory the consumer window size is configured in the JNDI context
+environment, e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.consumerWindowSize=0
+
+If the connection factory is directly instantiated, the consumer window
+size is specified by `ActiveMQConnectionFactory.setConsumerWindowSize()`
+method.
+
+Please see ? for an example which shows how to configure ActiveMQ to
+prevent consumer buffering when dealing with slow consumers.
+
+Rate limited flow control
+-------------------------
+
+It is also possible to control the *rate* at which a consumer can
+consume messages. This is a form of throttling and can be used to make
+sure that a consumer never consumes messages at a rate faster than the
+rate specified.
+
+The rate must be a positive integer to enable this functionality and is
+the maximum desired message consumption rate specified in units of
+messages per second. Setting this to `-1` disables rate limited flow
+control. The default value is `-1`.
+
+Please see ? for a working example of limiting consumer rate.
+
+### Using Core API
+
+If the ActiveMQ core API is being used the rate can be set via the
+`ServerLocator.setConsumerMaxRate(int consumerMaxRate)` method or
+alternatively via some of the `ClientSession.createConsumer()` methods.
+
+### Using JMS
+
+If JNDI is used to instantiate and look up the connection factory, the
+max rate can be configured in the JNDI context environment, e.g.
+`jndi.properties`. Here's a simple example using the "ConnectionFactory"
+connection factory which is available in the context by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.consumerMaxRate=10
+
+If the connection factory is directly instantiated, the max rate size
+can be set via the `ActiveMQConnectionFactory.setConsumerMaxRate(int
+ consumerMaxRate)` method.
+
+> **Note**
+>
+> Rate limited flow control can be used in conjunction with window based
+> flow control. Rate limited flow control only effects how many messages
+> a client can consume in a second and not how many messages are in its
+> buffer. So if you had a slow rate limit and a high window based limit
+> the clients internal buffer would soon fill up with messages.
+
+Please see ? for an example which shows how to configure ActiveMQ to
+prevent consumer buffering when dealing with slow consumers.
+
+Producer flow control
+=====================
+
+ActiveMQ also can limit the amount of data sent from a client to a
+server to prevent the server being overwhelmed.
+
+Window based flow control
+-------------------------
+
+In a similar way to consumer window based flow control, ActiveMQ
+producers, by default, can only send messages to an address as long as
+they have sufficient credits to do so. The amount of credits required to
+send a message is given by the size of the message.
+
+As producers run low on credits they request more from the server, when
+the server sends them more credits they can send more messages.
+
+The amount of credits a producer requests in one go is known as the
+*window size*.
+
+The window size therefore determines the amount of bytes that can be
+in-flight at any one time before more need to be requested - this
+prevents the remoting connection from getting overloaded.
+
+### Using Core API
+
+If the ActiveMQ core API is being used, window size can be set via the
+`ServerLocator.setProducerWindowSize(int producerWindowSize)` method.
+
+### Using JMS
+
+If JNDI is used to instantiate and look up the connection factory, the
+producer window size can be configured in the JNDI context environment,
+e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.producerWindowSize=10
+
+If the connection factory is directly instantiated, the producer window
+size can be set via the
+`ActiveMQConnectionFactory.setProducerWindowSize(int
+ producerWindowSize)` method.
+
+### Blocking producer window based flow control
+
+Normally the server will always give the same number of credits as have
+been requested. However, it is also possible to set a maximum size on
+any address, and the server will never send more credits than could
+cause the address's upper memory limit to be exceeded.
+
+For example, if I have a JMS queue called "myqueue", I could set the
+maximum memory size to 10MiB, and the the server will control the number
+of credits sent to any producers which are sending any messages to
+myqueue such that the total messages in the queue never exceeds 10MiB.
+
+When the address gets full, producers will block on the client side
+until more space frees up on the address, i.e. until messages are
+consumed from the queue thus freeing up space for more messages to be
+sent.
+
+We call this blocking producer flow control, and it's an efficient way
+to prevent the server running out of memory due to producers sending
+more messages than can be handled at any time.
+
+It is an alternative approach to paging, which does not block producers
+but instead pages messages to storage.
+
+To configure an address with a maximum size and tell the server that you
+want to block producers for this address if it becomes full, you need to
+define an AddressSettings (?) block for the address and specify
+`max-size-bytes` and `address-full-policy`
+
+The address block applies to all queues registered to that address. I.e.
+the total memory for all queues bound to that address will not exceed
+`max-size-bytes`. In the case of JMS topics this means the *total*
+memory of all subscriptions in the topic won't exceed max-size-bytes.
+
+Here's an example:
+
+ <address-settings>
+ <address-setting match="jms.queue.exampleQueue">
+ <max-size-bytes>100000</max-size-bytes>
+ <address-full-policy>BLOCK</address-full-policy>
+ </address-setting>
+ </address-settings>
+
+The above example would set the max size of the JMS queue "exampleQueue"
+to be 100000 bytes and would block any producers sending to that address
+to prevent that max size being exceeded.
+
+Note the policy must be set to `BLOCK` to enable blocking producer flow
+control.
+
+> **Note**
+>
+> Note that in the default configuration all addresses are set to block
+> producers after 10 MiB of message data is in the address. This means
+> you cannot send more than 10MiB of message data to an address without
+> it being consumed before the producers will be blocked. If you do not
+> want this behaviour increase the `max-size-bytes` parameter or change
+> the address full message policy.
+
+Rate limited flow control
+-------------------------
+
+ActiveMQ also allows the rate a producer can emit message to be limited,
+in units of messages per second. By specifying such a rate, ActiveMQ
+will ensure that producer never produces messages at a rate higher than
+that specified.
+
+The rate must be a positive integer to enable this functionality and is
+the maximum desired message consumption rate specified in units of
+messages per second. Setting this to `-1` disables rate limited flow
+control. The default value is `-1`.
+
+Please see the ? for a working example of limiting producer rate.
+
+### Using Core API
+
+If the ActiveMQ core API is being used the rate can be set via the
+`ServerLocator.setProducerMaxRate(int producerMaxRate)` method or
+alternatively via some of the `ClientSession.createProducer()` methods.
+
+### Using JMS
+
+If JNDI is used to instantiate and look up the connection factory, the
+max rate size can be configured in the JNDI context environment, e.g.
+`jndi.properties`. Here's a simple example using the "ConnectionFactory"
+connection factory which is available in the context by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.producerMaxRate=10
+
+If the connection factory is directly instantiated, the max rate size
+can be set via the `ActiveMQConnectionFactory.setProducerMaxRate(int
+ producerMaxRate)` method.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/flow-control.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/flow-control.xml b/docs/user-manual/en/flow-control.xml
deleted file mode 100644
index 70ab4e2..0000000
--- a/docs/user-manual/en/flow-control.xml
+++ /dev/null
@@ -1,290 +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="flow-control">
- <title>Flow Control</title>
- <para>Flow control is used to limit the flow of data between a client and server, or a server and
- another server in order to prevent the client or server being overwhelmed with data.</para>
- <section>
- <title>Consumer Flow Control</title>
- <para>This controls the flow of data between the server and the client as the client consumes
- messages. For performance reasons clients normally buffer messages before delivering to the
- consumer via the <literal>receive()</literal> method or asynchronously via a message
- listener. If the consumer cannot process messages as fast as they are being delivered and
- stored in the internal buffer, then you could end up with a situation where messages would
- keep building up possibly causing out of memory on the client if they cannot be processed
- in time.</para>
- <section id="flow-control.consumer.window">
- <title>Window-Based Flow Control</title>
- <para>By default, ActiveMQ consumers buffer messages from the server in a client side buffer
- before the client consumes them. This improves performance: otherwise every time the
- client consumes a message, ActiveMQ would have to go the server to request the next
- message. In turn, this message would then get sent to the client side, if one was
- available.</para>
- <para>A network round trip would be involved for <emphasis>every</emphasis> message and
- considerably reduce performance.</para>
- <para>To prevent this, ActiveMQ pre-fetches messages into a buffer on each consumer. The
- total maximum size of messages (in bytes) that will be buffered on each consumer is
- determined by the <literal>consumer-window-size</literal> parameter.</para>
- <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024
- bytes).</para>
- <para>The value can be:</para>
- <itemizedlist>
- <listitem>
- <para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para>
- </listitem>
- <listitem>
- <para><literal>0</literal> to not buffer any messages. See <xref
- linkend="examples.no-consumer-buffering"/> for working example of a consumer
- with no buffering.</para>
- </listitem>
- <listitem>
- <para><literal>>0</literal> for a buffer with the given maximum size in
- bytes.</para>
- </listitem>
- </itemizedlist>
- <para>Setting the consumer window size can considerably improve performance depending on
- the messaging use case. As an example, let's consider the two extremes: </para>
- <variablelist>
- <varlistentry>
- <term>Fast consumers</term>
- <listitem>
- <para>Fast consumers can process messages as fast as they consume them (or even
- faster)</para>
- <para>To allow fast consumers, set the <literal>consumer-window-size</literal> to
- -1. This will allow <emphasis>unbounded</emphasis> message buffering on the
- client side.</para>
- <para>Use this setting with caution: it can overflow the client memory if the
- consumer is not able to process messages as fast as it receives them.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Slow consumers</term>
- <listitem>
- <para>Slow consumers takes significant time to process each message and it is
- desirable to prevent buffering messages on the client side so that they can be
- delivered to another consumer instead.</para>
- <para>Consider a situation where a queue has 2 consumers; 1 of which is very slow.
- Messages are delivered in a round robin fashion to both consumers, the fast
- consumer processes all of its messages very quickly until its buffer is empty.
- At this point there are still messages awaiting to be processed in the buffer
- of the slow consumer thus preventing them being processed by the fast consumer.
- The fast consumer is therefore sitting idle when it could be processing the
- other messages. </para>
- <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to
- 0 (for no buffer at all). This will prevent the slow consumer from buffering
- any messages on the client side. Messages will remain on the server side ready
- to be consumed by other consumers.</para>
- <para>Setting this to 0 can give deterministic distribution between multiple
- consumers on a queue.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Most of the consumers cannot be clearly identified as fast or slow consumers but are
- in-between. In that case, setting the value of <literal>consumer-window-size</literal>
- to optimize performance depends on the messaging use case and requires benchmarks to
- find the optimal value, but a value of 1MiB is fine in most cases.</para>
- <section id="flow-control.core.api">
- <title>Using Core API</title>
- <para>If ActiveMQ Core API is used, the consumer window size is specified by <literal
- >ServerLocator.setConsumerWindowSize()</literal> method and some of the
- <literal>ClientSession.createConsumer()</literal> methods.</para>
- </section>
- <section>
- <title>Using JMS</title>
- <para>If JNDI is used on the client to instantiate and look up the connection factory the consumer window
- size is configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a
- simple example using the "ConnectionFactory" connection factory which is available in the context by
- default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.consumerWindowSize=0</programlisting>
- <para>If the connection factory is directly instantiated, the consumer window size is
- specified by <literal>ActiveMQConnectionFactory.setConsumerWindowSize()</literal>
- method.</para>
- <para>Please see <xref linkend="examples.no-consumer-buffering"/> for an example which
- shows how to configure ActiveMQ to prevent consumer buffering when dealing with slow
- consumers.</para>
- </section>
- </section>
- <section>
- <title>Rate limited flow control</title>
- <para>It is also possible to control the <emphasis>rate</emphasis> at which a consumer can
- consume messages. This is a form of throttling and can be used to make sure that a
- consumer never consumes messages at a rate faster than the rate specified. </para>
- <para>The rate must be a positive integer to enable this functionality and is the maximum
- desired message consumption rate specified in units of messages per second. Setting this
- to <literal>-1</literal> disables rate limited flow control. The default value is
- <literal>-1</literal>.</para>
- <para>Please see <xref linkend="examples.consumer-rate-limit"/> for a working example of
- limiting consumer rate.</para>
- <section id="flow-control.rate.core.api">
- <title>Using Core API</title>
- <para>If the ActiveMQ core API is being used the rate can be set via the <literal
- >ServerLocator.setConsumerMaxRate(int consumerMaxRate)</literal> method or
- alternatively via some of the <literal>ClientSession.createConsumer()</literal>
- methods. </para>
- </section>
- <section>
- <title>Using JMS</title>
- <para>If JNDI is used to instantiate and look up the connection factory, the max rate can be configured in
- the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple example using the
- "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.consumerMaxRate=10</programlisting>
- <para>If the connection factory is directly instantiated, the max rate size can be set
- via the <literal>ActiveMQConnectionFactory.setConsumerMaxRate(int
- consumerMaxRate)</literal> method.</para>
- <note>
- <para>Rate limited flow control can be used in conjunction with window based flow
- control. Rate limited flow control only effects how many messages a client can
- consume in a second and not how many messages are in its buffer. So if you had a
- slow rate limit and a high window based limit the clients internal buffer would
- soon fill up with messages.</para>
- </note>
- <para>Please see <xref linkend="examples.consumer-rate-limit"/> for an example which
- shows how to configure ActiveMQ to prevent consumer buffering when dealing with slow
- consumers.</para>
- </section>
- </section>
- </section>
- <section>
- <title>Producer flow control</title>
- <para>ActiveMQ also can limit the amount of data sent from a client to a server to prevent the
- server being overwhelmed.</para>
- <section>
- <title>Window based flow control</title>
- <para>In a similar way to consumer window based flow control, ActiveMQ producers, by
- default, can only send messages to an address as long as they have sufficient credits to
- do so. The amount of credits required to send a message is given by the size of the
- message.</para>
- <para>As producers run low on credits they request more from the server, when the server
- sends them more credits they can send more messages.</para>
- <para>The amount of credits a producer requests in one go is known as the <emphasis
- role="italic">window size</emphasis>.</para>
- <para>The window size therefore determines the amount of bytes that can be in-flight at any
- one time before more need to be requested - this prevents the remoting connection from
- getting overloaded.</para>
- <section>
- <title>Using Core API</title>
- <para>If the ActiveMQ core API is being used, window size can be set via the <literal
- >ServerLocator.setProducerWindowSize(int producerWindowSize)</literal>
- method.</para>
- </section>
- <section>
- <title>Using JMS</title>
- <para>If JNDI is used to instantiate and look up the connection factory, the producer window size can be
- configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple
- example using the "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.producerWindowSize=10</programlisting>
- <para>If the connection factory is directly instantiated, the producer window size can
- be set via the <literal>ActiveMQConnectionFactory.setProducerWindowSize(int
- producerWindowSize)</literal> method.</para>
- </section>
- <section>
- <title>Blocking producer window based flow control</title>
- <para>Normally the server will always give the same number of credits as have been
- requested. However, it is also possible to set a maximum size on any address, and the
- server will never send more credits than could cause the address's upper memory limit
- to be exceeded.</para>
- <para>For example, if I have a JMS queue called "myqueue", I could set the maximum
- memory size to 10MiB, and the the server will control the number of credits sent to
- any producers which are sending any messages to myqueue such that the total messages
- in the queue never exceeds 10MiB.</para>
- <para>When the address gets full, producers will block on the client side until more
- space frees up on the address, i.e. until messages are consumed from the queue thus
- freeing up space for more messages to be sent.</para>
- <para>We call this blocking producer flow control, and it's an efficient way to prevent
- the server running out of memory due to producers sending more messages than can be
- handled at any time.</para>
- <para>It is an alternative approach to paging, which does not block producers but
- instead pages messages to storage.</para>
- <para>To configure an address with a maximum size and tell the server that you want to
- block producers for this address if it becomes full, you need to define an
- AddressSettings (<xref linkend="queue-attributes.address-settings"/>) block for the
- address and specify <literal>max-size-bytes</literal> and <literal
- >address-full-policy</literal></para>
- <para>The address block applies to all queues registered to that address. I.e. the total
- memory for all queues bound to that address will not exceed <literal
- >max-size-bytes</literal>. In the case of JMS topics this means the <emphasis
- role="italic">total</emphasis> memory of all subscriptions in the topic won't
- exceed max-size-bytes.</para>
- <para>Here's an example:</para>
- <programlisting>
-<address-settings>
- <address-setting match="jms.queue.exampleQueue">
- <max-size-bytes>100000</max-size-bytes>
- <address-full-policy>BLOCK</address-full-policy>
- </address-setting>
-</address-settings></programlisting>
- <para>The above example would set the max size of the JMS queue "exampleQueue" to be
- 100000 bytes and would block any producers sending to that address to prevent that
- max size being exceeded.</para>
- <para>Note the policy must be set to <literal>BLOCK</literal> to enable blocking producer
- flow control.</para>
- <note><para>Note that in the default configuration all addresses are set to block producers after 10 MiB of message data
- is in the address. This means you cannot send more than 10MiB of message data to an address without it being consumed before the producers
- will be blocked. If you do not want this behaviour increase the <literal>max-size-bytes</literal> parameter or change the
- address full message policy.</para>
- </note>
- </section>
- </section>
- <section>
- <title>Rate limited flow control</title>
- <para>ActiveMQ also allows the rate a producer can emit message to be limited, in units of
- messages per second. By specifying such a rate, ActiveMQ will ensure that producer never
- produces messages at a rate higher than that specified.</para>
- <para>The rate must be a positive integer to enable this functionality and is the maximum
- desired message consumption rate specified in units of messages per second. Setting this
- to <literal>-1</literal> disables rate limited flow control. The default value is
- <literal>-1</literal>.</para>
- <para>Please see the <xref linkend="producer-rate-limiting-example"/> for a working example
- of limiting producer rate.</para>
- <section id="flow-control.producer.rate.core.api">
- <title>Using Core API</title>
- <para>If the ActiveMQ core API is being used the rate can be set via the <literal
- >ServerLocator.setProducerMaxRate(int producerMaxRate)</literal> method or
- alternatively via some of the <literal>ClientSession.createProducer()</literal>
- methods. </para>
- </section>
- <section>
- <title>Using JMS</title>
- <para>If JNDI is used to instantiate and look up the connection factory, the max rate size can be
- configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple
- example using the "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.producerMaxRate=10</programlisting>
- <para>If the connection factory is directly instantiated, the max rate size can be set
- via the <literal>ActiveMQConnectionFactory.setProducerMaxRate(int
- producerMaxRate)</literal> method.</para>
- </section>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/ha.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/ha.md b/docs/user-manual/en/ha.md
new file mode 100644
index 0000000..a35536c
--- /dev/null
+++ b/docs/user-manual/en/ha.md
@@ -0,0 +1,892 @@
+High Availability and Failover
+==============================
+
+We define high availability as the *ability for the system to continue
+functioning after failure of one or more of the servers*.
+
+A part of high availability is *failover* which we define as the
+*ability for client connections to migrate from one server to another in
+event of server failure so client applications can continue to operate*.
+
+Live - Backup Groups
+====================
+
+ActiveMQ allows servers to be linked together as *live - backup* 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
+
+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.
+
+HA Policies
+-----------
+
+ActiveMQ supports two different strategies for backing up a server
+*shared store* and *replication*. Which is configured via the
+`ha-policy` configuration element.
+
+ <ha-policy>
+ <replication/>
+ </ha-policy>
+
+
+or
+
+ <ha-policy>
+ <shared-store/>
+ </ha-policy>
+
+
+As well as these 2 strategies there is also a 3rd called `live-only`.
+This of course means there will be no Backup Strategy and is the default
+if none is provided, however this is used to configure `scale-down`
+which we will cover in a later chapter.
+
+> **Note**
+>
+> The `ha-policy` configurations replaces any current HA configuration
+> in the root of the `activemq-configuration.xml` configuration. All old
+> configuration is now deprecated altho best efforts will be made to
+> honour it if configured this way.
+
+> **Note**
+>
+> Only persistent message data will survive failover. Any non persistent
+> message data will not be available after failover.
+
+The `ha-policy` 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:
+
+ <ha-policy>
+ <replication>
+ <master/>
+ </replication>
+ </ha-policy>
+
+
+or
+
+ <ha-policy>
+ <shared-store/>
+ <slave/>
+ </shared-store/>
+ </ha-policy>
+
+
+or
+
+ <ha-policy>
+ <replication>
+ <colocated/>
+ </replication>
+ </ha-policy>
+
+
+Data Replication
+----------------
+
+Support for network-based data replication was added in version 2.3.
+
+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.
+
+c
+
+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.
+
+> **Note**
+>
+> Synchronization occurs in parallel with current network traffic so
+> this won't cause any blocking on current clients.
+
+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 ? 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.
+
+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 ? for details on how this is done,
+and how to configure a cluster connection. Notice that:
+
+- 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.
+
+- Their cluster user and password must match.
+
+Within a cluster, there are two ways that a backup server will locate a
+live server to replicate from, these are:
+
+- `specifying a node group`. You can specify a group of live servers
+ that a backup server can connect to. This is done by configuring
+ `group-name` in either the `master` or the `slave` element of the
+ `activemq-configuration.xml`. A Backup server will only connect to a
+ live server that shares the same node group name
+
+- `connecting to any live`. This will be the behaviour if `group-name`
+ is not configured allowing a backup server to connect to any live
+ server
+
+> **Note**
+>
+> A `group-name` example: suppose you have 5 live servers and 6 backup
+> servers:
+>
+> - `live1`, `live2`, `live3`: with `group-name=fish`
+>
+> - `live4`, `live5`: with `group-name=bird`
+>
+> - `backup1`, `backup2`, `backup3`, `backup4`: with `group-name=fish`
+>
+> - `backup5`, `backup6`: with `group-name=bird`
+>
+> After joining the cluster the backups with `group-name=fish` will
+> search for live servers with `group-name=fish` to pair with. Since
+> there is one backup too many, the `fish` will remain with one spare
+> backup.
+>
+> The 2 backups with `group-name=bird` (`backup5` and `backup6`) will
+> pair with live servers `live4` and `live5`.
+
+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.
+
+> **Note**
+>
+> 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 `slave` to `master`.
+
+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.
+
+### Configuration
+
+To configure the live and backup servers to be a replicating pair,
+configure the live server in ' `activemq-configuration.xml` to have:
+
+ <ha-policy>
+ <replication>
+ <master/>
+ </replication>
+ </ha-policy>
+ .
+ <cluster-connections>
+ <cluster-connection name="my-cluster">
+ ...
+ </cluster-connection>
+ </cluster-connections>
+
+
+The backup server must be similarly configured but as a `slave`
+
+ <ha-policy>
+ <replication>
+ <slave/>
+ </replication>
+ </ha-policy>
+
+### All Replication Configuration
+
+The following table lists all the `ha-policy` configuration elements for
+HA strategy Replication for `master`:
+
+ name Description
+ ------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ `check-for-live-server` 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.
+ `cluster-name` 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 `check-for-live-server`. If unset then the default cluster connections configuration is used (the first one configured)
+ `group-name` If set, backup servers will only pair with live servers with matching group-name
+
+The following table lists all the `ha-policy` configuration elements for
+HA strategy Replication for `slave`:
+
+ name Description
+ -------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ `cluster-name` 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 `check-for-live-server`. If unset then the default cluster connections configuration is used (the first one configured)
+ `group-name` If set, backup servers will only pair with live servers with matching group-name
+ `max-saved-replicated-journals-size` 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.
+ `allow-failback` 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
+ `failback-delay` delay to wait before fail-back occurs on (failed over live's) restart
+
+Shared Store
+------------
+
+When using a shared store, both live and backup servers share the *same*
+entire data directory using a shared file system. This means the paging
+directory, journal directory, large messages and binding journal.
+
+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.
+
+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).
+
+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.
+
+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.
+
+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).
+
+
+
+### Configuration
+
+To configure the live and backup servers to share their store, configure
+id via the `ha-policy` configuration in `activemq-configuration.xml`:
+
+ <ha-policy>
+ <shared-store>
+ <master/>
+ </shared-store>
+ </ha-policy>
+ .
+ <cluster-connections>
+ <cluster-connection name="my-cluster">
+ ...
+ </cluster-connection>
+ </cluster-connections>
+
+
+The backup server must also be configured as a backup.
+
+ <ha-policy>
+ <shared-store>
+ <slave/>
+ </shared-store>
+ </ha-policy>
+
+
+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 *same shared location* (as explained in ?)
+
+> **Note**
+>
+> todo write something about GFS
+
+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 ? for details on how this is
+done.
+
+Failing Back to live Server
+---------------------------
+
+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.
+
+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 `allow-fail-back` to `true` on the slave
+config which will force the backup that has become live to automatically
+stop. This configuration would look like:
+
+ <ha-policy>
+ <shared-store>
+ <slave>
+ <allow-failback>true</allow-failback>
+ <failback-delay>5000</failback-delay>
+ </slave>
+ </shared-store>
+ </ha-policy>
+
+
+The `failback-delay` 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.
+
+In replication HA mode you need to set an extra property
+`check-for-live-server` to `true` in the `master` 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 `activemq-configuration.xml`
+configuration file as follows:
+
+ <ha-policy>
+ <replication>
+ <master>
+ <check-for-live-server>true</check-for-live-server>
+ <master>
+ </replication>
+ </ha-policy>
+
+> **Warning**
+>
+> Be aware that if you restart a live server while after failover has
+> occurred then this value must be set to ``. If not the live server
+> will restart and server the same messages that the backup has already
+> handled causing duplicates.
+
+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 `ha-policy` configuration on either the `master`
+or `slave` like so:
+
+ <ha-policy>
+ <shared-store>
+ <master>
+ <failover-on-shutdown>true</failover-on-shutdown>
+ </master>
+ </shared-store>
+ </ha-policy>
+
+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 ?
+
+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
+`activemq-configuration.xml` configuration file as follows:
+
+ <ha-policy>
+ <shared-store>
+ <slave>
+ <allow-failback>true</allow-failback>
+ </slave>
+ </shared-store>
+ </ha-policy>
+
+### All Shared Store Configuration
+
+The following table lists all the `ha-policy` configuration elements for
+HA strategy shared store for `master`:
+
+ name Description
+ ------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ `failback-delay` 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
+ `failover-on-server-shutdown` 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 ?
+
+The following table lists all the `ha-policy` configuration elements for
+HA strategy Shared Store for `slave`:
+
+ name Description
+ ------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ `failover-on-server-shutdown` 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 ?
+ `allow-failback` 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.
+ `failback-delay` 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 `allow-failback` is set to true.
+
+Colocated Backup Servers
+------------------------
+
+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 `colocated_backup_n` 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 `ha-policy` element in the `activemq-configuration.xml` file like
+so:
+
+ <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>
+
+
+the above example is configured to use replication, in this case the
+`master` and `slave` configurations must match those for normal
+replication as in the previous chapter. `shared-store` is also supported
+
+
+
+### Configuring Connectors and Acceptors
+
+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 `backup-port-offset` 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.
+
+> **Note**
+>
+> for INVM connectors and Acceptors the id will have
+> `colocated_backup_n` appended, where n is the backup server number.
+
+#### Remote Connectors
+
+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 `ha-policy` configuration like so:
+
+ <ha-policy>
+ <replication>
+ <colocated>
+ <excludes>
+ <connector-ref>remote-connector</connector-ref>
+ </excludes>
+ .........
+ </ha-policy>
+
+
+### Configuring Directories
+
+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.
+
+The following table lists all the `ha-policy` configuration elements:
+
+ name Description
+ --------------------------------- ---------------------------------------------------------------------------------------
+ `request-backup` If true then the server will request a backup on another node
+ `backup-request-retries` How many times the live server will try to request a backup, -1 means for ever.
+ `backup-request-retry-interval` How long to wait for retries between attempts to request a backup server.
+ `max-backups` Whether or not this live server will accept backup requests from other live servers.
+ `backup-port-offset` The offset to use for the Connectors and Acceptors when creating a new backup server.
+
+Scaling Down
+============
+
+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.
+
+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.
+
+
+
+The configuration for a live server to scale down would be something
+like:
+
+ <ha-policy>
+ <live-only>
+ <scale-down>
+ <connectors>
+ <connector-ref>server1-connector</connector-ref>
+ </connectors>
+ </scale-down>
+ </live-only>
+ </ha-policy>
+
+
+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:
+
+ <ha-policy>
+ <live-only>
+ <scale-down>
+ <discovery-group>my-discovery-group</discovery-group>
+ </scale-down>
+ </live-only>
+ </ha-policy>
+
+
+Scale Down with groups
+----------------------
+
+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:
+
+ <ha-policy>
+ <live-only>
+ <scale-down>
+ ...
+ <group-name>my-group</group-name>
+ </scale-down>
+ </live-only>
+ </ha-policy>
+
+
+In this scenario only servers that belong to the group `my-group` will
+be scaled down to
+
+Scale Down and Backups
+----------------------
+
+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 `colocated` 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:
+
+ <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>
+
+
+Scale Down and Clients
+----------------------
+
+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.
+
+Failover Modes
+==============
+
+ActiveMQ defines two types of client failover:
+
+- Automatic client failover
+
+- Application-level client failover
+
+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 ?
+
+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.
+
+Automatic Client Failover
+-------------------------
+
+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.
+
+ActiveMQ clients detect connection failure when it has not received
+packets from the server within the time given by
+`client-failure-check-period` as explained in section ?. 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.
+
+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
+*server discovery* for the client to automatically discover the list.
+For full details on how to configure server discovery, please see ?.
+Alternatively, the clients can explicitly connect to a specific server
+and download the current servers and backups see ?.
+
+To enable automatic client failover, the client must be configured to
+allow non-zero reconnection attempts (as explained in ?).
+
+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.
+
+### Failing over on the Initial Connection
+
+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 `initialConnectAttempts`
+on the `ClientSessionFactoryImpl` or `ActiveMQConnectionFactory` or
+`initial-connect-attempts` in xml. The default for this is `0`, that is
+try only once. Once the number of attempts has been made an exception
+will be thrown.
+
+For examples of automatic failover with transacted and non-transacted
+JMS sessions, please see ? and ?.
+
+### A Note on Server Replication
+
+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.
+
+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.
+
+It is possible to provide full state machine replication using
+techniques such as *virtual synchrony*, but this does not scale well and
+effectively serializes all operations to a single thread, dramatically
+reducing concurrency.
+
+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.
+
+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 *once
+and only once* 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.
+
+### Handling Blocking Calls During Failover
+
+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.
+
+To prevent this, ActiveMQ will unblock any blocking calls that were in
+progress at the time of failover by making them throw a
+`javax.jms.JMSException` (if using JMS), or a `ActiveMQException` with
+error code `ActiveMQException.UNBLOCKED`. It is up to the client code to
+catch this exception and retry any operations if desired.
+
+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 `javax.jms.TransactionRolledBackException` (if using JMS), or a
+`ActiveMQException` with error code
+`ActiveMQException.TRANSACTION_ROLLED_BACK` if using the core API.
+
+### Handling Failover With Transactions
+
+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.
+
+Consequently the transaction will be marked as rollback-only, and any
+subsequent attempt to commit it will throw a
+`javax.jms.TransactionRolledBackException` (if using JMS), or a
+`ActiveMQException` with error code
+`ActiveMQException.TRANSACTION_ROLLED_BACK` if using the core API.
+
+> **Warning**
+>
+> 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 `HeuristicMixedException`.
+> Because of this the commit will throw a `XAException.XA_RETRY`
+> 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.
+
+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.
+
+ActiveMQ ships with a fully functioning example demonstrating how to do
+this, please see ?
+
+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.
+
+> **Note**
+>
+> If XA is being used either via JMS or through the core API then an
+> `XAException.XA_RETRY` 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.
+
+To remedy this, the client can simply enable 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.
+
+> **Note**
+>
+> 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.
+
+### Handling Failover With Non Transactional Sessions
+
+If the session is non transactional, messages or acknowledgements can be
+lost in the event of failover.
+
+If you wish to provide *once and only once* delivery guarantees for non
+transacted sessions too, enabled duplicate detection, and catch unblock
+exceptions as described in ?
+
+Getting Notified of Connection Failure
+--------------------------------------
+
+JMS provides a standard mechanism for getting notified asynchronously of
+connection failure: `java.jms.ExceptionListener`. Please consult the JMS
+javadoc or any good JMS tutorial for more information on how to use
+this.
+
+The ActiveMQ core API also provides a similar feature in the form of the
+class `org.apache.activemq.core.client.SessionFailureListener`
+
+Any ExceptionListener or SessionFailureListener instance will always be
+called by ActiveMQ on event of connection failure, **irrespective** 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 `failedOver` flag passed in on the
+`connectionFailed` on `SessionfailureListener` or by inspecting the
+error code on the `javax.jms.JMSException` which will be one of the
+following:
+
+ error code Description
+ ------------ ---------------------------------------------------------------------------
+ FAILOVER Failover has occurred and we have successfully reattached or reconnected.
+ DISCONNECT No failover has occurred and we are disconnected.
+
+ : JMSException error codes
+
+Application-Level Failover
+--------------------------
+
+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
+*application-level* failover, since the failover is handled at the user
+application level.
+
+To implement application-level failover, if you're using JMS then you
+need to set an `ExceptionListener` class on the JMS connection. The
+`ExceptionListener` will be called by ActiveMQ in the event that
+connection failure is detected. In your `ExceptionListener`, 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
+[HA-JNDI](http://www.jboss.org/community/wiki/JBossHAJNDIImpl) to ensure
+that the new connection factory is looked up from a different server.
+
+For a working example of application-level failover, please see ?.
+
+If you are using the core API, then the procedure is very similar: you
+would set a `FailureListener` on the core `ClientSession` instances.
[22/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/examples.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/examples.xml b/docs/quickstart-guide/en/examples.xml
deleted file mode 100644
index 37c4e15..0000000
--- a/docs/quickstart-guide/en/examples.xml
+++ /dev/null
@@ -1,329 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="examples">
- <title>Running the Examples</title>
- <para>In the directory <literal>examples</literal> there are 2 sets of examples, these are </para>
- <itemizedlist>
- <listitem>
- <para>JMS Examples - these demonstrate functionality while sending and consumng JMS
- messages.</para>
- </listitem>
- <listitem>
- <para>Java EE Examples - these demonstrate application server integration, e.g. MDBs, EJBs,
- Servlets, etc.</para>
- </listitem>
- </itemizedlist>
- <section id="examples.jms">
- <title>The JMS examples</title>
- <para>The JMS Examples all follow the same format. Each examples is contained in its own
- directory which contains the following.</para>
- <itemizedlist>
- <listitem>
- <para><literal>pom.xml</literal></para>
- <para>This is the Maven build file used to run the example</para>
- </listitem>
- <listitem>
- <para><literal>src</literal> directory</para>
- <para>This contains the source code for the example</para>
- </listitem>
- <listitem>
- <para><literal>resources/activemq/server0</literal> configuration directory</para>
- <para>This contains the configuration files needed to run the server for the example.
- There may be multiple configuration directories <literal>server0</literal>, <literal
- >server1</literal> etc for clustered examples etc.</para>
- </listitem>
- </itemizedlist>
- <para>Each example will start one or more stand-alone servers and stop them after the example
- has completed.</para>
- <para>As a quick start we'll run the queue example. For all other examples refer to the main
- user manual.</para>
- <para>Firstly open a Shell or a Command prompt and navigate to the <literal
- >examples/jms/queue</literal> directory.</para>
- <para>Type the command <literal>mvn verify</literal> and you should see the following output:</para>
- <programlisting>
-
-[INFO] Scanning for projects...
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building ActiveMQ JMS Queue Example 2.3.0.BETA-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-[INFO]
-[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ activemq-jms-queue-example ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] Copying 3 resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.0:compile (default-compile) @ activemq-jms-queue-example ---
-[INFO] Nothing to compile - all classes are up to date
-[INFO]
-[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ activemq-jms-queue-example ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] skip non existing resourceDirectory /home/andy/projects/activemq-master/examples/jms/queue/src/test/resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.0:testCompile (default-testCompile) @ activemq-jms-queue-example ---
-[INFO] No sources to compile
-[INFO]
-[INFO] --- maven-surefire-plugin:2.13:test (default-test) @ activemq-jms-queue-example ---
-[INFO]
-[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ activemq-jms-queue-example ---
-[INFO] Building jar: /home/andy/projects/activemq-master/examples/jms/queue/target/activemq-jms-queue-example-2.3.0.BETA-SNAPSHOT.jar
-[INFO]
-[INFO] >>> maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example >>>
-[INFO]
-[INFO] <<< maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example <<<
-[INFO]
-[INFO] --- maven-source-plugin:2.2.1:jar (attach-sources) @ activemq-jms-queue-example ---
-[INFO] Building jar: /home/andy/projects/activemq-master/examples/jms/queue/target/activemq-jms-queue-example-2.3.0.BETA-SNAPSHOT-sources.jar
-[INFO]
-[INFO] >>> maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example >>>
-[INFO]
-[INFO] <<< maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example <<<
-[INFO]
-[INFO] --- maven-source-plugin:2.2.1:jar (default) @ activemq-jms-queue-example ---
-[WARNING] Artifact org.apache.activemq.examples.jms:activemq-jms-queue-example:java-source:sources:2.3.0.BETA-SNAPSHOT already attached to project, ignoring duplicate
-[INFO]
-[INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:start (start) @ activemq-jms-queue-example ---
-[file:/home/andy/projects/activemq-master/examples/jms/queue/target/classes/activemq/server0/]
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.deployers.impl.FileConfigurationParser parseMainConfig
-WARN: HQ222018: AIO was not located on this platform, it will fall back to using pure Java NIO. If your platform is Linux, install LibAIO to enable the AIO journal
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl start
-INFO: HQ221000: live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/journal,bindingsDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/bindings,largeMessagesDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/largemessages,pagingDirectory=/home/andy/projects/activemq-master/examples/jms/queue/target//server0/data/messaging/paging)
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl$SharedStoreLiveActivation run
-INFO: HQ221006: Waiting to obtain live lock
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.persistence.impl.journal.JournalStorageManager <init>
-INFO: HQ221013: Using NIO Journal
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl initialisePart1
-WARN: HQ222007: Security risk! ActiveMQ is running with the default cluster admin user and default password. Please see the ActiveMQ user guide, cluster chapter, for instructions on how to change this.
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.FileLockNodeManager startLiveNode
-INFO: HQ221034: Waiting to obtain live lock
-Apr 17, 2013 10:51:01 AM org.apache.activemq.core.server.impl.FileLockNodeManager startLiveNode
-INFO: HQ221035: Live Server Obtained live lock
-Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl deployQueue
-INFO: HQ221003: trying to deploy queue jms.queue.exampleQueue
-Apr 17, 2013 10:51:02 AM org.apache.activemq.core.remoting.impl.netty.NettyAcceptor start
-INFO: HQ221020: Started Netty Acceptor version 3.6.2.Final-c0d783c localhost:5445 for CORE protocol
-Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl$SharedStoreLiveActivation run
-INFO: HQ221007: Server is now live
-Apr 17, 2013 10:51:02 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl start
-INFO: HQ221001: ActiveMQ Server version 2.3.0.SNAPSHOT (black'n'yellow, 123) [a57893ff-7783-11e2-9787-07ca142fc9f7]
-[INFO]
-[INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:runClient (runClient) @ activemq-jms-queue-example ---
-Apr 17, 2013 10:51:02 AM org.apache.activemq.common.example.ActiveMQExample getContext
-INFO: using jnp://localhost:1099 for jndi
-Sent message: This is a text message
-Received message: This is a text message
-example complete
-
-#####################
-### SUCCESS! ###
-#####################
-[INFO]
-[INFO] --- activemq-maven-plugin:1.1.1-SNAPSHOT:stop (stop) @ activemq-jms-queue-example ---
-Apr 17, 2013 10:51:03 AM org.apache.activemq.core.server.management.impl.ManagementServiceImpl stop
-WARN: HQ222113: On ManagementService stop, there are 1 unexpected registered MBeans: [core.acceptor.netty-acceptor]
-Apr 17, 2013 10:51:03 AM org.apache.activemq.core.server.impl.ActiveMQServerImpl stop
-INFO: HQ221002: ActiveMQ Server version 2.3.0.SNAPSHOT (black'n'yellow, 123) [a57893ff-7783-11e2-9787-07ca142fc9f7] stopped
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 4.428s
-[INFO] Finished at: Wed Apr 17 10:51:03 BST 2013
-[INFO] Final Memory: 11M/456M
-[INFO] ------------------------------------------------------------------------
-
-</programlisting>
- <para>Congratulations! You have successfully run your first ActiveMQ example. Try some of the
- others.</para>
- </section>
- <section id="examples.messaging">
- <title>The Java EE Examples</title>
- <para>The Java EE Examples are examples that require a JEE application server to run. They
- include MDB, Servlet, EJB examples etc. For this you will need the JBoss Application Server 7.1.x
- installed and uses Arquillian to run the example. How to do this is explained in the previous chapters.</para>
- <para>We'll use the MDB example for the purposes of this guide. For the other examples refer
- to the user guide. Before going any further ensure that the JBoss Application Server is
- running.</para>
- <para> The first thing we need to do is set the <literal>JBOSS_HOME</literal> environment property to the location of the JBoss
- Application Server, in a Linux shell this would be something like:</para>
- <programlisting>export JBOSS_HOME=/home/jbossas7.1/build/output/jboss-7.1.0</programlisting>
- <para>Yoy can then run the example via maven by running <literal>mvn test</literal></para>
- <para>In the shell window you should see something like the following output:</para>
- <programlisting>
-[INFO] Scanning for projects...
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building ActiveMQ JEE MDB Example 2.3.0.BETA-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-[INFO]
-[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ activemq-jee-mdb-bmt-example ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] skip non existing resourceDirectory /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/src/main/resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.0:compile (default-compile) @ activemq-jee-mdb-bmt-example ---
-[INFO] Nothing to compile - all classes are up to date
-[INFO]
-[INFO] --- maven-resources-plugin:2.6:copy-resources (as-node-0) @ activemq-jee-mdb-bmt-example ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] Copying 1112 resources
-[INFO] Copying 5 resources
-[INFO]
-[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ activemq-jee-mdb-bmt-example ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] Copying 1 resource
-[INFO]
-[INFO] --- maven-compiler-plugin:3.0:testCompile (default-testCompile) @ activemq-jee-mdb-bmt-example ---
-[INFO] Changes detected - recompiling the module!
-[INFO] Compiling 1 source file to /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/test-classes
-[INFO]
-[INFO] --- maven-surefire-plugin:2.12:test (default-test) @ activemq-jee-mdb-bmt-example ---
-[INFO] Surefire report directory: /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/surefire-reports
-
--------------------------------------------------------
- T E S T S
--------------------------------------------------------
-Running org.apache.activemq.javaee.example.server.ExampleRunnerTest
-log4j:WARN No appenders could be found for logger (org.jboss.logging).
-log4j:WARN Please initialize the log4j system properly.
-log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
-Apr 17, 2013 10:58:04 AM org.jboss.arquillian.container.impl.MapObject populate
-WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.managed.ManagedContainerConfiguration
-Unused property entries: {waitForPortsTimeoutInSeconds=8, waitForPorts=8787 9999}
-Supported property names: [jbossHome, outputToConsole, enableAssertions, password, managementPort, javaHome, javaVmArguments, username, serverConfig, allowConnectingToRunningServer, managementAddress, startupTimeoutInSeconds, modulePath]
-Apr 17, 2013 10:58:04 AM org.jboss.as.arquillian.container.managed.ManagedDeployableContainer startInternal
-INFO: Starting container with: [/home/andy/devtools/jdk1.6.0_25//bin/java, -Djboss.inst=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0, -ea, -Djboss.home.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0, -Dorg.jboss.boot.log.file=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/log/boot.log, -Dlogging.configuration=file:/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/configuration/logging.properties, -Djboss.modules.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/modules, -Djboss.bundles.dir=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/bundles, -jar, /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/jboss-modules.jar, -mp, /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/modules, -jaxpmodule, ja
vax.xml.jaxp-provider, org.jboss.as.standalone, -server-config, standalone-example.xml]
-10:58:04,525 INFO [org.jboss.modules] JBoss Modules version 1.1.1.GA
-10:58:04,664 INFO [org.jboss.msc] JBoss MSC version 1.0.2.GA
-10:58:04,703 INFO [org.jboss.as] JBAS015899: JBoss AS 7.1.1.Final "Brontes" starting
-10:58:05,492 INFO [org.xnio] XNIO Version 3.0.3.GA
-10:58:05,494 INFO [org.jboss.as.server] JBAS015888: Creating http management service using socket-binding (management-http)
-10:58:05,502 INFO [org.xnio.nio] XNIO NIO Implementation Version 3.0.3.GA
-10:58:05,509 INFO [org.jboss.remoting] JBoss Remoting version 3.2.3.GA
-10:58:05,527 INFO [org.jboss.as.logging] JBAS011502: Removing bootstrap log handlers
-10:58:05,530 INFO [org.jboss.as.configadmin] (ServerService Thread Pool -- 32) JBAS016200: Activating ConfigAdmin Subsystem
-10:58:05,560 INFO [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 37) JBAS010280: Activating Infinispan subsystem.
-10:58:05,562 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 33) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
-10:58:05,573 INFO [org.jboss.as.jacorb] (ServerService Thread Pool -- 38) JBAS016300: Activating JacORB Subsystem
-10:58:05,595 INFO [org.jboss.as.connector] (MSC service thread 1-12) JBAS010408: Starting JCA Subsystem (JBoss IronJacamar 1.0.9.Final)
-10:58:05,612 INFO [org.jboss.as.naming] (ServerService Thread Pool -- 48) JBAS011800: Activating Naming Subsystem
-10:58:05,625 INFO [org.jboss.as.osgi] (ServerService Thread Pool -- 49) JBAS011940: Activating OSGi Subsystem
-10:58:05,649 INFO [org.jboss.as.security] (ServerService Thread Pool -- 54) JBAS013101: Activating Security Subsystem
-10:58:05,657 INFO [org.jboss.as.naming] (MSC service thread 1-8) JBAS011802: Starting Naming Service
-10:58:05,663 INFO [org.jboss.as.mail.extension] (MSC service thread 1-16) JBAS015400: Bound mail session [java:jboss/mail/Default]
-10:58:05,675 INFO [org.jboss.as.security] (MSC service thread 1-14) JBAS013100: Current PicketBox version=4.0.7.Final
-10:58:05,683 INFO [org.jboss.as.webservices] (ServerService Thread Pool -- 58) JBAS015537: Activating WebServices Extension
-10:58:05,705 INFO [org.jboss.jaxr] (MSC service thread 1-8) JBAS014000: Started JAXR subsystem, binding JAXR connection factory into JNDI as: java:jboss/jaxr/ConnectionFactory
-10:58:05,831 INFO [org.jboss.ws.common.management.AbstractServerConfig] (MSC service thread 1-4) JBoss Web Services - Stack CXF Server 4.0.2.GA
-10:58:05,943 INFO [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-6) Starting Coyote HTTP/1.1 on http-localhost.localdomain-127.0.0.1-8080
-10:58:05,966 INFO [org.jboss.as.jacorb] (MSC service thread 1-2) JBAS016330: CORBA ORB Service started
-10:58:05,988 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingjournal,bindingsDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingbindings,largeMessagesDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messaginglargemessages,pagingDirectory=/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/messagingpaging)
-10:58:05,996 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) Waiting to obtain live lock
-10:58:06,037 INFO [org.apache.activemq.core.persistence.impl.journal.JournalStorageManager] (MSC service thread 1-11) Using AIO Journal
-10:58:06,122 INFO [org.jboss.as.jacorb] (MSC service thread 1-14) JBAS016328: CORBA Naming Service started
-10:58:06,184 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-7) JBAS010400: Bound data source [java:jboss/datasources/ExampleDS]
-10:58:06,204 INFO [org.apache.activemq.core.server.impl.AIOFileLockNodeManager] (MSC service thread 1-11) Waiting to obtain live lock
-10:58:06,205 INFO [org.apache.activemq.core.server.impl.AIOFileLockNodeManager] (MSC service thread 1-11) Live Server Obtained live lock
-10:58:06,434 INFO [org.jboss.as.remoting] (MSC service thread 1-2) JBAS017100: Listening on localhost.localdomain/127.0.0.1:4447
-10:58:06,434 INFO [org.jboss.as.remoting] (MSC service thread 1-15) JBAS017100: Listening on /127.0.0.1:9999
-10:58:06,436 INFO [org.jboss.as.server.deployment.scanner] (MSC service thread 1-16) JBAS015012: Started FileSystemDeploymentService for directory /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/deployments
-10:58:08,790 INFO [org.apache.activemq.core.remoting.impl.netty.NettyAcceptor] (MSC service thread 1-11) Started Netty Acceptor version 3.2.5.Final-a96d88c localhost.localdomain:5445 for CORE protocol
-10:58:08,793 INFO [org.apache.activemq.core.remoting.impl.netty.NettyAcceptor] (MSC service thread 1-11) Started Netty Acceptor version 3.2.5.Final-a96d88c localhost.localdomain:5455 for CORE protocol
-10:58:08,795 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) Server is now live
-10:58:08,797 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-11) ActiveMQ Server version 2.2.13.Final (HQ_2_2_13_FINAL_AS7, 122) [5c499e88-9c63-11e2-bfa3-fe5400591699]) started
-10:58:08,822 INFO [org.jboss.as.messaging] (MSC service thread 1-4) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/RemoteConnectionFactory
-10:58:08,824 INFO [org.jboss.as.messaging] (MSC service thread 1-4) JBAS011601: Bound messaging object to jndi name java:/RemoteConnectionFactory
-10:58:08,825 INFO [org.jboss.as.messaging] (MSC service thread 1-10) JBAS011601: Bound messaging object to jndi name java:/ConnectionFactory
-10:58:08,830 INFO [org.apache.activemq.core.server.impl.ActiveMQServerImpl] (MSC service thread 1-3) trying to deploy queue jms.queue.testQueue
-10:58:08,836 INFO [org.jboss.as.messaging] (MSC service thread 1-3) JBAS011601: Bound messaging object to jndi name java:/queue/test
-10:58:08,840 INFO [org.jboss.as.messaging] (MSC service thread 1-3) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/queues/testQueue
-10:58:08,859 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-9) JBAS010406: Registered connection factory java:/JmsXA
-10:58:08,866 INFO [org.apache.activemq.ra.ActiveMQResourceAdapter] (MSC service thread 1-9) ActiveMQ resource adaptor started
-10:58:08,867 INFO [org.jboss.as.connector.services.ResourceAdapterActivatorService$ResourceAdapterActivator] (MSC service thread 1-9) IJ020002: Deployed: file://RaActivatoractivemq-ra
-10:58:08,870 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-5) JBAS010401: Bound JCA ConnectionFactory [java:/JmsXA]
-10:58:08,898 INFO [org.jboss.as.server.deployment] (MSC service thread 1-10) JBAS015876: Starting deployment of "ONT001-1.0.war"
-10:58:09,146 INFO [org.jboss.wsf.stack.cxf.metadata.MetadataBuilder] (MSC service thread 1-1) Add Service
- id=com.hpm.webservices.BasicWSImpl
- address=http://localhost:8080/hpm/BasicWService
- implementor=com.hpm.webservices.BasicWSImpl
- invoker=org.jboss.wsf.stack.cxf.JBossWSInvoker
- serviceName={http://ont001-hpm.rhcloud.com/BasicWS}BasicWService
- portName={http://ont001-hpm.rhcloud.com/BasicWS}BasicWS
- wsdlLocation=null
- mtomEnabled=false
-10:58:09,361 INFO [org.apache.cxf.service.factory.ReflectionServiceFactoryBean] (MSC service thread 1-1) Creating Service {http://ont001-hpm.rhcloud.com/BasicWS}BasicWService from WSDL: WEB-INF/wsdl/BasicWService.wsdl
-10:58:09,517 INFO [org.jboss.wsf.stack.cxf.transport.AddressRewritingEndpointInfo] (MSC service thread 1-1) Setting new service endpoint address in wsdl: http://ONT001-HPM.rhcloud.com:80/BasicWService
-10:58:09,656 INFO [org.jboss.wsf.stack.cxf.transport.AddressRewritingEndpointInfo] (MSC service thread 1-1) Setting new service endpoint address in wsdl: http://localhost:8080/hpm/BasicWService
-10:58:09,688 INFO [org.apache.cxf.endpoint.ServerImpl] (MSC service thread 1-1) Setting the server's publish address to be http://localhost:8080/hpm/BasicWService
-10:58:09,729 INFO [org.jboss.wsf.stack.cxf.deployment.WSDLFilePublisher] (MSC service thread 1-1) WSDL published to: file:/home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/wsdl/ONT001-1.0.war/BasicWService.wsdl
-10:58:09,735 INFO [org.jboss.as.webservices] (MSC service thread 1-11) JBAS015539: Starting service jboss.ws.port-component-link
-10:58:09,748 INFO [org.jboss.as.webservices] (MSC service thread 1-10) JBAS015539: Starting service jboss.ws.endpoint."ONT001-1.0.war"."com.hpm.webservices.BasicWSImpl"
-10:58:09,753 INFO [org.jboss.ws.common.management.DefaultEndpointRegistry] (MSC service thread 1-10) register: jboss.ws:context=hpm,endpoint=com.hpm.webservices.BasicWSImpl
-10:58:09,829 INFO [org.jboss.web] (MSC service thread 1-3) JBAS018210: Registering web context: /hpm
-10:58:09,834 INFO [org.jboss.as] (MSC service thread 1-7) JBAS015951: Admin console listening on http://127.0.0.1:9990
-10:58:09,835 INFO [org.jboss.as] (MSC service thread 1-7) JBAS015874: JBoss AS 7.1.1.Final "Brontes" started in 5506ms - Started 216 of 296 services (79 services are passive or on-demand)
-10:58:09,979 INFO [org.jboss.as.server] (DeploymentScanner-threads - 2) JBAS018559: Deployed "ONT001-1.0.war"
-mdb.jar:
-/org/
-/org.apache.activemq/
-/org.apache.activemq/javaee/
-/org.apache.activemq/javaee/example/
-/org.apache.activemq/javaee/example/server/
-/org.apache.activemq/javaee/example/server/MDB_BMTExample.class
-10:58:11,612 INFO [org.jboss.as.repository] (management-handler-thread - 2) JBAS014900: Content added at location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/f0/e2d589ab9490193e109c8bc833f725c87defae/content
-10:58:11,620 INFO [org.jboss.as.server.deployment] (MSC service thread 1-8) JBAS015876: Starting deployment of "arquillian-service"
-10:58:11,811 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.jmx:main") which may be changed or removed in future versions without notice.
-10:58:11,812 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.server:main") which may be changed or removed in future versions without notice.
-10:58:11,813 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.as.osgi:main") which may be changed or removed in future versions without notice.
-10:58:11,815 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.jandex:main") which may be changed or removed in future versions without notice.
-10:58:11,817 WARN [org.jboss.as.dependency.private] (MSC service thread 1-1) JBAS018567: Deployment "deployment.arquillian-service" is using a private module ("org.jboss.osgi.framework:main") which may be changed or removed in future versions without notice.
-10:58:11,953 INFO [org.jboss.as.server] (management-handler-thread - 2) JBAS018559: Deployed "arquillian-service"
-10:58:12,328 INFO [org.jboss.as.repository] (management-handler-thread - 3) JBAS014900: Content added at location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/59/7dcdb0f420ed57aea638b2599f7a86eecf6c85/content
-10:58:12,333 INFO [org.jboss.as.server.deployment] (MSC service thread 1-7) JBAS015876: Starting deployment of "mdb.jar"
-10:58:12,401 INFO [org.jboss.as.arquillian] (MSC service thread 1-14) Arquillian deployment detected: ArquillianConfig[service=jboss.arquillian.config."mdb.jar",unit=mdb.jar,tests=[org.apache.activemq.javaee.example.server.ExampleRunnerTest]]
-10:58:12,418 INFO [org.jboss.as.ejb3] (MSC service thread 1-15) JBAS014142: Started message driven bean 'MDB_BMTExample' with 'activemq-ra' resource adapter
-10:58:12,562 INFO [org.jboss.as.server] (management-handler-thread - 3) JBAS018559: Deployed "mdb.jar"
-Sent message: This is a text message
-10:58:13,229 INFO [org.jboss.as.naming] (Remoting "localhost" task-3) JBAS011806: Channel end notification received, closing channel Channel ID 57be4578 (inbound) of Remoting connection 3ac552d5 to /127.0.0.1:58571
-10:58:13,255 INFO [stdout] (Thread-0 (ActiveMQ-client-global-threads-1402019528)) message This is a text message received
-10:58:13,257 INFO [stdout] (Thread-0 (ActiveMQ-client-global-threads-1402019528)) we're in the middle of a transaction: org.jboss.tm.usertx.client.ServerVMClientUserTransaction@6b04d3c8
-10:58:14,292 INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) JBAS015877: Stopped deployment mdb.jar in 33ms
-10:58:14,413 INFO [org.jboss.as.repository] (management-handler-thread - 1) JBAS014901: Content removed from location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/59/7dcdb0f420ed57aea638b2599f7a86eecf6c85/content
-10:58:14,415 INFO [org.jboss.as.server] (management-handler-thread - 1) JBAS018558: Undeployed "mdb.jar"
-Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 10.609 sec
-10:58:14,436 INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) JBAS015877: Stopped deployment arquillian-service in 6ms
-10:58:14,530 INFO [org.jboss.as.repository] (management-handler-thread - 2) JBAS014901: Content removed from location /home/andy/projects/activemq-master/examples/javaee/mdb-bmt/target/jbossas-node0/standalone/data/content/f0/e2d589ab9490193e109c8bc833f725c87defae/content
-10:58:14,532 INFO [org.jboss.as.server] (management-handler-thread - 2) JBAS018558: Undeployed "arquillian-service"
-
-Results :
-
-Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
-
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 23.441s
-[INFO] Finished at: Wed Apr 17 10:58:16 BST 2013
-[INFO] Final Memory: 19M/361M
-[INFO] ------------------------------------------------------------------------
-</programlisting>
-<para>Congratulations! you have successfully deployed and run a Java EE example.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/images/hornetQ_logo_600px.png
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/images/hornetQ_logo_600px.png b/docs/quickstart-guide/en/images/hornetQ_logo_600px.png
deleted file mode 100644
index b71f4ba..0000000
Binary files a/docs/quickstart-guide/en/images/hornetQ_logo_600px.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/installation.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/installation.md b/docs/quickstart-guide/en/installation.md
new file mode 100644
index 0000000..192f118
--- /dev/null
+++ b/docs/quickstart-guide/en/installation.md
@@ -0,0 +1,85 @@
+Installation
+============
+
+This section describes how to install ActiveMQ.
+
+Prerequisites
+=============
+
+> **Note**
+>
+> ActiveMQ only runs on Java 7 or later.
+
+By default, ActiveMQ server runs with 1GiB of memory. If your computer
+has less memory, or you want to run it with more available RAM, modify
+the value in `bin/run.sh` accordingly.
+
+For persistence, ActiveMQ uses its own fast journal, which you can
+configure to use libaio (which is the default when running on Linux) or
+Java NIO. In order to use the libaio module on Linux, you'll need to
+install libaio, if it's not already installed.
+
+If you're not running on Linux then you don't need to worry about this.
+
+You can install libaio using the following steps as the root user:
+
+Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+
+ yum install libaio
+
+Using aptitude, (e.g. on Ubuntu or Debian system):
+
+ apt-get install libaio
+
+Stand-alone ActiveMQ Server
+===========================
+
+After downloading the distribution, unzip it into your chosen directory.
+At this point it should be possible to [run straight out of the
+box](#running.standalone), the following describes the directory
+structure:
+
+ |___ bin
+ |
+ |___ config
+ | |___ jboss-as-4
+ | |___ jboss-as-5
+ | |___ stand-alone
+ |
+ |___ docs
+ | |___ api
+ | |___ quickstart-guide
+ | |___ user-manual
+ |
+ |___ examples
+ | |___ core
+ | |___ javaee
+ | |___ jms
+ |
+ |___ lib
+ |
+ |___ licenses
+ |
+ |___ schemas
+
+
+- `bin` -- binaries and scripts needed to run ActiveMQ.
+
+- `config` -- configuration files needed to configure ActiveMQ. This
+ contains configurations to run ActiveMQ either in stand-alone or
+ inside JBoss AS 4 and 5. Please refer to the reference guide for
+ details on configuration.
+
+- `docs` -- guides and javadocs for ActiveMQ
+
+- `examples` -- JMS and Java EE examples. Please refer to the 'running
+ examples' chapter for details on how to run them.
+
+- `lib` -- jars and libraries needed to run ActiveMQ
+
+- `licenses` -- licenses for ActiveMQ
+
+- `schemas` -- XML Schemas used to validate ActiveMQ configuration
+ files
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/installation.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/installation.xml b/docs/quickstart-guide/en/installation.xml
deleted file mode 100644
index 8e5fddb..0000000
--- a/docs/quickstart-guide/en/installation.xml
+++ /dev/null
@@ -1,101 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="installation">
- <title>Installation</title>
- <para>This section describes how to install ActiveMQ. </para>
- <section id="installation.prerequisites">
- <title>Prerequisites</title>
- <note>
- <para>ActiveMQ only runs on Java 7 or later.</para>
- </note>
- <para>By default, ActiveMQ server runs with 1GiB of memory. If your computer has less memory,
- or you want to run it with more available RAM, modify the value in <literal
- >bin/run.sh</literal> accordingly.</para>
- <para>For persistence, ActiveMQ uses its own fast journal, which you can configure to use
- libaio (which is the default when running on Linux) or Java NIO. In order to use the libaio
- module on Linux, you'll need to install libaio, if it's not already installed.</para>
- <para>If you're not running on Linux then you don't need to worry about this.</para>
- <para>You can install libaio using the following steps as the root user:</para>
- <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):</para>
- <programlisting>yum install libaio</programlisting>
- <para>Using aptitude, (e.g. on Ubuntu or Debian system):</para>
- <programlisting>apt-get install libaio</programlisting>
- </section>
- <section id="installation.standalone">
- <title>Stand-alone ActiveMQ Server</title>
- <para>After downloading the distribution, unzip it into your chosen directory. At this point
- it should be possible to <link linkend="running.standalone">run straight out of the
- box</link>, the following describes the directory structure: </para>
- <programlisting>
- |___ bin
- |
- |___ config
- | |___ jboss-as-4
- | |___ jboss-as-5
- | |___ stand-alone
- |
- |___ docs
- | |___ api
- | |___ quickstart-guide
- | |___ user-manual
- |
- |___ examples
- | |___ core
- | |___ javaee
- | |___ jms
- |
- |___ lib
- |
- |___ licenses
- |
- |___ schemas
- </programlisting>
- <itemizedlist>
- <listitem>
- <para><literal>bin</literal> -- binaries and scripts needed to run ActiveMQ.</para>
- </listitem>
- <listitem>
- <para><literal>config</literal> -- configuration files needed to configure ActiveMQ. This
- contains configurations to run ActiveMQ either in stand-alone or inside JBoss AS 4 and 5.
- Please refer to the reference guide for details on configuration. </para>
- </listitem>
- <listitem>
- <para><literal>docs</literal> -- guides and javadocs for ActiveMQ </para>
- </listitem>
- <listitem>
- <para><literal>examples</literal> -- JMS and Java EE examples. Please refer to the
- 'running examples' chapter for details on how to run them. </para>
- </listitem>
- <listitem>
- <para><literal>lib</literal> -- jars and libraries needed to run ActiveMQ </para>
- </listitem>
- <listitem>
- <para><literal>licenses</literal> -- licenses for ActiveMQ </para>
- </listitem>
- <listitem>
- <para><literal>schemas</literal> -- XML Schemas used to validate ActiveMQ configuration
- files</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/introduction.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/introduction.md b/docs/quickstart-guide/en/introduction.md
new file mode 100644
index 0000000..98f7a43
--- /dev/null
+++ b/docs/quickstart-guide/en/introduction.md
@@ -0,0 +1,13 @@
+Getting Started
+===============
+
+This short guide explains how to download, install and quickly get
+started with ActiveMQ.
+
+After downloading and installing we highly recommend you run the
+examples to get acquainted with ActiveMQ. We ship with over 70 examples
+demonstrating most of the features.
+
+This guide is not intended to be a replacement for the user manual. The
+user manual goes into much more depth, so please consult that for
+further information.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/introduction.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/introduction.xml b/docs/quickstart-guide/en/introduction.xml
deleted file mode 100644
index 516b4c0..0000000
--- a/docs/quickstart-guide/en/introduction.xml
+++ /dev/null
@@ -1,32 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="introduction">
- <title>Getting Started</title>
- <para>This short guide explains how to download, install and quickly get started with
- ActiveMQ.</para>
- <para>After downloading and installing we highly recommend you run the examples to get
- acquainted with ActiveMQ. We ship with over 70 examples demonstrating most of the
- features.</para>
- <para>This guide is not intended to be a replacement for the user manual. The user manual goes
- into much more depth, so please consult that for further information.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/master.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/master.xml b/docs/quickstart-guide/en/master.xml
deleted file mode 100644
index e69de29..0000000
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/migrate.sh
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/migrate.sh b/docs/quickstart-guide/en/migrate.sh
new file mode 100644
index 0000000..8758806
--- /dev/null
+++ b/docs/quickstart-guide/en/migrate.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+for i in `find . -name "*.xml"`; do
+ newFile=`echo $i | sed 's/xml/md/'`
+ echo creating $newFile
+ pandoc -f docbook -t markdown $i -o $newFile
+done
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/notice.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/notice.md b/docs/quickstart-guide/en/notice.md
new file mode 100644
index 0000000..2b2cdc2
--- /dev/null
+++ b/docs/quickstart-guide/en/notice.md
@@ -0,0 +1,17 @@
+Legal Notice
+============
+
+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.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/notice.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/notice.xml b/docs/quickstart-guide/en/notice.xml
deleted file mode 100644
index fede82d..0000000
--- a/docs/quickstart-guide/en/notice.xml
+++ /dev/null
@@ -1,40 +0,0 @@
-<!-- ============================================================================= -->
-<!-- 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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-
-<chapter id="notice">
- <title>Legal Notice</title>
-
- <para>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</para>
- <para></para>
- <para>http://www.apache.org/licenses/LICENSE-2.0</para>
- <para></para>
- <para>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.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/running.md
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/running.md b/docs/quickstart-guide/en/running.md
new file mode 100644
index 0000000..d12ddf6
--- /dev/null
+++ b/docs/quickstart-guide/en/running.md
@@ -0,0 +1,106 @@
+Starting The Server
+===================
+
+Standalone ActiveMQ
+===================
+
+To run a stand-alone server, open up a shell or command prompt and
+navigate into the `bin` directory. Then execute `./activemq run` (or
+`./activemq.cmd run` on Windows) and you should see the following output
+
+ bin$ ./activemq run
+
+ 11:05:06,589 INFO [org.apache.activemq.integration.bootstrap] HQ101000: Starting ActiveMQ Server
+ ...
+ 11:05:10,848 INFO [org.apache.activemq.core.server] HQ221001: ActiveMQ Server version 2.5.0.SNAPSHOT (Wild Hornet, 125) [e32ae252-52ee-11e4-a716-7785dc3013a3]
+
+
+ActiveMQ is now running.
+
+Both the run and the stop scripts use the config under
+`config/non-clustered` by default. The configuration can be changed by
+running `./activemq run xml:../config/non-clustered/bootstrap.xml` or
+another config of your choosing.
+
+The server can be stopped by running `./activemq stop`
+
+ActiveMQ In Wildfly
+===================
+
+ActiveMQ is the Default Messaging Provider in the [Wildfly Application
+Server](http://www.wildfly.org/) To run the server you need to run the
+standalone-full.xml configuration by running the command
+'./standalone.sh -c standalone-full.xml'. You will see something like:/
+
+ bin$ ./standalone.sh -c standalone-full.xml
+ =========================================================================
+
+ JBoss Bootstrap Environment
+
+ JBOSS_HOME: /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT
+
+ JAVA: java
+
+ JAVA_OPTS: -server -XX:+UseCompressedOops -Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true
+
+ =========================================================================
+
+ 14:47:33,642 INFO [org.jboss.modules] (main) JBoss Modules version 1.3.0.Final
+ 14:47:34,780 INFO [org.jboss.msc] (main) JBoss MSC version 1.2.0.Beta2
+ 14:47:34,875 INFO [org.jboss.as] (MSC service thread 1-6) JBAS015899: WildFly 8.0.0.Beta1-SNAPSHOT "WildFly" starting
+ 14:47:40,382 INFO [org.jboss.as.server] (Controller Boot Thread) JBAS015888: Creating http management service using socket-binding (management-http)
+ 14:47:40,383 INFO [org.xnio] (MSC service thread 1-15) XNIO version 3.1.0.CR7
+ 14:47:40,402 INFO [org.xnio.nio] (MSC service thread 1-15) XNIO NIO Implementation Version 3.1.0.CR7
+ 14:47:40,488 INFO [org.jboss.remoting] (MSC service thread 1-15) JBoss Remoting version 4.0.0.Beta1
+ 14:47:40,547 INFO [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 36) JBAS010280: Activating Infinispan subsystem.
+ 14:47:40,560 INFO [org.jboss.as.naming] (ServerService Thread Pool -- 47) JBAS011800: Activating Naming Subsystem
+ 14:47:40,560 INFO [org.jboss.as.security] (ServerService Thread Pool -- 52) JBAS013171: Activating Security Subsystem
+ 14:47:40,567 INFO [org.jboss.as.jacorb] (ServerService Thread Pool -- 37) JBAS016300: Activating JacORB Subsystem
+ 14:47:40,571 INFO [org.jboss.as.jsf] (ServerService Thread Pool -- 43) JBAS012605: Activated the following JSF Implementations: [main]
+ 14:47:40,574 INFO [org.jboss.as.webservices] (ServerService Thread Pool -- 56) JBAS015537: Activating WebServices Extension
+ 14:47:40,721 INFO [org.jboss.as.connector.logging] (MSC service thread 1-6) JBAS010408: Starting JCA Subsystem (IronJacamar 1.1.0.Final)
+ 14:47:41,321 INFO [org.jboss.as.naming] (MSC service thread 1-4) JBAS011802: Starting Naming Service
+ 14:47:41,323 INFO [org.jboss.as.mail.extension] (MSC service thread 1-11) JBAS015400: Bound mail session [java:jboss/mail/Default]
+ 14:47:41,552 INFO [org.wildfly.extension.undertow] (MSC service thread 1-10) JBAS017502: Undertow 1.0.0.Beta16 starting
+ 14:47:41,552 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 55) JBAS017502: Undertow 1.0.0.Beta16 starting
+ 14:47:41,573 INFO [org.jboss.as.security] (MSC service thread 1-6) JBAS013170: Current PicketBox version=4.0.17.SP1
+ 14:47:41,775 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 31) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
+ 14:47:41,777 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-16) JBAS010417: Started Driver service with driver-name = h2
+ 14:47:42,085 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 55) JBAS017527: Creating file handler for path /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/welcome-content
+ 14:47:42,086 INFO [org.wildfly.extension.undertow] (MSC service thread 1-2) JBAS017525: Started server default-server.
+ 14:47:42,088 INFO [org.wildfly.extension.undertow] (MSC service thread 1-13) JBAS017531: Host default-host starting
+ 14:47:42,471 INFO [org.wildfly.extension.undertow] (MSC service thread 1-7) JBAS017519: Undertow HTTP listener default listening on /127.0.0.1:8080
+ 14:47:42,823 INFO [org.jboss.as.server.deployment.scanner] (MSC service thread 1-10) JBAS015012: Started FileSystemDeploymentService for directory /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/deployments
+ 14:47:42,882 INFO [org.jboss.as.remoting] (MSC service thread 1-16) JBAS017100: Listening on 127.0.0.1:9999
+ 14:47:43,037 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221000: live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingjournal,bindingsDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingbindings,largeMessagesDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messaginglargemessages,pagingDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingpaging)
+ 14:47:43,062 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221006: Waiting to obtain live lock
+ 14:47:43,103 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221012: Using AIO Journal
+ 14:47:43,313 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support CORE
+ 14:47:43,426 INFO [org.jboss.ws.common.management] (MSC service thread 1-3) JBWS022052: Starting JBoss Web Services - Stack CXF Server 4.2.1.Final
+ 14:47:43,448 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support AMQP
+ 14:47:43,451 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support STOMP
+ 14:47:43,453 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support STOMP_WS
+ 14:47:43,567 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221034: Waiting to obtain live lock
+ 14:47:43,567 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221035: Live Server Obtained live lock
+ 14:47:43,777 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-8) JBAS010400: Bound data source [java:jboss/datasources/ExampleDS]
+ 14:47:43,781 INFO [org.jboss.as.jacorb] (MSC service thread 1-1) JBAS016330: CORBA ORB Service started
+ 14:47:44,115 INFO [org.jboss.as.jacorb] (MSC service thread 1-13) JBAS016328: CORBA Naming Service started
+ 14:47:44,345 INFO [org.wildfly.extension.undertow] (MSC service thread 1-3) JBAS018210: Register web context: /activemq-server
+ 14:47:44,361 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 127.0.0.1:5455 for CORE protocol
+ 14:47:44,362 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 127.0.0.1:5445 for CORE protocol
+ 14:47:44,364 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 org.apache.activemq.default.servlet:5445 for CORE protocol
+ 14:47:44,366 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221007: Server is now live
+ 14:47:44,366 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221001: ActiveMQ Server version 2.4.0.Beta2 (Andromedian Flyer, 123) [bcc1cd10-2bfb-11e3-ad5f-9f88840f9e1a]
+ 14:47:44,435 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 58) JBAS011601: Bound messaging object to jndi name java:/ConnectionFactory
+ 14:47:44,437 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 59) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/ServletConnectionFactory
+ 14:47:44,439 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 60) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/RemoteConnectionFactory
+ 14:47:44,462 INFO [org.jboss.as.connector.deployment] (MSC service thread 1-3) JBAS010406: Registered connection factory java:/JmsXA
+ 14:47:44,531 INFO [org.apache.activemq.ra] (MSC service thread 1-3) ActiveMQ resource adaptor started
+ 14:47:44,532 INFO [org.jboss.as.connector.services.resourceadapters.ResourceAdapterActivatorService$ResourceAdapterActivator] (MSC service thread 1-3) IJ020002: Deployed: file://RaActivatoractivemq-ra
+ 14:47:44,535 INFO [org.jboss.as.connector.deployment] (MSC service thread 1-12) JBAS010401: Bound JCA ConnectionFactory [java:/JmsXA]
+ 14:47:44,536 INFO [org.jboss.as.messaging] (MSC service thread 1-15) JBAS011601: Bound messaging object to jndi name java:jboss/DefaultJMSConnectionFactory
+ 14:47:44,719 INFO [org.jboss.as] (Controller Boot Thread) JBAS015961: Http management interface listening on http://127.0.0.1:9990/management
+ 14:47:44,720 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990
+ 14:47:44,721 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: WildFly 8.0.0.Beta1-SNAPSHOT "WildFly" started in 12184ms - Started 213 of 249 services (73 services are lazy, passive or on-demand)
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/en/running.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/en/running.xml b/docs/quickstart-guide/en/running.xml
deleted file mode 100644
index 161fa41..0000000
--- a/docs/quickstart-guide/en/running.xml
+++ /dev/null
@@ -1,124 +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_QuickStart_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="running">
- <title>Starting The Server</title>
- <section id="running.standalone">
- <title>Standalone ActiveMQ</title>
- <para>To run a stand-alone server, open up a shell or command prompt and navigate into the
- <literal>bin</literal> directory. Then execute <literal>./activemq run</literal> (or <literal
- >./activemq.cmd run</literal> on Windows) and you should see the following output </para>
- <programlisting>
- bin$ ./activemq run
-
- 11:05:06,589 INFO [org.apache.activemq.integration.bootstrap] HQ101000: Starting ActiveMQ Server
- ...
- 11:05:10,848 INFO [org.apache.activemq.core.server] HQ221001: ActiveMQ Server version 2.5.0.SNAPSHOT (Wild Hornet, 125) [e32ae252-52ee-11e4-a716-7785dc3013a3]
- </programlisting>
- <para>ActiveMQ is now running.</para>
- <para>Both the run and the stop scripts use the config under <literal
- >config/non-clustered</literal> by default. The configuration can be changed
- by running <literal>./activemq run xml:../config/non-clustered/bootstrap.xml</literal> or another config of
- your choosing.</para>
- <para>The server can be stopped by running <literal>./activemq stop</literal></para>
- </section>
- <section id="running.jboss.Wildfly">
- <title>ActiveMQ In Wildfly</title>
- <para>ActiveMQ is the Default Messaging Provider in the <ulink
- url="http://www.wildfly.org/" >Wildfly Application Server</ulink>
- To run the server you need to run the standalone-full.xml configuration by running the command './standalone.sh -c standalone-full.xml'.
- You will see something like:/</para>
- <programlisting>
- bin$ ./standalone.sh -c standalone-full.xml
- =========================================================================
-
- JBoss Bootstrap Environment
-
- JBOSS_HOME: /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT
-
- JAVA: java
-
- JAVA_OPTS: -server -XX:+UseCompressedOops -Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true
-
- =========================================================================
-
- 14:47:33,642 INFO [org.jboss.modules] (main) JBoss Modules version 1.3.0.Final
- 14:47:34,780 INFO [org.jboss.msc] (main) JBoss MSC version 1.2.0.Beta2
- 14:47:34,875 INFO [org.jboss.as] (MSC service thread 1-6) JBAS015899: WildFly 8.0.0.Beta1-SNAPSHOT "WildFly" starting
- 14:47:40,382 INFO [org.jboss.as.server] (Controller Boot Thread) JBAS015888: Creating http management service using socket-binding (management-http)
- 14:47:40,383 INFO [org.xnio] (MSC service thread 1-15) XNIO version 3.1.0.CR7
- 14:47:40,402 INFO [org.xnio.nio] (MSC service thread 1-15) XNIO NIO Implementation Version 3.1.0.CR7
- 14:47:40,488 INFO [org.jboss.remoting] (MSC service thread 1-15) JBoss Remoting version 4.0.0.Beta1
- 14:47:40,547 INFO [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 36) JBAS010280: Activating Infinispan subsystem.
- 14:47:40,560 INFO [org.jboss.as.naming] (ServerService Thread Pool -- 47) JBAS011800: Activating Naming Subsystem
- 14:47:40,560 INFO [org.jboss.as.security] (ServerService Thread Pool -- 52) JBAS013171: Activating Security Subsystem
- 14:47:40,567 INFO [org.jboss.as.jacorb] (ServerService Thread Pool -- 37) JBAS016300: Activating JacORB Subsystem
- 14:47:40,571 INFO [org.jboss.as.jsf] (ServerService Thread Pool -- 43) JBAS012605: Activated the following JSF Implementations: [main]
- 14:47:40,574 INFO [org.jboss.as.webservices] (ServerService Thread Pool -- 56) JBAS015537: Activating WebServices Extension
- 14:47:40,721 INFO [org.jboss.as.connector.logging] (MSC service thread 1-6) JBAS010408: Starting JCA Subsystem (IronJacamar 1.1.0.Final)
- 14:47:41,321 INFO [org.jboss.as.naming] (MSC service thread 1-4) JBAS011802: Starting Naming Service
- 14:47:41,323 INFO [org.jboss.as.mail.extension] (MSC service thread 1-11) JBAS015400: Bound mail session [java:jboss/mail/Default]
- 14:47:41,552 INFO [org.wildfly.extension.undertow] (MSC service thread 1-10) JBAS017502: Undertow 1.0.0.Beta16 starting
- 14:47:41,552 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 55) JBAS017502: Undertow 1.0.0.Beta16 starting
- 14:47:41,573 INFO [org.jboss.as.security] (MSC service thread 1-6) JBAS013170: Current PicketBox version=4.0.17.SP1
- 14:47:41,775 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread Pool -- 31) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
- 14:47:41,777 INFO [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-16) JBAS010417: Started Driver service with driver-name = h2
- 14:47:42,085 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 55) JBAS017527: Creating file handler for path /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/welcome-content
- 14:47:42,086 INFO [org.wildfly.extension.undertow] (MSC service thread 1-2) JBAS017525: Started server default-server.
- 14:47:42,088 INFO [org.wildfly.extension.undertow] (MSC service thread 1-13) JBAS017531: Host default-host starting
- 14:47:42,471 INFO [org.wildfly.extension.undertow] (MSC service thread 1-7) JBAS017519: Undertow HTTP listener default listening on /127.0.0.1:8080
- 14:47:42,823 INFO [org.jboss.as.server.deployment.scanner] (MSC service thread 1-10) JBAS015012: Started FileSystemDeploymentService for directory /home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/deployments
- 14:47:42,882 INFO [org.jboss.as.remoting] (MSC service thread 1-16) JBAS017100: Listening on 127.0.0.1:9999
- 14:47:43,037 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221000: live server is starting with configuration ActiveMQ Configuration (clustered=false,backup=false,sharedStore=true,journalDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingjournal,bindingsDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingbindings,largeMessagesDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messaginglargemessages,pagingDirectory=/home/andy/projects/wildfly/build/target/wildfly-8.0.0.Beta1-SNAPSHOT/standalone/data/messagingpaging)
- 14:47:43,062 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221006: Waiting to obtain live lock
- 14:47:43,103 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221012: Using AIO Journal
- 14:47:43,313 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support CORE
- 14:47:43,426 INFO [org.jboss.ws.common.management] (MSC service thread 1-3) JBWS022052: Starting JBoss Web Services - Stack CXF Server 4.2.1.Final
- 14:47:43,448 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support AMQP
- 14:47:43,451 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support STOMP
- 14:47:43,453 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ224067: Adding protocol support STOMP_WS
- 14:47:43,567 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221034: Waiting to obtain live lock
- 14:47:43,567 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221035: Live Server Obtained live lock
- 14:47:43,777 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-8) JBAS010400: Bound data source [java:jboss/datasources/ExampleDS]
- 14:47:43,781 INFO [org.jboss.as.jacorb] (MSC service thread 1-1) JBAS016330: CORBA ORB Service started
- 14:47:44,115 INFO [org.jboss.as.jacorb] (MSC service thread 1-13) JBAS016328: CORBA Naming Service started
- 14:47:44,345 INFO [org.wildfly.extension.undertow] (MSC service thread 1-3) JBAS018210: Register web context: /activemq-server
- 14:47:44,361 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 127.0.0.1:5455 for CORE protocol
- 14:47:44,362 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 127.0.0.1:5445 for CORE protocol
- 14:47:44,364 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221020: Started Netty Acceptor version 3.6.6.Final-90e1eb2 org.apache.activemq.default.servlet:5445 for CORE protocol
- 14:47:44,366 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221007: Server is now live
- 14:47:44,366 INFO [org.apache.activemq.core.server] (ServerService Thread Pool -- 58) HQ221001: ActiveMQ Server version 2.4.0.Beta2 (Andromedian Flyer, 123) [bcc1cd10-2bfb-11e3-ad5f-9f88840f9e1a]
- 14:47:44,435 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 58) JBAS011601: Bound messaging object to jndi name java:/ConnectionFactory
- 14:47:44,437 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 59) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/ServletConnectionFactory
- 14:47:44,439 INFO [org.jboss.as.messaging] (ServerService Thread Pool -- 60) JBAS011601: Bound messaging object to jndi name java:jboss/exported/jms/RemoteConnectionFactory
- 14:47:44,462 INFO [org.jboss.as.connector.deployment] (MSC service thread 1-3) JBAS010406: Registered connection factory java:/JmsXA
- 14:47:44,531 INFO [org.apache.activemq.ra] (MSC service thread 1-3) ActiveMQ resource adaptor started
- 14:47:44,532 INFO [org.jboss.as.connector.services.resourceadapters.ResourceAdapterActivatorService$ResourceAdapterActivator] (MSC service thread 1-3) IJ020002: Deployed: file://RaActivatoractivemq-ra
- 14:47:44,535 INFO [org.jboss.as.connector.deployment] (MSC service thread 1-12) JBAS010401: Bound JCA ConnectionFactory [java:/JmsXA]
- 14:47:44,536 INFO [org.jboss.as.messaging] (MSC service thread 1-15) JBAS011601: Bound messaging object to jndi name java:jboss/DefaultJMSConnectionFactory
- 14:47:44,719 INFO [org.jboss.as] (Controller Boot Thread) JBAS015961: Http management interface listening on http://127.0.0.1:9990/management
- 14:47:44,720 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990
- 14:47:44,721 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: WildFly 8.0.0.Beta1-SNAPSHOT "WildFly" started in 12184ms - Started 213 of 249 services (73 services are lazy, passive or on-demand)
-
- </programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/quickstart-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/quickstart-guide/pom.xml b/docs/quickstart-guide/pom.xml
deleted file mode 100644
index 932d813..0000000
--- a/docs/quickstart-guide/pom.xml
+++ /dev/null
@@ -1,300 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.activemq.docs</groupId>
- <artifactId>activemq-docs</artifactId>
- <version>6.0.0-SNAPSHOT</version>
- </parent>
-
- <groupId>org.apache.activemq.docs</groupId>
- <artifactId>quickstart-guide</artifactId>
- <version>1.0</version>
- <packaging>jdocbook</packaging>
- <name>quickstart-guide</name>
-
- <properties>
- <translation>en</translation>
- <docname>ActiveMQ_QuickStart_Guide</docname>
- <bookname>ActiveMQ QuickStart Guide</bookname>
- </properties>
-
- <repositories>
- <repository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </snapshots>
- </repository>
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository>
- <!--pluginRepository>
- <id>jboss-snapshot-repository-group</id>
- <name>JBoss Snapshot Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/snapshot/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository-->
- </pluginRepositories>
-
- <profiles>
-
- <!-- mvn compile -->
- <profile>
- <id>all</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.3.5</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml -->
- <profile>
- <id>html</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml-single -->
- <profile>
- <id>html-single</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Ppdf -->
- <profile>
- <id>pdf</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- </profiles>
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>2.0.2</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDirectory>${project.basedir}</sourceDirectory>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <masterTranslation>en</masterTranslation>
- <imageResource>
- <directory>${project.basedir}/en</directory>
- <includes>
- <include>images/*.png</include>
- </includes>
- </imageResource>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${pdf.name}</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <docbookVersion>1.72.0</docbookVersion>
- <localeSeparator>-</localeSeparator>
- <applyStandardInjectionValues>false</applyStandardInjectionValues>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </pluginManagement>
- </build>
- <!--<build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <sourceDirectory>.</sourceDirectory>
- <imageResource>
- <directory>${translation}</directory>
- <includes>
- <include>images/*</include>
- </includes>
- </imageResource>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
-
- </plugins>
- </build>-->
-
-</project>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/ActiveMQ_User_Manual.ent
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/ActiveMQ_User_Manual.ent b/docs/user-manual/en/ActiveMQ_User_Manual.ent
deleted file mode 100644
index d09b05b..0000000
--- a/docs/user-manual/en/ActiveMQ_User_Manual.ent
+++ /dev/null
@@ -1,22 +0,0 @@
-<!ENTITY PRODUCT "ActiveMQ">
-<!ENTITY BOOKID "ActiveMQ_QuickStart_Guide">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "Red Hat Inc.">
-<!ENTITY semi ";"><!--
- ~ 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.
- -->
-
-
[02/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-jms.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-jms.xml b/docs/user-manual/en/using-jms.xml
deleted file mode 100644
index fdf0729..0000000
--- a/docs/user-manual/en/using-jms.xml
+++ /dev/null
@@ -1,364 +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="using-jms">
- <title>Using JMS</title>
- <para>Although ActiveMQ provides a JMS agnostic messaging API, many users will be more
- comfortable using JMS.</para>
- <para>JMS is a very popular API standard for messaging, and most messaging systems provide a JMS
- API. If you are completely new to JMS we suggest you follow the<ulink
- url="http://docs.oracle.com/javaee/1.3/jms/tutorial"> Sun
- JMS tutorial</ulink> - a full JMS tutorial is out of scope for this guide.</para>
- <para>ActiveMQ also ships with a wide range of examples, many of which demonstrate JMS API usage.
- A good place to start would be to play around with the simple JMS Queue and Topic example,
- but we also provide examples for many other parts of the JMS API. A full description of the
- examples is available in <xref linkend="examples"/>.</para>
- <para>In this section we'll go through the main steps in configuring the server for JMS and
- creating a simple JMS program. We'll also show how to configure and use JNDI, and also how
- to use JMS with ActiveMQ without using any JNDI.</para>
- <section>
- <title>A simple ordering system</title>
- <para>For this chapter we're going to use a very simple ordering system as our example. It is
- a somewhat contrived example because of its extreme simplicity, but it serves to
- demonstrate the very basics of setting up and using JMS.</para>
- <para>We will have a single JMS Queue called <literal>OrderQueue</literal>, and we will have
- a single <literal>MessageProducer</literal> sending an order message to the queue and a
- single <literal>MessageConsumer</literal> consuming the order message from the
- queue.</para>
- <para>The queue will be a <literal>durable</literal> queue, i.e. it will survive a server
- restart or crash. We also want to pre-deploy the queue, i.e. specify the queue in the
- server JMS configuration so it is created automatically without us having to explicitly
- create it from the client.</para>
- </section>
- <section id="using-jms.jndi.configuration">
- <title>JNDI Configuration</title>
- <para>The JMS specification establishes the convention that <emphasis>administered
- objects</emphasis> (i.e. JMS queue, topic and connection factory instances) are made
- available via the JNDI API. Brokers are free to implement JNDI as they see fit assuming
- the implementation fits the API. ActiveMQ does not have a JNDI server. Rather, it uses a
- client-side JNDI implementation that relies on special properties set in the environment
- to construct the appropriate JMS objects. In other words, no objects are stored in JNDI
- on the ActiveMQ server. There are simply instantiated on the client based on the provided
- configuration. Let's look at the different kinds of administered objects and how to configure
- them.</para>
- <note>
- <para>The following configuration properties <emphasis>are strictly required when ActiveMQ
- is running in stand-alone mode</emphasis>. When ActiveMQ is integrated to an application
- server (e.g. Wildfly) the application server itself will almost certainly provide a JNDI
- client with its own properties.</para>
- </note>
- <section>
- <title>ConnectionFactory JNDI</title>
- <para>A JMS connection factory is used by the client to make connections to the server.
- It knows the location of the server it is connecting to, as well as many other
- configuration parameters.</para>
- <para>By default, a <literal>javax.naming.Context</literal> instance created using the
- <literal>org.apache.activemq.jndi.ActiveMQInitialContextFactory</literal> will automatically
- have the following connection factories available for lookup:</para>
- <itemizedlist>
- <listitem>
- <para><literal>ConnectionFactory</literal></para>
- </listitem>
- <listitem>
- <para><literal>XAConnectionFactory</literal></para>
- </listitem>
- <listitem>
- <para><literal>QueueConnectionFactory</literal></para>
- </listitem>
- <listitem>
- <para><literal>TopicConnectionFactory</literal></para>
- </listitem>
- </itemizedlist>
- <para>Here's a simple example of the JNDI context environment for a client looking up a connection factory
- to access an <emphasis>embedded</emphasis> instance of ActiveMQ:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory</programlisting>
- <para>It's really as simple as that. As noted previously, any JNDI context created with the
- <literal>ActiveMQInitialContextFactory</literal> will have a set of default connection factories
- available. Therefore, only the <literal>java.naming.factory.initial</literal> property is required
- to access an embedded broker.</para>
- <para>In certain situations there could be multiple server instances running within a particular JVM. In
- that situation each server would typically have an InVM acceptor with a unique server-ID. A client
- using JMS and JNDI can account for this by specifying a
- <literal>javax.naming.Context.PROVIDER_URL</literal> (<literal>String</literal> value of
- "java.naming.provider.url") in the JNDI environment like <literal>vm://2</literal> where
- <literal>2</literal> is the server-ID for acceptor.</para>
- <para>Here is a list of all the supported URL schemes:</para>
- <itemizedlist>
- <listitem><para><literal>vm</literal></para></listitem>
- <listitem><para><literal>tcp</literal></para></listitem>
- <listitem><para><literal>udp</literal></para></listitem>
- <listitem><para><literal>jgroups</literal></para></listitem>
- </itemizedlist>
- <para>Most clients won't be connecting to an embedded broker. Clients will most commonly connect
- across a network a remote broker. In that case the client can use the
- <literal>javax.naming.Context.PROVIDER_URL</literal> (<literal>String</literal> value of
- "java.naming.provider.url") in the JNDI environment to specify where to connect. Here's a simple
- example of a client configuring a connection factory to connect to a remote broker running on
- myhost:5445:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445</programlisting>
- <para>In the example above the client is using the <literal>tcp</literal> scheme for the provider URL.
- A client may also specify multiple comma-delimited host:port combinations in the URL (e.g.
- <literal>tcp://remote-host1:5445,remote-host2:5445</literal>). Whether there is one or many
- host:port combinations in the URL they are treated as the <emphasis>initial connector(s)</emphasis>
- for the underlying connection.</para>
- <para>The <literal>udp</literal> scheme is also supported which should use an host:port combination that
- matches the <literal>group-address</literal> and <literal>group-port</literal> from the corresponding
- <literal>broadcast-group</literal> configured on the ActiveMQ server(s).</para>
- <para>Each scheme has a specific set of properties which can be set using the traditional URL query string
- format (e.g. <literal>scheme://host:port?key1=value1&key2=value2</literal>) to customize the underlying
- transport mechanism. For example, if a client wanted to connect to a remote server using TCP and SSL
- it would use a <literal>Context.PROVIDER_URL</literal> of
- <literal>tcp://remote-host:5445?ssl-enabled=true</literal>.</para>
- <para>All the properties available for the <literal>tcp</literal> scheme are described in
- <link linkend="configuring-transports.netty">the documentation regarding the Netty transport</link>.</para>
- <para>The <literal>udp</literal> scheme supports 4 properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>local-address</literal> - If you are running with multiple network interfaces on the same
- machine, you may want to specify that the discovery group listens only only a specific interface. To
- do this you can specify the interface address with this parameter.</para>
- </listitem>
- <listitem>
- <para><literal>local-port</literal> - If you want to specify a local port to which the datagram socket is
- bound you can specify it here. Normally you would just use the default value of -1 which signifies
- that an anonymous port should be used. This parameter is always specified in conjunction with
- <literal>local-address</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>refresh-timeout</literal> - This is the period the discovery group waits after receiving
- the last broadcast from a particular server before removing that servers connector pair entry from its
- list. You would normally set this to a value significantly higher than the broadcast-period on the
- broadcast group otherwise servers might intermittently disappear from the list even though they are
- still broadcasting due to slight differences in timing. This parameter is optional, the default value
- is 10000 milliseconds (10 seconds).</para>
- </listitem>
- <listitem>
- <para><literal>discovery-initial-wait-timeout</literal> - If the connection factory is used immediately
- after creation then it may not have had enough time to received broadcasts from all the nodes in the
- cluster. On first usage, the connection factory will make sure it waits this long since creation
- before creating the first connection. The default value for this parameter is 10000 milliseconds.</para>
- </listitem>
- </itemizedlist>
- <para>Lastly, the <literal>jgroups</literal> scheme is supported which provides an alternative to the
- <literal>udp</literal> scheme for server discovery. The URL pattern is as follows
- <literal>jgroups://<jgroups-xml-conf-filename></literal> where
- <literal><jgroups-xml-conf-filename></literal> refers to an XML file on the classpath that contains
- the JGroups configuration.</para>
- <para>The <literal>refresh-timeout</literal> and <literal>discovery-initial-wait-timeout</literal> properties
- are supported just like with <literal>udp</literal>.</para>
- <para>Although a <literal>javax.naming.Context</literal> instance created using the
- <literal>org.apache.activemq.jndi.ActiveMQInitialContextFactory</literal> will automatically
- have some connection factories present, it is possible for a client to specify its own connection
- factories. This is done using the
- <literal>org.apache.activemq.jndi.ActiveMQInitialContextFactory.CONNECTION_FACTORY_NAMES</literal>
- property (String value of "connectionFactoryNames"). The value for this property is a comma delimited
- String of all the connection factories the client wishes to create. For example:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connectionFactoryNames=myConnectionFactory</programlisting>
- <para>In this example, the client is creating a connection factory named "myConnectionFactory." This
- replaces all the default connection factories so that only the "myConnectionFactory" connection factory
- is available to the client.</para>
- <para>Aside from the underlying transport, the underlying connection factory implementation can also be
- configured using special properties. To configure a particular connection factory the client would
- follow this pattern for the property name to set in the environment:
- <literal>connection.<connection-factory-name>.<property-name></literal>. For example, if the
- client wanted to customize the default connection factory "ConnectionFactory" to support
- high-availability then it would do this:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445
-connection.ConnectionFactory.ha=true</programlisting>
- <para>Any property available on the underlying
- <literal>org.apache.activemq.jms.client.ActiveMQConnectionFactory</literal> can be set this way in
- addition to the <literal>ha</literal> (boolean) and <literal>type</literal> (String) properties. Here
- are the different options for the <literal>type</literal>:</para>
- <table frame="topbot" id="using-jms.table.configure.factory.types">
- <title>Configuration for Connection Factory Types</title>
- <tgroup cols="3">
- <colspec colname="cftype" colnum="1"/>
- <colspec colname="interface" colnum="2"/>
- <thead>
- <row>
- <entry>type</entry>
- <entry>interface</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>CF (default)</entry>
- <entry>javax.jms.ConnectionFactory</entry>
- </row>
- <row>
- <entry>XA_CF</entry>
- <entry>javax.jms.XAConnectionFactory</entry>
- </row>
- <row>
- <entry>QUEUE_CF</entry>
- <entry>javax.jms.QueueConnectionFactory</entry>
- </row>
- <row>
- <entry>QUEUE_XA_CF</entry>
- <entry>javax.jms.XAQueueConnectionFactory</entry>
- </row>
- <row>
- <entry>TOPIC_CF</entry>
- <entry>javax.jms.TopicConnectionFactory</entry>
- </row>
- <row>
- <entry>TOPIC_XA_CF</entry>
- <entry>javax.jms.XATopicConnectionFactory</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Destination JNDI</title>
- <para>JMS destinations are also typically looked up via JNDI. As with connection factories, destinations can
- be configured using special properties in the JNDI context environment. The property
- <emphasis>name</emphasis> should follow the pattern: <literal>queue.<jndi-binding></literal> or
- <literal>topic.<jndi-binding></literal>. The property <emphasis>value</emphasis> should be the name
- of the queue hosted by the ActiveMQ server. For example, if the server had a JMS queue configured like
- so:</para>
- <programlisting>
-<queue name="OrderQueue"/></programlisting>
- <para>And if the client wanted to bind this queue to "queues/OrderQueue" then the JNDI properties would be
- configured like so:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445
-queue.queues/OrderQueue=OrderQueue</programlisting>
- <para>It is also possible to look-up JMS destinations which haven't been configured explicitly in the JNDI
- context environment. This is possible using <literal>dynamicQueues/</literal> or
- <literal>dynamicTopics/</literal> in the look-up string. For example, if the client wanted to look-up the
- aforementioned "OrderQueue" it could do so simply by using the string "dynamicQueues/OrderQueue". Note,
- the text that follows <literal>dynamicQueues/</literal> or <literal>dynamicTopics/</literal> must
- correspond <emphasis>exactly</emphasis> to the name of the destination on the server.</para>
- </section>
- <section>
- <title>The code</title>
- <para>Here's the code for the example:</para>
- <para>First we'll create a JNDI initial context from which to lookup our JMS objects. If the above
- properties are set in <literal>jndi.properties</literal> and it is on the classpath then any new, empty
- <literal>InitialContext</literal> will be initialized using those properties:</para>
- <programlisting>InitialContext ic = new InitialContext();</programlisting>
- <para>Now we'll look up the connection factory from which we can create connections to myhost:5445:</para>
- <programlisting>ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");</programlisting>
- <para>And look up the Queue:</para>
- <programlisting>Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue");</programlisting>
- <para>Next we create a JMS connection using the connection factory:</para>
- <programlisting>Connection connection = cf.createConnection();</programlisting>
- <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge
- mode:</para>
- <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
- <para>We create a MessageProducer that will send orders to the queue:</para>
- <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
- <para>And we create a MessageConsumer which will consume orders from the queue:</para>
- <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
- <para>We make sure we start the connection, or delivery won't occur on it:</para>
- <programlisting>connection.start();</programlisting>
- <para>We create a simple TextMessage and send it:</para>
- <programlisting>TextMessage message = session.createTextMessage("This is an order");
-producer.send(message);</programlisting>
- <para>And we consume the message:</para>
- <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
-System.out.println("Got order: " + receivedMessage.getText());</programlisting>
- <para>It is as simple as that. For a wide range of working JMS examples please see the
- examples directory in the distribution.</para>
- <warning>
- <para>Please note that JMS connections, sessions, producers and consumers are
- <emphasis>designed to be re-used</emphasis>.</para>
- <para>It is an anti-pattern to create new connections, sessions, producers and consumers
- for each message you produce or consume. If you do this, your application will
- perform very poorly. This is discussed further in the section on performance tuning
- <xref linkend="perf-tuning"/>.</para>
- </warning>
- </section>
- </section>
- <section>
- <title>Directly instantiating JMS Resources without using JNDI</title>
- <para>Although it is a very common JMS usage pattern to lookup JMS <emphasis>Administered
- Objects</emphasis> (that's JMS Queue, Topic and ConnectionFactory instances) from JNDI,
- in some cases you just think "Why do I need JNDI? Why can't I just instantiate these
- objects directly?"</para>
- <para>With ActiveMQ you can do exactly that. ActiveMQ supports the direct instantiation of JMS
- Queue, Topic and ConnectionFactory instances, so you don't have to use JNDI at
- all.</para>
- <para>For a full working example of direct instantiation please see the JMS examples in
- <xref linkend="examples"/>.</para>
- <para>Here's our simple example, rewritten to not use JNDI at all:</para>
- <para>We create the JMS ConnectionFactory object via the ActiveMQJMSClient Utility class,
- note we need to provide connection parameters and specify which transport we are using,
- for more information on connectors please see <xref linkend="configuring-transports"
- />.</para>
- <programlisting>
-TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
-ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);</programlisting>
- <para>We also create the JMS Queue object via the ActiveMQJMSClient Utility class:</para>
- <programlisting>Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");</programlisting>
- <para>Next we create a JMS connection using the connection factory:</para>
- <programlisting>Connection connection = cf.createConnection();</programlisting>
- <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge
- mode:</para>
- <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
- <para>We create a MessageProducer that will send orders to the queue:</para>
- <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
- <para>And we create a MessageConsumer which will consume orders from the queue:</para>
- <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
- <para>We make sure we start the connection, or delivery won't occur on it:</para>
- <programlisting>connection.start();</programlisting>
- <para>We create a simple TextMessage and send it:</para>
- <programlisting>TextMessage message = session.createTextMessage("This is an order");
-producer.send(message);</programlisting>
- <para>And we consume the message:</para>
- <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
-System.out.println("Got order: " + receivedMessage.getText());</programlisting>
- </section>
- <section id="using-jms.clientid">
- <title>Setting The Client ID</title>
- <para>This represents the client id for a JMS client and is needed for creating durable
- subscriptions. It is possible to configure this on the connection factory and can be set
- via the <literal>client-id</literal> element. Any connection created by this connection
- factory will have this set as its client id.</para>
- </section>
- <section id="using-jms.dupsokbatchsize">
- <title>Setting The Batch Size for DUPS_OK </title>
- <para>When the JMS acknowledge mode is set to <literal>DUPS_OK</literal> it is possible to
- configure the consumer so that it sends acknowledgements in batches rather that one at a
- time, saving valuable bandwidth. This can be configured via the connection factory via
- the <literal>dups-ok-batch-size</literal> element and is set in bytes. The default is
- 1024 * 1024 bytes = 1 MiB.</para>
- </section>
- <section id="using-jms.txbatchsize">
- <title>Setting The Transaction Batch Size</title>
- <para>When receiving messages in a transaction it is possible to configure the consumer to
- send acknowledgements in batches rather than individually saving valuable bandwidth.
- This can be configured on the connection factory via the <literal
- >transaction-batch-size</literal> element and is set in bytes. The default is 1024 *
- 1024.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-server.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-server.md b/docs/user-manual/en/using-server.md
new file mode 100644
index 0000000..9998646
--- /dev/null
+++ b/docs/user-manual/en/using-server.md
@@ -0,0 +1,204 @@
+Using the Server
+================
+
+This chapter will familiarise you with how to use the ActiveMQ server.
+
+We'll show where it is, how to start and stop it, and we'll describe the
+directory layout and what all the files are and what they do.
+
+For the remainder of this chapter when we talk about the ActiveMQ server
+we mean the ActiveMQ standalone server, in its default configuration
+with a JMS Service and JNDI service enabled.
+
+When running embedded in JBoss Application Server the layout may be
+slightly different but by-and-large will be the same.
+
+Starting and Stopping the standalone server
+===========================================
+
+In the distribution you will find a directory called `bin`.
+
+`cd` into that directory and you will find a Unix/Linux script called
+`activemq` and a Windows script called `activemq.cmd`.
+
+To start the ActiveMQ instance on Unix/Linux type `./activemq run`
+
+To start the ActiveMQ instance on Windows type `activemq.cmd run`
+
+These scripts are very simple and basically just set-up the classpath
+and some JVM parameters and bootstrap the server using
+[Airline](https://github.com/airlift/airline).
+
+To stop the ActiveMQ instance you will use the same `activemq` script.
+
+To run on Unix/Linux type `./activemq stop`
+
+To run on Windows type `activemq.cmd stop`
+
+Please note that ActiveMQ requires a Java 6 or later runtime to run.
+
+By default the `config/non-clustered/bootstrap.xml` configuration is
+used. The configuration can be changed e.g. by running
+`./activemq run -- xml:../config/clustered/bootstrap.xml` or another
+config of your choosing.
+
+Server JVM settings
+===================
+
+The run scripts set some JVM settings for tuning the garbage collection
+policy and heap size. We recommend using a parallel garbage collection
+algorithm to smooth out latency and minimise large GC pauses.
+
+By default ActiveMQ runs in a maximum of 1GiB of RAM. To increase the
+memory settings change the `-Xms` and `-Xmx` memory settings as you
+would for any Java program.
+
+If you wish to add any more JVM arguments or tune the existing ones, the
+run scripts are the place to do it.
+
+Pre-configured Options
+======================
+
+The distribution contains several standard configuration sets for
+running:
+
+- Non clustered stand-alone.
+
+- Clustered stand-alone
+
+- Replicated stand-alone
+
+- Shared-store stand-alone
+
+You can of course create your own configuration and specify any
+configuration when running the run script.
+
+Library Path
+============
+
+If you're using the [Asynchronous IO Journal](#aio-journal) on Linux,
+you need to specify `java.library.path` as a property on your Java
+options. This is done automatically in the scripts.
+
+If you don't specify `java.library.path` at your Java options then the
+JVM will use the environment variable `LD_LIBRARY_PATH`.
+
+System properties
+=================
+
+ActiveMQ can take a system property on the command line for configuring
+logging.
+
+For more information on configuring logging, please see ?.
+
+Configuration files
+===================
+
+The configuration file used to bootstrap the server (e.g.
+`bootstrap.xml` by default) references the specific broker configuration
+files.
+
+- `activemq-configuration.xml`. This is the main ActiveMQ
+ configuration file. All the parameters in this file are described in
+ ?. Please see ? for more information on this file.
+
+- `activemq-queues.xml`. This file contains predefined queues, queue
+ settings and security settings. The file is optional - all this
+ configuration can also live in `activemq-configuration.xml`. In
+ fact, the default configuration sets do not have a
+ `activemq-queues.xml` file. The purpose of allowing queues to be
+ configured in these files is to allow you to manage your queue
+ configuration over many files instead of being forced to maintain it
+ in a single file. There can be many `activemq-queues.xml` files on
+ the classpath. All will be loaded if found.
+
+- `activemq-users.xml` ActiveMQ ships with a basic security manager
+ implementation which obtains user credentials from the
+ `activemq-users.xml` file. This file contains user, password and
+ role information. For more information on security, please see ?.
+
+- `activemq-jms.xml` The distro configuration by default includes a
+ server side JMS service which mainly deploys JMS Queues, Topics and
+ ConnectionFactorys from this file into JNDI. If you're not using
+ JMS, or you don't need to deploy JMS objects on the server side,
+ then you don't need this file. For more information on using JMS,
+ please see ?.
+
+> **Note**
+>
+> The property `file-deployment-enabled` in the
+> `activemq-configuration.xml` configuration when set to false means
+> that the other configuration files are not loaded. This is true by
+> default.
+
+It is also possible to use system property substitution in all the
+configuration files. by replacing a value with the name of a system
+property. Here is an example of this with a connector configuration:
+
+ <connector name="netty">
+ <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
+ <param key="host" value="${activemq.remoting.netty.host:localhost}"/>
+ <param key="port" value="${activemq.remoting.netty.port:5445}"/>
+ </connector>
+
+Here you can see we have replaced 2 values with system properties
+`activemq.remoting.netty.host` and `activemq.remoting.netty.port`. These
+values will be replaced by the value found in the system property if
+there is one, if not they default back to localhost or 5445
+respectively. It is also possible to not supply a default. i.e.
+`${activemq.remoting.netty.host}`, however the system property *must* be
+supplied in that case.
+
+Bootstrap File
+==============
+
+The stand-alone server is basically a set of POJOs which are
+instantiated by Airline commands.
+
+The bootstrap file is very simple. Let's take a look at an example:
+
+ <broker xmlns="http://activemq.org/schema">
+
+ <file:core configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-configuration.xml"></core>
+ <file:jms configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-jms.xml"></jms>
+
+ <basic-security/>
+
+ <naming bindAddress="localhost" port="1099" rmiBindAddress="localhost" rmiPort="1098"/>
+
+ </broker>
+
+- core
+
+ Instantiates a core server using the configuration file from the
+ `configuration` attribute. This is the main broker POJO necessary to
+ do all the real messaging work.
+
+- jms
+
+ This deploys any JMS Objects such as JMS Queues, Topics and
+ ConnectionFactory instances from the `activemq-jms.xml` file
+ specified. It also provides a simple management API for manipulating
+ JMS Objects. On the whole it just translates and delegates its work
+ to the core server. If you don't need to deploy JMS Queues, Topics
+ and ConnectionFactories from server side configuration and don't
+ require the JMS management interface this can be disabled.
+
+- naming
+
+ Instantiates a naming server which implements JNDI. This is used by
+ JMS clients
+
+The main configuration file.
+============================
+
+The configuration for the ActiveMQ core server is contained in
+`activemq-configuration.xml`. This is what the FileConfiguration bean
+uses to configure the messaging server.
+
+There are many attributes which you can configure ActiveMQ. In most
+cases the defaults will do fine, in fact every attribute can be
+defaulted which means a file with a single empty `configuration` element
+is a valid configuration file. The different configuration will be
+explained throughout the manual or you can refer to the configuration
+reference [here](#configuration-index).
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-server.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-server.xml b/docs/user-manual/en/using-server.xml
deleted file mode 100644
index 3653711..0000000
--- a/docs/user-manual/en/using-server.xml
+++ /dev/null
@@ -1,208 +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="using-server">
- <title>Using the Server</title>
- <para>This chapter will familiarise you with how to use the ActiveMQ server.</para>
- <para>We'll show where it is, how to start and stop it, and we'll describe the directory layout
- and what all the files are and what they do.</para>
- <para>For the remainder of this chapter when we talk about the ActiveMQ server we mean the
- ActiveMQ standalone server, in its default configuration with a JMS Service and JNDI service
- enabled.</para>
- <para>When running embedded in JBoss Application Server the layout may be slightly different but
- by-and-large will be the same.</para>
- <section>
- <title>Starting and Stopping the standalone server</title>
- <para>In the distribution you will find a directory called <literal>bin</literal>.</para>
- <para><literal>cd</literal> into that directory and you will find a Unix/Linux script called
- <literal>activemq</literal> and a Windows script called <literal>activemq.cmd</literal>.</para>
- <para>To start the ActiveMQ instance on Unix/Linux type <literal>./activemq run</literal></para>
- <para>To start the ActiveMQ instance on Windows type <literal>activemq.cmd run</literal></para>
- <para>These scripts are very simple and basically just set-up the classpath and some JVM
- parameters and bootstrap the server using <ulink
- url="https://github.com/airlift/airline">Airline</ulink>.</para>
- <para>To stop the ActiveMQ instance you will use the same <literal>activemq</literal> script.</para>
- <para>To run on Unix/Linux type <literal>./activemq stop</literal></para>
- <para>To run on Windows type <literal>activemq.cmd stop</literal></para>
- <para>Please note that ActiveMQ requires a Java 6 or later runtime to run.</para>
- <para>By default the <literal>config/non-clustered/bootstrap.xml</literal> configuration is used. The
- configuration can be changed e.g. by running
- <literal>./activemq run -- xml:../config/clustered/bootstrap.xml</literal> or another config of
- your choosing.</para>
- </section>
- <section>
- <title>Server JVM settings</title>
- <para>The run scripts set some JVM settings for tuning the garbage collection policy
- and heap size. We recommend using a parallel garbage collection algorithm to smooth
- out latency and minimise large GC pauses.</para>
- <para>By default ActiveMQ runs in a maximum of 1GiB of RAM. To increase the memory settings
- change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings as you
- would for any Java program.</para>
- <para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts
- are the place to do it.</para>
- </section>
- <section>
- <title>Pre-configured Options</title>
- <para>The distribution contains several standard configuration sets for running:</para>
- <itemizedlist>
- <listitem>
- <para>Non clustered stand-alone.</para>
- </listitem>
- <listitem>
- <para>Clustered stand-alone</para>
- </listitem>
- <listitem>
- <para>Replicated stand-alone</para>
- </listitem>
- <listitem>
- <para>Shared-store stand-alone</para>
- </listitem>
- </itemizedlist>
- <para>You can of course create your own configuration and specify any configuration
- when running the run script.</para>
- </section>
- <section id="using-server.library.path">
- <title>Library Path</title>
- <para>If you're using the <link linkend="aio-journal">Asynchronous IO Journal</link> on
- Linux, you need to specify <literal>java.library.path</literal> as a property on your
- Java options. This is done automatically in the scripts.</para>
- <para>If you don't specify <literal>java.library.path</literal> at your Java options then
- the JVM will use the environment variable <literal>LD_LIBRARY_PATH</literal>.</para>
- </section>
- <section>
- <title>System properties</title>
- <para>ActiveMQ can take a system property on the command line for configuring logging.</para>
- <para>For more information on configuring logging, please see <xref linkend="logging"
- />.</para>
- </section>
- <section id="using-server.configuration">
- <title>Configuration files</title>
- <para>The configuration file used to bootstrap the server (e.g. <literal>bootstrap.xml</literal>
- by default) references the specific broker configuration files.</para>
- <itemizedlist>
- <listitem>
- <para><literal>activemq-configuration.xml</literal>. This is the main ActiveMQ
- configuration file. All the parameters in this file are described in <xref
- linkend="configuration-index"/>. Please see <xref
- linkend="usingserver.mainconfig"/> for more information on this file.</para>
- </listitem>
- <listitem>
- <para><literal>activemq-queues.xml</literal>. This file contains predefined queues,
- queue settings and security settings. The file is optional - all this
- configuration can also live in <literal>activemq-configuration.xml</literal>. In
- fact, the default configuration sets do not have a <literal
- >activemq-queues.xml</literal> file. The purpose of allowing queues to be
- configured in these files is to allow you to manage your queue configuration
- over many files instead of being forced to maintain it in a single file. There
- can be many <literal>activemq-queues.xml</literal> files on the classpath. All
- will be loaded if found.</para>
- </listitem>
- <listitem>
- <para><literal>activemq-users.xml</literal> ActiveMQ ships with a basic security
- manager implementation which obtains user credentials from the <literal
- >activemq-users.xml</literal> file. This file contains user, password and
- role information. For more information on security, please see <xref
- linkend="security"/>.</para>
- </listitem>
- <listitem>
- <para><literal>activemq-jms.xml</literal> The distro configuration by default
- includes a server side JMS service which mainly deploys JMS Queues, Topics and
- ConnectionFactorys from this file into JNDI. If you're not using JMS, or you
- don't need to deploy JMS objects on the server side, then you don't need this
- file. For more information on using JMS, please see <xref linkend="using-jms"
- />.</para>
- </listitem>
- </itemizedlist>
- <note>
- <para>The property <literal>file-deployment-enabled</literal> in the <literal
- >activemq-configuration.xml</literal> configuration when set to false means that
- the other configuration files are not loaded. This is true by default.</para>
- </note>
- <para>It is also possible to use system property substitution in all the configuration
- files. by replacing a value with the name of a system property. Here is an example of
- this with a connector configuration:</para>
- <programlisting>
-<connector name="netty">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
- <param key="host" value="${activemq.remoting.netty.host:localhost}"/>
- <param key="port" value="${activemq.remoting.netty.port:5445}"/>
-</connector></programlisting>
- <para>Here you can see we have replaced 2 values with system properties <literal
- >activemq.remoting.netty.host</literal> and <literal
- >activemq.remoting.netty.port</literal>. These values will be replaced by the value
- found in the system property if there is one, if not they default back to localhost or
- 5445 respectively. It is also possible to not supply a default. i.e. <literal
- >${activemq.remoting.netty.host}</literal>, however the system property
- <emphasis>must</emphasis> be supplied in that case.</para>
- </section>
- <section id="server.bootstrap.configuration">
- <title>Bootstrap File</title>
- <para>The stand-alone server is basically a set of POJOs which are instantiated by Airline commands.</para>
- <para>The bootstrap file is very simple. Let's take a look at an example:</para>
- <para>
- <programlisting>
-<broker xmlns="http://activemq.org/schema">
-
- <file:core configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-configuration.xml"></core>
- <file:jms configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-jms.xml"></jms>
-
- <basic-security/>
-
- <naming bindAddress="localhost" port="1099" rmiBindAddress="localhost" rmiPort="1098"/>
-
-</broker></programlisting>
- </para>
- <itemizedlist>
- <listitem>
- <para>core</para>
- <para>Instantiates a core server using the configuration file from the
- <literal>configuration</literal> attribute. This is the main broker POJO necessary
- to do all the real messaging work.</para>
- </listitem>
- <listitem id="jms">
- <para>jms</para>
- <para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory
- instances from the <literal>activemq-jms.xml</literal> file specified. It also
- provides a simple management API for manipulating JMS Objects. On the whole it
- just translates and delegates its work to the core server. If you don't need to
- deploy JMS Queues, Topics and ConnectionFactories from server side configuration
- and don't require the JMS management interface this can be disabled.</para>
- </listitem>
- <listitem>
- <para>naming</para>
- <para>Instantiates a naming server which implements JNDI. This is used by JMS
- clients</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="usingserver.mainconfig">
- <title>The main configuration file.</title>
- <para>The configuration for the ActiveMQ core server is contained in <literal
- >activemq-configuration.xml</literal>. This is what the FileConfiguration bean uses
- to configure the messaging server.</para>
- <para>There are many attributes which you can configure ActiveMQ. In most cases the defaults
- will do fine, in fact every attribute can be defaulted which means a file with a single
- empty <literal>configuration</literal> element is a valid configuration file. The
- different configuration will be explained throughout the manual or you can refer to the
- configuration reference <link linkend="configuration-index">here</link>.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/vertx-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/vertx-integration.md b/docs/user-manual/en/vertx-integration.md
new file mode 100644
index 0000000..0b89d79
--- /dev/null
+++ b/docs/user-manual/en/vertx-integration.md
@@ -0,0 +1,91 @@
+Vert.x Integration
+==================
+
+[Vert.x](http://vertx.io/) is a lightweight, high performance
+application platform for the JVM that's designed for modern mobile, web,
+and enterprise applications. Vert.x provides a distributed event bus
+that allows messages to be sent across vert.x instances and clients. You
+can now redirect and persist any vert.x messages to ActiveMQ and route
+those messages to a specified vertx address by configuring ActiveMQ
+vertx incoming and outgoing vertx connector services.
+
+Configuring a Vertx Incoming Connector Service
+==============================================
+
+Vertx Incoming Connector services receive messages from vertx event bus
+and route them to a ActiveMQ queue. Such a service can be configured as
+follows:
+
+ <connector-service name="vertx-incoming-connector">
+ <factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class>
+ <param key="host" value="127.0.0.1"/>
+ <param key="port" value="0"/>
+ <param key="queue" value="jms.queue.vertxQueue"/>
+ <param key="vertx-address" value="vertx.in.eventaddress"/>
+ </connector-service>
+
+
+Shown are the required params for the connector service:
+
+- `queue`. The name of the ActiveMQ queue to send message to.
+
+As well as these required paramaters there are the following optional
+parameters
+
+- `host`. The host name on which the vertx target container is
+ running. Default is localhost.
+
+- `port`. The port number to which the target vertx listens. Default
+ is zero.
+
+- `quorum-size`. The quorum size of the target vertx instance.
+
+- `ha-group`. The name of the ha-group of target vertx instance.
+ Default is `activemq`.
+
+- `vertx-address`. The vertx address to listen to. default is
+ org.apache.activemq.
+
+Configuring a Vertx Outgoing Connector Service
+==============================================
+
+Vertx Outgoing Connector services fetch vertx messages from a ActiveMQ
+queue and put them to vertx event bus. Such a service can be configured
+as follows:
+
+ <connector-service name="vertx-outgoing-connector">
+ <factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class>
+ <param key="host" value="127.0.0.1"/>
+ <param key="port" value="0"/>
+ <param key="queue" value="jms.queue.vertxQueue"/>
+ <param key="vertx-address" value="vertx.out.eventaddress"/>
+ <param key="publish" value="true"/>
+ </connector-service>
+
+
+Shown are the required params for the connector service:
+
+- `queue`. The name of the ActiveMQ queue to fetch message from.
+
+As well as these required paramaters there are the following optional
+parameters
+
+- `host`. The host name on which the vertx target container is
+ running. Default is localhost.
+
+- `port`. The port number to which the target vertx listens. Default
+ is zero.
+
+- `quorum-size`. The quorum size of the target vertx instance.
+
+- `ha-group`. The name of the ha-group of target vertx instance.
+ Default is `activemq`.
+
+- `vertx-address`. The vertx address to put messages to. default is
+ org.apache.activemq.
+
+- `publish`. How messages is sent to vertx event bus. "true" means
+ using publish style. "false" means using send style. Default is
+ false.
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/vertx-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/vertx-integration.xml b/docs/user-manual/en/vertx-integration.xml
deleted file mode 100644
index adcb612..0000000
--- a/docs/user-manual/en/vertx-integration.xml
+++ /dev/null
@@ -1,114 +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="vertx-integration">
- <title>Vert.x Integration</title>
- <para><ulink url="http://vertx.io/">Vert.x</ulink> is a lightweight, high performance application platform for the
- JVM that's designed for modern mobile, web, and enterprise applications. Vert.x provides a distributed event bus that
- allows messages to be sent across vert.x instances and clients. You can now redirect and persist any vert.x messages
- to ActiveMQ and route those messages to a specified vertx address by configuring ActiveMQ vertx incoming and outgoing
- vertx connector services.
- </para>
-
- <section>
- <title>Configuring a Vertx Incoming Connector Service</title>
- <para>Vertx Incoming Connector services receive messages from vertx event bus and route them to a ActiveMQ queue.
- Such a service can be configured as follows:</para>
- <programlisting>
- <connector-service name="vertx-incoming-connector">
- <factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class>
- <param key="host" value="127.0.0.1"/>
- <param key="port" value="0"/>
- <param key="queue" value="jms.queue.vertxQueue"/>
- <param key="vertx-address" value="vertx.in.eventaddress"/>
- </connector-service>
- </programlisting>
- <para>Shown are the required params for the connector service:</para>
- <itemizedlist>
- <listitem>
- <para><literal>queue</literal>. The name of the ActiveMQ queue to send message to.</para>
- </listitem>
- </itemizedlist>
- <para>As well as these required paramaters there are the following optional parameters</para>
- <itemizedlist>
- <listitem>
- <para><literal>host</literal>. The host name on which the vertx target container is running. Default is localhost.</para>
- </listitem>
- <listitem>
- <para><literal>port</literal>. The port number to which the target vertx listens. Default is zero.</para>
- </listitem>
- <listitem>
- <para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para>
- </listitem>
- <listitem>
- <para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>activemq</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>vertx-address</literal>. The vertx address to listen to. default is org.apache.activemq.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Configuring a Vertx Outgoing Connector Service</title>
- <para>Vertx Outgoing Connector services fetch vertx messages from a ActiveMQ queue and put them to vertx event bus.
- Such a service can be configured as follows:</para>
- <programlisting>
- <connector-service name="vertx-outgoing-connector">
- <factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class>
- <param key="host" value="127.0.0.1"/>
- <param key="port" value="0"/>
- <param key="queue" value="jms.queue.vertxQueue"/>
- <param key="vertx-address" value="vertx.out.eventaddress"/>
- <param key="publish" value="true"/>
- </connector-service>
- </programlisting>
- <para>Shown are the required params for the connector service:</para>
- <itemizedlist>
- <listitem>
- <para><literal>queue</literal>. The name of the ActiveMQ queue to fetch message from.</para>
- </listitem>
- </itemizedlist>
- <para>As well as these required paramaters there are the following optional parameters</para>
- <itemizedlist>
- <listitem>
- <para><literal>host</literal>. The host name on which the vertx target container is running. Default is localhost.</para>
- </listitem>
- <listitem>
- <para><literal>port</literal>. The port number to which the target vertx listens. Default is zero.</para>
- </listitem>
- <listitem>
- <para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para>
- </listitem>
- <listitem>
- <para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>activemq</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>vertx-address</literal>. The vertx address to put messages to. default is org.apache.activemq.</para>
- </listitem>
- <listitem>
- <para><literal>publish</literal>. How messages is sent to vertx event bus. "true" means using publish style.
- "false" means using send style. Default is false.</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/wildcard-routing.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/wildcard-routing.md b/docs/user-manual/en/wildcard-routing.md
new file mode 100644
index 0000000..cabf9bd
--- /dev/null
+++ b/docs/user-manual/en/wildcard-routing.md
@@ -0,0 +1,21 @@
+Routing Messages With Wild Cards
+================================
+
+ActiveMQ allows the routing of messages via wildcard addresses.
+
+If a queue is created with an address of say `queue.news.#` then it will
+receive any messages sent to addresses that match this, for instance
+`queue.news.europe` or `queue.news.usa` or `queue.news.usa.sport`. If
+you create a consumer on this queue, this allows a consumer to consume
+messages which are sent to a *hierarchy* of addresses.
+
+> **Note**
+>
+> In JMS terminology this allows "topic hierarchies" to be created.
+
+To enable this functionality set the property
+`wild-card-routing-enabled` in the `activemq-configuration.xml` file to
+`true`. This is `true` by default.
+
+For more information on the wild card syntax take a look at ? chapter,
+also see ?.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/wildcard-routing.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/wildcard-routing.xml b/docs/user-manual/en/wildcard-routing.xml
deleted file mode 100644
index e8ca400..0000000
--- a/docs/user-manual/en/wildcard-routing.xml
+++ /dev/null
@@ -1,42 +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="wildcard-routing">
- <title>Routing Messages With Wild Cards</title>
- <para>ActiveMQ allows the routing of messages via wildcard addresses.</para>
- <para>If a queue is created with an address of say <literal>queue.news.#</literal> then it
- will receive any messages sent to addresses that match this, for instance <literal
- >queue.news.europe</literal> or <literal>queue.news.usa</literal> or <literal
- >queue.news.usa.sport</literal>. If you create a consumer on this queue, this allows a consumer to consume messages which are
- sent to a <emphasis>hierarchy</emphasis> of addresses.</para>
- <note>
- <para>In JMS terminology this allows "topic hierarchies" to be created.</para>
- </note>
- <para>To enable this functionality set the property <literal>wild-card-routing-enabled</literal>
- in the <literal>activemq-configuration.xml</literal> file to <literal>true</literal>. This is
- <literal>true</literal> by default.</para>
- <para>For more information on the wild card syntax take a look at <xref
- linkend="wildcard-syntax" /> chapter, also see <xref
- linkend="topic-hierarchy-example" />.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/wildcard-syntax.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/wildcard-syntax.md b/docs/user-manual/en/wildcard-syntax.md
new file mode 100644
index 0000000..3fe7b37
--- /dev/null
+++ b/docs/user-manual/en/wildcard-syntax.md
@@ -0,0 +1,28 @@
+Understanding the ActiveMQ Wildcard Syntax
+==========================================
+
+ActiveMQ uses a specific syntax for representing wildcards in security
+settings, address settings and when creating consumers.
+
+The syntax is similar to that used by [AMQP](http://www.amqp.org).
+
+A ActiveMQ wildcard expression contains words delimited by the character
+'`.`' (full stop).
+
+The special characters '`#`' and '`*`' also have special meaning and can
+take the place of a word.
+
+The character '`#`' means 'match any sequence of zero or more words'.
+
+The character '`*`' means 'match a single word'.
+
+So the wildcard 'news.europe.\#' would match 'news.europe',
+'news.europe.sport', 'news.europe.politics', and
+'news.europe.politics.regional' but would not match 'news.usa',
+'news.usa.sport' nor 'entertainment'.
+
+The wildcard 'news.\*' would match 'news.europe', but not
+'news.europe.sport'.
+
+The wildcard 'news.\*.sport' would match 'news.europe.sport' and also
+'news.usa.sport', but not 'news.europe.politics'.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/wildcard-syntax.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/wildcard-syntax.xml b/docs/user-manual/en/wildcard-syntax.xml
deleted file mode 100644
index 4ad78bb..0000000
--- a/docs/user-manual/en/wildcard-syntax.xml
+++ /dev/null
@@ -1,43 +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="wildcard-syntax">
- <title>Understanding the ActiveMQ Wildcard Syntax</title>
- <para>ActiveMQ uses a specific syntax for representing wildcards in security settings,
- address settings and when creating consumers.</para>
- <para>The syntax is similar to that used by <ulink url="http://www.amqp.org">AMQP</ulink>.</para>
- <para>A ActiveMQ wildcard expression contains words delimited by the character '<literal
- >.</literal>' (full stop).</para>
- <para>The special characters '<literal>#</literal>' and '<literal>*</literal>' also have special
- meaning and can take the place of a word.</para>
- <para>The character '<literal>#</literal>' means 'match any sequence of zero or more
- words'.</para>
- <para>The character '<literal>*</literal>' means 'match a single word'.</para>
- <para>So the wildcard 'news.europe.#' would match 'news.europe', 'news.europe.sport',
- 'news.europe.politics', and 'news.europe.politics.regional' but would not match 'news.usa',
- 'news.usa.sport' nor 'entertainment'.</para>
- <para>The wildcard 'news.*' would match 'news.europe', but not 'news.europe.sport'.</para>
- <para>The wildcard 'news.*.sport' would match 'news.europe.sport' and also 'news.usa.sport', but
- not 'news.europe.politics'.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/pom.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/pom.xml b/docs/user-manual/pom.xml
deleted file mode 100644
index cf693f2..0000000
--- a/docs/user-manual/pom.xml
+++ /dev/null
@@ -1,365 +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.
- -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.activemq.docs</groupId>
- <artifactId>activemq-docs</artifactId>
- <version>6.0.0-SNAPSHOT</version>
- </parent>
-
- <groupId>org.apache.activemq.docs</groupId>
- <artifactId>user-manual</artifactId>
- <version>1.0</version>
- <packaging>jdocbook</packaging>
- <name>user-manual</name>
-
- <properties>
- <translation>en</translation>
- <docname>ActiveMQ_User_Manual</docname>
- <bookname>ActiveMQ User Manual</bookname>
- </properties>
-
- <repositories>
- <repository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- </snapshots>
- </repository>
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>jboss-public-repository-group</id>
- <name>JBoss Public Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/public/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository>
- <!--pluginRepository>
- <id>jboss-snapshot-repository-group</id>
- <name>JBoss Snapshot Maven Repository Group</name>
- <url>https://repository.jboss.org/nexus/content/groups/snapshot/</url>
- <layout>default</layout>
- <releases>
- <enabled>true</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository-->
- </pluginRepositories>
-
- <profiles>
-
- <!-- mvn compile -Phtml -->
- <profile>
- <id>html</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.3.5</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
- <!-- mvn compile -->
- <profile>
- <id>all</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.3.5</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Phtml-single -->
- <profile>
- <id>html-single</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.3.5</version>
- <extensions>true</extensions>
- </plugin>
- </plugins>
- </build>
- </profile>
-
- <!-- mvn compile -Ppdf -->
- <profile>
- <id>pdf</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.3.5</version>
- <extensions>true</extensions>
- <configuration>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${docname}.pdf</finalName>
- </format>
- </formats>
- </configuration>
- </plugin>
- </plugins>
- </build>
- </profile>
- </profiles>
-
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>2.0.2</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDirectory>${project.basedir}</sourceDirectory>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <masterTranslation>en</masterTranslation>
- <imageResource>
- <directory>${project.basedir}/en</directory>
- <includes>
- <include>images/*.png</include>
- <include>images/*.jpg</include>
- </includes>
- </imageResource>
- <formats>
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>${pdf.name}</finalName>
- </format>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <docbookVersion>1.72.0</docbookVersion>
- <localeSeparator>-</localeSeparator>
- <applyStandardInjectionValues>false</applyStandardInjectionValues>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>xml-maven-plugin</artifactId>
- <executions>
- <execution>
- <goals>
- <goal>transform</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <transformerFactory>net.sf.saxon.TransformerFactoryImpl</transformerFactory>
- <transformationSets>
- <transformationSet>
- <dir>../../activemq-server/src/main/resources/schema</dir>
- <stylesheet>./src/main/resources/schemaToTable.xsl</stylesheet>
- <includes>
- <include>activemq-configuration.xsd</include>
- </includes>
- <fileMappers>
- <fileMapper implementation="org.codehaus.plexus.components.io.filemappers.FileExtensionMapper">
- <targetExtension>.xml</targetExtension>
- </fileMapper>
- </fileMappers>
- </transformationSet>
- <transformationSet>
- <dir>../../activemq-jms-server/src/main/resources/schema</dir>
- <stylesheet>./src/main/resources/schemaToTable.xsl</stylesheet>
- <includes>
- <include>activemq-jms.xsd</include>
- </includes>
- <fileMappers>
- <fileMapper implementation="org.codehaus.plexus.components.io.filemappers.FileExtensionMapper">
- <targetExtension>.xml</targetExtension>
- </fileMapper>
- </fileMappers>
- </transformationSet>
- </transformationSets>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>net.sf.saxon</groupId>
- <artifactId>saxon</artifactId>
- <version>8.7</version>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <!--<build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.2.1</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss.pressgang</groupId>
- <artifactId>pressgang-xslt</artifactId>
- <version>1.2.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.1.1</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDocumentName>${docname}.xml</sourceDocumentName>
- <sourceDirectory>.</sourceDirectory>
- <imageResource>
- <directory>${translation}</directory>
- <includes>
- <include>images/*</include>
- </includes>
- </imageResource>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </build>-->
-</project>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/publican.cfg
----------------------------------------------------------------------
diff --git a/docs/user-manual/publican.cfg b/docs/user-manual/publican.cfg
deleted file mode 100644
index 821b348..0000000
--- a/docs/user-manual/publican.cfg
+++ /dev/null
@@ -1,7 +0,0 @@
-# Config::Simple 4.59
-# Tue Mar 29 06:11:07 2011
-
-xml_lang: en
-type: Book
-brand: common
-
[08/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/message-grouping.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/message-grouping.xml b/docs/user-manual/en/message-grouping.xml
deleted file mode 100644
index 6ed962b..0000000
--- a/docs/user-manual/en/message-grouping.xml
+++ /dev/null
@@ -1,195 +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="message-grouping">
- <title>Message Grouping</title>
- <para>Message groups are sets of messages that have the following characteristics:</para>
- <itemizedlist>
- <listitem>
- <para>Messages in a message group share the same group id, i.e. they have same group
- identifier property (<literal>JMSXGroupID</literal> for JMS, <literal
- >_HQ_GROUP_ID</literal> for ActiveMQ Core API).</para>
- </listitem>
- <listitem>
- <para>Messages in a message group are always consumed by the same consumer, even if there
- are many consumers on a queue. They pin all messages with the same group id to the same
- consumer. If that consumer closes another consumer is chosen and will receive all
- messages with the same group id.</para>
- </listitem>
- </itemizedlist>
- <para>Message groups are useful when you want all messages for a certain value of the property to
- be processed serially by the same consumer.</para>
- <para>An example might be orders for a certain stock. You may want orders for any particular
- stock to be processed serially by the same consumer. To do this you can create a pool of
- consumers (perhaps one for each stock, but less will work too), then set the stock name as the
- value of the _HQ_GROUP_ID property.</para>
- <para>This will ensure that all messages for a particular stock will always be processed by the
- same consumer.</para>
- <note>
- <para>Grouped messages can impact the concurrent processing of non-grouped messages due to the
- underlying FIFO semantics of a queue. For example, if there is a chunk of 100 grouped messages at
- the head of a queue followed by 1,000 non-grouped messages then all the grouped messages will need
- to be sent to the appropriate client (which is consuming those grouped messages serially) before
- any of the non-grouped messages can be consumed. The functional impact in this scenario is a
- temporary suspension of concurrent message processing while all the grouped messages are processed.
- This can be a performance bottleneck so keep it in mind when determining the size of your message
- groups, and consider whether or not you should isolate your grouped messages from your non-grouped
- messages.</para>
- </note>
- <section>
- <title>Using Core API</title>
- <para>The property name used to identify the message group is <literal
- >"_HQ_GROUP_ID"</literal> (or the constant <literal
- >MessageImpl.HDR_GROUP_ID</literal>). Alternatively, you can set <literal
- >autogroup</literal> to true on the <literal>SessionFactory</literal> which will pick a
- random unique id. </para>
- </section>
- <section id="message-grouping.jmsconfigure">
- <title>Using JMS</title>
- <para>The property name used to identify the message group is <literal
- >JMSXGroupID</literal>.</para>
- <programlisting>
- // send 2 messages in the same group to ensure the same
- // consumer will receive both
- Message message = ...
- message.setStringProperty("JMSXGroupID", "Group-0");
- producer.send(message);
-
- message = ...
- message.setStringProperty("JMSXGroupID", "Group-0");
- producer.send(message);</programlisting>
- <para>Alternatively, you can set <literal>autogroup</literal> to true on the
- <literal>ActiveMQConnectonFactory</literal> which will pick a random unique id. This can also be set in the
- JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple example using the
- "ConnectionFactory" connection factory which is available in the context by default</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.autoGroup=true</programlisting>
- <para>Alternatively you can set the group id via the connection factory. All messages sent
- with producers created via this connection factory will set the <literal
- >JMSXGroupID</literal> to the specified value on all messages sent. This can also be set in the
- JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple example using the
- "ConnectionFactory" connection factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.groupID=Group-0</programlisting>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.message-group"/> for an example which shows how message
- groups are configured and used with JMS.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.message-group2"/> for an example which shows how message
- groups are configured via a connection factory.</para>
- </section>
- <section>
- <title> Clustered Grouping</title>
- <para>Using message groups in a cluster is a bit more complex. This is because messages with a
- particular group id can arrive on any node so each node needs to know about which group
- id's are bound to which consumer on which node. The consumer handling messages for a
- particular group id may be on a different node of the cluster, so each node needs to know
- this information so it can route the message correctly to the node which has that consumer. </para>
- <para>To solve this there is the notion of a grouping handler. Each node will have its own
- grouping handler and when a messages is sent with a group id assigned, the handlers will
- decide between them which route the message should take.</para>
- <para id="message-grouping.type">There are 2 types of handlers; Local and Remote. Each cluster should choose 1 node to
- have a local grouping handler and all the other nodes should have remote handlers- it's the
- local handler that actually makes the decision as to what route should be used, all the
- other remote handlers converse with this. Here is a sample config for both types of
- handler, this should be configured in the <emphasis role="italic"
- >activemq-configuration.xml</emphasis>
- file.<programlisting>
-<grouping-handler name="my-grouping-handler">
- <type>LOCAL</type>
- <address>jms</address>
- <timeout>5000</timeout>
-</grouping-handler>
-
-<grouping-handler name="my-grouping-handler">
- <type>REMOTE</type>
- <address>jms</address>
- <timeout>5000</timeout>
-</grouping-handler></programlisting></para>
- <para id="message-grouping.address">The <emphasis role="italic">address</emphasis> attribute refers to a
- <link linkend="clusters.address">cluster connection and the address it uses</link>,
- refer to the clustering section on how to configure clusters. The
- <emphasis role="italic">timeout</emphasis> attribute referees to how long to wait for a
- decision to be made, an exception will be thrown during the send if this timeout is
- reached, this ensures that strict ordering is kept.</para>
- <para>The decision as to where a message should be routed to is initially proposed by the node
- that receives the message. The node will pick a suitable route as per the normal clustered
- routing conditions, i.e. round robin available queues, use a local queue first and choose a
- queue that has a consumer. If the proposal is accepted by the grouping handlers the node
- will route messages to this queue from that point on, if rejected an alternative route will
- be offered and the node will again route to that queue indefinitely. All other nodes will
- also route to the queue chosen at proposal time. Once the message arrives at the queue then
- normal single server message group semantics take over and the message is pinned to a
- consumer on that queue.</para>
- <para>You may have noticed that there is a single point of failure with the single local
- handler. If this node crashes then no decisions will be able to be made. Any messages sent
- will be not be delivered and an exception thrown. To avoid this happening Local Handlers
- can be replicated on another backup node. Simple create your back up node and configure it
- with the same Local handler.</para>
- <para/>
- <section>
- <title>Clustered Grouping Best Practices</title>
- <para>Some best practices should be followed when using clustered grouping:<orderedlist>
- <listitem>
- <para>Make sure your consumers are distributed evenly across the different nodes
- if possible. This is only an issue if you are creating and closing consumers
- regularly. Since messages are always routed to the same queue once pinned,
- removing a consumer from this queue may leave it with no consumers meaning the
- queue will just keep receiving the messages. Avoid closing consumers or make
- sure that you always have plenty of consumers, i.e., if you have 3 nodes have 3
- consumers.</para>
- </listitem>
- <listitem>
- <para>Use durable queues if possible. If queues are removed once a group is bound
- to it, then it is possible that other nodes may still try to route messages to
- it. This can be avoided by making sure that the queue is deleted by the session
- that is sending the messages. This means that when the next message is sent it
- is sent to the node where the queue was deleted meaning a new proposal can
- successfully take place. Alternatively you could just start using a different
- group id.</para>
- </listitem>
- <listitem>
- <para>Always make sure that the node that has the Local Grouping Handler is
- replicated. These means that on failover grouping will still occur.</para>
- </listitem>
- <listitem>
- <para>In case you are using group-timeouts, the remote node should have a smaller group-timeout with at least half
- of the value on the main coordinator. This is because this will determine how often the last-time-use
- value should be updated with a round trip for a request to the group between the nodes.</para>
- </listitem>
- </orderedlist></para>
- </section>
- <section>
- <title>Clustered Grouping Example</title>
- <para>See <xref linkend="examples.clustered.grouping"/> for an example of how to configure
- message groups with a ActiveMQ cluster</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/messaging-concepts.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/messaging-concepts.md b/docs/user-manual/en/messaging-concepts.md
new file mode 100644
index 0000000..284473b
--- /dev/null
+++ b/docs/user-manual/en/messaging-concepts.md
@@ -0,0 +1,312 @@
+Messaging Concepts
+==================
+
+ActiveMQ is an asynchronous messaging system, an example of [Message
+Oriented
+Middleware](http://en.wikipedia.org/wiki/Message_oriented_middleware) ,
+we'll just call them messaging systems in the remainder of this book.
+
+We'll first present a brief overview of what kind of things messaging
+systems do, where they're useful and the kind of concepts you'll hear
+about in the messaging world.
+
+If you're already familiar with what a messaging system is and what it's
+capable of, then you can skip this chapter.
+
+Messaging Concepts
+==================
+
+Messaging systems allow you to loosely couple heterogeneous systems
+together, whilst typically providing reliability, transactions and many
+other features.
+
+Unlike systems based on a [Remote Procedure
+Call](http://en.wikipedia.org/wiki/Remote_procedure_call) (RPC) pattern,
+messaging systems primarily use an asynchronous message passing pattern
+with no tight relationship between requests and responses. Most
+messaging systems also support a request-response mode but this is not a
+primary feature of messaging systems.
+
+Designing systems to be asynchronous from end-to-end allows you to
+really take advantage of your hardware resources, minimizing the amount
+of threads blocking on IO operations, and to use your network bandwidth
+to its full capacity. With an RPC approach you have to wait for a
+response for each request you make so are limited by the network round
+trip time, or *latency* of your network. With an asynchronous system you
+can pipeline flows of messages in different directions, so are limited
+by the network *bandwidth* not the latency. This typically allows you to
+create much higher performance applications.
+
+Messaging systems decouple the senders of messages from the consumers of
+messages. The senders and consumers of messages are completely
+independent and know nothing of each other. This allows you to create
+flexible, loosely coupled systems.
+
+Often, large enterprises use a messaging system to implement a message
+bus which loosely couples heterogeneous systems together. Message buses
+often form the core of an [Enterprise Service
+Bus](http://en.wikipedia.org/wiki/Enterprise_service_bus). (ESB). Using
+a message bus to de-couple disparate systems can allow the system to
+grow and adapt more easily. It also allows more flexibility to add new
+systems or retire old ones since they don't have brittle dependencies on
+each other.
+
+Messaging styles
+================
+
+Messaging systems normally support two main styles of asynchronous
+messaging: [message queue](http://en.wikipedia.org/wiki/Message_queue)
+messaging (also known as *point-to-point messaging*) and [publish
+subscribe](http://en.wikipedia.org/wiki/Publish_subscribe) messaging.
+We'll summarise them briefly here:
+
+The Message Queue Pattern
+-------------------------
+
+With this type of messaging you send a message to a queue. The message
+is then typically persisted to provide a guarantee of delivery, then
+some time later the messaging system delivers the message to a consumer.
+The consumer then processes the message and when it is done, it
+acknowledges the message. Once the message is acknowledged it disappears
+from the queue and is not available to be delivered again. If the system
+crashes before the messaging server receives an acknowledgement from the
+consumer, then on recovery, the message will be available to be
+delivered to a consumer again.
+
+With point-to-point messaging, there can be many consumers on the queue
+but a particular message will only ever be consumed by a maximum of one
+of them. Senders (also known as*producers*) to the queue are completely
+decoupled from receivers (also known as *consumers*) of the queue - they
+do not know of each other's existence.
+
+A classic example of point to point messaging would be an order queue in
+a company's book ordering system. Each order is represented as a message
+which is sent to the order queue. Let's imagine there are many front end
+ordering systems which send orders to the order queue. When a message
+arrives on the queue it is persisted - this ensures that if the server
+crashes the order is not lost. Let's also imagine there are many
+consumers on the order queue - each representing an instance of an order
+processing component - these can be on different physical machines but
+consuming from the same queue. The messaging system delivers each
+message to one and only one of the ordering processing components.
+Different messages can be processed by different order processors, but a
+single order is only processed by one order processor - this ensures
+orders aren't processed twice.
+
+As an order processor receives a message, it fulfills the order, sends
+order information to the warehouse system and then updates the order
+database with the order details. Once it's done that it acknowledges the
+message to tell the server that the order has been processed and can be
+forgotten about. Often the send to the warehouse system, update in
+database and acknowledgement will be completed in a single transaction
+to ensure [ACID](http://en.wikipedia.org/wiki/ACID) properties.
+
+The Publish-Subscribe Pattern
+-----------------------------
+
+With publish-subscribe messaging many senders can send messages to an
+entity on the server, often called a *topic* (e.g. in the JMS world).
+
+There can be many *subscriptions* on a topic, a subscription is just
+another word for a consumer of a topic. Each subscription receives a
+*copy* of *each* message sent to the topic. This differs from the
+message queue pattern where each message is only consumed by a single
+consumer.
+
+Subscriptions can optionally be *durable* which means they retain a copy
+of each message sent to the topic until the subscriber consumes them -
+even if the server crashes or is restarted in between. Non-durable
+subscriptions only last a maximum of the lifetime of the connection that
+created them.
+
+An example of publish-subscribe messaging would be a news feed. As news
+articles are created by different editors around the world they are sent
+to a news feed topic. There are many subscribers around the world who
+are interested in receiving news items - each one creates a subscription
+and the messaging system ensures that a copy of each news message is
+delivered to each subscription.
+
+Delivery guarantees
+===================
+
+A key feature of most messaging systems is *reliable messaging*. With
+reliable messaging the server gives a guarantee that the message will be
+delivered once and only once to each consumer of a queue or each durable
+subscription of a topic, even in the event of system failure. This is
+crucial for many businesses; e.g. you don't want your orders fulfilled
+more than once or any of your orders to be lost.
+
+In other cases you may not care about a once and only once delivery
+guarantee and are happy to cope with duplicate deliveries or lost
+messages - an example of this might be transient stock price updates -
+which are quickly superseded by the next update on the same stock. The
+messaging system allows you to configure which delivery guarantees you
+require.
+
+Transactions
+============
+
+Messaging systems typically support the sending and acknowledgement of
+multiple messages in a single local transaction. ActiveMQ also supports
+the sending and acknowledgement of message as part of a large global
+transaction - using the Java mapping of XA: JTA.
+
+Durability
+==========
+
+Messages are either durable or non durable. Durable messages will be
+persisted in permanent storage and will survive server failure or
+restart. Non durable messages will not survive server failure or
+restart. Examples of durable messages might be orders or trades, where
+they cannot be lost. An example of a non durable message might be a
+stock price update which is transitory and doesn't need to survive a
+restart.
+
+Messaging APIs and protocols
+============================
+
+How do client applications interact with messaging systems in order to
+send and consume messages?
+
+Several messaging systems provide their own proprietary APIs with which
+the client communicates with the messaging system.
+
+There are also some standard ways of operating with messaging systems
+and some emerging standards in this space.
+
+Let's take a brief look at these:
+
+Java Message Service (JMS)
+--------------------------
+
+[JMS](http://en.wikipedia.org/wiki/Java_Message_Service) is part of
+Sun's JEE specification. It's a Java API that encapsulates both message
+queue and publish-subscribe messaging patterns. JMS is a lowest common
+denominator specification - i.e. it was created to encapsulate common
+functionality of the already existing messaging systems that were
+available at the time of its creation.
+
+JMS is a very popular API and is implemented by most messaging systems.
+JMS is only available to clients running Java.
+
+JMS does not define a standard wire format - it only defines a
+programmatic API so JMS clients and servers from different vendors
+cannot directly interoperate since each will use the vendor's own
+internal wire protocol.
+
+ActiveMQ provides a fully compliant JMS 1.1 and JMS 2.0 API.
+
+System specific APIs
+--------------------
+
+Many systems provide their own programmatic API for which to interact
+with the messaging system. The advantage of this it allows the full set
+of system functionality to be exposed to the client application. API's
+like JMS are not normally rich enough to expose all the extra features
+that most messaging systems provide.
+
+ActiveMQ provides its own core client API for clients to use if they
+wish to have access to functionality over and above that accessible via
+the JMS API.
+
+RESTful API
+-----------
+
+[REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)
+approaches to messaging are showing a lot interest recently.
+
+It seems plausible that API standards for cloud computing may converge
+on a REST style set of interfaces and consequently a REST messaging
+approach is a very strong contender for becoming the de-facto method for
+messaging interoperability.
+
+With a REST approach messaging resources are manipulated as resources
+defined by a URI and typically using a simple set of operations on those
+resources, e.g. PUT, POST, GET etc. REST approaches to messaging often
+use HTTP as their underlying protocol.
+
+The advantage of a REST approach with HTTP is in its simplicity and the
+fact the internet is already tuned to deal with HTTP optimally.
+
+Please see ? for using ActiveMQ's RESTful interface.
+
+STOMP
+-----
+
+[Stomp](http://stomp.github.io/) is a very simple text protocol for
+interoperating with messaging systems. It defines a wire format, so
+theoretically any Stomp client can work with any messaging system that
+supports Stomp. Stomp clients are available in many different
+programming languages.
+
+Please see ? for using STOMP with ActiveMQ.
+
+AMQP
+----
+
+[AMQP](http://en.wikipedia.org/wiki/AMQP) is a specification for
+interoperable messaging. It also defines a wire format, so any AMQP
+client can work with any messaging system that supports AMQP. AMQP
+clients are available in many different programming languages.
+
+ActiveMQ implements the [AMQP
+1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp)
+specification. Any client that supports the 1.0 specification will be
+able to interact with ActiveMQ.
+
+High Availability
+=================
+
+High Availability (HA) means that the system should remain operational
+after failure of one or more of the servers. The degree of support for
+HA varies between various messaging systems.
+
+ActiveMQ provides automatic failover where your sessions are
+automatically reconnected to the backup server on event of live server
+failure.
+
+For more information on HA, please see ?.
+
+Clusters
+========
+
+Many messaging systems allow you to create groups of messaging servers
+called *clusters*. Clusters allow the load of sending and consuming
+messages to be spread over many servers. This allows your system to
+scale horizontally by adding new servers to the cluster.
+
+Degrees of support for clusters varies between messaging systems, with
+some systems having fairly basic clusters with the cluster members being
+hardly aware of each other.
+
+ActiveMQ provides very configurable state-of-the-art clustering model
+where messages can be intelligently load balanced between the servers in
+the cluster, according to the number of consumers on each node, and
+whether they are ready for messages.
+
+ActiveMQ also has the ability to automatically redistribute messages
+between nodes of a cluster to prevent starvation on any particular node.
+
+For full details on clustering, please see ?.
+
+Bridges and routing
+===================
+
+Some messaging systems allow isolated clusters or single nodes to be
+bridged together, typically over unreliable connections like a wide area
+network (WAN), or the internet.
+
+A bridge normally consumes from a queue on one server and forwards
+messages to another queue on a different server. Bridges cope with
+unreliable connections, automatically reconnecting when the connections
+becomes available again.
+
+ActiveMQ bridges can be configured with filter expressions to only
+forward certain messages, and transformation can also be hooked in.
+
+ActiveMQ also allows routing between queues to be configured in server
+side configuration. This allows complex routing networks to be set up
+forwarding or copying messages from one destination to another, forming
+a global network of interconnected brokers.
+
+For more information please see ? and ?.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/messaging-concepts.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/messaging-concepts.xml b/docs/user-manual/en/messaging-concepts.xml
deleted file mode 100644
index a744837..0000000
--- a/docs/user-manual/en/messaging-concepts.xml
+++ /dev/null
@@ -1,267 +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="messaging-concepts">
- <title>Messaging Concepts</title>
- <para>ActiveMQ is an asynchronous messaging system, an example of <ulink
- url="http://en.wikipedia.org/wiki/Message_oriented_middleware">Message Oriented
- Middleware</ulink> , we'll just call them messaging systems in the remainder of this
- book.</para>
- <para>We'll first present a brief overview of what kind of things messaging systems do,
- where they're useful and the kind of concepts you'll hear about in the messaging
- world.</para>
- <para>If you're already familiar with what a messaging system is and what it's capable of, then
- you can skip this chapter.</para>
- <section>
- <title>Messaging Concepts</title>
- <para>Messaging systems allow you to loosely couple heterogeneous systems together, whilst
- typically providing reliability, transactions and many other features.</para>
- <para>Unlike systems based on a <ulink
- url="http://en.wikipedia.org/wiki/Remote_procedure_call">Remote Procedure
- Call</ulink> (RPC) pattern, messaging systems primarily use an asynchronous message
- passing pattern with no tight relationship between requests and responses. Most
- messaging systems also support a request-response mode but this is not a primary feature
- of messaging systems.</para>
- <para>Designing systems to be asynchronous from end-to-end allows you to really take
- advantage of your hardware resources, minimizing the amount of threads blocking on IO
- operations, and to use your network bandwidth to its full capacity. With an RPC approach
- you have to wait for a response for each request you make so are limited by the network
- round trip time, or <emphasis role="italic">latency</emphasis> of your network. With an
- asynchronous system you can pipeline flows of messages in different directions, so are
- limited by the network <emphasis role="italic">bandwidth</emphasis> not the latency.
- This typically allows you to create much higher performance applications.</para>
- <para>Messaging systems decouple the senders of messages from the consumers of messages. The
- senders and consumers of messages are completely independent and know nothing of each
- other. This allows you to create flexible, loosely coupled systems.</para>
- <para>Often, large enterprises use a messaging system to implement a message bus which
- loosely couples heterogeneous systems together. Message buses often form the core of an
- <ulink url="http://en.wikipedia.org/wiki/Enterprise_service_bus">Enterprise Service
- Bus</ulink>. (ESB). Using a message bus to de-couple disparate systems can allow the
- system to grow and adapt more easily. It also allows more flexibility to add new systems
- or retire old ones since they don't have brittle dependencies on each other.</para>
- </section>
- <section>
- <title>Messaging styles</title>
- <para>Messaging systems normally support two main styles of asynchronous messaging: <ulink
- url="http://en.wikipedia.org/wiki/Message_queue"> message queue</ulink> messaging
- (also known as <emphasis role="italic">point-to-point messaging</emphasis>) and <ulink
- url="http://en.wikipedia.org/wiki/Publish_subscribe">publish subscribe</ulink>
- messaging. We'll summarise them briefly here:</para>
- <section>
- <title>The Message Queue Pattern</title>
- <para>With this type of messaging you send a message to a queue. The message is then
- typically persisted to provide a guarantee of delivery, then some time later the
- messaging system delivers the message to a consumer. The consumer then processes the
- message and when it is done, it acknowledges the message. Once the message is
- acknowledged it disappears from the queue and is not available to be delivered
- again. If the system crashes before the messaging server receives an acknowledgement
- from the consumer, then on recovery, the message will be available to be delivered
- to a consumer again.</para>
- <para>With point-to-point messaging, there can be many consumers on the queue but a
- particular message will only ever be consumed by a maximum of one of them. Senders
- (also known as<emphasis role="italic"> producers</emphasis>) to the queue are
- completely decoupled from receivers (also known as <emphasis role="italic"
- >consumers</emphasis>) of the queue - they do not know of each other's
- existence.</para>
- <para>A classic example of point to point messaging would be an order queue in a
- company's book ordering system. Each order is represented as a message which is sent
- to the order queue. Let's imagine there are many front end ordering systems which
- send orders to the order queue. When a message arrives on the queue it is persisted
- - this ensures that if the server crashes the order is not lost. Let's also imagine
- there are many consumers on the order queue - each representing an instance of an
- order processing component - these can be on different physical machines but
- consuming from the same queue. The messaging system delivers each message to one and
- only one of the ordering processing components. Different messages can be processed
- by different order processors, but a single order is only processed by one order
- processor - this ensures orders aren't processed twice.</para>
- <para>As an order processor receives a message, it fulfills the order, sends order
- information to the warehouse system and then updates the order database with the
- order details. Once it's done that it acknowledges the message to tell the server
- that the order has been processed and can be forgotten about. Often the send to the
- warehouse system, update in database and acknowledgement will be completed in a
- single transaction to ensure <ulink url="http://en.wikipedia.org/wiki/ACID"
- >ACID</ulink> properties.</para>
- </section>
- <section>
- <title>The Publish-Subscribe Pattern</title>
- <para>With publish-subscribe messaging many senders can send messages to an entity on
- the server, often called a <emphasis role="italic">topic</emphasis> (e.g. in the JMS
- world).</para>
- <para>There can be many <emphasis>subscriptions</emphasis> on a topic, a subscription is
- just another word for a consumer of a topic. Each subscription receives a
- <emphasis>copy</emphasis> of <emphasis role="italic">each</emphasis> message
- sent to the topic. This differs from the message queue pattern where each message is
- only consumed by a single consumer.</para>
- <para>Subscriptions can optionally be <emphasis role="italic">durable</emphasis> which
- means they retain a copy of each message sent to the topic until the subscriber
- consumes them - even if the server crashes or is restarted in between. Non-durable
- subscriptions only last a maximum of the lifetime of the connection that created
- them.</para>
- <para>An example of publish-subscribe messaging would be a news feed. As news articles
- are created by different editors around the world they are sent to a news feed
- topic. There are many subscribers around the world who are interested in receiving
- news items - each one creates a subscription and the messaging system ensures that a
- copy of each news message is delivered to each subscription.</para>
- </section>
- </section>
- <section>
- <title>Delivery guarantees</title>
- <para>A key feature of most messaging systems is <emphasis role="italic">reliable
- messaging</emphasis>. With reliable messaging the server gives a guarantee that the
- message will be delivered once and only once to each consumer of a queue or each durable
- subscription of a topic, even in the event of system failure. This is crucial for many
- businesses; e.g. you don't want your orders fulfilled more than once or any of your
- orders to be lost.</para>
- <para>In other cases you may not care about a once and only once delivery guarantee and are
- happy to cope with duplicate deliveries or lost messages - an example of this might be
- transient stock price updates - which are quickly superseded by the next update on the
- same stock. The messaging system allows you to configure which delivery guarantees you
- require.</para>
- </section>
- <section>
- <title>Transactions</title>
- <para>Messaging systems typically support the sending and acknowledgement of multiple
- messages in a single local transaction. ActiveMQ also supports the sending and
- acknowledgement of message as part of a large global transaction - using the Java
- mapping of XA: JTA.</para>
- </section>
- <section>
- <title>Durability</title>
- <para>Messages are either durable or non durable. Durable messages will be persisted in
- permanent storage and will survive server failure or restart. Non durable messages will
- not survive server failure or restart. Examples of durable messages might be orders or
- trades, where they cannot be lost. An example of a non durable message might be a stock
- price update which is transitory and doesn't need to survive a restart.</para>
- </section>
- <section>
- <title>Messaging APIs and protocols</title>
- <para>How do client applications interact with messaging systems in order to send and
- consume messages?</para>
- <para>Several messaging systems provide their own proprietary APIs with which the client
- communicates with the messaging system.</para>
- <para>There are also some standard ways of operating with messaging systems and some
- emerging standards in this space.</para>
- <para>Let's take a brief look at these:</para>
- <section>
- <title>Java Message Service (JMS)</title>
- <para><ulink url="http://en.wikipedia.org/wiki/Java_Message_Service">JMS</ulink> is part
- of Sun's JEE specification. It's a Java API that encapsulates both message queue and
- publish-subscribe messaging patterns. JMS is a lowest common denominator
- specification - i.e. it was created to encapsulate common functionality of the
- already existing messaging systems that were available at the time of its
- creation.</para>
- <para>JMS is a very popular API and is implemented by most messaging systems. JMS is
- only available to clients running Java.</para>
- <para>JMS does not define a standard wire format - it only defines a programmatic API so
- JMS clients and servers from different vendors cannot directly interoperate since
- each will use the vendor's own internal wire protocol.</para>
- <para>ActiveMQ provides a fully compliant JMS 1.1 and JMS 2.0 API.</para>
- </section>
- <section>
- <title>System specific APIs</title>
- <para>Many systems provide their own programmatic API for which to interact with the
- messaging system. The advantage of this it allows the full set of system
- functionality to be exposed to the client application. API's like JMS are not
- normally rich enough to expose all the extra features that most messaging systems
- provide.</para>
- <para>ActiveMQ provides its own core client API for clients to use if they wish to have
- access to functionality over and above that accessible via the JMS API.</para>
- </section>
- <section>
- <title>RESTful API</title>
- <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer"
- >REST</ulink> approaches to messaging are showing a lot interest
- recently.</para>
- <para>It seems plausible that API standards for cloud computing may converge on a REST
- style set of interfaces and consequently a REST messaging approach is a very strong
- contender for becoming the de-facto method for messaging interoperability.</para>
- <para>With a REST approach messaging resources are manipulated as resources defined by a
- URI and typically using a simple set of operations on those resources, e.g. PUT,
- POST, GET etc. REST approaches to messaging often use HTTP as their underlying
- protocol.</para>
- <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
- internet is already tuned to deal with HTTP optimally.</para>
- <para>Please see <xref linkend="rest"/> for using ActiveMQ's RESTful interface.</para>
- </section>
- <section>
- <title>STOMP</title>
- <para><ulink
- url="http://stomp.github.io/"
- >Stomp</ulink> is a very simple text protocol for interoperating with messaging
- systems. It defines a wire format, so theoretically any Stomp client can work with
- any messaging system that supports Stomp. Stomp clients are available in many
- different programming languages.</para>
- <para>Please see <xref linkend="stomp"/> for using STOMP with ActiveMQ.</para>
- </section>
- <section>
- <title>AMQP</title>
- <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is a specification for
- interoperable messaging. It also defines a wire format, so any AMQP client can work
- with any messaging system that supports AMQP. AMQP clients are available in many
- different programming languages.</para>
- <para>ActiveMQ implements the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink>
- specification. Any client that supports the 1.0 specification will be able to interact with ActiveMQ.</para>
- </section>
- </section>
- <section>
- <title>High Availability</title>
- <para>High Availability (HA) means that the system should remain operational after failure
- of one or more of the servers. The degree of support for HA varies between various
- messaging systems.</para>
- <para>ActiveMQ provides automatic failover where your sessions are automatically reconnected
- to the backup server on event of live server failure.</para>
- <para>For more information on HA, please see <xref linkend="ha"/>.</para>
- </section>
- <section>
- <title>Clusters</title>
- <para>Many messaging systems allow you to create groups of messaging servers called
- <emphasis role="italic">clusters</emphasis>. Clusters allow the load of sending and
- consuming messages to be spread over many servers. This allows your system to scale
- horizontally by adding new servers to the cluster.</para>
- <para>Degrees of support for clusters varies between messaging systems, with some systems
- having fairly basic clusters with the cluster members being hardly aware of each
- other.</para>
- <para>ActiveMQ provides very configurable state-of-the-art clustering model where messages
- can be intelligently load balanced between the servers in the cluster, according to the
- number of consumers on each node, and whether they are ready for messages.</para>
- <para>ActiveMQ also has the ability to automatically redistribute messages between nodes of a
- cluster to prevent starvation on any particular node.</para>
- <para>For full details on clustering, please see <xref linkend="clusters"/>.</para>
- </section>
- <section>
- <title>Bridges and routing</title>
- <para>Some messaging systems allow isolated clusters or single nodes to be bridged together,
- typically over unreliable connections like a wide area network (WAN), or the
- internet.</para>
- <para>A bridge normally consumes from a queue on one server and forwards messages to another
- queue on a different server. Bridges cope with unreliable connections, automatically
- reconnecting when the connections becomes available again.</para>
- <para>ActiveMQ bridges can be configured with filter expressions to only forward certain
- messages, and transformation can also be hooked in.</para>
- <para>ActiveMQ also allows routing between queues to be configured in server side
- configuration. This allows complex routing networks to be set up forwarding or copying
- messages from one destination to another, forming a global network of interconnected
- brokers.</para>
- <para>For more information please see <xref linkend="core-bridges"/> and <xref
- linkend="diverts"/>.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/notice.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/notice.md b/docs/user-manual/en/notice.md
new file mode 100644
index 0000000..2b2cdc2
--- /dev/null
+++ b/docs/user-manual/en/notice.md
@@ -0,0 +1,17 @@
+Legal Notice
+============
+
+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.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/notice.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/notice.xml b/docs/user-manual/en/notice.xml
deleted file mode 100644
index eba09cb..0000000
--- a/docs/user-manual/en/notice.xml
+++ /dev/null
@@ -1,39 +0,0 @@
-<!-- ============================================================================= -->
-<!-- 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="notice">
- <title>Legal Notice</title>
-
- <para>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
-</para>
- <para>http://www.apache.org/licenses/LICENSE-2.0</para>
- <para>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.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/paging.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/paging.md b/docs/user-manual/en/paging.md
new file mode 100644
index 0000000..392c9ae
--- /dev/null
+++ b/docs/user-manual/en/paging.md
@@ -0,0 +1,160 @@
+Paging
+======
+
+ActiveMQ transparently supports huge queues containing millions of
+messages while the server is running with limited memory.
+
+In such a situation it's not possible to store all of the queues in
+memory at any one time, so ActiveMQ transparently *pages* messages into
+and out of memory as they are needed, thus allowing massive queues with
+a low memory footprint.
+
+ActiveMQ will start paging messages to disk, when the size of all
+messages in memory for an address exceeds a configured maximum size.
+
+By default, ActiveMQ does not page messages - this must be explicitly
+configured to activate it.
+
+Page Files
+==========
+
+Messages are stored per address on the file system. Each address has an
+individual folder where messages are stored in multiple files (page
+files). Each file will contain messages up to a max configured size
+(`page-size-bytes`). The system will navigate on the files as needed,
+and it will remove the page file as soon as all the messages are
+acknowledged up to that point.
+
+Browsers will read through the page-cursor system.
+
+Consumers with selectors will also navigate through the page-files and
+it will ignore messages that don't match the criteria.
+
+Configuration
+=============
+
+You can configure the location of the paging folder
+
+Global paging parameters are specified on the main configuration file
+(`activemq-configuration.xml`).
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
+ ...
+ <paging-directory>/somewhere/paging-directory</paging-directory>
+ ...
+
+ Property Name Description Default
+ -------------------- --------------------------------------------------------------------------------------------------------------------------- -------------
+ `paging-directory` Where page files are stored. ActiveMQ will create one folder for each address being paged under this configured location. data/paging
+
+ : Paging Configuration Parameters
+
+Paging Mode
+===========
+
+As soon as messages delivered to an address exceed the configured size,
+that address alone goes into page mode.
+
+> **Note**
+>
+> Paging is done individually per address. If you configure a
+> max-size-bytes for an address, that means each matching address will
+> have a maximum size that you specified. It DOES NOT mean that the
+> total overall size of all matching addresses is limited to
+> max-size-bytes.
+
+Configuration
+-------------
+
+Configuration is done at the address settings, done at the main
+configuration file (`activemq-configuration.xml`).
+
+ <address-settings>
+ <address-setting match="jms.someaddress">
+ <max-size-bytes>104857600</max-size-bytes>
+ <page-size-bytes>10485760</page-size-bytes>
+ <address-full-policy>PAGE</address-full-policy>
+ </address-setting>
+ </address-settings>
+
+This is the list of available parameters on the address settings.
+
+ Property Name Description Default
+ ----------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ----------------------------------
+ `max-size-bytes` What's the max memory the address could have before entering on page mode. -1 (disabled)
+ `page-size-bytes` The size of each page file used on the paging system 10MiB (10 \* 1024 \* 1024 bytes)
+ `address-full-policy` This must be set to PAGE for paging to enable. If the value is PAGE then further messages will be paged to disk. If the value is DROP then further messages will be silently dropped. If the value is FAIL then the messages will be dropped and the client message producers will receive an exception. If the value is BLOCK then client message producers will block when they try and send further messages. PAGE
+ `page-max-cache-size` The system will keep up to \<`page-max-cache-size` page files in memory to optimize IO during paging navigation. 5
+
+ : Paging Address Settings
+
+Dropping messages
+=================
+
+Instead of paging messages when the max size is reached, an address can
+also be configured to just drop messages when the address is full.
+
+To do this just set the `address-full-policy` to `DROP` in the address
+settings
+
+Dropping messages and throwing an exception to producers
+========================================================
+
+Instead of paging messages when the max size is reached, an address can
+also be configured to drop messages and also throw an exception on the
+client-side when the address is full.
+
+To do this just set the `address-full-policy` to `FAIL` in the address
+settings
+
+Blocking producers
+==================
+
+Instead of paging messages when the max size is reached, an address can
+also be configured to block producers from sending further messages when
+the address is full, thus preventing the memory being exhausted on the
+server.
+
+When memory is freed up on the server, producers will automatically
+unblock and be able to continue sending.
+
+To do this just set the `address-full-policy` to `BLOCK` in the address
+settings
+
+In the default configuration, all addresses are configured to block
+producers after 10 MiB of data are in the address.
+
+Caution with Addresses with Multiple Queues
+===========================================
+
+When a message is routed to an address that has multiple queues bound to
+it, e.g. a JMS subscription in a Topic, there is only 1 copy of the
+message in memory. Each queue only deals with a reference to this.
+Because of this the memory is only freed up once all queues referencing
+the message have delivered it.
+
+If you have a single lazy subscription, the entire address will suffer
+IO performance hit as all the queues will have messages being sent
+through an extra storage on the paging system.
+
+For example:
+
+- An address has 10 queues
+
+- One of the queues does not deliver its messages (maybe because of a
+ slow consumer).
+
+- Messages continually arrive at the address and paging is started.
+
+- The other 9 queues are empty even though messages have been sent.
+
+In this example all the other 9 queues will be consuming messages from
+the page system. This may cause performance issues if this is an
+undesirable state.
+
+Example
+=======
+
+See ? for an example which shows how to use paging with ActiveMQ.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/paging.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/paging.xml b/docs/user-manual/en/paging.xml
deleted file mode 100644
index de03020..0000000
--- a/docs/user-manual/en/paging.xml
+++ /dev/null
@@ -1,215 +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="paging">
- <title>Paging</title>
- <para>ActiveMQ transparently supports huge queues containing millions of messages while the
- server is running with limited memory.</para>
- <para>In such a situation it's not possible to store all of the queues in memory at any one
- time, so ActiveMQ transparently <emphasis>pages</emphasis> messages into and out of memory as
- they are needed, thus allowing massive queues with a low memory footprint.</para>
- <para>ActiveMQ will start paging messages to disk, when the size of all messages in memory for an
- address exceeds a configured maximum size.</para>
- <para>By default, ActiveMQ does not page messages - this must be explicitly configured to
- activate it.</para>
- <section>
- <title>Page Files</title>
- <para>Messages are stored per address on the file system. Each address has an individual
- folder where messages are stored in multiple files (page files). Each file will contain
- messages up to a max configured size (<literal>page-size-bytes</literal>). The system
- will navigate on the files as needed, and it will remove the page file as soon as all
- the messages are acknowledged up to that point.</para>
- <para>Browsers will read through the page-cursor system.</para>
- <para>Consumers with selectors will also navigate through the page-files and it will ignore
- messages that don't match the criteria.</para>
- </section>
- <section id="paging.main.config">
- <title>Configuration</title>
- <para>You can configure the location of the paging folder</para>
- <para>Global paging parameters are specified on the main configuration file (<literal
- >activemq-configuration.xml</literal>).</para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
-...
-<paging-directory>/somewhere/paging-directory</paging-directory>
-...</programlisting>
- <para>
- <table frame="topbot">
- <title>Paging Configuration Parameters</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Description</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>paging-directory</literal></entry>
- <entry>Where page files are stored. ActiveMQ will create one folder for
- each address being paged under this configured location.</entry>
- <entry>data/paging</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- <section id="paging.mode">
- <title>Paging Mode</title>
- <para>As soon as messages delivered to an address exceed the configured size, that address
- alone goes into page mode.</para>
- <note>
- <para>Paging is done individually per address. If you configure a max-size-bytes for an
- address, that means each matching address will have a maximum size that you
- specified. It DOES NOT mean that the total overall size of all matching addresses is
- limited to max-size-bytes.</para>
- </note>
- <section>
- <title>Configuration</title>
- <para>Configuration is done at the address settings, done at the main configuration file
- (<literal>activemq-configuration.xml</literal>).</para>
- <programlisting>
-<address-settings>
- <address-setting match="jms.someaddress">
- <max-size-bytes>104857600</max-size-bytes>
- <page-size-bytes>10485760</page-size-bytes>
- <address-full-policy>PAGE</address-full-policy>
- </address-setting>
-</address-settings></programlisting>
- <para>This is the list of available parameters on the address settings.</para>
- <para>
- <table frame="topbot">
- <title>Paging Address Settings</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Description</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>max-size-bytes</literal></entry>
- <entry>What's the max memory the address could have before entering
- on page mode.</entry>
- <entry>-1 (disabled)</entry>
- </row>
- <row>
- <entry><literal>page-size-bytes</literal></entry>
- <entry>The size of each page file used on the paging system</entry>
- <entry>10MiB (10 * 1024 * 1024 bytes)</entry>
- </row>
- <row>
- <entry><literal>address-full-policy</literal></entry>
- <entry>This must be set to PAGE for paging to enable. If the value
- is PAGE then further messages will be paged to disk. If the
- value is DROP then further messages will be silently dropped. If
- the value is FAIL then the messages will be dropped and the client
- message producers will receive an exception. If the value is
- BLOCK then client message producers will block when they try and
- send further messages.</entry>
- <entry>PAGE</entry>
- </row>
- <row>
- <entry><literal>page-max-cache-size</literal></entry>
- <entry>The system will keep up to <<literal
- >page-max-cache-size</literal> page files in memory to
- optimize IO during paging navigation.</entry>
- <entry>5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- </section>
- <section>
- <title>Dropping messages</title>
- <para>Instead of paging messages when the max size is reached, an address can also be
- configured to just drop messages when the address is full.</para>
- <para>To do this just set the <literal>address-full-policy</literal> to <literal
- >DROP</literal> in the address settings</para>
- </section>
- <section>
- <title>Dropping messages and throwing an exception to producers</title>
- <para>Instead of paging messages when the max size is reached, an address can also be
- configured to drop messages and also throw an exception on the client-side
- when the address is full.</para>
- <para>To do this just set the <literal>address-full-policy</literal> to <literal
- >FAIL</literal> in the address settings</para>
- </section>
- <section>
- <title>Blocking producers</title>
- <para>Instead of paging messages when the max size is reached, an address can also be
- configured to block producers from sending further messages when the address is full,
- thus preventing the memory being exhausted on the server.</para>
- <para>When memory is freed up on the server, producers will automatically unblock and be
- able to continue sending.</para>
- <para>To do this just set the <literal>address-full-policy</literal> to <literal
- >BLOCK</literal> in the address settings</para>
- <para>In the default configuration, all addresses are configured to block producers after 10
- MiB of data are in the address.</para>
- </section>
- <section>
- <title>Caution with Addresses with Multiple Queues</title>
- <para>When a message is routed to an address that has multiple queues bound to it, e.g. a
- JMS subscription in a Topic, there is only 1 copy of the message in memory. Each queue
- only deals with a reference to this. Because of this the memory is only freed up once
- all queues referencing the message have delivered it.</para>
- <para>If you have a single lazy subscription, the entire address will suffer IO performance
- hit as all the queues will have messages being sent through an extra storage on the
- paging system.</para>
- <para>For example:</para>
- <itemizedlist>
- <listitem>
- <para>An address has 10 queues </para>
- </listitem>
- <listitem>
- <para>One of the queues does not deliver its messages (maybe because of a slow
- consumer).</para>
- </listitem>
- <listitem>
- <para>Messages continually arrive at the address and paging is started.</para>
- </listitem>
- <listitem>
- <para>The other 9 queues are empty even though messages have been sent.</para>
- </listitem>
- </itemizedlist>
- <para>In this example all the other 9 queues will be consuming messages from the page
- system. This may cause performance issues if this is an undesirable state.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.paging"/> for an example which shows how to use paging
- with ActiveMQ.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/perf-tuning.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/perf-tuning.md b/docs/user-manual/en/perf-tuning.md
new file mode 100644
index 0000000..f1410af
--- /dev/null
+++ b/docs/user-manual/en/perf-tuning.md
@@ -0,0 +1,255 @@
+Performance Tuning
+==================
+
+In this chapter we'll discuss how to tune ActiveMQ for optimum
+performance.
+
+Tuning persistence
+==================
+
+- Put the message journal on its own physical volume. If the disk is
+ shared with other processes e.g. transaction co-ordinator, database
+ or other journals which are also reading and writing from it, then
+ this may greatly reduce performance since the disk head may be
+ skipping all over the place between the different files. One of the
+ advantages of an append only journal is that disk head movement is
+ minimised - this advantage is destroyed if the disk is shared. If
+ you're using paging or large messages make sure they're ideally put
+ on separate volumes too.
+
+- Minimum number of journal files. Set `journal-min-files` to a number
+ of files that would fit your average sustainable rate. If you see
+ new files being created on the journal data directory too often,
+ i.e. lots of data is being persisted, you need to increase the
+ minimal number of files, this way the journal would reuse more files
+ instead of creating new data files.
+
+- Journal file size. The journal file size should be aligned to the
+ capacity of a cylinder on the disk. The default value 10MiB should
+ be enough on most systems.
+
+- Use AIO journal. If using Linux, try to keep your journal type as
+ AIO. AIO will scale better than Java NIO.
+
+- Tune `journal-buffer-timeout`. The timeout can be increased to
+ increase throughput at the expense of latency.
+
+- If you're running AIO you might be able to get some better
+ performance by increasing `journal-max-io`. DO NOT change this
+ parameter if you are running NIO.
+
+Tuning JMS
+==========
+
+There are a few areas where some tweaks can be done if you are using the
+JMS API
+
+- Disable message id. Use the `setDisableMessageID()` method on the
+ `MessageProducer` class to disable message ids if you don't need
+ them. This decreases the size of the message and also avoids the
+ overhead of creating a unique ID.
+
+- Disable message timestamp. Use the `setDisableMessageTimeStamp()`
+ method on the `MessageProducer` class to disable message timestamps
+ if you don't need them.
+
+- Avoid `ObjectMessage`. `ObjectMessage` is convenient but it comes at
+ a cost. The body of a `ObjectMessage` uses Java serialization to
+ serialize it to bytes. The Java serialized form of even small
+ objects is very verbose so takes up a lot of space on the wire, also
+ Java serialization is slow compared to custom marshalling
+ techniques. Only use `ObjectMessage` if you really can't use one of
+ the other message types, i.e. if you really don't know the type of
+ the payload until run-time.
+
+- Avoid `AUTO_ACKNOWLEDGE`. `AUTO_ACKNOWLEDGE` mode requires an
+ acknowledgement to be sent from the server for each message received
+ on the client, this means more traffic on the network. If you can,
+ use `DUPS_OK_ACKNOWLEDGE` or use `CLIENT_ACKNOWLEDGE` or a
+ transacted session and batch up many acknowledgements with one
+ acknowledge/commit.
+
+- Avoid durable messages. By default JMS messages are durable. If you
+ don't really need durable messages then set them to be non-durable.
+ Durable messages incur a lot more overhead in persisting them to
+ storage.
+
+- Batch many sends or acknowledgements in a single transaction.
+ ActiveMQ will only require a network round trip on the commit, not
+ on every send or acknowledgement.
+
+Other Tunings
+=============
+
+There are various other places in ActiveMQ where we can perform some
+tuning:
+
+- Use Asynchronous Send Acknowledgements. If you need to send durable
+ messages non transactionally and you need a guarantee that they have
+ reached the server by the time the call to send() returns, don't set
+ durable messages to be sent blocking, instead use asynchronous send
+ acknowledgements to get your acknowledgements of send back in a
+ separate stream, see ? for more information on this.
+
+- Use pre-acknowledge mode. With pre-acknowledge mode, messages are
+ acknowledged `before` they are sent to the client. This reduces the
+ amount of acknowledgement traffic on the wire. For more information
+ on this, see ?.
+
+- Disable security. You may get a small performance boost by disabling
+ security by setting the `security-enabled` parameter to `false` in
+ `activemq-configuration.xml`.
+
+- Disable persistence. If you don't need message persistence, turn it
+ off altogether by setting `persistence-enabled` to false in
+ `activemq-configuration.xml`.
+
+- Sync transactions lazily. Setting `journal-sync-transactional` to
+ `false` in `activemq-configuration.xml` can give you better
+ transactional persistent performance at the expense of some
+ possibility of loss of transactions on failure. See ? for more
+ information.
+
+- Sync non transactional lazily. Setting
+ `journal-sync-non-transactional` to `false` in
+ `activemq-configuration.xml` can give you better non-transactional
+ persistent performance at the expense of some possibility of loss of
+ durable messages on failure. See ? for more information.
+
+- Send messages non blocking. Setting `block-on-durable-send` and
+ `block-on-non-durable-send` to `false` in `activemq-jms.xml` (if
+ you're using JMS and JNDI) or directly on the ServerLocator. This
+ means you don't have to wait a whole network round trip for every
+ message sent. See ? for more information.
+
+- If you have very fast consumers, you can increase
+ consumer-window-size. This effectively disables consumer flow
+ control.
+
+- Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking)
+ on the server and the client side (see the chapter on configuring
+ transports for more information ?). NIO is much more scalable but
+ can give you some latency hit compared to old blocking IO. If you
+ need to be able to service many thousands of connections on the
+ server, then you should make sure you're using NIO on the server.
+ However, if don't expect many thousands of connections on the server
+ you can keep the server acceptors using old IO, and might get a
+ small performance advantage.
+
+- Use the core API not JMS. Using the JMS API you will have slightly
+ lower performance than using the core API, since all JMS operations
+ need to be translated into core operations before the server can
+ handle them. If using the core API try to use methods that take
+ `SimpleString` as much as possible. `SimpleString`, unlike
+ java.lang.String does not require copying before it is written to
+ the wire, so if you re-use `SimpleString` instances between calls
+ then you can avoid some unnecessary copying.
+
+Tuning Transport Settings
+=========================
+
+- TCP buffer sizes. If you have a fast network and fast machines you
+ may get a performance boost by increasing the TCP send and receive
+ buffer sizes. See the ? for more information on this.
+
+ > **Note**
+ >
+ > Note that some operating systems like later versions of Linux
+ > include TCP auto-tuning and setting TCP buffer sizes manually can
+ > prevent auto-tune from working and actually give you worse
+ > performance!
+
+- Increase limit on file handles on the server. If you expect a lot of
+ concurrent connections on your servers, or if clients are rapidly
+ opening and closing connections, you should make sure the user
+ running the server has permission to create sufficient file handles.
+
+ This varies from operating system to operating system. On Linux
+ systems you can increase the number of allowable open file handles
+ in the file `/etc/security/limits.conf` e.g. add the lines
+
+ serveruser soft nofile 20000
+ serveruser hard nofile 20000
+
+ This would allow up to 20000 file handles to be open by the user
+ `serveruser`.
+
+- Use `batch-delay` and set `direct-deliver` to false for the best
+ throughput for very small messages. ActiveMQ comes with a
+ preconfigured connector/acceptor pair (`netty-throughput`) in
+ `activemq-configuration.xml` and JMS connection factory
+ (`ThroughputConnectionFactory`) in `activemq-jms.xml`which can be
+ used to give the very best throughput, especially for small
+ messages. See the ? for more information on this.
+
+Tuning the VM
+=============
+
+We highly recommend you use the latest Java JVM for the best
+performance. We test internally using the Sun JVM, so some of these
+tunings won't apply to JDKs from other providers (e.g. IBM or JRockit)
+
+- Garbage collection. For smooth server operation we recommend using a
+ parallel garbage collection algorithm, e.g. using the JVM argument
+ `-XX:+UseParallelOldGC` on Sun JDKs.
+
+- Memory settings. Give as much memory as you can to the server.
+ ActiveMQ can run in low memory by using paging (described in ?) but
+ if it can run with all queues in RAM this will improve performance.
+ The amount of memory you require will depend on the size and number
+ of your queues and the size and number of your messages. Use the JVM
+ arguments `-Xms` and `-Xmx` to set server available RAM. We
+ recommend setting them to the same high value.
+
+- Aggressive options. Different JVMs provide different sets of JVM
+ tuning parameters, for the Sun Hotspot JVM the full list of options
+ is available
+ [here](http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html).
+ We recommend at least using `-XX:+AggressiveOpts` and`
+ -XX:+UseFastAccessorMethods`. You may get
+ some mileage with the other tuning parameters depending on your OS
+ platform and application usage patterns.
+
+Avoiding Anti-Patterns
+======================
+
+- Re-use connections / sessions / consumers / producers. Probably the
+ most common messaging anti-pattern we see is users who create a new
+ connection/session/producer for every message they send or every
+ message they consume. This is a poor use of resources. These objects
+ take time to create and may involve several network round trips.
+ Always re-use them.
+
+ > **Note**
+ >
+ > Some popular libraries such as the Spring JMS Template are known
+ > to use these anti-patterns. If you're using Spring JMS Template
+ > and you're getting poor performance you know why. Don't blame
+ > ActiveMQ! The Spring JMS Template can only safely be used in an
+ > app server which caches JMS sessions (e.g. using JCA), and only
+ > then for sending messages. It cannot be safely be used for
+ > synchronously consuming messages, even in an app server.
+
+- Avoid fat messages. Verbose formats such as XML take up a lot of
+ space on the wire and performance will suffer as result. Avoid XML
+ in message bodies if you can.
+
+- Don't create temporary queues for each request. This common
+ anti-pattern involves the temporary queue request-response pattern.
+ With the temporary queue request-response pattern a message is sent
+ to a target and a reply-to header is set with the address of a local
+ temporary queue. When the recipient receives the message they
+ process it then send back a response to the address specified in the
+ reply-to. A common mistake made with this pattern is to create a new
+ temporary queue on each message sent. This will drastically reduce
+ performance. Instead the temporary queue should be re-used for many
+ requests.
+
+- Don't use Message-Driven Beans for the sake of it. As soon as you
+ start using MDBs you are greatly increasing the codepath for each
+ message received compared to a straightforward message consumer,
+ since a lot of extra application server code is executed. Ask
+ yourself do you really need MDBs? Can you accomplish the same task
+ using just a normal message consumer?
+
+
[07/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/perf-tuning.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/perf-tuning.xml b/docs/user-manual/en/perf-tuning.xml
deleted file mode 100644
index d9ee18c..0000000
--- a/docs/user-manual/en/perf-tuning.xml
+++ /dev/null
@@ -1,304 +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="perf-tuning">
- <title>Performance Tuning</title>
- <para>In this chapter we'll discuss how to tune ActiveMQ for optimum performance.</para>
- <section>
- <title>Tuning persistence</title>
- <itemizedlist>
- <listitem>
- <para>Put the message journal on its own physical volume. If the disk is shared with
- other processes e.g. transaction co-ordinator, database or other journals which
- are also reading and writing from it, then this may greatly reduce performance
- since the disk head may be skipping all over the place between the different
- files. One of the advantages of an append only journal is that disk head
- movement is minimised - this advantage is destroyed if the disk is shared. If
- you're using paging or large messages make sure they're ideally put on separate
- volumes too.</para>
- </listitem>
- <listitem>
- <para>Minimum number of journal files. Set <literal>journal-min-files</literal> to a
- number of files that would fit your average sustainable rate. If you see new
- files being created on the journal data directory too often, i.e. lots of data
- is being persisted, you need to increase the minimal number of files, this way
- the journal would reuse more files instead of creating new data files.</para>
- </listitem>
- <listitem>
- <para>Journal file size. The journal file size should be aligned to the capacity of
- a cylinder on the disk. The default value 10MiB should be enough on most
- systems.</para>
- </listitem>
- <listitem>
- <para>Use AIO journal. If using Linux, try to keep your journal type as AIO. AIO
- will scale better than Java NIO.</para>
- </listitem>
- <listitem>
- <para>Tune <literal>journal-buffer-timeout</literal>. The timeout can be increased
- to increase throughput at the expense of latency.</para>
- </listitem>
- <listitem>
- <para>If you're running AIO you might be able to get some better performance by
- increasing <literal>journal-max-io</literal>. DO NOT change this parameter if
- you are running NIO.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning JMS</title>
- <para>There are a few areas where some tweaks can be done if you are using the JMS
- API</para>
- <itemizedlist>
- <listitem>
- <para>Disable message id. Use the <literal>setDisableMessageID()</literal> method on
- the <literal>MessageProducer</literal> class to disable message ids if you don't
- need them. This decreases the size of the message and also avoids the overhead
- of creating a unique ID.</para>
- </listitem>
- <listitem>
- <para>Disable message timestamp. Use the <literal
- >setDisableMessageTimeStamp()</literal> method on the <literal
- >MessageProducer</literal> class to disable message timestamps if you don't
- need them.</para>
- </listitem>
- <listitem>
- <para>Avoid <literal>ObjectMessage</literal>. <literal>ObjectMessage</literal> is
- convenient but it comes at a cost. The body of a <literal
- >ObjectMessage</literal> uses Java serialization to serialize it to bytes.
- The Java serialized form of even small objects is very verbose so takes up a lot
- of space on the wire, also Java serialization is slow compared to custom
- marshalling techniques. Only use <literal>ObjectMessage</literal> if you really
- can't use one of the other message types, i.e. if you really don't know the type
- of the payload until run-time.</para>
- </listitem>
- <listitem>
- <para>Avoid <literal>AUTO_ACKNOWLEDGE</literal>. <literal>AUTO_ACKNOWLEDGE</literal>
- mode requires an acknowledgement to be sent from the server for each message
- received on the client, this means more traffic on the network. If you can, use
- <literal>DUPS_OK_ACKNOWLEDGE</literal> or use <literal
- >CLIENT_ACKNOWLEDGE</literal> or a transacted session and batch up many
- acknowledgements with one acknowledge/commit. </para>
- </listitem>
- <listitem>
- <para>Avoid durable messages. By default JMS messages are durable. If you don't
- really need durable messages then set them to be non-durable. Durable messages
- incur a lot more overhead in persisting them to storage.</para>
- </listitem>
- <listitem>
- <para>Batch many sends or acknowledgements in a single transaction. ActiveMQ will
- only require a network round trip on the commit, not on every send or
- acknowledgement.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Other Tunings</title>
- <para>There are various other places in ActiveMQ where we can perform some tuning:</para>
- <itemizedlist>
- <listitem>
- <para>Use Asynchronous Send Acknowledgements. If you need to send durable messages
- non transactionally and you need a guarantee that they have reached the server
- by the time the call to send() returns, don't set durable messages to be sent
- blocking, instead use asynchronous send acknowledgements to get your
- acknowledgements of send back in a separate stream, see <xref
- linkend="send-guarantees"/> for more information on this.</para>
- </listitem>
- <listitem>
- <para>Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged
- <literal>before</literal> they are sent to the client. This reduces the
- amount of acknowledgement traffic on the wire. For more information on this, see
- <xref linkend="pre-acknowledge"/>.</para>
- </listitem>
- <listitem>
- <para>Disable security. You may get a small performance boost by disabling security
- by setting the <literal>security-enabled</literal> parameter to <literal
- >false</literal> in <literal>activemq-configuration.xml</literal>.</para>
- </listitem>
- <listitem>
- <para>Disable persistence. If you don't need message persistence, turn it off
- altogether by setting <literal>persistence-enabled</literal> to false in
- <literal>activemq-configuration.xml</literal>.</para>
- </listitem>
- <listitem>
- <para>Sync transactions lazily. Setting <literal
- >journal-sync-transactional</literal> to <literal>false</literal> in
- <literal>activemq-configuration.xml</literal> can give you better
- transactional persistent performance at the expense of some possibility of loss
- of transactions on failure. See <xref linkend="send-guarantees"/> for more
- information.</para>
- </listitem>
- <listitem>
- <para>Sync non transactional lazily. Setting <literal
- >journal-sync-non-transactional</literal> to <literal>false</literal> in
- <literal>activemq-configuration.xml</literal> can give you better
- non-transactional persistent performance at the expense of some possibility of
- loss of durable messages on failure. See <xref linkend="send-guarantees"/> for
- more information.</para>
- </listitem>
- <listitem>
- <para>Send messages non blocking. Setting <literal>block-on-durable-send</literal>
- and <literal>block-on-non-durable-send</literal> to <literal>false</literal> in
- <literal>activemq-jms.xml</literal> (if you're using JMS and JNDI) or
- directly on the ServerLocator. This means you don't have to wait a whole
- network round trip for every message sent. See <xref linkend="send-guarantees"/>
- for more information.</para>
- </listitem>
- <listitem>
- <para>If you have very fast consumers, you can increase consumer-window-size. This
- effectively disables consumer flow control.</para>
- </listitem>
- <listitem>
- <para>Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking) on the
- server and the client side (see the chapter on configuring transports for more
- information <xref linkend="configuring-transports"/>). NIO is much more scalable
- but can give you some latency hit compared to old blocking IO. If you need to be
- able to service many thousands of connections on the server, then you should
- make sure you're using NIO on the server. However, if don't expect many
- thousands of connections on the server you can keep the server acceptors using
- old IO, and might get a small performance advantage.</para>
- </listitem>
- <listitem>
- <para>Use the core API not JMS. Using the JMS API you will have slightly lower
- performance than using the core API, since all JMS operations need to be
- translated into core operations before the server can handle them. If using the
- core API try to use methods that take <literal>SimpleString</literal> as much as
- possible. <literal>SimpleString</literal>, unlike java.lang.String does not
- require copying before it is written to the wire, so if you re-use <literal
- >SimpleString</literal> instances between calls then you can avoid some
- unnecessary copying.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning Transport Settings</title>
- <itemizedlist>
- <listitem>
- <para>TCP buffer sizes. If you have a fast network and fast machines you may get a
- performance boost by increasing the TCP send and receive buffer sizes. See the
- <xref linkend="configuring-transports"/> for more information on this. </para>
- <note>
- <para> Note that some operating systems like later versions of Linux include TCP
- auto-tuning and setting TCP buffer sizes manually can prevent auto-tune from
- working and actually give you worse performance!</para>
- </note>
- </listitem>
- <listitem>
- <para>Increase limit on file handles on the server. If you expect a lot of
- concurrent connections on your servers, or if clients are rapidly opening and
- closing connections, you should make sure the user running the server has
- permission to create sufficient file handles.</para>
- <para>This varies from operating system to operating system. On Linux systems you
- can increase the number of allowable open file handles in the file <literal
- >/etc/security/limits.conf</literal> e.g. add the lines
- <programlisting>
-serveruser soft nofile 20000
-serveruser hard nofile 20000</programlisting>
- This would allow up to 20000 file handles to be open by the user <literal
- >serveruser</literal>. </para>
- </listitem>
- <listitem>
- <para>Use <literal>batch-delay</literal> and set <literal>direct-deliver</literal>
- to false for the best throughput for very small messages. ActiveMQ comes with a
- preconfigured connector/acceptor pair (<literal>netty-throughput</literal>) in
- <literal>activemq-configuration.xml</literal> and JMS connection factory
- (<literal>ThroughputConnectionFactory</literal>) in <literal
- >activemq-jms.xml</literal>which can be used to give the very best
- throughput, especially for small messages. See the <xref
- linkend="configuring-transports"/> for more information on this.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning the VM</title>
- <para>We highly recommend you use the latest Java JVM for the best performance. We test
- internally using the Sun JVM, so some of these tunings won't apply to JDKs from other
- providers (e.g. IBM or JRockit)</para>
- <itemizedlist>
- <listitem>
- <para>Garbage collection. For smooth server operation we recommend using a parallel
- garbage collection algorithm, e.g. using the JVM argument <literal
- >-XX:+UseParallelOldGC</literal> on Sun JDKs.</para>
- </listitem>
- <listitem id="perf-tuning.memory">
- <para>Memory settings. Give as much memory as you can to the server. ActiveMQ can run
- in low memory by using paging (described in <xref linkend="paging"/>) but if it
- can run with all queues in RAM this will improve performance. The amount of
- memory you require will depend on the size and number of your queues and the
- size and number of your messages. Use the JVM arguments <literal>-Xms</literal>
- and <literal>-Xmx</literal> to set server available RAM. We recommend setting
- them to the same high value.</para>
- </listitem>
- <listitem>
- <para>Aggressive options. Different JVMs provide different sets of JVM tuning
- parameters, for the Sun Hotspot JVM the full list of options is available <ulink
- url="http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html"
- >here</ulink>. We recommend at least using <literal
- >-XX:+AggressiveOpts</literal> and<literal>
- -XX:+UseFastAccessorMethods</literal>. You may get some mileage with the
- other tuning parameters depending on your OS platform and application usage
- patterns.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Avoiding Anti-Patterns</title>
- <itemizedlist>
- <listitem>
- <para>Re-use connections / sessions / consumers / producers. Probably the most
- common messaging anti-pattern we see is users who create a new
- connection/session/producer for every message they send or every message they
- consume. This is a poor use of resources. These objects take time to create and
- may involve several network round trips. Always re-use them.</para>
- <note>
- <para>Some popular libraries such as the Spring JMS Template are known to use
- these anti-patterns. If you're using Spring JMS Template and you're getting
- poor performance you know why. Don't blame ActiveMQ! The Spring JMS Template
- can only safely be used in an app server which caches JMS sessions (e.g.
- using JCA), and only then for sending messages. It cannot be safely be used
- for synchronously consuming messages, even in an app server. </para>
- </note>
- </listitem>
- <listitem>
- <para>Avoid fat messages. Verbose formats such as XML take up a lot of space on the
- wire and performance will suffer as result. Avoid XML in message bodies if you
- can.</para>
- </listitem>
- <listitem>
- <para>Don't create temporary queues for each request. This common anti-pattern
- involves the temporary queue request-response pattern. With the temporary queue
- request-response pattern a message is sent to a target and a reply-to header is
- set with the address of a local temporary queue. When the recipient receives the
- message they process it then send back a response to the address specified in
- the reply-to. A common mistake made with this pattern is to create a new
- temporary queue on each message sent. This will drastically reduce performance.
- Instead the temporary queue should be re-used for many requests.</para>
- </listitem>
- <listitem>
- <para>Don't use Message-Driven Beans for the sake of it. As soon as you start using
- MDBs you are greatly increasing the codepath for each message received compared
- to a straightforward message consumer, since a lot of extra application server
- code is executed. Ask yourself do you really need MDBs? Can you accomplish the
- same task using just a normal message consumer?</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/persistence.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/persistence.md b/docs/user-manual/en/persistence.md
new file mode 100644
index 0000000..e2c6f58
--- /dev/null
+++ b/docs/user-manual/en/persistence.md
@@ -0,0 +1,392 @@
+Persistence
+===========
+
+In this chapter we will describe how persistence works with ActiveMQ and
+how to configure it.
+
+ActiveMQ ships with a high performance journal. Since ActiveMQ handles
+its own persistence, rather than relying on a database or other 3rd
+party persistence engine it is very highly optimised for the specific
+messaging use cases.
+
+A ActiveMQ journal is an *append only* journal. It consists of a set of
+files on disk. Each file is pre-created to a fixed size and initially
+filled with padding. As operations are performed on the server, e.g. add
+message, update message, delete message, records are appended to the
+journal. When one journal file is full we move to the next one.
+
+Because records are only appended, i.e. added to the end of the journal
+we minimise disk head movement, i.e. we minimise random access
+operations which is typically the slowest operation on a disk.
+
+Making the file size configurable means that an optimal size can be
+chosen, i.e. making each file fit on a disk cylinder. Modern disk
+topologies are complex and we are not in control over which cylinder(s)
+the file is mapped onto so this is not an exact science. But by
+minimising the number of disk cylinders the file is using, we can
+minimise the amount of disk head movement, since an entire disk cylinder
+is accessible simply by the disk rotating - the head does not have to
+move.
+
+As delete records are added to the journal, ActiveMQ has a sophisticated
+file garbage collection algorithm which can determine if a particular
+journal file is needed any more - i.e. has all its data been deleted in
+the same or other files. If so, the file can be reclaimed and re-used.
+
+ActiveMQ also has a compaction algorithm which removes dead space from
+the journal and compresses up the data so it takes up less files on
+disk.
+
+The journal also fully supports transactional operation if required,
+supporting both local and XA transactions.
+
+The majority of the journal is written in Java, however we abstract out
+the interaction with the actual file system to allow different pluggable
+implementations. ActiveMQ ships with two implementations:
+
+- Java [NIO](http://en.wikipedia.org/wiki/New_I/O).
+
+ The first implementation uses standard Java NIO to interface with
+ the file system. This provides extremely good performance and runs
+ on any platform where there's a Java 6+ runtime.
+
+- Linux Asynchronous IO
+
+ The second implementation uses a thin native code wrapper to talk to
+ the Linux asynchronous IO library (AIO). With AIO, ActiveMQ will be
+ called back when the data has made it to disk, allowing us to avoid
+ explicit syncs altogether and simply send back confirmation of
+ completion when AIO informs us that the data has been persisted.
+
+ Using AIO will typically provide even better performance than using
+ Java NIO.
+
+ The AIO journal is only available when running Linux kernel 2.6 or
+ later and after having installed libaio (if it's not already
+ installed). For instructions on how to install libaio please see ?.
+
+ Also, please note that AIO will only work with the following file
+ systems: ext2, ext3, ext4, jfs, xfs. With other file systems, e.g.
+ NFS it may appear to work, but it will fall back to a slower
+ synchronous behaviour. Don't put the journal on a NFS share!
+
+ For more information on libaio please see ?.
+
+ libaio is part of the kernel project.
+
+The standard ActiveMQ core server uses two instances of the journal:
+
+- Bindings journal.
+
+ This journal is used to store bindings related data. That includes
+ the set of queues that are deployed on the server and their
+ attributes. It also stores data such as id sequence counters.
+
+ The bindings journal is always a NIO journal as it is typically low
+ throughput compared to the message journal.
+
+ The files on this journal are prefixed as `activemq-bindings`. Each
+ file has a `bindings` extension. File size is `1048576`, and it is
+ located at the bindings folder.
+
+- JMS journal.
+
+ This journal instance stores all JMS related data, This is basically
+ any JMS Queues, Topics and Connection Factories and any JNDI
+ bindings for these resources.
+
+ Any JMS Resources created via the management API will be persisted
+ to this journal. Any resources configured via configuration files
+ will not. The JMS Journal will only be created if JMS is being used.
+
+ The files on this journal are prefixed as `activemq-jms`. Each file
+ has a `jms` extension. File size is `1048576`, and it is located at
+ the bindings folder.
+
+- Message journal.
+
+ This journal instance stores all message related data, including the
+ message themselves and also duplicate-id caches.
+
+ By default ActiveMQ will try and use an AIO journal. If AIO is not
+ available, e.g. the platform is not Linux with the correct kernel
+ version or AIO has not been installed then it will automatically
+ fall back to using Java NIO which is available on any Java platform.
+
+ The files on this journal are prefixed as `activemq-data`. Each file
+ has a `hq` extension. File size is by the default `10485760`
+ (configurable), and it is located at the journal folder.
+
+For large messages, ActiveMQ persists them outside the message journal.
+This is discussed in ?.
+
+ActiveMQ can also be configured to page messages to disk in low memory
+situations. This is discussed in ?.
+
+If no persistence is required at all, ActiveMQ can also be configured
+not to persist any data at all to storage as discussed in ?.
+
+Configuring the bindings journal
+================================
+
+The bindings journal is configured using the following attributes in
+`activemq-configuration.xml`
+
+- `bindings-directory`
+
+ This is the directory in which the bindings journal lives. The
+ default value is `data/bindings`.
+
+- `create-bindings-dir`
+
+ If this is set to `true` then the bindings directory will be
+ automatically created at the location specified in
+ `bindings-directory` if it does not already exist. The default value
+ is `true`
+
+Configuring the jms journal
+===========================
+
+The jms config shares its configuration with the bindings journal.
+
+Configuring the message journal
+===============================
+
+The message journal is configured using the following attributes in
+`activemq-configuration.xml`
+
+- `journal-directory`
+
+ This is the directory in which the message journal lives. The
+ default value is `data/journal`.
+
+ For the best performance, we recommend the journal is located on its
+ own physical volume in order to minimise disk head movement. If the
+ journal is on a volume which is shared with other processes which
+ might be writing other files (e.g. bindings journal, database, or
+ transaction coordinator) then the disk head may well be moving
+ rapidly between these files as it writes them, thus drastically
+ reducing performance.
+
+ When the message journal is stored on a SAN we recommend each
+ journal instance that is stored on the SAN is given its own LUN
+ (logical unit).
+
+- `create-journal-dir`
+
+ If this is set to `true` then the journal directory will be
+ automatically created at the location specified in
+ `journal-directory` if it does not already exist. The default value
+ is `true`
+
+- `journal-type`
+
+ Valid values are `NIO` or `ASYNCIO`.
+
+ Choosing `NIO` chooses the Java NIO journal. Choosing `AIO` chooses
+ the Linux asynchronous IO journal. If you choose `AIO` but are not
+ running Linux or you do not have libaio installed then ActiveMQ will
+ detect this and automatically fall back to using `NIO`.
+
+- `journal-sync-transactional`
+
+ If this is set to true then ActiveMQ will make sure all transaction
+ data is flushed to disk on transaction boundaries (commit, prepare
+ and rollback). The default value is `true`.
+
+- `journal-sync-non-transactional`
+
+ If this is set to true then ActiveMQ will make sure non
+ transactional message data (sends and acknowledgements) are flushed
+ to disk each time. The default value for this is `true`.
+
+- `journal-file-size`
+
+ The size of each journal file in bytes. The default value for this
+ is `10485760` bytes (10MiB).
+
+- `journal-min-files`
+
+ The minimum number of files the journal will maintain. When ActiveMQ
+ starts and there is no initial message data, ActiveMQ will
+ pre-create `journal-min-files` number of files.
+
+ Creating journal files and filling them with padding is a fairly
+ expensive operation and we want to minimise doing this at run-time
+ as files get filled. By pre-creating files, as one is filled the
+ journal can immediately resume with the next one without pausing to
+ create it.
+
+ Depending on how much data you expect your queues to contain at
+ steady state you should tune this number of files to match that
+ total amount of data.
+
+- `journal-max-io`
+
+ Write requests are queued up before being submitted to the system
+ for execution. This parameter controls the maximum number of write
+ requests that can be in the IO queue at any one time. If the queue
+ becomes full then writes will block until space is freed up.
+
+ When using NIO, this value should always be equal to `1`
+
+ When using AIO, the default should be `500`.
+
+ The system maintains different defaults for this parameter depending
+ on whether it's NIO or AIO (default for NIO is 1, default for AIO is
+ 500)
+
+ There is a limit and the total max AIO can't be higher than what is
+ configured at the OS level (/proc/sys/fs/aio-max-nr) usually at
+ 65536.
+
+- `journal-buffer-timeout`
+
+ Instead of flushing on every write that requires a flush, we
+ maintain an internal buffer, and flush the entire buffer either when
+ it is full, or when a timeout expires, whichever is sooner. This is
+ used for both NIO and AIO and allows the system to scale better with
+ many concurrent writes that require flushing.
+
+ This parameter controls the timeout at which the buffer will be
+ flushed if it hasn't filled already. AIO can typically cope with a
+ higher flush rate than NIO, so the system maintains different
+ defaults for both NIO and AIO (default for NIO is 3333333
+ nanoseconds - 300 times per second, default for AIO is 500000
+ nanoseconds - ie. 2000 times per second).
+
+ > **Note**
+ >
+ > By increasing the timeout, you may be able to increase system
+ > throughput at the expense of latency, the default parameters are
+ > chosen to give a reasonable balance between throughput and
+ > latency.
+
+- `journal-buffer-size`
+
+ The size of the timed buffer on AIO. The default value is `490KiB`.
+
+- `journal-compact-min-files`
+
+ The minimal number of files before we can consider compacting the
+ journal. The compacting algorithm won't start until you have at
+ least `journal-compact-min-files`
+
+ The default for this parameter is `10`
+
+- `journal-compact-percentage`
+
+ The threshold to start compacting. When less than this percentage is
+ considered live data, we start compacting. Note also that compacting
+ won't kick in until you have at least `journal-compact-min-files`
+ data files on the journal
+
+ The default for this parameter is `30`
+
+An important note on disabling disk write cache.
+================================================
+
+> **Warning**
+>
+> Most disks contain hardware write caches. A write cache can increase
+> the apparent performance of the disk because writes just go into the
+> cache and are then lazily written to the disk later.
+>
+> This happens irrespective of whether you have executed a fsync() from
+> the operating system or correctly synced data from inside a Java
+> program!
+>
+> By default many systems ship with disk write cache enabled. This means
+> that even after syncing from the operating system there is no
+> guarantee the data has actually made it to disk, so if a failure
+> occurs, critical data can be lost.
+>
+> Some more expensive disks have non volatile or battery backed write
+> caches which won't necessarily lose data on event of failure, but you
+> need to test them!
+>
+> If your disk does not have an expensive non volatile or battery backed
+> cache and it's not part of some kind of redundant array (e.g. RAID),
+> and you value your data integrity you need to make sure disk write
+> cache is disabled.
+>
+> Be aware that disabling disk write cache can give you a nasty shock
+> performance wise. If you've been used to using disks with write cache
+> enabled in their default setting, unaware that your data integrity
+> could be compromised, then disabling it will give you an idea of how
+> fast your disk can perform when acting really reliably.
+>
+> On Linux you can inspect and/or change your disk's write cache
+> settings using the tools `hdparm` (for IDE disks) or `sdparm` or
+> `sginfo` (for SDSI/SATA disks)
+>
+> On Windows you can check / change the setting by right clicking on the
+> disk and clicking properties.
+
+Installing AIO
+==============
+
+The Java NIO journal gives great performance, but If you are running
+ActiveMQ using Linux Kernel 2.6 or later, we highly recommend you use
+the `AIO` journal for the very best persistence performance.
+
+It's not possible to use the AIO journal under other operating systems
+or earlier versions of the Linux kernel.
+
+If you are running Linux kernel 2.6 or later and don't already have
+`libaio` installed, you can easily install it using the following steps:
+
+Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+
+ yum install libaio
+
+Using aptitude, (e.g. on Ubuntu or Debian system):
+
+ apt-get install libaio
+
+Configuring ActiveMQ for Zero Persistence
+=========================================
+
+In some situations, zero persistence is sometimes required for a
+messaging system. Configuring ActiveMQ to perform zero persistence is
+straightforward. Simply set the parameter `persistence-enabled` in
+`activemq-configuration.xml` to `false`.
+
+Please note that if you set this parameter to false, then *zero*
+persistence will occur. That means no bindings data, message data, large
+message data, duplicate id caches or paging data will be persisted.
+
+Import/Export the Journal Data
+==============================
+
+You may want to inspect the existent records on each one of the journals
+used by ActiveMQ, and you can use the export/import tool for that
+purpose. The export/import are classes located at the activemq-core.jar,
+you can export the journal as a text file by using this command:
+
+`java -cp activemq-core.jar org.apache.activemq.core.journal.impl.ExportJournal
+ <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
+ <FileOutput>`
+
+To import the file as binary data on the journal (Notice you also
+require netty.jar):
+
+`java -cp activemq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal
+ <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
+ <FileInput>`
+
+- JournalDirectory: Use the configured folder for your selected
+ folder. Example: ./activemq/data/journal
+
+- JournalPrefix: Use the prefix for your selected journal, as
+ discussed [here](#persistence.journallist)
+
+- FileExtension: Use the extension for your selected journal, as
+ discussed [here](#persistence.journallist)
+
+- FileSize: Use the size for your selected journal, as discussed
+ [here](#persistence.journallist)
+
+- FileOutput: text file that will contain the exported data
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/persistence.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/persistence.xml b/docs/user-manual/en/persistence.xml
deleted file mode 100644
index 473d4a1..0000000
--- a/docs/user-manual/en/persistence.xml
+++ /dev/null
@@ -1,356 +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="persistence">
- <title>Persistence</title>
- <para>In this chapter we will describe how persistence works with ActiveMQ and how to configure
- it.</para>
- <para>ActiveMQ ships with a high performance journal. Since ActiveMQ handles its own persistence,
- rather than relying on a database or other 3rd party persistence engine it is very highly
- optimised for the specific messaging use cases.</para>
- <para>A ActiveMQ journal is an <emphasis>append only</emphasis> journal. It consists of a set of
- files on disk. Each file is pre-created to a fixed size and initially filled with padding.
- As operations are performed on the server, e.g. add message, update message, delete message,
- records are appended to the journal. When one journal file is full we move to the next
- one.</para>
- <para>Because records are only appended, i.e. added to the end of the journal we minimise disk
- head movement, i.e. we minimise random access operations which is typically the slowest
- operation on a disk.</para>
- <para>Making the file size configurable means that an optimal size can be chosen, i.e. making
- each file fit on a disk cylinder. Modern disk topologies are complex and we are not in
- control over which cylinder(s) the file is mapped onto so this is not an exact science. But
- by minimising the number of disk cylinders the file is using, we can minimise the amount of
- disk head movement, since an entire disk cylinder is accessible simply by the disk rotating
- - the head does not have to move.</para>
- <para>As delete records are added to the journal, ActiveMQ has a sophisticated file garbage
- collection algorithm which can determine if a particular journal file is needed any more -
- i.e. has all its data been deleted in the same or other files. If so, the file can be
- reclaimed and re-used. </para>
- <para>ActiveMQ also has a compaction algorithm which removes dead space from the journal and
- compresses up the data so it takes up less files on disk.</para>
- <para>The journal also fully supports transactional operation if required, supporting both local
- and XA transactions.</para>
- <para>The majority of the journal is written in Java, however we abstract out the interaction
- with the actual file system to allow different pluggable implementations. ActiveMQ ships with
- two implementations:</para>
- <itemizedlist>
- <listitem>
- <para>Java <ulink url="http://en.wikipedia.org/wiki/New_I/O">NIO</ulink>.</para>
- <para>The first implementation uses standard Java NIO to interface with the file system.
- This provides extremely good performance and runs on any platform where there's a
- Java 6+ runtime.</para>
- </listitem>
- <listitem id="aio-journal">
- <para>Linux Asynchronous IO</para>
- <para>The second implementation uses a thin native code wrapper to talk to the Linux
- asynchronous IO library (AIO). With AIO, ActiveMQ will be called back when the data
- has made it to disk, allowing us to avoid explicit syncs altogether and simply send
- back confirmation of completion when AIO informs us that the data has been
- persisted.</para>
- <para>Using AIO will typically provide even better performance than using Java
- NIO.</para>
- <para>The AIO journal is only available when running Linux kernel 2.6 or later and after
- having installed libaio (if it's not already installed). For instructions on how to
- install libaio please see <xref linkend="installing-aio"/>.</para>
- <para>Also, please note that AIO will only work with the following file systems: ext2,
- ext3, ext4, jfs, xfs. With other file systems, e.g. NFS it may appear to work, but
- it will fall back to a slower synchronous behaviour. Don't put the journal on a NFS
- share!</para>
- <para>For more information on libaio please see <xref linkend="libaio"/>.</para>
- <para>libaio is part of the kernel project.</para>
- </listitem>
- </itemizedlist>
- <para>The standard ActiveMQ core server uses two instances of the journal:</para>
- <itemizedlist id="persistence.journallist">
- <listitem>
- <para>Bindings journal.</para>
- <para>This journal is used to store bindings related data. That includes the set of
- queues that are deployed on the server and their attributes. It also stores data
- such as id sequence counters. </para>
- <para>The bindings journal is always a NIO journal as it is typically low throughput
- compared to the message journal.</para>
- <para>The files on this journal are prefixed as <literal>activemq-bindings</literal>.
- Each file has a <literal>bindings</literal> extension. File size is <literal
- >1048576</literal>, and it is located at the bindings folder.</para>
- </listitem>
- <listitem>
- <para>JMS journal.</para>
- <para>This journal instance stores all JMS related data, This is basically any JMS
- Queues, Topics and Connection Factories and any JNDI bindings for these
- resources.</para>
- <para>Any JMS Resources created via the management API will be persisted to this
- journal. Any resources configured via configuration files will not. The JMS Journal
- will only be created if JMS is being used.</para>
- <para>The files on this journal are prefixed as <literal>activemq-jms</literal>. Each
- file has a <literal>jms</literal> extension. File size is <literal
- >1048576</literal>, and it is located at the bindings folder.</para>
- </listitem>
- <listitem>
- <para>Message journal.</para>
- <para>This journal instance stores all message related data, including the message
- themselves and also duplicate-id caches.</para>
- <para>By default ActiveMQ will try and use an AIO journal. If AIO is not available, e.g.
- the platform is not Linux with the correct kernel version or AIO has not been
- installed then it will automatically fall back to using Java NIO which is available
- on any Java platform.</para>
- <para>The files on this journal are prefixed as <literal>activemq-data</literal>. Each
- file has a <literal>hq</literal> extension. File size is by the default <literal
- >10485760</literal> (configurable), and it is located at the journal
- folder.</para>
- </listitem>
- </itemizedlist>
- <para>For large messages, ActiveMQ persists them outside the message journal. This is discussed
- in <xref linkend="large-messages"/>.</para>
- <para>ActiveMQ can also be configured to page messages to disk in low memory situations. This is
- discussed in <xref linkend="paging"/>.</para>
- <para>If no persistence is required at all, ActiveMQ can also be configured not to persist any
- data at all to storage as discussed in <xref linkend="persistence.enabled"/>.</para>
- <section id="configuring.bindings.journal">
- <title>Configuring the bindings journal</title>
- <para>The bindings journal is configured using the following attributes in <literal
- >activemq-configuration.xml</literal></para>
- <itemizedlist>
- <listitem>
- <para><literal>bindings-directory</literal></para>
- <para>This is the directory in which the bindings journal lives. The default value
- is <literal>data/bindings</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>create-bindings-dir</literal></para>
- <para>If this is set to <literal>true</literal> then the bindings directory will be
- automatically created at the location specified in <literal
- >bindings-directory</literal> if it does not already exist. The default
- value is <literal>true</literal></para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="configuring.bindings.jms">
- <title>Configuring the jms journal</title>
- <para>The jms config shares its configuration with the bindings journal.</para>
- </section>
- <section id="configuring.message.journal">
- <title>Configuring the message journal</title>
- <para>The message journal is configured using the following attributes in <literal
- >activemq-configuration.xml</literal></para>
- <itemizedlist>
- <listitem id="configuring.message.journal.journal-directory">
- <para><literal>journal-directory</literal></para>
- <para>This is the directory in which the message journal lives. The default value is
- <literal>data/journal</literal>.</para>
- <para>For the best performance, we recommend the journal is located on its own
- physical volume in order to minimise disk head movement. If the journal is on a
- volume which is shared with other processes which might be writing other files
- (e.g. bindings journal, database, or transaction coordinator) then the disk head
- may well be moving rapidly between these files as it writes them, thus
- drastically reducing performance.</para>
- <para>When the message journal is stored on a SAN we recommend each journal instance
- that is stored on the SAN is given its own LUN (logical unit).</para>
- </listitem>
- <listitem id="configuring.message.journal.create-journal-dir">
- <para><literal>create-journal-dir</literal></para>
- <para>If this is set to <literal>true</literal> then the journal directory will be
- automatically created at the location specified in <literal
- >journal-directory</literal> if it does not already exist. The default value
- is <literal>true</literal></para>
- </listitem>
- <listitem id="configuring.message.journal.journal-type">
- <para><literal>journal-type</literal></para>
- <para>Valid values are <literal>NIO</literal> or <literal>ASYNCIO</literal>.</para>
- <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
- <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
- choose <literal>AIO</literal> but are not running Linux or you do not have
- libaio installed then ActiveMQ will detect this and automatically fall back to
- using <literal>NIO</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-sync-transactional">
- <para><literal>journal-sync-transactional</literal></para>
- <para>If this is set to true then ActiveMQ will make sure all transaction data is
- flushed to disk on transaction boundaries (commit, prepare and rollback). The
- default value is <literal>true</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-sync-non-transactional">
- <para><literal>journal-sync-non-transactional</literal></para>
- <para>If this is set to true then ActiveMQ will make sure non transactional message
- data (sends and acknowledgements) are flushed to disk each time. The default
- value for this is <literal>true</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-file-size">
- <para><literal>journal-file-size</literal></para>
- <para>The size of each journal file in bytes. The default value for this is <literal
- >10485760</literal> bytes (10MiB).</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-min-files">
- <para><literal>journal-min-files</literal></para>
- <para>The minimum number of files the journal will maintain. When ActiveMQ starts and
- there is no initial message data, ActiveMQ will pre-create <literal
- >journal-min-files</literal> number of files.</para>
- <para>Creating journal files and filling them with padding is a fairly expensive
- operation and we want to minimise doing this at run-time as files get filled. By
- pre-creating files, as one is filled the journal can immediately resume with the
- next one without pausing to create it.</para>
- <para>Depending on how much data you expect your queues to contain at steady state
- you should tune this number of files to match that total amount of data.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-max-io">
- <para><literal>journal-max-io</literal></para>
- <para>Write requests are queued up before being submitted to the system for
- execution. This parameter controls the maximum number of write requests that can
- be in the IO queue at any one time. If the queue becomes full then writes will
- block until space is freed up. </para>
- <para>When using NIO, this value should always be equal to <literal
- >1</literal></para>
- <para>When using AIO, the default should be <literal>500</literal>.</para>
- <para>The system maintains different defaults for this parameter depending on whether
- it's NIO or AIO (default for NIO is 1, default for AIO is 500)</para>
- <para>There is a limit and the total max AIO can't be higher than what is configured
- at the OS level (/proc/sys/fs/aio-max-nr) usually at 65536.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-buffer-timeout">
- <para><literal>journal-buffer-timeout</literal></para>
- <para>Instead of flushing on every write that requires a flush, we maintain an
- internal buffer, and flush the entire buffer either when it is full, or when a
- timeout expires, whichever is sooner. This is used for both NIO and AIO and
- allows the system to scale better with many concurrent writes that require
- flushing.</para>
- <para>This parameter controls the timeout at which the buffer will be flushed if it
- hasn't filled already. AIO can typically cope with a higher flush rate than NIO,
- so the system maintains different defaults for both NIO and AIO (default for NIO
- is 3333333 nanoseconds - 300 times per second, default for AIO is 500000
- nanoseconds - ie. 2000 times per second).</para>
- <note>
- <para>By increasing the timeout, you may be able to increase system throughput
- at the expense of latency, the default parameters are chosen to give a
- reasonable balance between throughput and latency.</para>
- </note>
- </listitem>
- <listitem id="configuring.message.journal.journal-buffer-size">
- <para><literal>journal-buffer-size</literal></para>
- <para>The size of the timed buffer on AIO. The default value is <literal
- >490KiB</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-compact-min-files">
- <para><literal>journal-compact-min-files</literal></para>
- <para>The minimal number of files before we can consider compacting the journal. The
- compacting algorithm won't start until you have at least <literal
- >journal-compact-min-files</literal></para>
- <para>The default for this parameter is <literal>10</literal></para>
- </listitem>
- <listitem id="configuring.message.journal.journal-compact-percentage">
- <para><literal>journal-compact-percentage</literal></para>
- <para>The threshold to start compacting. When less than this percentage is
- considered live data, we start compacting. Note also that compacting won't kick
- in until you have at least <literal>journal-compact-min-files</literal> data
- files on the journal</para>
- <para>The default for this parameter is <literal>30</literal></para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="disk-write-cache">
- <title>An important note on disabling disk write cache.</title>
- <warning>
- <para>Most disks contain hardware write caches. A write cache can increase the apparent
- performance of the disk because writes just go into the cache and are then lazily
- written to the disk later. </para>
- <para>This happens irrespective of whether you have executed a fsync() from the
- operating system or correctly synced data from inside a Java program!</para>
- <para>By default many systems ship with disk write cache enabled. This means that even
- after syncing from the operating system there is no guarantee the data has actually
- made it to disk, so if a failure occurs, critical data can be lost.</para>
- <para>Some more expensive disks have non volatile or battery backed write caches which
- won't necessarily lose data on event of failure, but you need to test them!</para>
- <para>If your disk does not have an expensive non volatile or battery backed cache and
- it's not part of some kind of redundant array (e.g. RAID), and you value your data
- integrity you need to make sure disk write cache is disabled.</para>
- <para>Be aware that disabling disk write cache can give you a nasty shock performance
- wise. If you've been used to using disks with write cache enabled in their default
- setting, unaware that your data integrity could be compromised, then disabling it
- will give you an idea of how fast your disk can perform when acting really
- reliably.</para>
- <para>On Linux you can inspect and/or change your disk's write cache settings using the
- tools <literal>hdparm</literal> (for IDE disks) or <literal>sdparm</literal> or
- <literal>sginfo</literal> (for SDSI/SATA disks)</para>
- <para>On Windows you can check / change the setting by right clicking on the disk and
- clicking properties.</para>
- </warning>
- </section>
- <section id="installing-aio">
- <title>Installing AIO</title>
- <para>The Java NIO journal gives great performance, but If you are running ActiveMQ using
- Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
- journal for the very best persistence performance.</para>
- <para>It's not possible to use the AIO journal under other operating systems or earlier
- versions of the Linux kernel.</para>
- <para>If you are running Linux kernel 2.6 or later and don't already have <literal
- >libaio</literal> installed, you can easily install it using the following
- steps:</para>
- <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
- <programlisting>yum install libaio</programlisting></para>
- <para>Using aptitude, (e.g. on Ubuntu or Debian system):
- <programlisting>apt-get install libaio</programlisting></para>
- </section>
- <section id="persistence.enabled">
- <title>Configuring ActiveMQ for Zero Persistence</title>
- <para>In some situations, zero persistence is sometimes required for a messaging system.
- Configuring ActiveMQ to perform zero persistence is straightforward. Simply set the
- parameter <literal>persistence-enabled</literal> in <literal
- >activemq-configuration.xml</literal> to <literal>false</literal>. </para>
- <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
- persistence will occur. That means no bindings data, message data, large message data,
- duplicate id caches or paging data will be persisted.</para>
- </section>
- <section id="persistence.importexport">
- <title>Import/Export the Journal Data</title>
- <para>You may want to inspect the existent records on each one of the journals used by
- ActiveMQ, and you can use the export/import tool for that purpose. The export/import are
- classes located at the activemq-core.jar, you can export the journal as a text file by
- using this command:</para>
- <para><literal>java -cp activemq-core.jar org.apache.activemq.core.journal.impl.ExportJournal
- <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
- <FileOutput></literal></para>
- <para>To import the file as binary data on the journal (Notice you also require
- netty.jar):</para>
- <para><literal>java -cp activemq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal
- <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
- <FileInput></literal></para>
- <itemizedlist>
- <listitem>
- <para>JournalDirectory: Use the configured folder for your selected folder. Example:
- ./activemq/data/journal</para>
- </listitem>
- <listitem>
- <para>JournalPrefix: Use the prefix for your selected journal, as discussed
- <link linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileExtension: Use the extension for your selected journal, as discussed
- <link linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileSize: Use the size for your selected journal, as discussed <link
- linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileOutput: text file that will contain the exported data</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/pre-acknowledge.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/pre-acknowledge.md b/docs/user-manual/en/pre-acknowledge.md
new file mode 100644
index 0000000..1bec75e
--- /dev/null
+++ b/docs/user-manual/en/pre-acknowledge.md
@@ -0,0 +1,92 @@
+Extra Acknowledge Modes
+=======================
+
+JMS specifies 3 acknowledgement modes:
+
+- `AUTO_ACKNOWLEDGE`
+
+- `CLIENT_ACKNOWLEDGE`
+
+- `DUPS_OK_ACKNOWLEDGE`
+
+ActiveMQ supports two additional modes: `PRE_ACKNOWLEDGE` and
+`INDIVIDUAL_ACKNOWLEDGE`
+
+In some cases you can afford to lose messages in event of failure, so it
+would make sense to acknowledge the message on the server *before*
+delivering it to the client.
+
+This extra mode is supported by ActiveMQ and will call it
+*pre-acknowledge* mode.
+
+The disadvantage of acknowledging on the server before delivery is that
+the message will be lost if the system crashes *after* acknowledging the
+message on the server but *before* it is delivered to the client. In
+that case, the message is lost and will not be recovered when the system
+restart.
+
+Depending on your messaging case, `pre-acknowledgement` mode can avoid
+extra network traffic and CPU at the cost of coping with message loss.
+
+An example of a use case for pre-acknowledgement is for stock price
+update messages. With these messages it might be reasonable to lose a
+message in event of crash, since the next price update message will
+arrive soon, overriding the previous price.
+
+> **Note**
+>
+> Please note, that if you use pre-acknowledge mode, then you will lose
+> transactional semantics for messages being consumed, since clearly
+> they are being acknowledged first on the server, not when you commit
+> the transaction. This may be stating the obvious but we like to be
+> clear on these things to avoid confusion!
+
+Using PRE\_ACKNOWLEDGE
+======================
+
+This can be configured in a client's JNDI context environment, e.g.
+`jndi.properties`, like this:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.preAcknowledge=true
+
+Alternatively, to use pre-acknowledgement mode using the JMS API, create
+a JMS Session with the `ActiveMQSession.PRE_ACKNOWLEDGE` constant.
+
+ // messages will be acknowledge on the server *before* being delivered to the client
+ Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);
+
+Or you can set pre-acknowledge directly on the
+`ActiveMQConnectionFactory` instance using the setter method.
+
+To use pre-acknowledgement mode using the core API you can set it
+directly on the `ClientSessionFactory` instance using the setter method.
+
+Individual Acknowledge
+======================
+
+A valid use-case for individual acknowledgement would be when you need
+to have your own scheduling and you don't know when your message
+processing will be finished. You should prefer having one consumer per
+thread worker but this is not possible in some circumstances depending
+on how complex is your processing. For that you can use the individual
+Acknowledgement.
+
+You basically setup Individual ACK by creating a session with the
+acknowledge mode with `ActiveMQJMSConstants.INDIVIDUAL_ACKNOWLEDGE`.
+Individual ACK inherits all the semantics from Client Acknowledge, with
+the exception the message is individually acked.
+
+> **Note**
+>
+> Please note, that to avoid confusion on MDB processing, Individual
+> ACKNOWLEDGE is not supported through MDBs (or the inbound resource
+> adapter). this is because you have to finish the process of your
+> message inside the MDB.
+
+Example
+=======
+
+See ? for an example which shows how to use pre-acknowledgement mode
+with JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/pre-acknowledge.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/pre-acknowledge.xml b/docs/user-manual/en/pre-acknowledge.xml
deleted file mode 100644
index d8eec48..0000000
--- a/docs/user-manual/en/pre-acknowledge.xml
+++ /dev/null
@@ -1,92 +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="pre-acknowledge">
- <title>Extra Acknowledge Modes</title>
- <para>JMS specifies 3 acknowledgement modes:</para>
- <itemizedlist>
- <listitem>
- <para><literal>AUTO_ACKNOWLEDGE</literal></para>
- </listitem>
- <listitem>
- <para><literal>CLIENT_ACKNOWLEDGE</literal></para>
- </listitem>
- <listitem>
- <para><literal>DUPS_OK_ACKNOWLEDGE</literal></para>
- </listitem>
- </itemizedlist>
- <para>ActiveMQ supports two additional modes: <literal>PRE_ACKNOWLEDGE</literal> and <literal>INDIVIDUAL_ACKNOWLEDGE</literal></para>
- <para>In some cases you can afford
- to lose messages in event of failure, so it would make sense to acknowledge the message on the
- server <emphasis>before</emphasis> delivering it to the client.</para>
- <para>This extra mode is supported by ActiveMQ and will call it
- <emphasis>pre-acknowledge</emphasis> mode.</para>
- <para>The disadvantage of acknowledging on the server before delivery is that the message will be
- lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server
- but <emphasis>before</emphasis> it is delivered to the client. In that case, the message is
- lost and will not be recovered when the system restart.</para>
- <para>Depending on your messaging case, <literal>pre-acknowledgement</literal> mode can avoid
- extra network traffic and CPU at the cost of coping with message loss.</para>
- <para>An example of a use case for pre-acknowledgement is for stock price update messages. With
- these messages it might be reasonable to lose a message in event of crash, since the next
- price update message will arrive soon, overriding the previous price. </para>
- <note>
- <para>Please note, that if you use pre-acknowledge mode, then you will lose transactional
- semantics for messages being consumed, since clearly they are being acknowledged first on
- the server, not when you commit the transaction. This may be stating the obvious but we
- like to be clear on these things to avoid confusion!</para>
- </note>
- <section id="pre-acknowledge.configure">
- <title>Using PRE_ACKNOWLEDGE</title>
- <para>This can be configured in a client's JNDI context environment, e.g. <literal>jndi.properties</literal>,
- like this:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.preAcknowledge=true</programlisting>
- <para>Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session
- with the <literal>ActiveMQSession.PRE_ACKNOWLEDGE</literal> constant.</para>
- <programlisting>
-// messages will be acknowledge on the server *before* being delivered to the client
-Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);</programlisting>
- <para>Or you can set pre-acknowledge directly on the <literal
- >ActiveMQConnectionFactory</literal> instance using the setter method.</para>
- <para>To use pre-acknowledgement mode using the core API you can set it directly on the
- <literal>ClientSessionFactory</literal> instance using the setter method.</para>
- </section>
- <section id="individual-ack">
- <title>Individual Acknowledge</title>
- <para>A valid use-case for individual acknowledgement would be when you need to have your own scheduling and you don't know when your message processing will be finished. You should prefer having one consumer per thread worker
- but this is not possible in some circumstances depending on how complex is your processing. For that you can use the individual Acknowledgement. </para>
- <para>You basically setup Individual ACK by creating a session with the acknowledge mode with <literal>ActiveMQJMSConstants.INDIVIDUAL_ACKNOWLEDGE</literal>. Individual ACK inherits all the semantics from Client Acknowledge,
- with the exception the message is individually acked.</para>
- <note>
- <para>Please note, that to avoid confusion on MDB processing, Individual ACKNOWLEDGE is not supported through MDBs (or the inbound resource adapter). this is because you have to finish the process of your message inside the MDB.
- </para>
- </note>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.pre-acknowledge"/> for an example which shows how to use
- pre-acknowledgement mode with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/preface.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/preface.md b/docs/user-manual/en/preface.md
new file mode 100644
index 0000000..8cc9717
--- /dev/null
+++ b/docs/user-manual/en/preface.md
@@ -0,0 +1,52 @@
+Preface
+=======
+
+What is ActiveMQ?
+
+- ActiveMQ is an open source project to build a multi-protocol,
+ embeddable, very high performance, clustered, asynchronous messaging
+ system.
+
+- ActiveMQ is an example of Message Oriented Middleware (MoM). For a
+ description of MoMs and other messaging concepts please see the ?.
+
+- For answers to more questions about what ActiveMQ is and what it
+ isn't please visit the [FAQs wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs).
+
+Why use ActiveMQ? Here are just a few of the reasons:
+
+- 100% open source software. ActiveMQ is licensed using the Apache
+ Software License v 2.0 to minimise barriers to adoption.
+
+- ActiveMQ is designed with usability in mind.
+
+- Written in Java. Runs on any platform with a Java 6+ runtime, that's
+ everything from Windows desktops to IBM mainframes.
+
+- Amazing performance. Our ground-breaking high performance journal
+ provides persistent messaging performance at rates normally seen for
+ non-persistent messaging, our non-persistent messaging performance
+ rocks the boat too.
+
+- Full feature set. All the features you'd expect in any serious
+ messaging system, and others you won't find anywhere else.
+
+- Elegant, clean-cut design with minimal third party dependencies. Run
+ ActiveMQ stand-alone, run it in integrated in your favourite JEE
+ application server, or run it embedded inside your own product. It's
+ up to you.
+
+- Seamless high availability. We provide a HA solution with automatic
+ client failover so you can guarantee zero message loss or
+ duplication in event of server failure.
+
+- Hugely flexible clustering. Create clusters of servers that know how
+ to load balance messages. Link geographically distributed clusters
+ over unreliable connections to form a global network. Configure
+ routing of messages in a highly flexible way.
+
+- For a full list of features, please see the [features wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQFeatures) .
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/preface.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/preface.xml b/docs/user-manual/en/preface.xml
deleted file mode 100644
index 427f5a0..0000000
--- a/docs/user-manual/en/preface.xml
+++ /dev/null
@@ -1,86 +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="preface">
- <title>Preface</title>
- <para>What is ActiveMQ?</para>
- <itemizedlist>
- <listitem>
- <para>ActiveMQ is an open source project to build a multi-protocol, embeddable, very high
- performance, clustered, asynchronous messaging system.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ is an example of Message Oriented Middleware (MoM). For a description of
- MoMs and other messaging concepts please see the <xref linkend="messaging-concepts"
- />.</para>
- </listitem>
- <listitem>
- <para>For answers to more questions about what ActiveMQ is and what it isn't please visit
- the <ulink url="http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs">FAQs wiki
- page</ulink>.</para>
- </listitem>
- </itemizedlist>
- <para>Why use ActiveMQ? Here are just a few of the reasons:</para>
- <itemizedlist>
- <listitem>
- <para>100% open source software. ActiveMQ is licensed using the Apache Software License v
- 2.0 to minimise barriers to adoption.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ is designed with usability in mind.</para>
- </listitem>
- <listitem>
- <para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything
- from Windows desktops to IBM mainframes.</para>
- </listitem>
- <listitem>
- <para>Amazing performance. Our ground-breaking high performance journal provides
- persistent messaging performance at rates normally seen for non-persistent
- messaging, our non-persistent messaging performance rocks the boat too.</para>
- </listitem>
- <listitem>
- <para>Full feature set. All the features you'd expect in any serious messaging system,
- and others you won't find anywhere else.</para>
- </listitem>
- <listitem>
- <para>Elegant, clean-cut design with minimal third party dependencies. Run ActiveMQ
- stand-alone, run it in integrated in your favourite JEE application server, or run
- it embedded inside your own product. It's up to you.</para>
- </listitem>
- <listitem>
- <para>Seamless high availability. We provide a HA solution with automatic client
- failover so you can guarantee zero message loss or duplication in event of server
- failure.</para>
- </listitem>
- <listitem>
- <para>Hugely flexible clustering. Create clusters of servers that know how to load
- balance messages. Link geographically distributed clusters over unreliable
- connections to form a global network. Configure routing of messages in a highly
- flexible way.</para>
- </listitem>
- <listitem>
- <para>For a full list of features, please see the <ulink
- url="http://www.jboss.org/community/wiki/ActiveMQFeatures">features wiki
- page</ulink> .</para>
- </listitem>
- </itemizedlist>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/project-info.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/project-info.md b/docs/user-manual/en/project-info.md
new file mode 100644
index 0000000..2465981
--- /dev/null
+++ b/docs/user-manual/en/project-info.md
@@ -0,0 +1,50 @@
+Project Information
+===================
+
+The official ActiveMQ project page is <http://activemq.org/>.
+
+Software Download
+=================
+
+The software can be download from the Download
+page:<http://activemq.org/downloads.html>
+
+Project Information
+===================
+
+- Please take a look at our project
+ [wiki](http://www.jboss.org/community/wiki/ActiveMQ)
+
+- If you have any user questions please use our [user
+ forum](https://community.jboss.org/en/activemq)
+
+- If you have development related questions, please use our [developer
+ forum](https://community.jboss.org/en/activemq/dev)
+
+- Pop in and chat to us in our [IRC
+ channel](irc://irc.freenode.net:6667/activemq)
+
+- Our project [blog](http://activemq.blogspot.com/)
+
+- Follow us on [twitter](http://twitter.com/activemq)
+
+- ActiveMQ Git repository is <https://github.com/activemq/activemq>
+
+- All release tags are available from
+ <https://github.com/activemq/activemq/tags>
+
+Red Hat kindly employs developers to work full time on ActiveMQ, they
+are:
+
+- Clebert Suconic (project lead)
+
+- Andy Taylor
+
+- Howard Gao
+
+- Justin Bertram
+
+And many thanks to all our contributors, both old and new who helped
+create ActiveMQ, for a full list of the people who made it happen, take
+a look at our [team
+page](http://jboss.org.apache.activemq/community/team.html).
[17/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuration-index.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuration-index.xml b/docs/user-manual/en/configuration-index.xml
deleted file mode 100644
index 8307d99..0000000
--- a/docs/user-manual/en/configuration-index.xml
+++ /dev/null
@@ -1,396 +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="configuration-index">
- <title>Configuration Reference</title>
- <para>This section is a quick index for looking up configuration. Click on the element name to
- go to the specific chapter.</para>
- <section id="server.configuration">
- <title>Server Configuration</title>
- <section>
- <title>activemq-configuration.xml</title>
- <para>This is the main core server configuration file.</para>
- <table frame="topbot" border="2">
- <title>Server Configuration</title>
- <tgroup cols="4">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <colspec colname="c4" colnum="4"/>
- <thead>
- <row>
- <entry>Element Name</entry>
- <entry>Element Type</entry>
- <entry>Description</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <!-- The options reference is generated from the schema. If something is wrong
- in the reference, it must be fixed in the annotations present in the
- schema. -->
- <xi:include href="../target/generated-resources/xml/xslt/activemq-configuration.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude"/>
- </tgroup>
- </table>
- </section>
- <section>
- <title>activemq-jms.xml</title>
- <para>This is the configuration file used by the server side JMS service to load JMS
- Queues, Topics and Connection Factories.</para>
- <table frame="topbot" border="2">
- <title>JMS Server Configuration</title>
- <tgroup cols="4">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <colspec colname="c4" colnum="4"/>
- <thead>
- <row>
- <entry>Element Name</entry>
- <entry>Element Type</entry>
- <entry>Description</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><link linkend="using-jms.server.configuration">queue</link></entry>
- <entry>Queue</entry>
- <entry>a queue to create and add to JNDI</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">queue.name (attribute)</link></entry>
- <entry>String</entry>
- <entry>unique name of the queue</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">queue.entry</link></entry>
- <entry>String</entry>
- <entry>context where the queue will be bound in JNDI (there can be many)</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">queue.durable</link></entry>
- <entry>Boolean</entry>
- <entry>is the queue durable?</entry>
- <entry>true</entry>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">queue.filter</link></entry>
- <entry>String</entry>
- <entry>optional filter expression for the queue</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">topic</link></entry>
- <entry>Topic</entry>
- <entry>a topic to create and add to JNDI</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">topic.name (attribute)</link></entry>
- <entry>String</entry>
- <entry>unique name of the topic</entry>
- <entry/>
- </row>
- <row>
- <entry><link linkend="using-jms.server.configuration">topic.entry</link></entry>
- <entry>String</entry>
- <entry>context where the topic will be bound in JNDI (there can be many)</entry>
- <entry/>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="configuration.masked-password">
- <title>Using Masked Passwords in Configuration Files</title>
- <para>By default all passwords in ActiveMQ server's configuration files are in plain text form. This usually poses no security issues as those
- files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more
- eyes than necessary. </para>
-
- <para>ActiveMQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation
- of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version.
- A user can then replace the real password in the configuration files with the new masked password.
- When ActiveMQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.</para>
-
- <para>ActiveMQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for
- masking the passwords.</para>
-
- <section> <title>Password Masking in Server Configuration File</title>
-
- <section> <title>The password masking property</title>
-
- <para>The server configuration file has a property that defines the default masking behaviors over the entire file scope.</para>
-
- <para><literal>mask-password</literal>: this boolean type property indicates if a password should be masked or not. Set it to "true"
- if you want your passwords masked. The default value is "false".</para>
- </section>
-
- <section> <title>Specific masking behaviors</title>
-
- <section> <title>cluster-password</title>
-
- <para>The nature of the value of cluster-password is subject to the value of property 'mask-password'. If it is true
- the cluster-password is masked.</para>
- </section>
-
- <section> <title>Passwords in connectors and acceptors</title>
-
- <para>In the server configuration, Connectors and Acceptors sometimes needs to specify passwords. For example
- if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because
- Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.</para>
-
- <para>When a Connector or Acceptor configuration is initialised, ActiveMQ will add the "mask-password" and
- "password-codec" values to the Connector or Acceptors params using the keys <literal>activemq.usemaskedpassword</literal>
- and <literal>activemq.passwordcodec</literal> respectively. The Netty and InVM implementations will use these
- as needed and any other implementations will have access to these to use if they so wish.</para>
- </section>
-
- <section> <title>Passwords in Core Bridge configurations</title>
-
- <para>Core Bridges are configured in the server configuration file and so the masking of its 'password' properties
- follows the same rules as that of 'cluster-password'.</para>
- </section>
- </section>
-
- <section> <title>Examples</title>
-
- <para>The following table summarizes the relations among the above-mentioned properties</para>
-
- <table frame="topbot" border="2">
- <tgroup cols="4">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <colspec colname="c4" colnum="4"/>
- <thead>
- <row>
- <entry>mask-password</entry>
- <entry>cluster-password</entry>
- <entry>acceptor/connector passwords</entry>
- <entry>bridge password</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>absent</entry>
- <entry>plain text</entry>
- <entry>plain text</entry>
- <entry>plain text</entry>
- </row>
- <row>
- <entry>false</entry>
- <entry>plain text</entry>
- <entry>plain text</entry>
- <entry>plain text</entry>
- </row>
- <row>
- <entry>true</entry>
- <entry>masked</entry>
- <entry>masked</entry>
- <entry>masked</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-<para>Examples</para>
-
-<para>Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.</para>
-
-<para>example 1</para>
-
-<programlisting>
-<cluster-password>bbc</cluster-password></programlisting>
-
-<para>This indicates the cluster password is a plain text value ("bbc").</para>
-
-<para>example 2</para>
-
-<programlisting>
-<mask-password>true</mask-password>
-<cluster-password>80cf731af62c290</cluster-password></programlisting>
-
- <para>This indicates the cluster password is a masked value and ActiveMQ will use its built-in decoder to decode it. All other
- passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.</para>
- </section>
- </section>
-
- <section> <title>JMS Bridge password masking</title>
-
- <para>The JMS Bridges are configured and deployed as separate beans so they need separate configuration to control the password masking.
- A JMS Bridge has two password parameters in its constructor, SourcePassword and TargetPassword. It uses the following two optional
- properties to control their masking:</para>
-
- <para><literal>useMaskedPassword</literal> -- If set to "true" the passwords are masked. Default is false.</para>
- <para><literal>passwordCodec</literal> -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if
- <literal>useMaskedPassword</literal> is false. The format of this property is a full qualified class name optionally followed by key/value pairs,
- separated by semi-colons. For example:</para>
-
-<literal>
-<property name="useMaskedPassword">true</property>
-</literal><para></para>
-<literal>
-<property name="passwordCodec">com.foo.FooDecoder;key=value</property>
-</literal>
- <para>ActiveMQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair.
- If <literal>passwordCodec</literal> is not specified, the built-in decoder is used.</para>
-
- </section>
-
- <section> <title>Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations</title>
-
- <para>Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two
- optional Resource Adapter properties in ra.xml:</para>
-
- <para><literal>UseMaskedPassword</literal> -- If setting to "true" the passwords are masked. Default is false.</para>
- <para><literal>PasswordCodec</literal> -- Class name and its parameters for the Decoder used to decode the masked password.
- Ignored if UseMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs.
- It is the same format as that for JMS Bridges. Example:</para>
-
-<programlisting>
-<config-property>
- <config-property-name>UseMaskedPassword</config-property-name>
- <config-property-type>boolean</config-property-type>
- <config-property-value>true</config-property-value>
-</config-property>
-<config-property>
- <config-property-name>PasswordCodec</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>com.foo.ADecoder;key=helloworld</config-property-value>
-</config-property></programlisting>
-
- <para>With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.</para>
-
- </section>
-
- <section> <title>Masking passwords in activemq-users.xml</title>
-
- <para>ActiveMQ's built-in security manager uses plain configuration files where the user passwords are specified in plaintext
- forms by default. To mask those parameters the following two properties are needed:</para>
-
- <para> <literal>mask-password</literal> -- If set to "true" all the passwords are masked. Default is false.</para>
- <para> <literal>password-codec</literal> -- Class name and its parameters for the Decoder used to decode the masked password.
- Ignored if <literal>mask-password</literal> is false. The format of this property is a full qualified class name optionally
- followed by key/value pairs. It is the same format as that for JMS Bridges. Example:</para>
-
-<programlisting>
-<mask-password>true</mask-password>
-<password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world</password-codec></programlisting>
-
- <para>When so configured, the ActiveMQ security manager will initialize a DefaultSensitiveStringCodec with the parameters
- "key"->"hello world", then use it to decode all the masked passwords in this configuration file.</para>
-
- </section>
-
- <section> <title>Choosing a decoder for password masking</title>
-
- <para>As described in the previous sections, all password masking requires a decoder. A decoder uses an algorithm to
- convert a masked password into its original clear text form in order to be used in various security operations. The algorithm
- used for decoding must match that for encoding. Otherwise the decoding may not be successful.</para>
-
- <para>For user's convenience ActiveMQ provides a default built-in Decoder. However a user can if they so wish implement their own.</para>
-
- <section><title>The built-in Decoder</title>
-
- <para>Whenever no decoder is specified in the configuration file, the built-in decoder is used. The class name for the built-in
- decoder is org.apache.activemq.utils.DefaultSensitiveStringCodec. It has both encoding and decoding capabilities. It uses java.crypto.Cipher
- utilities to encrypt (encode) a plaintext password and decrypt a mask string using same algorithm. Using this decoder/encoder is
- pretty straightforward. To get a mask for a password, just run the following in command line:</para>
-
-<programlisting>
-java org.apache.activemq.utils.DefaultSensitiveStringCodec "your plaintext password"</programlisting>
-
- <para>Make sure the classpath is correct. You'll get something like</para>
-
-<programlisting>
-Encoded password: 80cf731af62c290</programlisting>
-
- <para>Just copy "80cf731af62c290" and replace your plaintext password with it.</para>
- </section>
-
- <section><title>Using a different decoder</title>
-
- <para>It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder
- is in ActiveMQ's classpath and configure the server to use it as follows:</para>
-
-<programlisting>
-<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec></programlisting>
-
- <para>If your decoder needs params passed to it you can do this via key/value pairs when configuring.
- For instance if your decoder needs say a "key-location" parameter, you can define like so:</para>
-
-<programlisting>
-<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec></programlisting>
-
- <para>Then configure your cluster-password like this:</para>
-
-<programlisting>
-<mask-password>true</mask-password>
-<cluster-password>masked_password</cluster-password></programlisting>
-
- <para>When ActiveMQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password".
- It also process all passwords using the new defined decoder.</para>
- </section>
-
- <section><title>Implementing your own codecs</title>
-
- <para>To use a different decoder than the built-in one, you either pick one from existing libraries or you implement it yourself.
- All decoders must implement the <literal>org.apache.activemq.utils.SensitiveDataCodec<T></literal> interface:</para>
-
-<programlisting>
-public interface SensitiveDataCodec<T>
-{
- T decode(Object mask) throws Exception;
-
- void init(Map<String, String> params);
-}</programlisting>
-
- <para>This is a generic type interface but normally for a password you just need String type.
- So a new decoder would be defined like </para>
-
-<programlisting>
-public class MyNewDecoder implements SensitiveDataCodec<String>
-{
- public String decode(Object mask) throws Exception
- {
- //decode the mask into clear text password
- return "the password";
- }
-
- public void init(Map<String, String> params)
- {
- //initialization done here. It is called right after the decoder has been created.
- }
-}</programlisting>
-
- <para>Last but not least, once you get your own decoder, please add it to the classpath. Otherwise ActiveMQ will
- fail to load it!</para>
- </section>
- </section>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuring-transports.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md
new file mode 100644
index 0000000..f1d6194
--- /dev/null
+++ b/docs/user-manual/en/configuring-transports.md
@@ -0,0 +1,462 @@
+Configuring the Transport
+=========================
+
+ActiveMQ has a fully pluggable and highly flexible transport layer and
+defines its own Service Provider Interface (SPI) to make plugging in a
+new transport provider relatively straightforward.
+
+In this chapter we'll describe the concepts required for understanding
+ActiveMQ transports and where and how they're configured.
+
+Understanding Acceptors
+=======================
+
+One of the most important concepts in ActiveMQ transports is the
+*acceptor*. Let's dive straight in and take a look at an acceptor
+defined in xml in the configuration file `activemq-configuration.xml`.
+
+ <acceptors>
+ <acceptor name="netty">
+ <factory-class>
+ org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory
+ </factory-class>
+ <param key="port" value="5446"/>
+ </acceptor>
+ </acceptors>
+
+Acceptors are always defined inside an `acceptors` element. There can be
+one or more acceptors defined in the `acceptors` element. There's no
+upper limit to the number of acceptors per server.
+
+Each acceptor defines a way in which connections can be made to the
+ActiveMQ server.
+
+In the above example we're defining an acceptor that uses
+[Netty](http://jboss.org/netty) to listen for connections at port
+`5446`.
+
+The `acceptor` element contains a sub-element `factory-class`, this
+element defines the factory used to create acceptor instances. In this
+case we're using Netty to listen for connections so we use the Netty
+implementation of an `AcceptorFactory` to do this. Basically, the
+`factory-class` element determines which pluggable transport we're going
+to use to do the actual listening.
+
+The `acceptor` element can also be configured with zero or more `param`
+sub-elements. Each `param` element defines a key-value pair. These
+key-value pairs are used to configure the specific transport, the set of
+valid key-value pairs depends on the specific transport be used and are
+passed straight through to the underlying transport.
+
+Examples of key-value pairs for a particular transport would be, say, to
+configure the IP address to bind to, or the port to listen at.
+
+Note that unlike versions before 2.4 an Acceptor can now support
+multiple protocols. By default this will be all available protocols but
+can be limited by either the now deprecated `protocol` param or by
+setting a comma seperated list to the newly added `protocols` parameter.
+
+Understanding Connectors
+========================
+
+Whereas acceptors are used on the server to define how we accept
+connections, connectors are used by a client to define how it connects
+to a server.
+
+Let's look at a connector defined in our `activemq-configuration.xml`
+file:
+
+ <connectors>
+ <connector name="netty">
+ <factory-class>
+ org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
+ </factory-class>
+ <param key="port" value="5446"/>
+ </connector>
+ </connectors>
+
+Connectors can be defined inside a `connectors` element. There can be
+one or more connectors defined in the `connectors` element. There's no
+upper limit to the number of connectors per server.
+
+You make ask yourself, if connectors are used by the *client* to make
+connections then why are they defined on the *server*? There are a
+couple of reasons for this:
+
+- Sometimes the server acts as a client itself when it connects to
+ another server, for example when one server is bridged to another,
+ or when a server takes part in a cluster. In this cases the server
+ needs to know how to connect to other servers. That's defined by
+ *connectors*.
+
+- If you're using JMS and you're using JNDI on the client to look up
+ your JMS connection factory instances then when creating the
+ `ActiveMQConnectionFactory` it needs to know what server that
+ connection factory will create connections to.
+
+ That's defined by the `java.naming.provider.url` element in the JNDI
+ context environment, e.g. `jndi.properties`. Behind the scenes, the
+ `org.apache.activemq.jndi.ActiveMQInitialContextFactory` uses the
+ `java.naming.provider.url` to construct the transport. Here's a
+ simple example:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+
+Configuring the transport directly from the client side.
+========================================================
+
+How do we configure a core `ClientSessionFactory` with the information
+that it needs to connect with a server?
+
+Connectors are also used indirectly when directly configuring a core
+`ClientSessionFactory` to directly talk to a server. Although in this
+case there's no need to define such a connector in the server side
+configuration, instead we just create the parameters and tell the
+`ClientSessionFactory` which connector factory to use.
+
+Here's an example of creating a `ClientSessionFactory` which will
+connect directly to the acceptor we defined earlier in this chapter, it
+uses the standard Netty TCP transport and will try and connect on port
+5446 to localhost (default):
+
+ Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+ connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
+ 5446);
+
+ TransportConfiguration transportConfiguration =
+ new TransportConfiguration(
+ "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
+ connectionParams);
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
+
+ ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
+
+ ClientSession session = sessionFactory.createSession(...);
+
+ etc
+
+Similarly, if you're using JMS, you can configure the JMS connection
+factory directly on the client side without having to define a connector
+on the server side or define a connection factory in `activemq-jms.xml`:
+
+ Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+ connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446);
+
+ TransportConfiguration transportConfiguration =
+ new TransportConfiguration(
+ "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
+ connectionParams);
+
+ ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
+
+ Connection jmsConnection = connectionFactory.createConnection();
+
+ etc
+
+Configuring the Netty transport
+===============================
+
+Out of the box, ActiveMQ currently uses
+[Netty](http://www.jboss.org/netty/), a high performance low level
+network library.
+
+Our Netty transport can be configured in several different ways; to use
+old (blocking) Java IO, or NIO (non-blocking), also to use
+straightforward TCP sockets, SSL, or to tunnel over HTTP or HTTPS..
+
+We believe this caters for the vast majority of transport requirements.
+
+Single Port Support
+-------------------
+
+As of version 2.4 ActiveMQ now supports using a single port for all
+protocols, ActiveMQ will automatically detect which protocol is being
+used CORE, AMQP, STOMP or OPENWIRE and use the appropriate ActiveMQ
+handler. It will also detect whether protocols such as HTTP or Web
+Sockets are being used and also use the appropriate decoders
+
+It is possible to limit which protocols are supported by using the
+`protocols` parameter on the Acceptor like so:
+
+ <param key="protocols" value="CORE,AMQP"/>
+
+
+> **Note**
+>
+> The `protocol` parameter is now deprecated
+
+Configuring Netty TCP
+---------------------
+
+Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP
+can be configured to use old blocking Java IO or non blocking Java NIO.
+We recommend you use the Java NIO on the server side for better
+scalability with many concurrent connections. However using Java old IO
+can sometimes give you better latency than NIO when you're not so
+worried about supporting many thousands of concurrent connections.
+
+If you're running connections across an untrusted network please bear in
+mind this transport is unencrypted. You may want to look at the SSL or
+HTTPS configurations.
+
+With the Netty TCP transport all connections are initiated from the
+client side. I.e. the server does not initiate any connections to the
+client. This works well with firewall policies that typically only allow
+connections to be initiated in one direction.
+
+All the valid Netty transport keys are defined in the class
+`org.apache.activemq.core.remoting.impl.netty.TransportConstants`. Most
+parameters can be used either with acceptors or connectors, some only
+work with acceptors. The following parameters can be used to configure
+Netty for simple TCP:
+
+- `use-nio`. If this is `true` then Java non blocking NIO will be
+ used. If set to `false` then old blocking Java IO will be used.
+
+ If you require the server to handle many concurrent connections, we
+ highly recommend that you use non blocking Java NIO. Java NIO does
+ not maintain a thread per connection so can scale to many more
+ concurrent connections than with old blocking IO. If you don't
+ require the server to handle many concurrent connections, you might
+ get slightly better performance by using old (blocking) IO. The
+ default value for this property is `false` on the server side and
+ `false` on the client side.
+
+- `host`. This specifies the host name or IP address to connect to
+ (when configuring a connector) or to listen on (when configuring an
+ acceptor). The default value for this property is `localhost`. When
+ configuring acceptors, multiple hosts or IP addresses can be
+ specified by separating them with commas. It is also possible to
+ specify `0.0.0.0` to accept connection from all the host's network
+ interfaces. It's not valid to specify multiple addresses when
+ specifying the host for a connector; a connector makes a connection
+ to one specific address.
+
+ > **Note**
+ >
+ > Don't forget to specify a host name or IP address! If you want
+ > your server able to accept connections from other nodes you must
+ > specify a hostname or IP address at which the acceptor will bind
+ > and listen for incoming connections. The default is localhost
+ > which of course is not accessible from remote nodes!
+
+- `port`. This specified the port to connect to (when configuring a
+ connector) or to listen on (when configuring an acceptor). The
+ default value for this property is `5445`.
+
+- `tcp-no-delay`. If this is `true` then [Nagle's
+ algorithm](http://en.wikipedia.org/wiki/Nagle%27s_algorithm) will be
+ disabled. This is a [Java (client) socket
+ option](http://docs.oracle.com/javase/7/docs/technotes/guides/net/socketOpt.html).
+ The default value for this property is `true`.
+
+- `tcp-send-buffer-size`. This parameter determines the size of the
+ TCP send buffer in bytes. The default value for this property is
+ `32768` bytes (32KiB).
+
+ TCP buffer sizes should be tuned according to the bandwidth and
+ latency of your network. Here's a good link that explains the theory
+ behind [this](http://www-didc.lbl.gov/TCP-tuning/).
+
+ In summary TCP send/receive buffer sizes should be calculated as:
+
+ buffer_size = bandwidth * RTT.
+
+ Where bandwidth is in *bytes per second* and network round trip time
+ (RTT) is in seconds. RTT can be easily measured using the `ping`
+ utility.
+
+ For fast networks you may want to increase the buffer sizes from the
+ defaults.
+
+- `tcp-receive-buffer-size`. This parameter determines the size of the
+ TCP receive buffer in bytes. The default value for this property is
+ `32768` bytes (32KiB).
+
+- `batch-delay`. Before writing packets to the transport, ActiveMQ can
+ be configured to batch up writes for a maximum of `batch-delay`
+ milliseconds. This can increase overall throughput for very small
+ messages. It does so at the expense of an increase in average
+ latency for message transfer. The default value for this property is
+ `0` ms.
+
+- `direct-deliver`. When a message arrives on the server and is
+ delivered to waiting consumers, by default, the delivery is done on
+ the same thread as that on which the message arrived. This gives
+ good latency in environments with relatively small messages and a
+ small number of consumers, but at the cost of overall throughput and
+ scalability - especially on multi-core machines. If you want the
+ lowest latency and a possible reduction in throughput then you can
+ use the default value for `direct-deliver` (i.e. true). If you are
+ willing to take some small extra hit on latency but want the highest
+ throughput set `direct-deliver` to `false
+ `.
+
+- `nio-remoting-threads`. When configured to use NIO, ActiveMQ will,
+ by default, use a number of threads equal to three times the number
+ of cores (or hyper-threads) as reported by
+ `Runtime.getRuntime().availableProcessors()` for processing incoming
+ packets. If you want to override this value, you can set the number
+ of threads by specifying this parameter. The default value for this
+ parameter is `-1` which means use the value from
+ `Runtime.getRuntime().availableProcessors()` \* 3.
+
+- `local-address`. When configured a Netty Connector it is possible to
+ specify which local address the client will use when connecting to
+ the remote address. This is typically used in the Application Server
+ or when running Embedded to control which address is used for
+ outbound connections. If the local-address is not set then the
+ connector will use any local address available
+
+- `local-port`. When configured a Netty Connector it is possible to
+ specify which local port the client will use when connecting to the
+ remote address. This is typically used in the Application Server or
+ when running Embedded to control which port is used for outbound
+ connections. If the local-port default is used, which is 0, then the
+ connector will let the system pick up an ephemeral port. valid ports
+ are 0 to 65535
+
+Configuring Netty SSL
+---------------------
+
+Netty SSL is similar to the Netty TCP transport but it provides
+additional security by encrypting TCP connections using the Secure
+Sockets Layer SSL
+
+Please see the examples for a full working example of using Netty SSL.
+
+Netty SSL uses all the same properties as Netty TCP but adds the
+following additional properties:
+
+- `ssl-enabled`
+
+ Must be `true` to enable SSL. Default is `false`.
+
+- `key-store-path`
+
+ When used on an `acceptor` this is the path to the SSL key store on
+ the server which holds the server's certificates (whether
+ self-signed or signed by an authority).
+
+ When used on a `connector` this is the path to the client-side SSL
+ key store which holds the client certificates. This is only relevant
+ for a `connector` if you are using 2-way SSL (i.e. mutual
+ authentication). Although this value is configured on the server, it
+ is downloaded and used by the client. If the client needs to use a
+ different path from that set on the server then it can override the
+ server-side setting by either using the customary
+ "javax.net.ssl.keyStore" system property or the ActiveMQ-specific
+ "org.apache.activemq.ssl.keyStore" system property. The
+ ActiveMQ-specific system property is useful if another component on
+ client is already making use of the standard, Java system property.
+
+- `key-store-password`
+
+ When used on an `acceptor` this is the password for the server-side
+ keystore.
+
+ When used on a `connector` this is the password for the client-side
+ keystore. This is only relevant for a `connector` if you are using
+ 2-way SSL (i.e. mutual authentication). Although this value can be
+ configured on the server, it is downloaded and used by the client.
+ If the client needs to use a different password from that set on the
+ server then it can override the server-side setting by either using
+ the customary "javax.net.ssl.keyStorePassword" system property or
+ the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword"
+ system property. The ActiveMQ-specific system property is useful if
+ another component on client is already making use of the standard,
+ Java system property.
+
+- `trust-store-path`
+
+ When used on an `acceptor` this is the path to the server-side SSL
+ key store that holds the keys of all the clients that the server
+ trusts. This is only relevant for an `acceptor` if you are using
+ 2-way SSL (i.e. mutual authentication).
+
+ When used on a `connector` this is the path to the client-side SSL
+ key store which holds the public keys of all the servers that the
+ client trusts. Although this value can be configured on the server,
+ it is downloaded and used by the client. If the client needs to use
+ a different path from that set on the server then it can override
+ the server-side setting by either using the customary
+ "javax.net.ssl.trustStore" system property or the ActiveMQ-specific
+ "org.apache.activemq.ssl.trustStore" system property. The
+ ActiveMQ-specific system property is useful if another component on
+ client is already making use of the standard, Java system property.
+
+- `trust-store-password`
+
+ When used on an `acceptor` this is the password for the server-side
+ trust store. This is only relevant for an `acceptor` if you are
+ using 2-way SSL (i.e. mutual authentication).
+
+ When used on a `connector` this is the password for the client-side
+ truststore. Although this value can be configured on the server, it
+ is downloaded and used by the client. If the client needs to use a
+ different password from that set on the server then it can override
+ the server-side setting by either using the customary
+ "javax.net.ssl.trustStorePassword" system property or the
+ ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword"
+ system property. The ActiveMQ-specific system property is useful if
+ another component on client is already making use of the standard,
+ Java system property.
+
+- `enabled-cipher-suites`
+
+ Whether used on an `acceptor` or `connector` this is a comma
+ separated list of cipher suites used for SSL communication. The
+ default value is `null` which means the JVM's default will be used.
+
+- `enabled-protocols`
+
+ Whether used on an `acceptor` or `connector` this is a comma
+ separated list of protocols used for SSL communication. The default
+ value is `null` which means the JVM's default will be used.
+
+- `need-client-auth`
+
+ This property is only for an `acceptor`. It tells a client
+ connecting to this acceptor that 2-way SSL is required. Valid values
+ are `true` or `false`. Default is `false`.
+
+Configuring Netty HTTP
+----------------------
+
+Netty HTTP tunnels packets over the HTTP protocol. It can be useful in
+scenarios where firewalls only allow HTTP traffic to pass.
+
+Please see the examples for a full working example of using Netty HTTP.
+
+Netty HTTP uses the same properties as Netty TCP but adds the following
+additional properties:
+
+- `http-enabled`. This is now no longer needed as of version 2.4. With
+ single port support ActiveMQ will now automatically detect if http
+ is being used and configure itself.
+
+- `http-client-idle-time`. How long a client can be idle before
+ sending an empty http request to keep the connection alive
+
+- `http-client-idle-scan-period`. How often, in milliseconds, to scan
+ for idle clients
+
+- `http-response-time`. How long the server can wait before sending an
+ empty http response to keep the connection alive
+
+- `http-server-scan-period`. How often, in milliseconds, to scan for
+ clients needing responses
+
+- `http-requires-session-id`. If true the client will wait after the
+ first call to receive a session id. Used the http connector is
+ connecting to servlet acceptor (not recommended)
+
+Configuring Netty Servlet
+-------------------------
+
+As of 2.4 ActiveMQ Servlet support will be provided via Undertow in
+Wildfly
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuring-transports.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuring-transports.xml b/docs/user-manual/en/configuring-transports.xml
deleted file mode 100644
index 7e61d50..0000000
--- a/docs/user-manual/en/configuring-transports.xml
+++ /dev/null
@@ -1,443 +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="configuring-transports">
- <title>Configuring the Transport</title>
- <para>ActiveMQ has a fully pluggable and highly flexible transport layer and defines its own
- Service Provider Interface (SPI) to make plugging in a new transport provider relatively
- straightforward.</para>
- <para>In this chapter we'll describe the concepts required for understanding ActiveMQ transports
- and where and how they're configured.</para>
- <section id="configuring-transports.acceptors">
- <title>Understanding Acceptors</title>
- <para>One of the most important concepts in ActiveMQ transports is the
- <emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
- defined in xml in the configuration file <literal
- >activemq-configuration.xml</literal>.</para>
- <programlisting>
-<acceptors>
- <acceptor name="netty">
- <factory-class>
- org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory
- </factory-class>
- <param key="port" value="5446"/>
- </acceptor>
-</acceptors></programlisting>
- <para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can
- be one or more acceptors defined in the <literal>acceptors</literal> element. There's no
- upper limit to the number of acceptors per server.</para>
- <para>Each acceptor defines a way in which connections can be made to the ActiveMQ
- server.</para>
- <para>In the above example we're defining an acceptor that uses <ulink
- url="http://jboss.org/netty">Netty</ulink> to listen for connections at port
- <literal>5446</literal>. </para>
- <para>The <literal>acceptor</literal> element contains a sub-element <literal
- >factory-class</literal>, this element defines the factory used to create acceptor
- instances. In this case we're using Netty to listen for connections so we use the Netty
- implementation of an <literal>AcceptorFactory</literal> to do this. Basically, the
- <literal>factory-class</literal> element determines which pluggable transport we're
- going to use to do the actual listening.</para>
- <para>The <literal>acceptor</literal> element can also be configured with zero or more
- <literal>param</literal> sub-elements. Each <literal>param</literal> element defines
- a key-value pair. These key-value pairs are used to configure the specific transport,
- the set of valid key-value pairs depends on the specific transport be used and are
- passed straight through to the underlying transport.</para>
- <para>Examples of key-value pairs for a particular transport would be, say, to configure the
- IP address to bind to, or the port to listen at.</para>
- <para>Note that unlike versions before 2.4 an Acceptor can now support multiple protocols. By default this will
- be all available protocols but can be limited by either the now deprecated <literal>protocol</literal> param or
- by setting a comma seperated list to the newly added <literal>protocols</literal> parameter.</para>
- </section>
- <section id="configuring-transports.connectors">
- <title>Understanding Connectors</title>
- <para>Whereas acceptors are used on the server to define how we accept connections,
- connectors are used by a client to define how it connects to a server.</para>
- <para>Let's look at a connector defined in our <literal>activemq-configuration.xml</literal>
- file:</para>
- <programlisting>
-<connectors>
- <connector name="netty">
- <factory-class>
- org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
- </factory-class>
- <param key="port" value="5446"/>
- </connector>
-</connectors></programlisting>
- <para>Connectors can be defined inside a <literal>connectors</literal> element. There can be
- one or more connectors defined in the <literal>connectors</literal> element. There's no
- upper limit to the number of connectors per server.</para>
- <para>You make ask yourself, if connectors are used by the <emphasis>client</emphasis> to
- make connections then why are they defined on the <emphasis>server</emphasis>? There are
- a couple of reasons for this:</para>
- <itemizedlist>
- <listitem>
- <para>Sometimes the server acts as a client itself when it connects to another
- server, for example when one server is bridged to another, or when a server
- takes part in a cluster. In this cases the server needs to know how to connect
- to other servers. That's defined by <emphasis>connectors</emphasis>.</para>
- </listitem>
- <listitem>
- <para>If you're using JMS and you're using JNDI on the client to look up your JMS connection factory
- instances then when creating the <literal>ActiveMQConnectionFactory</literal> it needs to know what
- server that connection factory will create connections to.</para>
- <para>That's defined by the <literal>java.naming.provider.url</literal> element in the JNDI context
- environment, e.g. <literal>jndi.properties</literal>. Behind the scenes, the
- <literal>org.apache.activemq.jndi.ActiveMQInitialContextFactory</literal> uses the
- <literal>java.naming.provider.url</literal> to construct the transport. Here's a simple example:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445</programlisting>
- </listitem>
- </itemizedlist>
- </section>
- <section id="configuring-transports.client.side">
- <title>Configuring the transport directly from the client side.</title>
- <para>How do we configure a core <literal>ClientSessionFactory</literal> with the
- information that it needs to connect with a server?</para>
- <para>Connectors are also used indirectly when directly configuring a core <literal
- >ClientSessionFactory</literal> to directly talk to a server. Although in this case
- there's no need to define such a connector in the server side configuration, instead we
- just create the parameters and tell the <literal>ClientSessionFactory</literal> which
- connector factory to use.</para>
- <para>Here's an example of creating a <literal>ClientSessionFactory</literal> which will
- connect directly to the acceptor we defined earlier in this chapter, it uses the
- standard Netty TCP transport and will try and connect on port 5446 to localhost
- (default):</para>
- <programlisting>
-Map<String, Object> connectionParams = new HashMap<String, Object>();
-
-connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
- 5446);
-
-TransportConfiguration transportConfiguration =
- new TransportConfiguration(
- "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
- connectionParams);
-
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
-
-ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
-
-ClientSession session = sessionFactory.createSession(...);
-
-etc</programlisting>
- <para>Similarly, if you're using JMS, you can configure the JMS connection factory directly
- on the client side without having to define a connector on the server side or define a
- connection factory in <literal>activemq-jms.xml</literal>:</para>
- <programlisting>
-Map<String, Object> connectionParams = new HashMap<String, Object>();
-
-connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446);
-
-TransportConfiguration transportConfiguration =
- new TransportConfiguration(
- "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
- connectionParams);
-
-ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
-
-Connection jmsConnection = connectionFactory.createConnection();
-
-etc</programlisting>
- </section>
- <section id="configuring-transports.netty">
- <title>Configuring the Netty transport</title>
- <para>Out of the box, ActiveMQ currently uses <ulink url="http://www.jboss.org/netty/"
- >Netty</ulink>, a high performance low level network library.</para>
- <para>Our Netty transport can be configured in several different ways; to use old (blocking)
- Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
- tunnel over HTTP or HTTPS..</para>
- <para>We believe this caters for the vast majority of transport requirements.</para>
- <section id="configuring-transports.single-port">
- <title>Single Port Support</title>
- <para>As of version 2.4 ActiveMQ now supports using a single port for all protocols, ActiveMQ will automatically
- detect which protocol is being used CORE, AMQP, STOMP or OPENWIRE and use the appropriate ActiveMQ handler. It will also detect
- whether protocols such as HTTP or Web Sockets are being used and also use the appropriate decoders</para>
- <para>It is possible to limit which protocols are supported by using the <literal>protocols</literal> parameter
- on the Acceptor like so:</para>
- <programlisting>
- <param key="protocols" value="CORE,AMQP"/>
- </programlisting>
- <note><para>The <literal>protocol</literal> parameter is now deprecated</para></note>
- </section>
- <section>
- <title>Configuring Netty TCP</title>
- <para>Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
- configured to use old blocking Java IO or non blocking Java NIO. We recommend you
- use the Java NIO on the server side for better scalability with many concurrent
- connections. However using Java old IO can sometimes give you better latency than
- NIO when you're not so worried about supporting many thousands of concurrent
- connections. </para>
- <para>If you're running connections across an untrusted network please bear in mind this
- transport is unencrypted. You may want to look at the SSL or HTTPS
- configurations.</para>
- <para>With the Netty TCP transport all connections are initiated from the client side.
- I.e. the server does not initiate any connections to the client. This works well
- with firewall policies that typically only allow connections to be initiated in one
- direction.</para>
- <para>All the valid Netty transport keys are defined in the class <literal
- >org.apache.activemq.core.remoting.impl.netty.TransportConstants</literal>. Most
- parameters can be used either with acceptors or connectors, some only work with
- acceptors. The following parameters can be used to configure Netty for simple
- TCP:</para>
- <itemizedlist>
- <listitem>
- <para><literal>use-nio</literal>. If this is <literal>true</literal> then Java
- non blocking NIO will be used. If set to <literal>false</literal> then old
- blocking Java IO will be used.</para>
- <para>If you require the server to handle many concurrent connections, we highly
- recommend that you use non blocking Java NIO. Java NIO does not maintain a
- thread per connection so can scale to many more concurrent connections than
- with old blocking IO. If you don't require the server to handle many
- concurrent connections, you might get slightly better performance by using
- old (blocking) IO. The default value for this property is <literal
- >false</literal> on the server side and <literal>false</literal> on the
- client side.</para>
- </listitem>
- <listitem>
- <para><literal>host</literal>. This specifies the host name or IP address to
- connect to (when configuring a connector) or to listen on (when configuring
- an acceptor). The default value for this property is <literal
- >localhost</literal>. When configuring acceptors, multiple hosts or IP
- addresses can be specified by separating them with commas. It is also
- possible to specify <code>0.0.0.0</code> to accept connection from all the
- host's network interfaces. It's not valid to specify multiple addresses when
- specifying the host for a connector; a connector makes a connection to one
- specific address.</para>
- <note>
- <para>Don't forget to specify a host name or IP address! If you want your
- server able to accept connections from other nodes you must specify a
- hostname or IP address at which the acceptor will bind and listen for
- incoming connections. The default is localhost which of course is not
- accessible from remote nodes!</para>
- </note>
- </listitem>
- <listitem>
- <para><literal>port</literal>. This specified the port to connect to (when
- configuring a connector) or to listen on (when configuring an acceptor). The
- default value for this property is <literal>5445</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>tcp-no-delay</literal>. If this is <literal>true</literal> then
- <ulink url="http://en.wikipedia.org/wiki/Nagle%27s_algorithm">Nagle's
- algorithm</ulink> will be disabled. This is a
- <ulink url="http://docs.oracle.com/javase/7/docs/technotes/guides/net/socketOpt.html">Java (client) socket option</ulink>. The default value for this property is <literal>true</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>tcp-send-buffer-size</literal>. This parameter determines the
- size of the TCP send buffer in bytes. The default value for this property is
- <literal>32768</literal> bytes (32KiB).</para>
- <para>TCP buffer sizes should be tuned according to the bandwidth and latency of
- your network. Here's a good link that explains the theory behind <ulink
- url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>.</para>
- <para>In summary TCP send/receive buffer sizes should be calculated as:</para>
- <programlisting>
-buffer_size = bandwidth * RTT.</programlisting>
- <para>Where bandwidth is in <emphasis>bytes per second</emphasis> and network
- round trip time (RTT) is in seconds. RTT can be easily measured using the
- <literal>ping</literal> utility.</para>
- <para>For fast networks you may want to increase the buffer sizes from the
- defaults.</para>
- </listitem>
- <listitem>
- <para><literal>tcp-receive-buffer-size</literal>. This parameter determines the
- size of the TCP receive buffer in bytes. The default value for this property
- is <literal>32768</literal> bytes (32KiB).</para>
- </listitem>
- <listitem>
- <para><literal>batch-delay</literal>. Before writing packets to the transport,
- ActiveMQ can be configured to batch up writes for a maximum of <literal
- >batch-delay</literal> milliseconds. This can increase overall
- throughput for very small messages. It does so at the expense of an increase
- in average latency for message transfer. The default value for this property
- is <literal>0</literal> ms.</para>
- </listitem>
- <listitem>
- <para><literal>direct-deliver</literal>. When a message arrives on the server
- and is delivered to waiting consumers, by default, the delivery is done on
- the same thread as that on which the message arrived. This gives good latency
- in environments with relatively small messages and a small number of consumers,
- but at the cost of overall throughput and scalability - especially on multi-core
- machines. If you want the lowest latency and a possible reduction in throughput
- then you can use the default value for <literal>direct-deliver</literal> (i.e.
- true). If you are willing to take some small extra hit on latency but want the
- highest throughput set <literal>direct-deliver</literal> to <literal>false
- </literal>.</para>
- </listitem>
- <listitem>
- <para><literal>nio-remoting-threads</literal>. When configured to use NIO,
- ActiveMQ will, by default, use a number of threads equal to three times the
- number of cores (or hyper-threads) as reported by <literal
- >Runtime.getRuntime().availableProcessors()</literal> for processing
- incoming packets. If you want to override this value, you can set the number
- of threads by specifying this parameter. The default value for this
- parameter is <literal>-1</literal> which means use the value from <literal
- >Runtime.getRuntime().availableProcessors()</literal> * 3.</para>
- </listitem>
- <listitem>
- <para><literal>local-address</literal>. When configured a Netty Connector it is possible to specify
- which local address the client will use when connecting to the remote address. This is typically used
- in the Application Server or when running Embedded to control which address is used for outbound
- connections. If the local-address is not set then the connector will use any local address available</para>
- </listitem>
- <listitem>
- <para><literal>local-port</literal>. When configured a Netty Connector it is possible to specify
- which local port the client will use when connecting to the remote address. This is typically used
- in the Application Server or when running Embedded to control which port is used for outbound
- connections. If the local-port default is used, which is 0, then the connector will let the
- system pick up an ephemeral port. valid ports are 0 to 65535</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Configuring Netty SSL</title>
- <para>Netty SSL is similar to the Netty TCP transport but it provides additional
- security by encrypting TCP connections using the Secure Sockets Layer SSL</para>
- <para>Please see the examples for a full working example of using Netty SSL.</para>
- <para>Netty SSL uses all the same properties as Netty TCP but adds the following
- additional properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>ssl-enabled</literal></para>
- <para>Must be <literal>true</literal> to enable SSL. Default is <literal>false</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>key-store-path</literal></para>
- <para>When used on an <literal>acceptor</literal> this is the path to the SSL key
- store on the server which holds the server's certificates (whether self-signed
- or signed by an authority).</para>
- <para>When used on a <literal>connector</literal> this is the path to the client-side
- SSL key store which holds the client certificates. This is only relevant
- for a <literal>connector</literal> if you are using 2-way SSL (i.e. mutual
- authentication). Although this value is configured on the server, it is
- downloaded and used by the client. If the client needs to use a different path
- from that set on the server then it can override the server-side setting by either
- using the customary "javax.net.ssl.keyStore" system property or the ActiveMQ-specific
- "org.apache.activemq.ssl.keyStore" system property. The ActiveMQ-specific system property
- is useful if another component on client is already making use of the standard, Java
- system property.</para>
- </listitem>
- <listitem>
- <para><literal>key-store-password</literal></para>
- <para>When used on an <literal>acceptor</literal> this is the password for the
- server-side keystore.</para>
- <para>When used on a <literal>connector</literal> this is the password for the
- client-side keystore. This is only relevant for a <literal>connector</literal>
- if you are using 2-way SSL (i.e. mutual authentication). Although this value can
- be configured on the server, it is downloaded and used by the client. If the client
- needs to use a different password from that set on the server then it can override
- the server-side setting by either using the customary "javax.net.ssl.keyStorePassword"
- system property or the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword" system
- property. The ActiveMQ-specific system property is useful if another component on client
- is already making use of the standard, Java system property.</para>
- </listitem>
- <listitem>
- <para><literal>trust-store-path</literal></para>
- <para>When used on an <literal>acceptor</literal> this is the path to the server-side
- SSL key store that holds the keys of all the clients that the server trusts. This
- is only relevant for an <literal>acceptor</literal> if you are using 2-way SSL
- (i.e. mutual authentication).</para>
- <para>When used on a <literal>connector</literal> this is the path to the client-side
- SSL key store which holds the public keys of all the servers that the client
- trusts. Although this value can be configured on the server, it is downloaded and
- used by the client. If the client needs to use a different path
- from that set on the server then it can override the server-side setting by either
- using the customary "javax.net.ssl.trustStore" system property or the ActiveMQ-specific
- "org.apache.activemq.ssl.trustStore" system property. The ActiveMQ-specific system property
- is useful if another component on client is already making use of the standard, Java
- system property.</para>
- </listitem>
- <listitem>
- <para><literal>trust-store-password</literal></para>
- <para>When used on an <literal>acceptor</literal> this is the password for the
- server-side trust store. This is only relevant for an <literal>acceptor</literal>
- if you are using 2-way SSL (i.e. mutual authentication).</para>
- <para>When used on a <literal>connector</literal> this is the password for the
- client-side truststore. Although this value can be configured on the server, it is
- downloaded and used by the client. If the client
- needs to use a different password from that set on the server then it can override
- the server-side setting by either using the customary "javax.net.ssl.trustStorePassword"
- system property or the ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword" system
- property. The ActiveMQ-specific system property is useful if another component on client
- is already making use of the standard, Java system property.</para>
- </listitem>
- <listitem>
- <para><literal>enabled-cipher-suites</literal></para>
- <para>Whether used on an <literal>acceptor</literal> or <literal>connector</literal> this is a
- comma separated list of cipher suites used for SSL communication. The default value is
- <literal>null</literal> which means the JVM's default will be used.</para>
- </listitem>
- <listitem>
- <para><literal>enabled-protocols</literal></para>
- <para>Whether used on an <literal>acceptor</literal> or <literal>connector</literal> this is a
- comma separated list of protocols used for SSL communication. The default value is
- <literal>null</literal> which means the JVM's default will be used.</para>
- </listitem>
- <listitem>
- <para><literal>need-client-auth</literal></para>
- <para>This property is only for an <literal>acceptor</literal>. It tells a client connecting to this
- acceptor that 2-way SSL is required. Valid values are <literal>true</literal> or
- <literal>false</literal>. Default is <literal>false</literal>.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Configuring Netty HTTP</title>
- <para>Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios
- where firewalls only allow HTTP traffic to pass.</para>
- <para>Please see the examples for a full working example of using Netty HTTP.</para>
- <para>Netty HTTP uses the same properties as Netty TCP but adds the following additional
- properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>http-enabled</literal>. This is now no longer needed as of version 2.4. With single
- port support ActiveMQ will now automatically detect if http is being used and configure itself.</para>
- </listitem>
- <listitem>
- <para><literal>http-client-idle-time</literal>. How long a client can be idle
- before sending an empty http request to keep the connection alive</para>
- </listitem>
- <listitem>
- <para><literal>http-client-idle-scan-period</literal>. How often, in
- milliseconds, to scan for idle clients</para>
- </listitem>
- <listitem>
- <para><literal>http-response-time</literal>. How long the server can wait before
- sending an empty http response to keep the connection alive</para>
- </listitem>
- <listitem>
- <para><literal>http-server-scan-period</literal>. How often, in milliseconds, to
- scan for clients needing responses</para>
- </listitem>
- <listitem>
- <para><literal>http-requires-session-id</literal>. If true the client will wait
- after the first call to receive a session id. Used the http connector is
- connecting to servlet acceptor (not recommended) </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Configuring Netty Servlet</title>
- <para>As of 2.4 ActiveMQ Servlet support will be provided via Undertow in Wildfly</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/connection-ttl.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md
new file mode 100644
index 0000000..80af334
--- /dev/null
+++ b/docs/user-manual/en/connection-ttl.md
@@ -0,0 +1,198 @@
+Detecting Dead Connections
+==========================
+
+In this section we will discuss connection time-to-live (TTL) and
+explain how ActiveMQ deals with crashed clients and clients which have
+exited without cleanly closing their resources.
+
+Cleaning up Dead Connection Resources on the Server
+===================================================
+
+Before a ActiveMQ client application exits it is considered good
+practice that it should close its resources in a controlled manner,
+using a `finally` block.
+
+Here's an example of a well behaved core client application closing its
+session and session factory in a finally block:
+
+ ServerLocator locator = null;
+ ClientSessionFactory sf = null;
+ ClientSession session = null;
+
+ try
+ {
+ locator = ActiveMQClient.createServerLocatorWithoutHA(..);
+
+ sf = locator.createClientSessionFactory();;
+
+ session = sf.createSession(...);
+
+ ... do some stuff with the session...
+ }
+ finally
+ {
+ if (session != null)
+ {
+ session.close();
+ }
+
+ if (sf != null)
+ {
+ sf.close();
+ }
+
+ if(locator != null)
+ {
+ locator.close();
+ }
+ }
+
+And here's an example of a well behaved JMS client application:
+
+ Connection jmsConnection = null;
+
+ try
+ {
+ ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
+
+ jmsConnection = jmsConnectionFactory.createConnection();
+
+ ... do some stuff with the connection...
+ }
+ finally
+ {
+ if (connection != null)
+ {
+ connection.close();
+ }
+ }
+
+Unfortunately users don't always write well behaved applications, and
+sometimes clients just crash so they don't have a chance to clean up
+their resources!
+
+If this occurs then it can leave server side resources, like sessions,
+hanging on the server. If these were not removed they would cause a
+resource leak on the server and over time this result in the server
+running out of memory or other resources.
+
+We have to balance the requirement for cleaning up dead client resources
+with the fact that sometimes the network between the client and the
+server can fail and then come back, allowing the client to reconnect.
+ActiveMQ supports client reconnection, so we don't want to clean up
+"dead" server side resources too soon or this will prevent any client
+from reconnecting, as it won't be able to find its old sessions on the
+server.
+
+ActiveMQ makes all of this configurable. For each `ClientSessionFactory`
+we define a *connection TTL*. Basically, the TTL determines how long the
+server will keep a connection alive in the absence of any data arriving
+from the client. The client will automatically send "ping" packets
+periodically to prevent the server from closing it down. If the server
+doesn't receive any packets on a connection for the connection TTL time,
+then it will automatically close all the sessions on the server that
+relate to that connection.
+
+If you're using JMS, the connection TTL is defined by the
+`ConnectionTTL` attribute on a `ActiveMQConnectionFactory` instance, or
+if you're deploying JMS connection factory instances direct into JNDI on
+the server side, you can specify it in the xml config, using the
+parameter `connection-ttl`.
+
+The default value for connection ttl on an "unreliable" connection (e.g.
+a Netty connection) is `60000`ms, i.e. 1 minute. The default value for
+connection ttl on a "reliable" connection (e.g. an in-vm connection) is
+`-1`. A value of `-1` for `ConnectionTTL` means the server will never
+time out the connection on the server side.
+
+If you do not wish clients to be able to specify their own connection
+TTL, you can override all values used by a global value set on the
+server side. This can be done by specifying the
+`connection-ttl-override` attribute in the server side configuration.
+The default value for `connection-ttl-override` is `-1` which means "do
+not override" (i.e. let clients use their own values).
+
+Closing core sessions or JMS connections that you have failed to close
+----------------------------------------------------------------------
+
+As previously discussed, it's important that all core client sessions
+and JMS connections are always closed explicitly in a `finally` block
+when you are finished using them.
+
+If you fail to do so, ActiveMQ will detect this at garbage collection
+time, and log a warning similar to the following in the logs (If you are
+using JMS the warning will involve a JMS connection not a client
+session):
+
+ [Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] I'm closing a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
+ ting them go out of scope!
+ [Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] The session you didn't close was created here:
+ java.lang.Exception
+ at org.apache.activemq.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
+ at org.acme.yourproject.YourClass (YourClass.java:666)
+
+ActiveMQ will then close the connection / client session for you.
+
+Note that the log will also tell you the exact line of your user code
+where you created the JMS connection / client session that you later did
+not close. This will enable you to pinpoint the error in your code and
+correct it appropriately.
+
+Detecting failure from the client side.
+=======================================
+
+In the previous section we discussed how the client sends pings to the
+server and how "dead" connection resources are cleaned up by the server.
+There's also another reason for pinging, and that's for the *client* to
+be able to detect that the server or network has failed.
+
+As long as the client is receiving data from the server it will consider
+the connection to be still alive.
+
+If the client does not receive any packets for
+`client-failure-check-period` milliseconds then it will consider the
+connection failed and will either initiate failover, or call any
+`FailureListener` instances (or `ExceptionListener` instances if you are
+using JMS) depending on how it has been configured.
+
+If you're using JMS it's defined by the `ClientFailureCheckPeriod`
+attribute on a `ActiveMQConnectionFactory` instance, or if you're
+deploying JMS connection factory instances direct into JNDI on the
+server side, you can specify it in the `activemq-jms.xml ` configuration
+file, using the parameter `client-failure-check-period`.
+
+The default value for client failure check period on an "unreliable"
+connection (e.g. a Netty connection) is `30000`ms, i.e. 30 seconds. The
+default value for client failure check period on a "reliable" connection
+(e.g. an in-vm connection) is `-1`. A value of `-1` means the client
+will never fail the connection on the client side if no data is received
+from the server. Typically this is much lower than connection TTL to
+allow clients to reconnect in case of transitory failure.
+
+Configuring Asynchronous Connection Execution
+=============================================
+
+Most packets received on the server side are executed on the remoting
+thread. These packets represent short-running operations and are always
+executed on the remoting thread for performance reasons.
+
+However, by default some kinds of packets are executed using a thread
+from a thread pool so that the remoting thread is not tied up for too
+long. Please note that processing operations asynchronously on another
+thread adds a little more latency. These packets are:
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.RollbackMessage`
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.SessionCloseMessage`
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.SessionCommitMessage`
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXACommitMessage`
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXAPrepareMessage`
+
+- `org.apache.activemq.core.protocol.core.impl.wireformat.SessionXARollbackMessage`
+
+To disable asynchronous connection execution, set the parameter
+`async-connection-execution-enabled` in `activemq-configuration.xml` to
+`false` (default value is `true`).
[15/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/embedding-activemq.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/embedding-activemq.xml b/docs/user-manual/en/embedding-activemq.xml
deleted file mode 100644
index e19d786..0000000
--- a/docs/user-manual/en/embedding-activemq.xml
+++ /dev/null
@@ -1,270 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd"> -->
-<!-- ============================================================================= -->
-<!-- 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="embedding-activemq">
- <title>Embedding ActiveMQ</title>
-
- <para>ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
- This means ActiveMQ can be instantiated and run in any dependency injection
- framework such as JBoss Microcontainer, Spring or Google Guice. It also
- means that if you have an application that could use messaging functionality
- internally, then it can <emphasis>directly instantiate</emphasis> ActiveMQ
- clients and servers in its own application code to perform that
- functionality. We call this <emphasis>embedding</emphasis> ActiveMQ.</para>
-
- <para>Examples of applications that might want to do this include any
- application that needs very high performance, transactional, persistent
- messaging but doesn't want the hassle of writing it all from scratch.</para>
-
- <para>Embedding ActiveMQ can be done in very few easy steps. Instantiate the
- configuration object, instantiate the server, start it, and you have a
- ActiveMQ running in your virtual machine. It's as simple and easy as
- that.</para>
-
- <section>
- <title>Simple Config File Embedding</title>
-
- <para>The simplest way to embed ActiveMQ is to use the embedded wrapper
- classes and configure ActiveMQ through its configuration files. There are
- two different helper classes for this depending on whether your using the
- ActiveMQ Core API or JMS.</para>
-
- <section>
- <title>Core API Only</title>
- <para>For instantiating a core ActiveMQ Server only, the steps are pretty
- simple. The example requires that you have defined a configuration file
- <literal>activemq-configuration.xml</literal> in your
- classpath:</para>
- <programlisting>
-import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
-
-...
-
-EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
-embedded.start();
-
-ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
- new TransportConfiguration(
- InVMConnectorFactory.class.getName()));
-
-ClientSession session = factory.createSession();
-
-session.createQueue("example", "example", true);
-
-ClientProducer producer = session.createProducer("example");
-
-ClientMessage message = session.createMessage(true);
-
-message.getBody().writeString("Hello");
-
-producer.send(message);
-
-session.start();
-
-ClientConsumer consumer = session.createConsumer("example");
-
-ClientMessage msgReceived = consumer.receive();
-
-System.out.println("message = " + msgReceived.getBody().readString());
-
-session.close();</programlisting>
-
-<para>The <literal>EmbeddedActiveMQ</literal> class has a
- few additional setter methods that allow you to specify a different
- config file name as well as other properties. See the javadocs for this
- class for more details.</para>
- </section>
-
- <section id="simple.embedded.jms">
- <title>JMS API</title>
-
- <para>JMS embedding is simple as well. This example requires that you
- have defined the config files
- <literal>activemq-configuration.xml</literal>,
- <literal>activemq-jms.xml</literal>, and a
- <literal>activemq-users.xml</literal> if you have security enabled. Let's
- also assume that a queue and connection factory has been defined in the
- <literal>activemq-jms.xml</literal> config file.</para>
-
- <programlisting>
-import org.apache.activemq.jms.server.embedded.EmbeddedJMS;
-
-...
-
-EmbeddedJMS jms = new EmbeddedJMS();
-jms.start();
-
-// This assumes we have configured activemq-jms.xml with the appropriate config information
-ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
-Destination destination = jms.lookup("/example/queue");
-
-... regular JMS code ...</programlisting>
- <para>By default, the <literal>EmbeddedJMS</literal>
- class will store component entries defined within your
- <literal>activemq-jms.xml</literal> file in an internal concurrent hash
- map. The <literal>EmbeddedJMS.lookup()</literal> method returns
- components stored in this map. If you want to use JNDI, call the
- <literal>EmbeddedJMS.setContext()</literal> method with the root JNDI
- context you want your components bound into. See the javadocs for this
- class for more details on other config options.</para>
- </section>
- </section>
-
- <section>
- <title>POJO instantiation - Embedding Programmatically</title>
-
- <para>You can follow this step-by-step guide to programmatically embed the
- core, non-JMS ActiveMQ Server instance:</para>
-
- <para>Create the configuration object - this contains configuration
- information for a ActiveMQ instance. The setter methods of this class allow
- you to programmatically set configuration options as describe in the <xref
- linkend="server.configuration" /> section.</para>
-
- <para>The acceptors are configured through
- <literal>ConfigurationImpl</literal>. Just add the
- <literal>NettyAcceptorFactory</literal> on the transports the same way you
- would through the main configuration file.</para>
-
- <programlisting>
-import org.apache.activemq.core.config.Configuration;
-import org.apache.activemq.core.config.impl.ConfigurationImpl;
-
-...
-
-Configuration config = new ConfigurationImpl();
-HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
-
-transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
-transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
-
-config.setAcceptorConfigurations(transports);</programlisting>
-
- <para>You need to instantiate an instance of
- <literal>org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ</literal>
- and add the configuration object to it.</para>
-
- <programlisting>
-import org.apache.activemq.api.core.server.ActiveMQ;
-import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
-
-...
-
-EmbeddedActiveMQ server = new EmbeddedActiveMQ();
-server.setConfiguration(config);
-
-server.start();</programlisting>
-
- <para>You also have the option of instantiating
- <literal>ActiveMQServerImpl</literal> directly:</para>
-
- <programlisting>
-ActiveMQServer server = new ActiveMQServerImpl(config);
-server.start();</programlisting>
-
- <para>For JMS POJO instantiation, you work with the EmbeddedJMS class
- instead as described earlier. First you define the configuration
- programmatically for your ConnectionFactory and Destination objects, then
- set the JmsConfiguration property of the EmbeddedJMS class. Here is an
- example of this:</para>
-
- <programlisting>
-// Step 1. Create ActiveMQ core configuration, and set the properties accordingly
-Configuration configuration = new ConfigurationImpl();
-configuration.setPersistenceEnabled(false);
-configuration.setSecurityEnabled(false);
-configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
-
-// Step 2. Create the JMS configuration
-JMSConfiguration jmsConfig = new JMSConfigurationImpl();
-
-// Step 3. Configure the JMS ConnectionFactory
-TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
-ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
-jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
-
-// Step 4. Configure the JMS Queue
-JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
-jmsConfig.getQueueConfigurations().add(queueConfig);
-
-// Step 5. Start the JMS Server using the ActiveMQ core server and the JMS configuration
-EmbeddedJMS jmsServer = new EmbeddedJMS();
-jmsServer.setConfiguration(configuration);
-jmsServer.setJmsConfiguration(jmsConfig);
-jmsServer.start();</programlisting>
-
- <para>Please see <xref linkend="examples.embedded.jms" /> for an example which
- shows how to setup and run ActiveMQ embedded with JMS.</para>
- </section>
-
- <section>
- <title>Dependency Frameworks</title>
-
- <para>You may also choose to use a dependency injection framework such as
- <trademark>JBoss Micro Container</trademark> or <trademark>Spring
- Framework</trademark>. See <xref linkend="spring.integration" /> for more
- details on Spring and ActiveMQ, but here's how you would do things with the
- JBoss Micro Container.</para>
-
- <para>ActiveMQ standalone uses JBoss Micro Container as the injection
- framework. <literal>ActiveMQBootstrapServer</literal> and
- <literal>activemq-beans.xml</literal> which are part of the ActiveMQ
- distribution provide a very complete implementation of what's needed to
- bootstrap the server using JBoss Micro Container.</para>
-
- <para>When using JBoss Micro Container, you need to provide an XML file
- declaring the <literal>ActiveMQServer</literal> and
- <literal>Configuration</literal> object, you can also inject a security
- manager and a MBean server if you want, but those are optional.</para>
-
- <para>A very basic XML Bean declaration for the JBoss Micro Container
- would be:</para>
-
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<deployment xmlns="urn:jboss:bean-deployer:2.0">
- <!-- The core configuration -->
- <bean name="Configuration"
- class="org.apache.activemq.core.config.impl.FileConfiguration">
- </bean>
-
- <!-- The core server -->
- <bean name="ActiveMQServer"
- class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
- <constructor>
- <parameter>
- <inject bean="Configuration"/>
- </parameter>
- </constructor>
- </bean>
-</deployment></programlisting>
-
- <para><literal>ActiveMQBootstrapServer</literal> provides an easy
- encapsulation of JBoss Micro Container.</para>
-
- <programlisting>
-ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
-bootStrap.run();</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/examples.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/examples.md b/docs/user-manual/en/examples.md
new file mode 100644
index 0000000..52f45fa
--- /dev/null
+++ b/docs/user-manual/en/examples.md
@@ -0,0 +1,826 @@
+Examples
+========
+
+The ActiveMQ distribution comes with over 70 run out-of-the-box examples
+demonstrating many of the features.
+
+The examples are available in the distribution, in the `examples`
+directory. Examples are split into JMS and core examples. JMS examples
+show how a particular feature can be used by a normal JMS client. Core
+examples show how the equivalent feature can be used by a core messaging
+client.
+
+A set of Java EE examples are also provided which need WildFly installed
+to be able to run.
+
+JMS Examples
+============
+
+To run a JMS example, simply `cd` into the appropriate example directory
+and type `mvn verify` (For details please read the readme.html in each
+example directory).
+
+Here's a listing of the examples with a brief description.
+
+JMS AeroGear
+------------
+
+This example shows how you can send a message to a mobile device by
+leveraging AeroGears push technology which provides support for
+different push notification technologies like Google Cloud Messaging,
+Apple's APNs or Mozilla's SimplePush.
+
+Applet
+------
+
+This example shows you how to send and receive JMS messages from an
+Applet.
+
+Application-Layer Failover
+--------------------------
+
+ActiveMQ also supports Application-Layer failover, useful in the case
+that replication is not enabled on the server side.
+
+With Application-Layer failover, it's up to the application to register
+a JMS `ExceptionListener` with ActiveMQ which will be called by ActiveMQ
+in the event that connection failure is detected.
+
+The code in the `ExceptionListener` then recreates the JMS connection,
+session, etc on another node and the application can continue.
+
+Application-layer failover is an alternative approach to High
+Availability (HA). Application-layer failover differs from automatic
+failover in that some client side coding is required in order to
+implement this. Also, with Application-layer failover, since the old
+session object dies and a new one is created, any uncommitted work in
+the old session will be lost, and any unacknowledged messages might be
+redelivered.
+
+Core Bridge Example
+-------------------
+
+The `bridge` example demonstrates a core bridge deployed on one server,
+which consumes messages from a local queue and forwards them to an
+address on a second server.
+
+Core bridges are used to create message flows between any two ActiveMQ
+servers which are remotely separated. Core bridges are resilient and
+will cope with temporary connection failure allowing them to be an ideal
+choice for forwarding over unreliable connections, e.g. a WAN.
+
+Browser
+-------
+
+The `browser` example shows you how to use a JMS `QueueBrowser` with
+ActiveMQ.
+
+Queues are a standard part of JMS, please consult the JMS 1.1
+specification for full details.
+
+A `QueueBrowser` is used to look at messages on the queue without
+removing them. It can scan the entire content of a queue or only
+messages matching a message selector.
+
+Client Kickoff
+--------------
+
+The `client-kickoff` example shows how to terminate client connections
+given an IP address using the JMX management API.
+
+Client side failover listener
+-----------------------------
+
+The `client-side-failoverlistener` example shows how to register a
+listener to monitor failover events
+
+Client-Side Load-Balancing
+--------------------------
+
+The `client-side-load-balancing` example demonstrates how sessions
+created from a single JMS `Connection` can be created to different nodes
+of the cluster. In other words it demonstrates how ActiveMQ does
+client-side load-balancing of sessions across the cluster.
+
+Clustered Durable Subscription
+------------------------------
+
+This example demonstrates a clustered JMS durable subscription
+
+Clustered Grouping
+------------------
+
+This is similar to the message grouping example except that it
+demonstrates it working over a cluster. Messages sent to different nodes
+with the same group id will be sent to the same node and the same
+consumer.
+
+Clustered Queue
+---------------
+
+The `clustered-queue` example demonstrates a JMS queue deployed on two
+different nodes. The two nodes are configured to form a cluster. We then
+create a consumer for the queue on each node, and we create a producer
+on only one of the nodes. We then send some messages via the producer,
+and we verify that both consumers receive the sent messages in a
+round-robin fashion.
+
+Clustering with JGroups
+-----------------------
+
+The `clustered-jgroups` example demonstrates how to form a two node
+cluster using JGroups as its underlying topology discovery technique,
+rather than the default UDP broadcasting. We then create a consumer for
+the queue on each node, and we create a producer on only one of the
+nodes. We then send some messages via the producer, and we verify that
+both consumers receive the sent messages in a round-robin fashion.
+
+Clustered Standalone
+--------------------
+
+The `clustered-standalone` example demonstrates how to configure and
+starts 3 cluster nodes on the same machine to form a cluster. A
+subscriber for a JMS topic is created on each node, and we create a
+producer on only one of the nodes. We then send some messages via the
+producer, and we verify that the 3 subscribers receive all the sent
+messages.
+
+Clustered Static Discovery
+--------------------------
+
+This example demonstrates how to configure a cluster using a list of
+connectors rather than UDP for discovery
+
+Clustered Static Cluster One Way
+--------------------------------
+
+This example demonstrates how to set up a cluster where cluster
+connections are one way, i.e. server A -\> Server B -\> Server C
+
+Clustered Topic
+---------------
+
+The `clustered-topic` example demonstrates a JMS topic deployed on two
+different nodes. The two nodes are configured to form a cluster. We then
+create a subscriber on the topic on each node, and we create a producer
+on only one of the nodes. We then send some messages via the producer,
+and we verify that both subscribers receive all the sent messages.
+
+Message Consumer Rate Limiting
+------------------------------
+
+With ActiveMQ you can specify a maximum consume rate at which a JMS
+MessageConsumer will consume messages. This can be specified when
+creating or deploying the connection factory.
+
+If this value is specified then ActiveMQ will ensure that messages are
+never consumed at a rate higher than the specified rate. This is a form
+of consumer throttling.
+
+Dead Letter
+-----------
+
+The `dead-letter` example shows you how to define and deal with dead
+letter messages. Messages can be delivered unsuccessfully (e.g. if the
+transacted session used to consume them is rolled back).
+
+Such a message goes back to the JMS destination ready to be redelivered.
+However, this means it is possible for a message to be delivered again
+and again without any success and remain in the destination, clogging
+the system.
+
+To prevent this, messaging systems define dead letter messages: after a
+specified unsuccessful delivery attempts, the message is removed from
+the destination and put instead in a dead letter destination where they
+can be consumed for further investigation.
+
+Delayed Redelivery
+------------------
+
+The `delayed-redelivery` example demonstrates how ActiveMQ can be
+configured to provide a delayed redelivery in the case a message needs
+to be redelivered.
+
+Delaying redelivery can often be useful in the case that clients
+regularly fail or roll-back. Without a delayed redelivery, the system
+can get into a "thrashing" state, with delivery being attempted, the
+client rolling back, and delivery being re-attempted in quick
+succession, using up valuable CPU and network resources.
+
+Divert
+------
+
+ActiveMQ diverts allow messages to be transparently "diverted" or copied
+from one address to another with just some simple configuration defined
+on the server side.
+
+Durable Subscription
+--------------------
+
+The `durable-subscription` example shows you how to use a durable
+subscription with ActiveMQ. Durable subscriptions are a standard part of
+JMS, please consult the JMS 1.1 specification for full details.
+
+Unlike non-durable subscriptions, the key function of durable
+subscriptions is that the messages contained in them persist longer than
+the lifetime of the subscriber - i.e. they will accumulate messages sent
+to the topic even if there is no active subscriber on them. They will
+also survive server restarts or crashes. Note that for the messages to
+be persisted, the messages sent to them must be marked as durable
+messages.
+
+Embedded
+--------
+
+The `embedded` example shows how to embed JMS within your own code using
+POJO instantiation and no config files.
+
+Embedded Simple
+---------------
+
+The `embedded` example shows how to embed JMS within your own code using
+regular ActiveMQ XML files.
+
+Message Expiration
+------------------
+
+The `expiry` example shows you how to define and deal with message
+expiration. Messages can be retained in the messaging system for a
+limited period of time before being removed. JMS specification states
+that clients should not receive messages that have been expired (but it
+does not guarantee this will not happen).
+
+ActiveMQ can assign an expiry address to a given queue so that when
+messages are expired, they are removed from the queue and sent to the
+expiry address. These "expired" messages can later be consumed from the
+expiry address for further inspection.
+
+ActiveMQ Resource Adapter example
+---------------------------------
+
+This examples shows how to build the activemq resource adapters a rar
+for deployment in other Application Server's
+
+HTTP Transport
+--------------
+
+The `http-transport` example shows you how to configure ActiveMQ to use
+the HTTP protocol as its transport layer.
+
+Instantiate JMS Objects Directly
+--------------------------------
+
+Usually, JMS Objects such as `ConnectionFactory`, `Queue` and `Topic`
+instances are looked up from JNDI before being used by the client code.
+This objects are called "administered objects" in JMS terminology.
+
+However, in some cases a JNDI server may not be available or desired. To
+come to the rescue ActiveMQ also supports the direct instantiation of
+these administered objects on the client side so you don't have to use
+JNDI for JMS.
+
+Interceptor
+-----------
+
+ActiveMQ allows an application to use an interceptor to hook into the
+messaging system. Interceptors allow you to handle various message
+events in ActiveMQ.
+
+JAAS
+----
+
+The `jaas` example shows you how to configure ActiveMQ to use JAAS for
+security. ActiveMQ can leverage JAAS to delegate user authentication and
+authorization to existing security infrastructure.
+
+JMS Auto Closable
+-----------------
+
+The `jms-auto-closeable` example shows how JMS resources, such as
+connections, sessions and consumers, in JMS 2 can be automatically
+closed on error.
+
+JMS Completion Listener
+-----------------------
+
+The `jms-completion-listener` example shows how to send a message
+asynchronously to ActiveMQ and use a CompletionListener to be notified
+of the Broker receiving it.
+
+JMS Bridge
+----------
+
+The `jms-brige` example shows how to setup a bridge between two
+standalone ActiveMQ servers.
+
+JMS Context
+-----------
+
+The `jms-context` example shows how to send and receive a message to a
+JMS Queue using ActiveMQ by using a JMS Context.
+
+A JMSContext is part of JMS 2.0 and combines the JMS Connection and
+Session Objects into a simple Interface.
+
+JMS Shared Consumer
+-------------------
+
+The `jms-shared-consumer` example shows you how can use shared consumers
+to share a subscription on a topic. In JMS 1.1 this was not allowed and
+so caused a scalability issue. In JMS 2 this restriction has been lifted
+so you can share the load across different threads and connections.
+
+JMX Management
+--------------
+
+The `jmx` example shows how to manage ActiveMQ using JMX.
+
+Large Message
+-------------
+
+The `large-message` example shows you how to send and receive very large
+messages with ActiveMQ. ActiveMQ supports the sending and receiving of
+huge messages, much larger than can fit in available RAM on the client
+or server. Effectively the only limit to message size is the amount of
+disk space you have on the server.
+
+Large messages are persisted on the server so they can survive a server
+restart. In other words ActiveMQ doesn't just do a simple socket stream
+from the sender to the consumer.
+
+Last-Value Queue
+----------------
+
+The `last-value-queue` example shows you how to define and deal with
+last-value queues. Last-value queues are special queues which discard
+any messages when a newer message with the same value for a well-defined
+last-value property is put in the queue. In other words, a last-value
+queue only retains the last value.
+
+A typical example for last-value queue is for stock prices, where you
+are only interested by the latest price for a particular stock.
+
+Management
+----------
+
+The `management` example shows how to manage ActiveMQ using JMS Messages
+to invoke management operations on the server.
+
+Management Notification
+-----------------------
+
+The `management-notification` example shows how to receive management
+notifications from ActiveMQ using JMS messages. ActiveMQ servers emit
+management notifications when events of interest occur (consumers are
+created or closed, addresses are created or deleted, security
+authentication fails, etc.).
+
+Message Counter
+---------------
+
+The `message-counters` example shows you how to use message counters to
+obtain message information for a JMS queue.
+
+Message Group
+-------------
+
+The `message-group` example shows you how to configure and use message
+groups with ActiveMQ. Message groups allow you to pin messages so they
+are only consumed by a single consumer. Message groups are sets of
+messages that has the following characteristics:
+
+- Messages in a message group share the same group id, i.e. they have
+ same JMSXGroupID string property values
+
+- The consumer that receives the first message of a group will receive
+ all the messages that belongs to the group
+
+Message Group
+-------------
+
+The `message-group2` example shows you how to configure and use message
+groups with ActiveMQ via a connection factory.
+
+Message Priority
+----------------
+
+Message Priority can be used to influence the delivery order for
+messages.
+
+It can be retrieved by the message's standard header field 'JMSPriority'
+as defined in JMS specification version 1.1.
+
+The value is of type integer, ranging from 0 (the lowest) to 9 (the
+highest). When messages are being delivered, their priorities will
+effect their order of delivery. Messages of higher priorities will
+likely be delivered before those of lower priorities.
+
+Messages of equal priorities are delivered in the natural order of their
+arrival at their destinations. Please consult the JMS 1.1 specification
+for full details.
+
+Multiple Failover
+-----------------
+
+This example demonstrates how to set up a live server with multiple
+backups
+
+Multiple Failover Failback
+--------------------------
+
+This example demonstrates how to set up a live server with multiple
+backups but forcing failover back to the original live server
+
+No Consumer Buffering
+---------------------
+
+By default, ActiveMQ consumers buffer messages from the server in a
+client side buffer before you actually receive them on the client side.
+This improves performance since otherwise every time you called
+receive() or had processed the last message in a
+`MessageListener onMessage()` method, the ActiveMQ client would have to
+go the server to request the next message, which would then get sent to
+the client side, if one was available.
+
+This would involve a network round trip for every message and reduce
+performance. Therefore, by default, ActiveMQ pre-fetches messages into a
+buffer on each consumer.
+
+In some case buffering is not desirable, and ActiveMQ allows it to be
+switched off. This example demonstrates that.
+
+Non-Transaction Failover With Server Data Replication
+-----------------------------------------------------
+
+The `non-transaction-failover` example demonstrates two servers coupled
+as a live-backup pair for high availability (HA), and a client using a
+*non-transacted* JMS session failing over from live to backup when the
+live server is crashed.
+
+ActiveMQ implements failover of client connections between live and
+backup servers. This is implemented by the replication of state between
+live and backup nodes. When replication is configured and a live node
+crashes, the client connections can carry and continue to send and
+consume messages. When non-transacted sessions are used, once and only
+once message delivery is not guaranteed and it is possible that some
+messages will be lost or delivered twice.
+
+OpenWire
+--------
+
+The `Openwire` example shows how to configure a ActiveMQ server to
+communicate with an ActiveMQ JMS client that uses open-wire protocol.
+
+Paging
+------
+
+The `paging` example shows how ActiveMQ can support huge queues even
+when the server is running in limited RAM. It does this by transparently
+*paging* messages to disk, and *depaging* them when they are required.
+
+Pre-Acknowledge
+---------------
+
+Standard JMS supports three acknowledgement modes:`
+ AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, and
+`DUPS_OK_ACKNOWLEDGE`. For a full description on these modes please
+consult the JMS specification, or any JMS tutorial.
+
+All of these standard modes involve sending acknowledgements from the
+client to the server. However in some cases, you really don't mind
+losing messages in event of failure, so it would make sense to
+acknowledge the message on the server before delivering it to the
+client. This example demonstrates how ActiveMQ allows this with an extra
+acknowledgement mode.
+
+Message Producer Rate Limiting
+------------------------------
+
+The `producer-rte-limit` example demonstrates how, with ActiveMQ, you
+can specify a maximum send rate at which a JMS message producer will
+send messages.
+
+Proton Qpid
+-----------
+
+ActiveMQ can be configured to accept requests from any AMQP client that
+supports the 1.0 version of the protocol. This `proton-j` example shows
+a simply qpid java 1.0 client example.
+
+Proton Ruby
+-----------
+
+ActiveMQ can be configured to accept requests from any AMQP client that
+supports the 1.0 version of the protocol. This example shows a simply
+proton ruby client that sends and receives messages
+
+Queue
+-----
+
+A simple example demonstrating a JMS queue.
+
+Message Redistribution
+----------------------
+
+The `queue-message-redistribution` example demonstrates message
+redistribution between queues with the same name deployed in different
+nodes of a cluster.
+
+Queue Requestor
+---------------
+
+A simple example demonstrating a JMS queue requestor.
+
+Queue with Message Selector
+---------------------------
+
+The `queue-selector` example shows you how to selectively consume
+messages using message selectors with queue consumers.
+
+Reattach Node example
+---------------------
+
+The `Reattach Node` example shows how a client can try to reconnect to
+the same server instead of failing the connection immediately and
+notifying any user ExceptionListener objects. ActiveMQ can be configured
+to automatically retry the connection, and reattach to the server when
+it becomes available again across the network.
+
+Replicated Failback example
+---------------------------
+
+An example showing how failback works when using replication, In this
+example a live server will replicate all its Journal to a backup server
+as it updates it. When the live server crashes the backup takes over
+from the live server and the client reconnects and carries on from where
+it left off.
+
+Replicated Failback static example
+----------------------------------
+
+An example showing how failback works when using replication, but this
+time with static connectors
+
+Replicated multiple failover example
+------------------------------------
+
+An example showing how to configure multiple backups when using
+replication
+
+Replicated Failover transaction example
+---------------------------------------
+
+An example showing how failover works with a transaction when using
+replication
+
+Request-Reply example
+---------------------
+
+A simple example showing the JMS request-response pattern.
+
+Rest example
+------------
+
+An example showing how to use the ActiveMQ Rest API
+
+Scheduled Message
+-----------------
+
+The `scheduled-message` example shows you how to send a scheduled
+message to a JMS Queue with ActiveMQ. Scheduled messages won't get
+delivered until a specified time in the future.
+
+Security
+--------
+
+The `security` example shows you how configure and use role based queue
+security with ActiveMQ.
+
+Send Acknowledgements
+---------------------
+
+The `send-acknowledgements` example shows you how to use ActiveMQ's
+advanced *asynchronous send acknowledgements* feature to obtain
+acknowledgement from the server that sends have been received and
+processed in a separate stream to the sent messages.
+
+Spring Integration
+------------------
+
+This example shows how to use embedded JMS using ActiveMQ's Spring
+integration.
+
+SSL Transport
+-------------
+
+The `ssl-enabled` shows you how to configure SSL with ActiveMQ to send
+and receive message.
+
+Static Message Selector
+-----------------------
+
+The `static-selector` example shows you how to configure a ActiveMQ core
+queue with static message selectors (filters).
+
+Static Message Selector Using JMS
+---------------------------------
+
+The `static-selector-jms` example shows you how to configure a ActiveMQ
+queue with static message selectors (filters) using JMS.
+
+Stomp
+-----
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages.
+
+Stomp1.1
+--------
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages via a Stomp 1.1 connection.
+
+Stomp1.2
+--------
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages via a Stomp 1.2 connection.
+
+Stomp Over Web Sockets
+----------------------
+
+The `stomp-websockets` example shows you how to configure a ActiveMQ
+server to send and receive Stomp messages directly from Web browsers
+(provided they support Web Sockets).
+
+Symmetric Cluster
+-----------------
+
+The `symmetric-cluster` example demonstrates a symmetric cluster set-up
+with ActiveMQ.
+
+ActiveMQ has extremely flexible clustering which allows you to set-up
+servers in many different topologies. The most common topology that
+you'll perhaps be familiar with if you are used to application server
+clustering is a symmetric cluster.
+
+With a symmetric cluster, the cluster is homogeneous, i.e. each node is
+configured the same as every other node, and every node is connected to
+every other node in the cluster.
+
+Temporary Queue
+---------------
+
+A simple example demonstrating how to use a JMS temporary queue.
+
+Topic
+-----
+
+A simple example demonstrating a JMS topic.
+
+Topic Hierarchy
+---------------
+
+ActiveMQ supports topic hierarchies. With a topic hierarchy you can
+register a subscriber with a wild-card and that subscriber will receive
+any messages sent to an address that matches the wild card.
+
+Topic Selector 1
+----------------
+
+The `topic-selector-example1` example shows you how to send message to a
+JMS Topic, and subscribe them using selectors with ActiveMQ.
+
+Topic Selector 2
+----------------
+
+The `topic-selector-example2` example shows you how to selectively
+consume messages using message selectors with topic consumers.
+
+Transaction Failover
+--------------------
+
+The `transaction-failover` example demonstrates two servers coupled as a
+live-backup pair for high availability (HA), and a client using a
+transacted JMS session failing over from live to backup when the live
+server is crashed.
+
+ActiveMQ implements failover of client connections between live and
+backup servers. This is implemented by the sharing of a journal between
+the servers. When a live node crashes, the client connections can carry
+and continue to send and consume messages. When transacted sessions are
+used, once and only once message delivery is guaranteed.
+
+Failover Without Transactions
+-----------------------------
+
+The `stop-server-failover` example demonstrates failover of the JMS
+connection from one node to another when the live server crashes using a
+JMS non-transacted session.
+
+Transactional Session
+---------------------
+
+The `transactional` example shows you how to use a transactional Session
+with ActiveMQ.
+
+XA Heuristic
+------------
+
+The `xa-heuristic` example shows you how to make an XA heuristic
+decision through ActiveMQ Management Interface. A heuristic decision is
+a unilateral decision to commit or rollback an XA transaction branch
+after it has been prepared.
+
+XA Receive
+----------
+
+The `xa-receive` example shows you how message receiving behaves in an
+XA transaction in ActiveMQ.
+
+XA Send
+-------
+
+The `xa-send` example shows you how message sending behaves in an XA
+transaction in ActiveMQ.
+
+XA with Transaction Manager
+---------------------------
+
+The `xa-with-jta` example shows you how to use JTA interfaces to control
+transactions with ActiveMQ.
+
+Core API Examples
+=================
+
+To run a core example, simply `cd` into the appropriate example
+directory and type `ant`
+
+Embedded
+--------
+
+The `embedded` example shows how to embed the ActiveMQ server within
+your own code.
+
+Java EE Examples
+================
+
+Most of the Java EE examples can be run the following way. Simply
+navigate into the appropriate example directory and type `mvn verify`.
+This will use Arquillian to run the Application Server and deploy the
+application. Note that you must have WildFly installed and the
+JBOSS\_HOME environment variable set. Please refer to the examples
+documentation for further instructions.
+
+> **Note**
+>
+> When running the Java EE examples you may see warning messages in the
+> WildFly log about incompatible client and server versions. This is
+> normal if a newer version of the ActiveMQ project is being used with a
+> version of WildFly that ships an older version of ActiveMQ. These
+> examples should still complete without any functional errors.
+
+EJB/JMS Transaction
+-------------------
+
+An example that shows using an EJB and JMS together within a
+transaction.
+
+Resource Adapter Configuration
+------------------------------
+
+This example demonstrates how to configure several properties on the
+ActiveMQ JCA resource adaptor.
+
+Resource Adapter Remote Server Configuration
+--------------------------------------------
+
+This example demonstrates how to configure the ActiveMQ resource adapter
+to talk to a remote ActiveMQ server
+
+JMS Bridge
+----------
+
+An example demonstrating the use of the ActiveMQ JMS bridge.
+
+MDB (Message Driven Bean)
+-------------------------
+
+A simple set of examples of message driven beans, including failover
+examples.
+
+Servlet Transport
+-----------------
+
+An example of how to use the ActiveMQ servlet transport.
+
+Servlet SSL Transport
+---------------------
+
+An example of how to use the ActiveMQ servlet transport over SSL.
+
+XA Recovery
+-----------
+
+An example of how XA recovery works within the JBoss Application server
+using ActiveMQ.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/examples.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/examples.xml b/docs/user-manual/en/examples.xml
deleted file mode 100644
index 3d909fb..0000000
--- a/docs/user-manual/en/examples.xml
+++ /dev/null
@@ -1,693 +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="examples">
- <title>Examples</title>
- <para>The ActiveMQ distribution comes with over 70 run out-of-the-box examples demonstrating many
- of the features.</para>
- <para>The examples are available in the distribution, in the <literal>examples</literal>
- directory. Examples are split into JMS and core examples. JMS examples show how a particular
- feature can be used by a normal JMS client. Core examples show how the equivalent feature
- can be used by a core messaging client.</para>
- <para>A set of Java EE examples are also provided which need WildFly
- installed to be able to run.</para>
- <section>
- <title>JMS Examples</title>
- <para>To run a JMS example, simply <literal>cd</literal> into the appropriate example
- directory and type <literal>mvn verify</literal> (For details please read the readme.html
- in each example directory).</para>
- <para>Here's a listing of the examples with a brief description.</para>
- <section id="examples.aerogear">
- <title>JMS AeroGear</title>
- <para>This example shows how you can send a message to a mobile device by leveraging
- AeroGears push technology which provides support for different push notification technologies
- like Google Cloud Messaging, Apple's APNs or Mozilla's SimplePush.</para>
- </section>
- <section id="examples.applet">
- <title>Applet</title>
- <para>This example shows you how to send and receive JMS messages from an Applet.</para>
- </section>
- <section id="application-level-failover">
- <title>Application-Layer Failover</title>
- <para>ActiveMQ also supports Application-Layer failover, useful in the case that
- replication is not enabled on the server side.</para>
- <para>With Application-Layer failover, it's up to the application to register a JMS
- <literal>ExceptionListener</literal> with ActiveMQ which will be called by
- ActiveMQ in the event that connection failure is detected.</para>
- <para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
- connection, session, etc on another node and the application can continue.</para>
- <para>Application-layer failover is an alternative approach to High Availability (HA).
- Application-layer failover differs from automatic failover in that some client side
- coding is required in order to implement this. Also, with Application-layer
- failover, since the old session object dies and a new one is created, any
- uncommitted work in the old session will be lost, and any unacknowledged messages
- might be redelivered.</para>
- </section>
- <section id="examples.bridge">
- <title>Core Bridge Example</title>
- <para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one
- server, which consumes messages from a local queue and forwards them to an address
- on a second server.</para>
- <para>Core bridges are used to create message flows between any two ActiveMQ servers
- which are remotely separated. Core bridges are resilient and will cope with
- temporary connection failure allowing them to be an ideal choice for forwarding over
- unreliable connections, e.g. a WAN.</para>
- </section>
- <section id="examples.browsers">
- <title>Browser</title>
- <para>The <literal>browser</literal> example shows you how to use a JMS <literal
- >QueueBrowser</literal> with ActiveMQ.</para>
- <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
- full details.</para>
- <para> A <literal>QueueBrowser</literal> is used to look at messages on the queue
- without removing them. It can scan the entire content of a queue or only messages
- matching a message selector.</para>
- </section>
- <section>
- <title>Client Kickoff</title>
- <para>The <literal>client-kickoff</literal> example shows how to terminate client
- connections given an IP address using the JMX management API.</para>
- </section>
- <section>
- <title>Client side failover listener</title>
- <para>The <literal>client-side-failoverlistener</literal> example shows how to register a listener to monitor
- failover events</para>
- </section>
- <section>
- <title>Client-Side Load-Balancing</title>
- <para>The <literal>client-side-load-balancing</literal> example demonstrates how
- sessions created from a single JMS <literal>Connection</literal> can
- be created to different nodes of the cluster. In other words it demonstrates how
- ActiveMQ does client-side load-balancing of sessions across the cluster.</para>
- </section>
- <section id="examples.clustered.durable">
- <title>Clustered Durable Subscription</title>
- <para>This example demonstrates a clustered JMS durable subscription</para>
- </section>
- <section id="examples.clustered.grouping">
- <title>Clustered Grouping</title>
- <para>This is similar to the message grouping example except that it demonstrates it
- working over a cluster. Messages sent to different nodes with the same group id will
- be sent to the same node and the same consumer.</para>
- </section>
- <section id="examples.clustered.queue">
- <title>Clustered Queue</title>
- <para>The <literal>clustered-queue</literal> example demonstrates a JMS queue deployed
- on two different nodes. The two nodes are configured to form a cluster. We then
- create a consumer for the queue on each node, and we create a producer on only one
- of the nodes. We then send some messages via the producer, and we verify that both
- consumers receive the sent messages in a round-robin fashion.</para>
- </section>
- <section id="examples.clustered.jgroups">
- <title>Clustering with JGroups</title>
- <para>The <literal>clustered-jgroups</literal> example demonstrates how to form a two
- node cluster using JGroups as its underlying topology discovery technique, rather than
- the default UDP broadcasting. We then create a consumer for the queue on each node,
- and we create a producer on only one of the nodes. We then send some messages via the
- producer, and we verify that both consumers receive the sent messages in a round-robin fashion.</para>
- </section>
- <section id="examples.clustered.standalone">
- <title>Clustered Standalone</title>
- <para>The <literal>clustered-standalone</literal> example demonstrates how to configure
- and starts 3 cluster nodes on the same machine to form a cluster. A subscriber for a
- JMS topic is created on each node, and we create a producer on only one of the
- nodes. We then send some messages via the producer, and we verify that the 3
- subscribers receive all the sent messages.</para>
- </section>
- <section id="examples.clustered.static.discovery">
- <title>Clustered Static Discovery</title>
- <para>This example demonstrates how to configure a cluster using a list of connectors rather
- than UDP for discovery</para>
- </section>
- <section id="examples.clustered.static.oneway">
- <title>Clustered Static Cluster One Way</title>
- <para>This example demonstrates how to set up a cluster where cluster connections are one way,
- i.e. server A -> Server B -> Server C</para>
- </section>
- <section>
- <title>Clustered Topic</title>
- <para>The <literal>clustered-topic</literal> example demonstrates a JMS topic deployed
- on two different nodes. The two nodes are configured to form a cluster. We then
- create a subscriber on the topic on each node, and we create a producer on only one
- of the nodes. We then send some messages via the producer, and we verify that both
- subscribers receive all the sent messages.</para>
- </section>
- <section id="examples.consumer-rate-limit">
- <title>Message Consumer Rate Limiting</title>
- <para>With ActiveMQ you can specify a maximum consume rate at which a JMS MessageConsumer
- will consume messages. This can be specified when creating or deploying the
- connection factory.</para>
- <para>If this value is specified then ActiveMQ will ensure that messages are never
- consumed at a rate higher than the specified rate. This is a form of consumer
- throttling.</para>
- </section>
- <section id="examples.dead-letter">
- <title>Dead Letter</title>
- <para>The <literal>dead-letter</literal> example shows you how to define and deal with
- dead letter messages. Messages can be delivered unsuccessfully (e.g. if the
- transacted session used to consume them is rolled back). </para>
- <para>Such a message goes back to the JMS destination ready to be redelivered. However,
- this means it is possible for a message to be delivered again and again without any
- success and remain in the destination, clogging the system.</para>
- <para>To prevent this, messaging systems define dead letter messages: after a specified
- unsuccessful delivery attempts, the message is removed from the destination and put
- instead in a dead letter destination where they can be consumed for further
- investigation.</para>
- </section>
- <section id="examples.delayed-redelivery">
- <title>Delayed Redelivery</title>
- <para>The <literal>delayed-redelivery</literal> example demonstrates how ActiveMQ can be
- configured to provide a delayed redelivery in the case a message needs to be
- redelivered.</para>
- <para>Delaying redelivery can often be useful in the case that clients regularly fail or
- roll-back. Without a delayed redelivery, the system can get into a "thrashing"
- state, with delivery being attempted, the client rolling back, and delivery being
- re-attempted in quick succession, using up valuable CPU and network
- resources.</para>
- </section>
- <section id="divert-example">
- <title>Divert</title>
- <para>ActiveMQ diverts allow messages to be transparently "diverted" or copied from one
- address to another with just some simple configuration defined on the server
- side.</para>
- </section>
- <section>
- <title>Durable Subscription</title>
- <para>The <literal>durable-subscription</literal> example shows you how to use a durable
- subscription with ActiveMQ. Durable subscriptions are a standard part of JMS, please
- consult the JMS 1.1 specification for full details.</para>
- <para>Unlike non-durable subscriptions, the key function of durable subscriptions is
- that the messages contained in them persist longer than the lifetime of the
- subscriber - i.e. they will accumulate messages sent to the topic even if there is
- no active subscriber on them. They will also survive server restarts or crashes.
- Note that for the messages to be persisted, the messages sent to them must be marked
- as durable messages. </para>
- </section>
- <section id="examples.embedded.jms">
- <title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed JMS
- within your own code using POJO instantiation and no config files.</para>
- </section>
- <section id="examples.embedded.jms.simple">
- <title>Embedded Simple</title>
- <para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular ActiveMQ XML files.</para>
- </section>
- <section id="examples.expiry">
- <title>Message Expiration</title>
- <para>The <literal>expiry</literal> example shows you how to define and deal with
- message expiration. Messages can be retained in the messaging system for a limited
- period of time before being removed. JMS specification states that clients should
- not receive messages that have been expired (but it does not guarantee this will not
- happen).</para>
- <para>ActiveMQ can assign an expiry address to a given queue so that when messages
- are expired, they are removed from the queue and sent to the expiry address.
- These "expired" messages can later be consumed from the expiry address for
- further inspection.</para>
- </section>
- <section id="examples.activemq-ra-rar">
- <title>ActiveMQ Resource Adapter example</title>
- <para>This examples shows how to build the activemq resource adapters a rar for deployment in other Application
- Server's</para>
- </section>
- <section>
- <title>HTTP Transport</title>
- <para>The <literal>http-transport</literal> example shows you how to configure ActiveMQ
- to use the HTTP protocol as its transport layer.</para>
- </section>
- <section>
- <title>Instantiate JMS Objects Directly</title>
- <para>Usually, JMS Objects such as <literal>ConnectionFactory</literal>, <literal
- >Queue</literal> and <literal>Topic</literal> instances are looked up from JNDI
- before being used by the client code. This objects are called "administered objects"
- in JMS terminology.</para>
- <para>However, in some cases a JNDI server may not be available or desired. To come to
- the rescue ActiveMQ also supports the direct instantiation of these administered
- objects on the client side so you don't have to use JNDI for JMS.</para>
- </section>
- <section id="examples.interceptor">
- <title>Interceptor</title>
- <para>ActiveMQ allows an application to use an interceptor to hook into the messaging
- system. Interceptors allow you to handle various message events in ActiveMQ.</para>
- </section>
- <section id="examples.jaas">
- <title>JAAS</title>
- <para>The <literal>jaas</literal> example shows you how to configure ActiveMQ to use JAAS
- for security. ActiveMQ can leverage JAAS to delegate user authentication and
- authorization to existing security infrastructure.</para>
- </section>
- <section id="examples.jms.auto-closeable">
- <title>JMS Auto Closable</title>
- <para>The <literal>jms-auto-closeable</literal> example shows how JMS resources, such
- as connections, sessions and consumers, in JMS 2 can be automatically closed on error.</para>
- </section>
- <section id="examples.jms.completion-listener">
- <title>JMS Completion Listener</title>
- <para>The <literal>jms-completion-listener</literal> example shows how to send a message
- asynchronously to ActiveMQ and use a CompletionListener to be notified of the Broker
- receiving it.</para>
- </section>
- <section id="examples.jms.jms-bridge">
- <title>JMS Bridge</title>
- <para>The <literal>jms-brige</literal> example shows how to setup a bridge
- between two standalone ActiveMQ servers.</para>
- </section>
- <section id="examples.jms.jms-context">
- <title>JMS Context</title>
- <para>The <literal>jms-context</literal> example shows how to send and receive a message
- to a JMS Queue using ActiveMQ by using a JMS Context.</para>
- <para>A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects
- into a simple Interface.</para>
- </section>
- <section id="examples.jms.jms-shared-consumer">
- <title>JMS Shared Consumer</title>
- <para>The <literal>jms-shared-consumer</literal> example shows you how can use shared
- consumers to share a subscription on a topic. In JMS 1.1 this was not allowed and so caused
- a scalability issue. In JMS 2 this restriction has been lifted so you can share the load
- across different threads and connections.</para>
- </section>
- <section id="examples.jmx">
- <title>JMX Management</title>
- <para>The <literal>jmx</literal> example shows how to manage ActiveMQ using JMX.</para>
- </section>
- <section id="examples.large-message">
- <title>Large Message</title>
- <para>The <literal>large-message</literal> example shows you how to send and receive
- very large messages with ActiveMQ. ActiveMQ supports the sending and receiving of huge
- messages, much larger than can fit in available RAM on the client or server.
- Effectively the only limit to message size is the amount of disk space you have on
- the server.</para>
- <para>Large messages are persisted on the server so they can survive a server restart.
- In other words ActiveMQ doesn't just do a simple socket stream from the sender to the
- consumer.</para>
- </section>
- <section id="examples.last-value-queue">
- <title>Last-Value Queue</title>
- <para>The <literal>last-value-queue</literal> example shows you how to define and deal
- with last-value queues. Last-value queues are special queues which discard any
- messages when a newer message with the same value for a well-defined last-value
- property is put in the queue. In other words, a last-value queue only retains the
- last value.</para>
- <para>A typical example for last-value queue is for stock prices, where you are only
- interested by the latest price for a particular stock.</para>
- </section>
- <section id="examples.management">
- <title>Management</title>
- <para>The <literal>management</literal> example shows how to manage ActiveMQ using JMS
- Messages to invoke management operations on the server.</para>
- </section>
- <section id="examples.management-notifications">
- <title>Management Notification</title>
- <para>The <literal>management-notification</literal> example shows how to receive
- management notifications from ActiveMQ using JMS messages. ActiveMQ servers emit
- management notifications when events of interest occur (consumers are created or
- closed, addresses are created or deleted, security authentication fails,
- etc.).</para>
- </section>
- <section id="examples.message-counters">
- <title>Message Counter</title>
- <para>The <literal>message-counters</literal> example shows you how to use message
- counters to obtain message information for a JMS queue.</para>
- </section>
- <section id="examples.message-group">
- <title>Message Group</title>
- <para>The <literal>message-group</literal> example shows you how to configure and use
- message groups with ActiveMQ. Message groups allow you to pin messages so they are
- only consumed by a single consumer. Message groups are sets of messages that has the
- following characteristics:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>Messages in a message group share the same group id, i.e. they have
- same JMSXGroupID string property values</para>
- </listitem>
- <listitem>
- <para>The consumer that receives the first message of a group will receive
- all the messages that belongs to the group</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="examples.message-group2">
- <title>Message Group</title>
- <para>The <literal>message-group2</literal> example shows you how to configure and use
- message groups with ActiveMQ via a connection factory.</para>
- </section>
- <section id="examples.message-priority">
- <title>Message Priority</title>
- <para>Message Priority can be used to influence the delivery order for messages.</para>
- <para>It can be retrieved by the message's standard header field 'JMSPriority' as
- defined in JMS specification version 1.1. </para>
- <para>The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When
- messages are being delivered, their priorities will effect their order of delivery.
- Messages of higher priorities will likely be delivered before those of lower
- priorities. </para>
- <para>Messages of equal priorities are delivered in the natural order of their arrival
- at their destinations. Please consult the JMS 1.1 specification for full
- details.</para>
- </section>
- <section id="examples.multiple.failover">
- <title>Multiple Failover</title>
- <para>This example demonstrates how to set up a live server with multiple backups</para>
- </section>
- <section id="examples.multiple.failover.failback">
- <title>Multiple Failover Failback</title>
- <para>This example demonstrates how to set up a live server with multiple backups but
- forcing failover back to the original live server</para>
- </section>
- <section id="examples.no-consumer-buffering">
- <title>No Consumer Buffering</title>
- <para>By default, ActiveMQ consumers buffer messages from the server in a client side
- buffer before you actually receive them on the client side. This improves
- performance since otherwise every time you called receive() or had processed the
- last message in a <literal>MessageListener onMessage()</literal> method, the ActiveMQ
- client would have to go the server to request the next message, which would then get
- sent to the client side, if one was available.</para>
- <para>This would involve a network round trip for every message and reduce performance.
- Therefore, by default, ActiveMQ pre-fetches messages into a buffer on each
- consumer.</para>
- <para>In some case buffering is not desirable, and ActiveMQ allows it to be switched off.
- This example demonstrates that.</para>
- </section>
- <section id="examples.non-transaction-failover">
- <title>Non-Transaction Failover With Server Data Replication</title>
- <para>The <literal>non-transaction-failover</literal> example demonstrates two servers coupled
- as a live-backup pair for high availability (HA), and a client using a <emphasis>non-transacted
- </emphasis> JMS session failing over from live to backup when the live server is
- crashed.</para>
- <para>ActiveMQ implements failover of client connections between
- live and backup servers. This is implemented by the replication of state between
- live and backup nodes. When replication is configured and a live node crashes, the
- client connections can carry and continue to send and consume messages. When non-transacted
- sessions are used, once and only once message delivery is not guaranteed and it is possible
- that some messages will be lost or delivered twice.</para>
- </section>
- <section id="examples.openwire">
- <title>OpenWire</title>
- <para>The <literal>Openwire</literal> example shows how to configure a ActiveMQ
- server to communicate with an ActiveMQ JMS client that uses open-wire protocol.</para>
- </section>
- <section id="examples.paging">
- <title>Paging</title>
- <para>The <literal>paging</literal> example shows how ActiveMQ can support huge queues
- even when the server is running in limited RAM. It does this by transparently
- <emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
- them when they are required.</para>
- </section>
- <section id="examples.pre-acknowledge">
- <title>Pre-Acknowledge</title>
- <para>Standard JMS supports three acknowledgement modes:<literal>
- AUTO_ACKNOWLEDGE</literal>, <literal>CLIENT_ACKNOWLEDGE</literal>, and <literal
- >DUPS_OK_ACKNOWLEDGE</literal>. For a full description on these modes please
- consult the JMS specification, or any JMS tutorial.</para>
- <para>All of these standard modes involve sending acknowledgements from the client to
- the server. However in some cases, you really don't mind losing messages in event of
- failure, so it would make sense to acknowledge the message on the server before
- delivering it to the client. This example demonstrates how ActiveMQ allows this with
- an extra acknowledgement mode.</para>
- </section>
- <section id="producer-rate-limiting-example">
- <title>Message Producer Rate Limiting</title>
- <para>The <literal>producer-rte-limit</literal> example demonstrates how, with ActiveMQ,
- you can specify a maximum send rate at which a JMS message producer will send
- messages.</para>
- </section>
- <section id="examples.proton-qpid">
- <title>Proton Qpid</title>
- <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
- 1.0 version of the protocol. This <literal>proton-j</literal> example shows a simply
- qpid java 1.0 client example.</para>
- </section>
- <section id="examples.proton-ruby">
- <title>Proton Ruby</title>
- <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
- 1.0 version of the protocol. This example shows a simply proton ruby client
- that sends and receives messages</para>
- </section>
- <section id="examples.queue">
- <title>Queue</title>
- <para>A simple example demonstrating a JMS queue.</para>
- </section>
- <section id="examples.message-redistribution">
- <title>Message Redistribution</title>
- <para>The <literal>queue-message-redistribution</literal> example demonstrates message
- redistribution between queues with the same name deployed in different nodes of a
- cluster.</para>
- </section>
- <section id="examples.queue-requestor">
- <title>Queue Requestor</title>
- <para>A simple example demonstrating a JMS queue requestor.</para>
- </section>
- <section id="examples.queue-message-selector">
- <title>Queue with Message Selector</title>
- <para>The <literal>queue-selector</literal> example shows you how to selectively consume
- messages using message selectors with queue consumers.</para>
- </section>
- <section id="examples.reattach-node">
- <title>Reattach Node example</title>
- <para>The <literal>Reattach Node</literal> example shows how a client can try to reconnect to
- the same server instead of failing the connection immediately and
- notifying any user ExceptionListener objects. ActiveMQ can be configured to automatically
- retry the connection, and reattach to the server when it becomes available again across
- the network.</para>
- </section>
- <section id="examples.replicated-failback">
- <title>Replicated Failback example</title>
- <para>An example showing how failback works when using replication, In this example a live server will replicate
- all its Journal to a backup server as it updates it. When the live server crashes the backup takes over
- from the live server and the client reconnects and carries on from where it left off.</para>
- </section>
- <section id="examples.replicated-failback-static">
- <title>Replicated Failback static example</title>
- <para>An example showing how failback works when using replication, but this time with static connectors</para>
- </section>
- <section id="examples.replicated-multiple-failover">
- <title>Replicated multiple failover example</title>
- <para>An example showing how to configure multiple backups when using replication</para>
- </section>
- <section id="examples.replicated-failover-transaction">
- <title>Replicated Failover transaction example</title>
- <para>An example showing how failover works with a transaction when using replication</para>
- </section>
- <section id="examples.request-reply">
- <title>Request-Reply example</title>
- <para>A simple example showing the JMS request-response pattern.</para>
- </section>
- <section id="examples.rest">
- <title>Rest example</title>
- <para>An example showing how to use the ActiveMQ Rest API</para>
- </section>
- <section id="examples.scheduled-message">
- <title>Scheduled Message</title>
- <para>The <literal>scheduled-message</literal> example shows you how to send a scheduled
- message to a JMS Queue with ActiveMQ. Scheduled messages won't get delivered until a
- specified time in the future.</para>
- </section>
- <section id="examples.security">
- <title>Security</title>
- <para>The <literal>security</literal> example shows you how configure and use role based
- queue security with ActiveMQ.</para>
- </section>
- <section id="asynchronous-send-acknowledgements-example">
- <title>Send Acknowledgements</title>
- <para>The <literal>send-acknowledgements</literal> example shows you how to use
- ActiveMQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
- to obtain acknowledgement from the server that sends have been received and
- processed in a separate stream to the sent messages. </para>
- </section>
- <section id="examples.jms.spring.integration">
- <title>Spring Integration</title>
- <para>This example shows how to use embedded JMS using ActiveMQ's Spring integration.</para>
- </section>
- <section id="examples.ssl-transport">
- <title>SSL Transport</title>
- <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with ActiveMQ to
- send and receive message.</para>
- </section>
- <section id="examples.static-message-selector">
- <title>Static Message Selector</title>
- <para>The <literal>static-selector</literal> example shows you how to configure a
- ActiveMQ core queue with static message selectors (filters).</para>
- </section>
- <section id="examples.static-message-selector-jms">
- <title>Static Message Selector Using JMS</title>
- <para>The <literal>static-selector-jms</literal> example shows you how to configure a
- ActiveMQ queue with static message selectors (filters) using JMS.</para>
- </section>
- <section id="examples.stomp">
- <title>Stomp</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages.</para>
- </section>
- <section id="examples.stomp1.1">
- <title>Stomp1.1</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages via a Stomp 1.1 connection.</para>
- </section>
- <section id="examples.stomp1.2">
- <title>Stomp1.2</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages via a Stomp 1.2 connection.</para>
- </section>
- <section id="examples.stomp-web-socket">
- <title>Stomp Over Web Sockets</title>
- <para>The <literal>stomp-websockets</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages directly from Web browsers (provided
- they support Web Sockets).</para>
- </section>
- <section id="examples.symmetric-cluster">
- <title>Symmetric Cluster</title>
- <para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
- set-up with ActiveMQ.</para>
- <para>ActiveMQ has extremely flexible clustering which allows you to set-up servers in
- many different topologies. The most common topology that you'll perhaps be familiar
- with if you are used to application server clustering is a symmetric cluster.</para>
- <para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
- the same as every other node, and every node is connected to every other node in the
- cluster.</para>
- </section>
- <section id="examples.temporary-queue">
- <title>Temporary Queue</title>
- <para>A simple example demonstrating how to use a JMS temporary queue.</para>
- </section>
- <section id="examples.topic">
- <title>Topic</title>
- <para>A simple example demonstrating a JMS topic.</para>
- </section>
- <section id="topic-hierarchy-example">
- <title>Topic Hierarchy</title>
- <para>ActiveMQ supports topic hierarchies. With a topic hierarchy you can register a
- subscriber with a wild-card and that subscriber will receive any messages sent to an
- address that matches the wild card.</para>
- </section>
- <section id="examples.topic-selector-1">
- <title>Topic Selector 1</title>
- <para>The <literal>topic-selector-example1</literal> example shows you how to send
- message to a JMS Topic, and subscribe them using selectors with ActiveMQ.</para>
- </section>
- <section id="examples.topic-selector-2">
- <title>Topic Selector 2</title>
- <para>The <literal>topic-selector-example2</literal> example shows you how to
- selectively consume messages using message selectors with topic consumers.</para>
- </section>
- <section id="examples.transaction-failover">
- <title>Transaction Failover</title>
- <para>The <literal>transaction-failover</literal> example demonstrates two servers coupled
- as a live-backup pair for high availability (HA), and a client using a transacted JMS
- session failing over from live to backup when the live server is
- crashed.</para>
- <para>ActiveMQ implements failover of client connections between
- live and backup servers. This is implemented by the sharing of a journal between the
- servers. When a live node crashes, the
- client connections can carry and continue to send and consume messages. When transacted
- sessions are used, once and only once message delivery is guaranteed.</para>
- </section>
- <section id="examples.no-transaction-failover">
- <title>Failover Without Transactions</title>
- <para>The <literal>stop-server-failover</literal> example demonstrates failover of the
- JMS connection from one node to another when the live server crashes using a JMS
- non-transacted session.</para>
- </section>
- <section id="examples.transactional-session">
- <title>Transactional Session</title>
- <para>The <literal>transactional</literal> example shows you how to use a transactional
- Session with ActiveMQ.</para>
- </section>
- <section>
- <title>XA Heuristic</title>
- <para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic
- decision through ActiveMQ Management Interface. A heuristic decision is a unilateral
- decision to commit or rollback an XA transaction branch after it has been
- prepared.</para>
- </section>
- <section>
- <title>XA Receive</title>
- <para>The <literal>xa-receive</literal> example shows you how message receiving behaves
- in an XA transaction in ActiveMQ.</para>
- </section>
- <section>
- <title>XA Send</title>
- <para>The <literal>xa-send</literal> example shows you how message sending behaves in an
- XA transaction in ActiveMQ.</para>
- </section>
- <section>
- <title>XA with Transaction Manager</title>
- <para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to
- control transactions with ActiveMQ.</para>
- </section>
- </section>
- <section>
- <title>Core API Examples</title>
- <para>To run a core example, simply <literal>cd</literal> into the appropriate example
- directory and type <literal>ant</literal></para>
- <section id="examples.embedded">
- <title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed the ActiveMQ server
- within your own code.</para>
- </section>
- </section>
- <section>
- <title>Java EE Examples</title>
- <para>Most of the Java EE examples can be run the following way. Simply navigate into the
- appropriate example directory and type <literal>mvn verify</literal>. This will use Arquillian to run the Application
- Server and deploy the application. Note that you must have WildFly installed and the JBOSS_HOME environment
- variable set. Please refer to the examples documentation for further instructions.</para>
- <note>
- <para>When running the Java EE examples you may see warning messages in the WildFly log about incompatible client and
- server versions. This is normal if a newer version of the ActiveMQ project is being used with a version of WildFly that
- ships an older version of ActiveMQ. These examples should still complete without any functional errors.</para>
- </note>
- <section>
- <title>EJB/JMS Transaction</title>
- <para>An example that shows using an EJB and JMS together within a transaction.</para>
- </section>
- <section>
- <title>Resource Adapter Configuration</title>
- <para>This example demonstrates how to configure several properties on the ActiveMQ JCA
- resource adaptor.</para>
- </section>
- <section>
- <title>Resource Adapter Remote Server Configuration</title>
- <para>This example demonstrates how to configure the ActiveMQ resource adapter to talk to a remote ActiveMQ server</para>
- </section>
- <section id="examples.javaee.jms-bridge">
- <title>JMS Bridge</title>
- <para>An example demonstrating the use of the ActiveMQ JMS bridge.</para>
- </section>
- <section>
- <title>MDB (Message Driven Bean)</title>
- <para>A simple set of examples of message driven beans, including failover examples.</para>
- </section>
- <section>
- <title>Servlet Transport</title>
- <para>An example of how to use the ActiveMQ servlet transport.</para>
- </section>
- <section>
- <title>Servlet SSL Transport</title>
- <para>An example of how to use the ActiveMQ servlet transport over SSL.</para>
- </section>
- <section id="xa-recovery-example">
- <title>XA Recovery</title>
- <para>An example of how XA recovery works within the JBoss Application server using
- ActiveMQ.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/filter-expressions.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/filter-expressions.md b/docs/user-manual/en/filter-expressions.md
new file mode 100644
index 0000000..c1dfca5
--- /dev/null
+++ b/docs/user-manual/en/filter-expressions.md
@@ -0,0 +1,52 @@
+Filter Expressions
+==================
+
+ActiveMQ provides a powerful filter language based on a subset of the
+SQL 92 expression syntax.
+
+It is the same as the syntax used for JMS selectors, but the predefined
+identifiers are different. For documentation on JMS selector syntax
+please the JMS javadoc for
+[javax.jms.Message](http://docs.oracle.com/javaee/6/api/javax/jms/Message.html).
+
+Filter expressions are used in several places in ActiveMQ
+
+- Predefined Queues. When pre-defining a queue, either in
+ `activemq-configuration.xml` or `activemq-jms.xml` a filter
+ expression can be defined for a queue. Only messages that match the
+ filter expression will enter the queue.
+
+- Core bridges can be defined with an optional filter expression, only
+ matching messages will be bridged (see ?).
+
+- Diverts can be defined with an optional filter expression, only
+ matching messages will be diverted (see ?).
+
+- Filter are also used programmatically when creating consumers,
+ queues and in several places as described in ?.
+
+There are some differences between JMS selector expressions and ActiveMQ
+core filter expressions. Whereas JMS selector expressions operate on a
+JMS message, ActiveMQ core filter expressions operate on a core message.
+
+The following identifiers can be used in a core filter expressions to
+refer to attributes of the core message in an expression:
+
+- `HQPriority`. To refer to the priority of a message. Message
+ priorities are integers with valid values from `0 - 9`. `0` is the
+ lowest priority and `9` is the highest. E.g.
+ `HQPriority = 3 AND animal = 'aardvark'`
+
+- `HQExpiration`. To refer to the expiration time of a message. The
+ value is a long integer.
+
+- `HQDurable`. To refer to whether a message is durable or not. The
+ value is a string with valid values: `DURABLE` or `NON_DURABLE`.
+
+- `HQTimestamp`. The timestamp of when the message was created. The
+ value is a long integer.
+
+- `HQSize`. The size of a message in bytes. The value is an integer.
+
+Any other identifiers used in core filter expressions will be assumed to
+be properties of the message.
[10/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/management.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md
new file mode 100644
index 0000000..5c37827
--- /dev/null
+++ b/docs/user-manual/en/management.md
@@ -0,0 +1,1094 @@
+Management
+==========
+
+ActiveMQ has an extensive management API that allows a user to modify a
+server configuration, create new resources (e.g. JMS queues and topics),
+inspect these resources (e.g. how many messages are currently held in a
+queue) and interact with it (e.g. to remove messages from a queue). All
+the operations allows a client to *manage* ActiveMQ. It also allows
+clients to subscribe to management notifications.
+
+There are 3 ways to manage ActiveMQ:
+
+- Using JMX -- JMX is the standard way to manage Java applications
+
+- Using the core API -- management operations are sent to ActiveMQ
+ server using *core messages*
+
+- Using the JMS API -- management operations are sent to ActiveMQ
+ server using *JMS messages*
+
+Although there are 3 different ways to manage ActiveMQ each API supports
+the same functionality. If it is possible to manage a resource using JMX
+it is also possible to achieve the same result using Core messages or
+JMS messages.
+
+This choice depends on your requirements, your application settings and
+your environment to decide which way suits you best.
+
+The Management API
+==================
+
+Regardless of the way you *invoke* management operations, the management
+API is the same.
+
+For each *managed resource*, there exists a Java interface describing
+what can be invoked for this type of resource.
+
+ActiveMQ exposes its managed resources in 2 packages:
+
+- *Core* resources are located in the
+ `org.apache.activemq.api.core.management` package
+
+- *JMS* resources are located in the
+ `org.apache.activemq.api.jms.management` package
+
+The way to invoke a *management operations* depends whether JMX, core
+messages, or JMS messages are used.
+
+> **Note**
+>
+> A few management operations requires a `filter` parameter to chose
+> which messages are involved by the operation. Passing `null` or an
+> empty string means that the management operation will be performed on
+> *all messages*.
+
+Core Management API
+-------------------
+
+ActiveMQ defines a core management API to manage core resources. For
+full details of the API please consult the javadoc. In summary:
+
+### Core Server Management
+
+- Listing, creating, deploying and destroying queues
+
+ A list of deployed core queues can be retrieved using the
+ `getQueueNames()` method.
+
+ Core queues can be created or destroyed using the management
+ operations `createQueue()` or `deployQueue()` or `destroyQueue()`)on
+ the `ActiveMQServerControl` (with the ObjectName
+ `org.apache.activemq:module=Core,type=Server` or the resource name
+ `core.server`)
+
+ `createQueue` will fail if the queue already exists while
+ `deployQueue` will do nothing.
+
+- Pausing and resuming Queues
+
+ The `QueueControl` can pause and resume the underlying queue. When a
+ queue is paused, it will receive messages but will not deliver them.
+ When it's resumed, it'll begin delivering the queued messages, if
+ any.
+
+- Listing and closing remote connections
+
+ Client's remote addresses can be retrieved using
+ `listRemoteAddresses()`. It is also possible to close the
+ connections associated with a remote address using the
+ `closeConnectionsForAddress()` method.
+
+ Alternatively, connection IDs can be listed using
+ `listConnectionIDs()` and all the sessions for a given connection ID
+ can be listed using `listSessions()`.
+
+- Transaction heuristic operations
+
+ In case of a server crash, when the server restarts, it it possible
+ that some transaction requires manual intervention. The
+ `listPreparedTransactions()` method lists the transactions which are
+ in the prepared states (the transactions are represented as opaque
+ Base64 Strings.) To commit or rollback a given prepared transaction,
+ the `commitPreparedTransaction()` or `rollbackPreparedTransaction()`
+ method can be used to resolve heuristic transactions. Heuristically
+ completed transactions can be listed using the
+ `listHeuristicCommittedTransactions()` and
+ `listHeuristicRolledBackTransactions` methods.
+
+- Enabling and resetting Message counters
+
+ Message counters can be enabled or disabled using the
+ `enableMessageCounters()` or `disableMessageCounters()` method. To
+ reset message counters, it is possible to invoke
+ `resetAllMessageCounters()` and `resetAllMessageCounterHistories()`
+ methods.
+
+- Retrieving the server configuration and attributes
+
+ The `ActiveMQServerControl` exposes ActiveMQ server configuration
+ through all its attributes (e.g. `getVersion()` method to retrieve
+ the server's version, etc.)
+
+- Listing, creating and destroying Core bridges and diverts
+
+ A list of deployed core bridges (resp. diverts) can be retrieved
+ using the `getBridgeNames()` (resp. `getDivertNames()`) method.
+
+ Core bridges (resp. diverts) can be created or destroyed using the
+ management operations `createBridge()` and `destroyBridge()` (resp.
+ `createDivert()` and `destroyDivert()`) on the
+ `ActiveMQServerControl` (with the ObjectName
+ `org.apache.activemq:module=Core,type=Server` or the resource name
+ `core.server`).
+
+- It is possible to stop the server and force failover to occur with
+ any currently attached clients.
+
+ to do this use the `forceFailover()` on the `ActiveMQServerControl`
+ (with the ObjectName `org.apache.activemq:module=Core,type=Server`
+ or the resource name `core.server`)
+
+ > **Note**
+ >
+ > Since this method actually stops the server you will probably
+ > receive some sort of error depending on which management service
+ > you use to call it.
+
+### Core Address Management
+
+Core addresses can be managed using the `AddressControl` class (with the
+ObjectName `org.apache.activemq:module=Core,type=Address,name="<the
+ address name>"` or the resource name
+`core.address.<the
+ address name>`).
+
+- Modifying roles and permissions for an address
+
+ You can add or remove roles associated to a queue using the
+ `addRole()` or `removeRole()` methods. You can list all the roles
+ associated to the queue with the `getRoles()` method
+
+### Core Queue Management
+
+The bulk of the core management API deals with core queues. The
+`QueueControl` class defines the Core queue management operations (with
+the ObjectName
+`org.apache.activemq:module=Core,type=Queue,address="<the bound
+ address>",name="<the queue name>"` or the resource
+name `core.queue.<the queue name>`).
+
+Most of the management operations on queues take either a single message
+ID (e.g. to remove a single message) or a filter (e.g. to expire all
+messages with a given property.)
+
+- Expiring, sending to a dead letter address and moving messages
+
+ Messages can be expired from a queue by using the `expireMessages()`
+ method. If an expiry address is defined, messages will be sent to
+ it, otherwise they are discarded. The queue's expiry address can be
+ set with the `setExpiryAddress()` method.
+
+ Messages can also be sent to a dead letter address with the
+ `sendMessagesToDeadLetterAddress()` method. It returns the number of
+ messages which are sent to the dead letter address. If a dead letter
+ address is not defined, message are removed from the queue and
+ discarded. The queue's dead letter address can be set with the
+ `setDeadLetterAddress()` method.
+
+ Messages can also be moved from a queue to another queue by using
+ the `moveMessages()` method.
+
+- Listing and removing messages
+
+ Messages can be listed from a queue by using the `listMessages()`
+ method which returns an array of `Map`, one `Map` for each message.
+
+ Messages can also be removed from the queue by using the
+ `removeMessages()` method which returns a `boolean` for the single
+ message ID variant or the number of removed messages for the filter
+ variant. The `removeMessages()` method takes a `filter` argument to
+ remove only filtered messages. Setting the filter to an empty string
+ will in effect remove all messages.
+
+- Counting messages
+
+ The number of messages in a queue is returned by the
+ `getMessageCount()` method. Alternatively, the `countMessages()`
+ will return the number of messages in the queue which *match a given
+ filter*
+
+- Changing message priority
+
+ The message priority can be changed by using the
+ `changeMessagesPriority()` method which returns a `boolean` for the
+ single message ID variant or the number of updated messages for the
+ filter variant.
+
+- Message counters
+
+ Message counters can be listed for a queue with the
+ `listMessageCounter()` and `listMessageCounterHistory()` methods
+ (see ?). The message counters can also be reset for a single queue
+ using the `resetMessageCounter()` method.
+
+- Retrieving the queue attributes
+
+ The `QueueControl` exposes Core queue settings through its
+ attributes (e.g. `getFilter()` to retrieve the queue's filter if it
+ was created with one, `isDurable()` to know whether the queue is
+ durable or not, etc.)
+
+- Pausing and resuming Queues
+
+ The `QueueControl` can pause and resume the underlying queue. When a
+ queue is paused, it will receive messages but will not deliver them.
+ When it's resume, it'll begin delivering the queued messages, if
+ any.
+
+### Other Core Resources Management
+
+ActiveMQ allows to start and stop its remote resources (acceptors,
+diverts, bridges, etc.) so that a server can be taken off line for a
+given period of time without stopping it completely (e.g. if other
+management operations must be performed such as resolving heuristic
+transactions). These resources are:
+
+- Acceptors
+
+ They can be started or stopped using the `start()` or. `stop()`
+ method on the `AcceptorControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Acceptor,name="<the acceptor
+ name>"` or the resource name
+ `core.acceptor.<the
+ address name>`). The acceptors parameters
+ can be retrieved using the `AcceptorControl` attributes (see ?)
+
+- Diverts
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `DivertControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Divert,name=<the divert name>`
+ or the resource name `core.divert.<the divert name>`). Diverts
+ parameters can be retrieved using the `DivertControl` attributes
+ (see ?)
+
+- Bridges
+
+ They can be started or stopped using the `start()` (resp. `stop()`)
+ method on the `BridgeControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Bridge,name="<the bridge
+ name>"` or the resource name
+ `core.bridge.<the bridge
+ name>`). Bridges parameters can be retrieved
+ using the `BridgeControl` attributes (see ?)
+
+- Broadcast groups
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `BroadcastGroupControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=BroadcastGroup,name="<the broadcast group
+ name>"` or the resource name
+ `core.broadcastgroup.<the broadcast group name>`). Broadcast groups
+ parameters can be retrieved using the `BroadcastGroupControl`
+ attributes (see ?)
+
+- Discovery groups
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `DiscoveryGroupControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=DiscoveryGroup,name="<the discovery group
+ name>"` or the resource name
+ `core.discovery.<the
+ discovery group name>`). Discovery groups
+ parameters can be retrieved using the `DiscoveryGroupControl`
+ attributes (see ?)
+
+- Cluster connections
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `ClusterConnectionControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=ClusterConnection,name="<the cluster
+ connection name>"` or the resource name
+ `core.clusterconnection.<the cluster connection name>`). Cluster
+ connections parameters can be retrieved using the
+ `ClusterConnectionControl` attributes (see ?)
+
+JMS Management API
+------------------
+
+ActiveMQ defines a JMS Management API to manage JMS *administrated
+objects* (i.e. JMS queues, topics and connection factories).
+
+### JMS Server Management
+
+JMS Resources (connection factories and destinations) can be created
+using the `JMSServerControl` class (with the ObjectName
+`org.apache.activemq:module=JMS,type=Server` or the resource name
+`jms.server`).
+
+- Listing, creating, destroying connection factories
+
+ Names of the deployed connection factories can be retrieved by the
+ `getConnectionFactoryNames()` method.
+
+ JMS connection factories can be created or destroyed using the
+ `createConnectionFactory()` methods or `destroyConnectionFactory()`
+ methods. These connection factories are bound to JNDI so that JMS
+ clients can look them up. If a graphical console is used to create
+ the connection factories, the transport parameters are specified in
+ the text field input as a comma-separated list of key=value (e.g.
+ `key1=10, key2="value", key3=false`). If there are multiple
+ transports defined, you need to enclose the key/value pairs between
+ curly braces. For example `{key=10}, {key=20}`. In that case, the
+ first `key` will be associated to the first transport configuration
+ and the second `key` will be associated to the second transport
+ configuration (see ? for a list of the transport parameters)
+
+- Listing, creating, destroying queues
+
+ Names of the deployed JMS queues can be retrieved by the
+ `getQueueNames()` method.
+
+ JMS queues can be created or destroyed using the `createQueue()`
+ methods or `destroyQueue()` methods. These queues are bound to JNDI
+ so that JMS clients can look them up
+
+- Listing, creating/destroying topics
+
+ Names of the deployed topics can be retrieved by the
+ `getTopicNames()` method.
+
+ JMS topics can be created or destroyed using the `createTopic()` or
+ `destroyTopic()` methods. These topics are bound to JNDI so that JMS
+ clients can look them up
+
+- Listing and closing remote connections
+
+ JMS Clients remote addresses can be retrieved using
+ `listRemoteAddresses()`. It is also possible to close the
+ connections associated with a remote address using the
+ `closeConnectionsForAddress()` method.
+
+ Alternatively, connection IDs can be listed using
+ `listConnectionIDs()` and all the sessions for a given connection ID
+ can be listed using `listSessions()`.
+
+### JMS ConnectionFactory Management
+
+JMS Connection Factories can be managed using the
+`ConnectionFactoryControl` class (with the ObjectName
+`org.apache.activemq:module=JMS,type=ConnectionFactory,name="<the connection factory
+ name>"` or the resource name
+`jms.connectionfactory.<the
+ connection factory name>`).
+
+- Retrieving connection factory attributes
+
+ The `ConnectionFactoryControl` exposes JMS ConnectionFactory
+ configuration through its attributes (e.g. `getConsumerWindowSize()`
+ to retrieve the consumer window size for flow control,
+ `isBlockOnNonDurableSend()` to know whether the producers created
+ from the connection factory will block or not when sending
+ non-durable messages, etc.)
+
+### JMS Queue Management
+
+JMS queues can be managed using the `JMSQueueControl` class (with the
+ObjectName `org.apache.activemq:module=JMS,type=Queue,name="<the queue
+ name>"` or the resource name `jms.queue.<the queue
+ name>`).
+
+*The management operations on a JMS queue are very similar to the
+operations on a core queue.*
+
+- Expiring, sending to a dead letter address and moving messages
+
+ Messages can be expired from a queue by using the `expireMessages()`
+ method. If an expiry address is defined, messages will be sent to
+ it, otherwise they are discarded. The queue's expiry address can be
+ set with the `setExpiryAddress()` method.
+
+ Messages can also be sent to a dead letter address with the
+ `sendMessagesToDeadLetterAddress()` method. It returns the number of
+ messages which are sent to the dead letter address. If a dead letter
+ address is not defined, message are removed from the queue and
+ discarded. The queue's dead letter address can be set with the
+ `setDeadLetterAddress()` method.
+
+ Messages can also be moved from a queue to another queue by using
+ the `moveMessages()` method.
+
+- Listing and removing messages
+
+ Messages can be listed from a queue by using the `listMessages()`
+ method which returns an array of `Map`, one `Map` for each message.
+
+ Messages can also be removed from the queue by using the
+ `removeMessages()` method which returns a `boolean` for the single
+ message ID variant or the number of removed messages for the filter
+ variant. The `removeMessages()` method takes a `filter` argument to
+ remove only filtered messages. Setting the filter to an empty string
+ will in effect remove all messages.
+
+- Counting messages
+
+ The number of messages in a queue is returned by the
+ `getMessageCount()` method. Alternatively, the `countMessages()`
+ will return the number of messages in the queue which *match a given
+ filter*
+
+- Changing message priority
+
+ The message priority can be changed by using the
+ `changeMessagesPriority()` method which returns a `boolean` for the
+ single message ID variant or the number of updated messages for the
+ filter variant.
+
+- Message counters
+
+ Message counters can be listed for a queue with the
+ `listMessageCounter()` and `listMessageCounterHistory()` methods
+ (see ?)
+
+- Retrieving the queue attributes
+
+ The `JMSQueueControl` exposes JMS queue settings through its
+ attributes (e.g. `isTemporary()` to know whether the queue is
+ temporary or not, `isDurable()` to know whether the queue is durable
+ or not, etc.)
+
+- Pausing and resuming queues
+
+ The `JMSQueueControl` can pause and resume the underlying queue.
+ When the queue is paused it will continue to receive messages but
+ will not deliver them. When resumed again it will deliver the
+ enqueued messages, if any.
+
+### JMS Topic Management
+
+JMS Topics can be managed using the `TopicControl` class (with the
+ObjectName `org.apache.activemq:module=JMS,type=Topic,name="<the topic
+ name>"` or the resource name `jms.topic.<the topic
+ name>`).
+
+- Listing subscriptions and messages
+
+ JMS topics subscriptions can be listed using the
+ `listAllSubscriptions()`, `listDurableSubscriptions()`,
+ `listNonDurableSubscriptions()` methods. These methods return arrays
+ of `Object` representing the subscriptions information (subscription
+ name, client ID, durability, message count, etc.). It is also
+ possible to list the JMS messages for a given subscription with the
+ `listMessagesForSubscription()` method.
+
+- Dropping subscriptions
+
+ Durable subscriptions can be dropped from the topic using the
+ `dropDurableSubscription()` method.
+
+- Counting subscriptions messages
+
+ The `countMessagesForSubscription()` method can be used to know the
+ number of messages held for a given subscription (with an optional
+ message selector to know the number of messages matching the
+ selector)
+
+Using Management Via JMX
+========================
+
+ActiveMQ can be managed using
+[JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html).
+
+The management API is exposed by ActiveMQ using MBeans interfaces.
+ActiveMQ registers its resources with the domain `org.apache.activemq`.
+
+For example, the `ObjectName` to manage a JMS Queue `exampleQueue` is:
+
+ org.apache.activemq:module=JMS,type=Queue,name="exampleQueue"
+
+and the MBean is:
+
+ org.apache.activemq.api.jms.management.JMSQueueControl
+
+The MBean's `ObjectName` are built using the helper class
+`org.apache.activemq.api.core.management.ObjectNameBuilder`. You can
+also use `jconsole` to find the `ObjectName` of the MBeans you want to
+manage.
+
+Managing ActiveMQ using JMX is identical to management of any Java
+Applications using JMX. It can be done by reflection or by creating
+proxies of the MBeans.
+
+Configuring JMX
+---------------
+
+By default, JMX is enabled to manage ActiveMQ. It can be disabled by
+setting `jmx-management-enabled` to `false` in
+`activemq-configuration.xml`:
+
+ <!-- false to disable JMX management for ActiveMQ -->
+ <jmx-management-enabled>false</jmx-management-enabled>
+
+If JMX is enabled, ActiveMQ can be managed locally using `jconsole`.
+
+> **Note**
+>
+> Remote connections to JMX are not enabled by default for security
+> reasons. Please refer to [Java Management
+> guide](http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html)
+> to configure the server for remote management (system properties must
+> be set in `run.sh` or `run.bat` scripts).
+
+By default, ActiveMQ server uses the JMX domain "org.apache.activemq".
+To manage several ActiveMQ servers from the *same* MBeanServer, the JMX
+domain can be configured for each individual ActiveMQ server by setting
+`jmx-domain` in `activemq-configuration.xml`:
+
+ <!-- use a specific JMX domain for ActiveMQ MBeans -->
+ <jmx-domain>my.org.apache.activemq</jmx-domain>
+
+### MBeanServer configuration
+
+When ActiveMQ is run in standalone, it uses the Java Virtual Machine's
+`Platform MBeanServer` to register its MBeans. This is configured in
+JBoss Microcontainer Beans file (see ?):
+
+ <!-- MBeanServer -->
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
+ factoryMethod="getPlatformMBeanServer" />
+ </bean>
+
+When it is integrated in JBoss AS 5+, it uses the Application Server's
+own MBean Server so that it can be managed using AS 5's jmx-console:
+
+ <!-- MBeanServer -->
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
+ factoryMethod="locateJBoss" />
+ </bean>
+
+Example
+-------
+
+See ? for an example which shows how to use a remote connection to JMX
+and MBean proxies to manage ActiveMQ.
+
+Using Management Via Core API
+=============================
+
+The core management API in ActiveMQ is called by sending Core messages
+to a special address, the *management address*.
+
+*Management messages* are regular Core messages with well-known
+properties that the server needs to understand to interact with the
+management API:
+
+- The name of the managed resource
+
+- The name of the management operation
+
+- The parameters of the management operation
+
+When such a management message is sent to the management address,
+ActiveMQ server will handle it, extract the information, invoke the
+operation on the managed resources and send a *management reply* to the
+management message's reply-to address (specified by
+`ClientMessageImpl.REPLYTO_HEADER_NAME`).
+
+A `ClientConsumer` can be used to consume the management reply and
+retrieve the result of the operation (if any) stored in the reply's
+body. For portability, results are returned as a [JSON](http://json.org)
+String rather than Java Serialization (the
+`org.apache.activemq.api.core.management.ManagementHelper` can be used
+to convert the JSON string to Java objects).
+
+These steps can be simplified to make it easier to invoke management
+operations using Core messages:
+
+1. Create a `ClientRequestor` to send messages to the management
+ address and receive replies
+
+2. Create a `ClientMessage`
+
+3. Use the helper class
+ `org.apache.activemq.api.core.management.ManagementHelper` to fill
+ the message with the management properties
+
+4. Send the message using the `ClientRequestor`
+
+5. Use the helper class
+ `org.apache.activemq.api.core.management.ManagementHelper` to
+ retrieve the operation result from the management reply
+
+For example, to find out the number of messages in the core queue
+`exampleQueue`:
+
+ ClientSession session = ...
+ ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
+ ClientMessage message = session.createMessage(false);
+ ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
+ session.start();
+ ClientMessage reply = requestor.request(m);
+ int count = (Integer) ManagementHelper.getResult(reply);
+ System.out.println("There are " + count + " messages in exampleQueue");
+
+Management operation name and parameters must conform to the Java
+interfaces defined in the `management` packages.
+
+Names of the resources are built using the helper class
+`org.apache.activemq.api.core.management.ResourceNames` and are
+straightforward (`core.queue.exampleQueue` for the Core Queue
+`exampleQueue`, `jms.topic.exampleTopic` for the JMS Topic
+`exampleTopic`, etc.).
+
+Configuring Core Management
+---------------------------
+
+The management address to send management messages is configured in
+`activemq-configuration.xml`:
+
+ <management-address>jms.queue.activemq.management</management-address>
+
+By default, the address is `jms.queue.activemq.management` (it is
+prepended by "jms.queue" so that JMS clients can also send management
+messages).
+
+The management address requires a *special* user permission `manage` to
+be able to receive and handle management messages. This is also
+configured in activemq-configuration.xml:
+
+ <!-- users with the admin role will be allowed to manage -->
+ <!-- ActiveMQ using management messages -->
+ <security-setting match="jms.queue.activemq.management">
+ <permission type="manage" roles="admin" />
+ </security-setting>
+
+Using Management Via JMS
+========================
+
+Using JMS messages to manage ActiveMQ is very similar to using core API.
+
+An important difference is that JMS requires a JMS queue to send the
+messages to (instead of an address for the core API).
+
+The *management queue* is a special queue and needs to be instantiated
+directly by the client:
+
+ Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
+
+All the other steps are the same than for the Core API but they use JMS
+API instead:
+
+1. create a `QueueRequestor` to send messages to the management address
+ and receive replies
+
+2. create a `Message`
+
+3. use the helper class
+ `org.apache.activemq.api.jms.management.JMSManagementHelper` to fill
+ the message with the management properties
+
+4. send the message using the `QueueRequestor`
+
+5. use the helper class
+ `org.apache.activemq.api.jms.management.JMSManagementHelper` to
+ retrieve the operation result from the management reply
+
+For example, to know the number of messages in the JMS queue
+`exampleQueue`:
+
+ Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
+
+ QueueSession session = ...
+ QueueRequestor requestor = new QueueRequestor(session, managementQueue);
+ connection.start();
+ Message message = session.createMessage();
+ JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
+ Message reply = requestor.request(message);
+ int count = (Integer)JMSManagementHelper.getResult(reply);
+ System.out.println("There are " + count + " messages in exampleQueue");
+
+Configuring JMS Management
+--------------------------
+
+Whether JMS or the core API is used for management, the configuration
+steps are the same (see ?).
+
+Example
+-------
+
+See ? for an example which shows how to use JMS messages to manage
+ActiveMQ server.
+
+Management Notifications
+========================
+
+ActiveMQ emits *notifications* to inform listeners of potentially
+interesting events (creation of new resources, security violation,
+etc.).
+
+These notifications can be received by 3 different ways:
+
+- JMX notifications
+
+- Core messages
+
+- JMS messages
+
+JMX Notifications
+-----------------
+
+If JMX is enabled (see ?), JMX notifications can be received by
+subscribing to 2 MBeans:
+
+- `org.apache.activemq:module=Core,type=Server` for notifications on
+ *Core* resources
+
+- `org.apache.activemq:module=JMS,type=Server` for notifications on
+ *JMS* resources
+
+Core Messages Notifications
+---------------------------
+
+ActiveMQ defines a special *management notification address*. Core
+queues can be bound to this address so that clients will receive
+management notifications as Core messages
+
+A Core client which wants to receive management notifications must
+create a core queue bound to the management notification address. It can
+then receive the notifications from its queue.
+
+Notifications messages are regular core messages with additional
+properties corresponding to the notification (its type, when it
+occurred, the resources which were concerned, etc.).
+
+Since notifications are regular core messages, it is possible to use
+message selectors to filter out notifications and receives only a subset
+of all the notifications emitted by the server.
+
+### Configuring The Core Management Notification Address
+
+The management notification address to receive management notifications
+is configured in `activemq-configuration.xml`:
+
+ <management-notification-address>activemq.notifications</management-notification-address>
+
+By default, the address is `activemq.notifications`.
+
+JMS Messages Notifications
+--------------------------
+
+ActiveMQ's notifications can also be received using JMS messages.
+
+It is similar to receiving notifications using Core API but an important
+difference is that JMS requires a JMS Destination to receive the
+messages (preferably a Topic).
+
+To use a JMS Destination to receive management notifications, you must
+change the server's management notification address to start with
+`jms.queue` if it is a JMS Queue or `jms.topic` if it is a JMS Topic:
+
+ <!-- notifications will be consumed from "notificationsTopic" JMS Topic -->
+ <management-notification-address>jms.topic.notificationsTopic</management-notification-address>
+
+Once the notification topic is created, you can receive messages from it
+or set a `MessageListener`:
+
+ Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
+
+ Session session = ...
+ MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
+ notificationConsumer.setMessageListener(new MessageListener()
+ {
+ public void onMessage(Message notif)
+ {
+ System.out.println("------------------------");
+ System.out.println("Received notification:");
+ try
+ {
+ Enumeration propertyNames = notif.getPropertyNames();
+ while (propertyNames.hasMoreElements())
+ {
+ String propertyName = (String)propertyNames.nextElement();
+ System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
+ }
+ }
+ catch (JMSException e)
+ {
+ }
+ System.out.println("------------------------");
+ }
+ });
+
+Example
+-------
+
+See ? for an example which shows how to use a JMS `MessageListener` to
+receive management notifications from ActiveMQ server.
+
+Notification Types and Headers
+------------------------------
+
+Below is a list of all the different kinds of notifications as well as
+which headers are on the messages. Every notification has a
+`_HQ_NotifType` (value noted in parentheses) and `_HQ_NotifTimestamp`
+header. The timestamp is the un-formatted result of a call to
+`java.lang.System.currentTimeMillis()`.
+
+- `BINDING_ADDED` (0)
+
+ `_HQ_Binding_Type`, `_HQ_Address`, `_HQ_ClusterName`,
+ `_HQ_RoutingName`, `_HQ_Binding_ID`, `_HQ_Distance`,
+ `_HQ_FilterString`
+
+- `BINDING_REMOVED` (1)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`,
+ `_HQ_Binding_ID`, `_HQ_Distance`, `_HQ_FilterString`
+
+- `CONSUMER_CREATED` (2)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
+ `_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
+ `_HQ_SessionName`, `_HQ_FilterString`
+
+- `CONSUMER_CLOSED` (3)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
+ `_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
+ `_HQ_SessionName`, `_HQ_FilterString`
+
+- `SECURITY_AUTHENTICATION_VIOLATION` (6)
+
+ `_HQ_User`
+
+- `SECURITY_PERMISSION_VIOLATION` (7)
+
+ `_HQ_Address`, `_HQ_CheckType`, `_HQ_User`
+
+- `DISCOVERY_GROUP_STARTED` (8)
+
+ `name`
+
+- `DISCOVERY_GROUP_STOPPED` (9)
+
+ `name`
+
+- `BROADCAST_GROUP_STARTED` (10)
+
+ `name`
+
+- `BROADCAST_GROUP_STOPPED` (11)
+
+ `name`
+
+- `BRIDGE_STARTED` (12)
+
+ `name`
+
+- `BRIDGE_STOPPED` (13)
+
+ `name`
+
+- `CLUSTER_CONNECTION_STARTED` (14)
+
+ `name`
+
+- `CLUSTER_CONNECTION_STOPPED` (15)
+
+ `name`
+
+- `ACCEPTOR_STARTED` (16)
+
+ `factory`, `id`
+
+- `ACCEPTOR_STOPPED` (17)
+
+ `factory`, `id`
+
+- `PROPOSAL` (18)
+
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_HQ_Binding_Type`,
+ `_HQ_Address`, `_HQ_Distance`
+
+- `PROPOSAL_RESPONSE` (19)
+
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`,
+ `_JBM_ProposalAltValue`, `_HQ_Binding_Type`, `_HQ_Address`,
+ `_HQ_Distance`
+
+- `CONSUMER_SLOW` (21)
+
+ `_HQ_Address`, `_HQ_ConsumerCount`, `_HQ_RemoteAddress`,
+ `_HQ_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName`
+
+Message Counters
+================
+
+Message counters can be used to obtain information on queues *over time*
+as ActiveMQ keeps a history on queue metrics.
+
+They can be used to show *trends* on queues. For example, using the
+management API, it would be possible to query the number of messages in
+a queue at regular interval. However, this would not be enough to know
+if the queue is used: the number of messages can remain constant because
+nobody is sending or receiving messages from the queue or because there
+are as many messages sent to the queue than messages consumed from it.
+The number of messages in the queue remains the same in both cases but
+its use is widely different.
+
+Message counters gives additional information about the queues:
+
+- `count`
+
+ The *total* number of messages added to the queue since the server
+ was started
+
+- `countDelta`
+
+ the number of messages added to the queue *since the last message
+ counter update*
+
+- `messageCount`
+
+ The *current* number of messages in the queue
+
+- `messageCountDelta`
+
+ The *overall* number of messages added/removed from the queue *since
+ the last message counter update*. For example, if
+ `messageCountDelta` is equal to `-10` this means that overall 10
+ messages have been removed from the queue (e.g. 2 messages were
+ added and 12 were removed)
+
+- `lastAddTimestamp`
+
+ The timestamp of the last time a message was added to the queue
+
+- `udpateTimestamp`
+
+ The timestamp of the last message counter update
+
+These attributes can be used to determine other meaningful data as well.
+For example, to know specifically how many messages were *consumed* from
+the queue since the last update simply subtract the `messageCountDelta`
+from `countDelta`.
+
+Configuring Message Counters
+----------------------------
+
+By default, message counters are disabled as it might have a small
+negative effect on memory.
+
+To enable message counters, you can set it to `true` in
+`activemq-configuration.xml`:
+
+ <message-counter-enabled>true</message-counter-enabled>
+
+Message counters keeps a history of the queue metrics (10 days by
+default) and samples all the queues at regular interval (10 seconds by
+default). If message counters are enabled, these values should be
+configured to suit your messaging use case in
+`activemq-configuration.xml`:
+
+ <!-- keep history for a week -->
+ <message-counter-max-day-history>7</message-counter-max-day-history>
+ <!-- sample the queues every minute (60000ms) -->
+ <message-counter-sample-period>60000</message-counter-sample-period>
+
+Message counters can be retrieved using the Management API. For example,
+to retrieve message counters on a JMS Queue using JMX:
+
+ // retrieve a connection to ActiveMQ's MBeanServer
+ MBeanServerConnection mbsc = ...
+ JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
+ on,
+ JMSQueueControl.class,
+ false);
+ // message counters are retrieved as a JSON String
+ String counters = queueControl.listMessageCounter();
+ // use the MessageCounterInfo helper class to manipulate message counters more easily
+ MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
+ System.out.format("%s message(s) in the queue (since last sample: %s)\n",
+ messageCounter.getMessageCount(),
+ messageCounter.getMessageCountDelta());
+
+Example
+-------
+
+See ? for an example which shows how to use message counters to retrieve
+information on a JMS `Queue`.
+
+Administering ActiveMQ Resources Using The JBoss AS Admin Console
+=================================================================
+
+Its possible to create and configure ActiveMQ resources via the admin
+console within the JBoss Application Server.
+
+The Admin Console will allow you to create destinations (JMS Topics and
+Queues) and JMS Connection Factories.
+
+Once logged in to the admin console you will see a JMS Manager item in
+the left hand tree. All ActiveMQ resources will be configured via this.
+This will have a child items for JMS Queues, Topics and Connection
+Factories, clicking on each node will reveal which resources are
+currently available. The following sections explain how to create and
+configure each resource in turn.
+
+JMS Queues
+----------
+
+To create a new JMS Queue click on the JMS Queues item to reveal the
+available queues. On the right hand panel you will see an add a new
+resource button, click on this and then choose the default(JMS Queue)
+template and click continue. The important things to fill in here are
+the name of the queue and the JNDI name of the queue. The JNDI name is
+what you will use to look up the queue in JNDI from your client. For
+most queues this will be the only info you will need to provide as
+sensible defaults are provided for the others. You will also see a
+security roles section near the bottom. If you do not provide any roles
+for this queue then the servers default security configuration will be
+used, after you have created the queue these will be shown in the
+configuration. All configuration values, except the name and JNDI name,
+can be changed via the configuration tab after clicking on the queue in
+the admin console. The following section explains these in more detail
+
+After highlighting the configuration you will see the following screen
+
+
+
+The name and JNDI name can't be changed, if you want to change these
+recreate the queue with the appropriate settings. The rest of the
+configuration options, apart from security roles, relate to address
+settings for a particular address. The default address settings are
+picked up from the servers configuration, if you change any of these
+settings or create a queue via the console a new Address Settings entry
+will be added. For a full explanation on Address Settings see ?
+
+To delete a queue simply click on the delete button beside the queue
+name in the main JMS Queues screen. This will also delete any address
+settings or security settings previously created for the queues address
+
+The last part of the configuration options are security roles. If non
+are provided on creation then the servers default security settings will
+be shown. If these are changed or updated then new security settings are
+created for the address of this queue. For more information on security
+setting see ?
+
+It is also possible via the metrics tab to view statistics for this
+queue. This will show statistics such as message count, consumer count
+etc.
+
+Operations can be performed on a queue via the control tab. This will
+allow you to start and stop the queue, list,move,expire and delete
+messages from the queue and other useful operations. To invoke an
+operation click on the button for the operation you want, this will take
+you to a screen where you can parameters for the operation can be set.
+Once set clicking the ok button will invoke the operation, results
+appear at the bottom of the screen.
+
+JMS Topics
+----------
+
+Creating and configuring JMS Topics is almost identical to creating
+queues. The only difference is that the configuration will be applied to
+the queue representing a subscription.
+
+JMS Connection Factories
+------------------------
+
+The format for creating connection factories is the same as for JMS
+Queues and topics apart from the configuration being different. For as
+list of all the connection factory settings see the configuration index
[20/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/appserver-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/appserver-integration.xml b/docs/user-manual/en/appserver-integration.xml
deleted file mode 100644
index 897de10..0000000
--- a/docs/user-manual/en/appserver-integration.xml
+++ /dev/null
@@ -1,1338 +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="appserver-integration">
- <title>Application Server Integration and Java EE</title>
- <para>ActiveMQ can be easily installed in JBoss Application Server 4 or later. For details on
- installing ActiveMQ in the JBoss Application Server please refer to quick-start guide.</para>
- <para>Since ActiveMQ also provides a JCA adapter, it is also possible to integrate ActiveMQ
- as a JMS provider in other JEE compliant app servers. For instructions on how to integrate a
- remote JCA adaptor into another application sever, please consult the other application server's
- instructions.</para>
- <para>A JCA Adapter basically controls the inflow of messages to Message-Driven Beans (MDBs) and the
- outflow of messages sent from other JEE components, e.g. EJBs and Servlets.</para>
- <para>This section explains the basics behind configuring the different JEE components in the
- AS.</para>
- <section id="configuring-mdbs">
- <title>Configuring Message-Driven Beans</title>
- <para>The delivery of messages to an MDB using ActiveMQ is configured on the JCA Adapter via
- a configuration file <literal>ra.xml</literal> which can be found under the <literal
- >jms-ra.rar</literal> directory. By default this is configured to consume
- messages using an InVM connector from the instance of ActiveMQ running within the
- application server. The configuration properties are listed later in this chapter. </para>
- <para>All MDBs however need to have the destination type and the destination configured.
- The following example shows how this can be done using annotations:</para>
- <programlisting>
-@MessageDriven(name = "MDBExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@ResourceAdapter("activemq-ra.rar")
-public class MDBExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- <para>In this example you can see that the MDB will consume messages from a queue that is
- mapped into JNDI with the binding <literal>queue/testQueue</literal>. This queue must be
- preconfigured in the usual way using the ActiveMQ configuration files.</para>
- <para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor
- should be used. To use this you will need to import <literal
- >org.jboss.ejb3.annotation.ResourceAdapter</literal> for JBoss AS 5.X and later version which can be found in the
- <literal>jboss-ejb3-ext-api.jar</literal> which can be found in the JBoss
- repository. For JBoss AS 4.X, the annotation to use is <literal>org.jboss.annotation.ejb.ResourceAdaptor</literal>.</para>
- <para>
- Alternatively you can add use a deployment descriptor and add something like
- the following to <literal
- >jboss.xml</literal><programlisting><message-driven>
- <ejb-name>ExampleMDB</ejb-name>
- <resource-adapter-name>activemq-ra.rar</resource-adapter-name>
-</message-driven>
-</programlisting>You
- can also rename the activemq-ra.rar directory to jms-ra.rar and neither the annotation or
- the extra descriptor information will be needed. If you do this you will need to edit
- the <literal>jms-ds.xml</literal> datasource file and change <literal>rar-name</literal>
- element.</para>
- <note>
- <para>ActiveMQ is the default JMS provider for JBoss AS 6. Starting with this AS version, ActiveMQ resource
- adapter is named <literal>jms-ra.rar</literal> and you no longer need to annotate the MDB for the resource adapter name.</para>
- </note>
- <para>All the examples shipped with the ActiveMQ distribution use the annotation.</para>
- <section>
- <title>Using Container-Managed Transactions</title>
- <para>When an MDB is using Container-Managed Transactions (CMT), the delivery of the
- message is done within the scope of a JTA transaction. The commit or rollback of
- this transaction is controlled by the container itself. If the transaction is rolled
- back then the message delivery semantics will kick in (by default, it will try to
- redeliver the message up to 10 times before sending to a DLQ). Using annotations
- this would be configured as follows:</para>
- <programlisting>
-@MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_CMP_TxRequiredExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- <para>The <literal>TransactionManagement</literal> annotation tells the container to manage the
- transaction. The <literal>TransactionAttribute</literal> annotation tells the container that a JTA
- transaction is required for this MDB. Note that the only other valid value for this
- is <literal>TransactionAttributeType.NOT_SUPPORTED</literal> which tells the
- container that this MDB does not support JTA transactions and one should not be
- created.</para>
- <para>It is also possible to inform the container that it must rollback the transaction
- by calling <literal>setRollbackOnly</literal> on the <literal
- >MessageDrivenContext</literal>. The code for this would look something
- like:</para>
- <programlisting>
-@Resource
-MessageDrivenContextContext ctx;
-
-public void onMessage(Message message)
-{
- try
- {
- //something here fails
- }
- catch (Exception e)
- {
- ctx.setRollbackOnly();
- }
-}</programlisting>
- <para>If you do not want the overhead of an XA transaction being created every time but
- you would still like the message delivered within a transaction (i.e. you are only
- using a JMS resource) then you can configure the MDB to use a local transaction.
- This would be configured as such:</para>
- <programlisting>
-@MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
-})
-@TransactionManagement(value = TransactionManagementType.CONTAINER)
-@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_CMP_TxLocalExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- </section>
- <section>
- <title>Using Bean-Managed Transactions</title>
- <para>Message-driven beans can also be configured to use Bean-Managed Transactions
- (BMT). In this case a User Transaction is created. This would be configured as
- follows:</para>
- <programlisting>
-@MessageDriven(name = "MDB_BMPExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
-})
-@TransactionManagement(value= TransactionManagementType.BEAN)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_BMPExample implements MessageListener
-{
- public void onMessage(Message message)
-}</programlisting>
- <para>When using Bean-Managed Transactions the message delivery to the MDB will occur
- outside the scope of the user transaction and use the acknowledge mode specified by
- the user with the <literal>acknowledgeMode</literal> property. There are only 2
- acceptable values for this <literal>Auto-acknowledge</literal> and <literal
- >Dups-ok-acknowledge</literal>. Please note that because the message delivery is outside
- the scope of the transaction a failure within the MDB will not cause the message to
- be redelivered.</para>
- <para>A user would control the life-cycle of the transaction something like the
- following:</para>
- <programlisting>
-@Resource
-MessageDrivenContext ctx;
-
-public void onMessage(Message message)
-{
- UserTransaction tx;
- try
- {
- TextMessage textMessage = (TextMessage)message;
-
- String text = textMessage.getText();
-
- UserTransaction tx = ctx.getUserTransaction();
-
- tx.begin();
-
- //do some stuff within the transaction
-
- tx.commit();
-
- }
- catch (Exception e)
- {
- tx.rollback();
- }
-}</programlisting>
- </section>
- <section>
- <title>Using Message Selectors with Message-Driven Beans</title>
- <para>It is also possible to use MDBs with message selectors. To do this simple define
- your message selector as follows:</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDBMessageSelectorExample implements MessageListener
-{
- public void onMessage(Message message)....
-}</programlisting>
- </section>
- </section>
- <section>
- <title>Sending Messages from within JEE components</title>
- <para>The JCA adapter can also be used for sending messages. The Connection Factory to use
- is configured by default in the <literal>jms-ds.xml</literal> file and is mapped to
- <literal>java:/JmsXA</literal>. Using this from within a JEE component will mean
- that the sending of the message will be done as part of the JTA transaction being used
- by the component.</para>
- <para>This means that if the sending of the message fails the overall transaction would
- rollback and the message be re-sent. Heres an example of this from within an
- MDB:</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDBMessageSendTxExample implements MessageListener
-{
- @Resource(mappedName = "java:/JmsXA")
- ConnectionFactory connectionFactory;
-
- @Resource(mappedName = "queue/replyQueue")
- Queue replyQueue;
-
- public void onMessage(Message message)
- {
- Connection conn = null;
- try
- {
- //Step 9. We know the client is sending a text message so we cast
- TextMessage textMessage = (TextMessage)message;
-
- //Step 10. get the text from the message.
- String text = textMessage.getText();
-
- System.out.println("message " + text);
-
- conn = connectionFactory.createConnection();
-
- Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
- MessageProducer producer = sess.createProducer(replyQueue);
-
- producer.send(sess.createTextMessage("this is a reply"));
-
- }
- catch (Exception e)
- {
- e.printStackTrace();
- }
- finally
- {
- if(conn != null)
- {
- try
- {
- conn.close();
- }
- catch (JMSException e)
- {
- }
- }
- }
- }
- }</programlisting>
- <para>In JBoss Application Server you can use the JMS JCA adapter for sending messages from
- EJBs (including Session, Entity and Message-Driven Beans), Servlets (including jsps) and
- custom MBeans.</para>
- </section>
- <section>
- <title>MDB and Consumer pool size</title>
- <para>Most application servers, including JBoss, allow you to configure how many MDB's there are in a pool. In
- JBoss this is configured via the <literal>MaxPoolSize</literal> parameter in the ejb3-interceptors-aop.xml file. Configuring
- this has no actual effect on how many sessions/consumers there actually are created. This is because the Resource
- Adaptor implementation knows nothing about the application servers MDB implementation. So even if you set the MDB
- pool size to 1, 15 sessions/consumers will be created (this is the default). If you want to limit how many
- sessions/consumers are created then you need to set the <literal>maxSession</literal> parameter either on the
- resource adapter itself or via an an Activation Config Property on the MDB itself</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MyMDB implements MessageListener
-{ ....}
- </programlisting>
- </section>
- <section>
- <title>Configuring the JCA Adaptor</title>
- <para>The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to be integrated
- with JEE components such as MDBs and EJBs. It configures how components such as MDBs
- consume messages from the ActiveMQ server and also how components such as EJBs or
- Servlets can send messages.</para>
- <para>The ActiveMQ JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
- configuration of the adapter is found in this archive under <literal
- >META-INF/ra.xml</literal>.</para>
- <para>The configuration will look something like the following:</para>
- <programlisting>
-<resourceadapter>
- <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type. Multiple connectors can be configured by using a comma separated list,
- i.e. org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory,org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory.</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;,
- if multiple connectors are used then each set must be separated by a comma i.e. host=host1;port=5445,host=host2;port=5446.
- Each set of parameters maps to the connector classname specified.</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>server-id=0</config-property-value>
- </config-property>
-
- <outbound-resourceadapter>
- <connection-definition>
- <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnection
- Factory</managedconnectionfactory-class>
-
- <config-property>
- <description>The default session type</description>
- <config-property-name>SessionDefaultType</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>javax.jms.Queue</config-property-value>
- </config-property>
- <config-property>
- <description>Try to obtain a lock within specified number of seconds; less
- than or equal to 0 disable this functionality</description>
- <config-property-name>UseTryLock</config-property-name>
- <config-property-type>java.lang.Integer</config-property-type>
- <config-property-value>0</config-property-value>
- </config-property>
-
- <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory
- </connectionfactory-interface>
- <connectionfactororg.apache.activemq.ra.ActiveMQConnectionFactoryImplonFactoryImpl
- </connectionfactory-impl-class>
- <connection-interface>javax.jms.Session</connection-interface>
- <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession
- </connection-impl-class>
- </connection-definition>
- <transaction-support>XATransaction</transaction-support>
- <authentication-mechanism>
- <authentication-mechanism-type>BasicPassword
- </authentication-mechanism-type>
- <credential-interface>javax.resource.spi.security.PasswordCredential
- </credential-interface>
- </authentication-mechanism>
- <reauthentication-support>false</reauthentication-support>
- </outbound-resourceadapter>
-
- <inbound-resourceadapter>
- <messageadapter>
- <messagelistener>
- <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
- <activationspec>
- <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec
- </activationspec-class>
- <required-config-property>
- <config-property-name>destination</config-property-name>
- </required-config-property>
- </activationspec>
- </messagelistener>
- </messageadapter>
- </inbound-resourceadapter>
-</resourceadapter></programlisting>
- <para>There are three main parts to this configuration.</para>
- <orderedlist>
- <listitem>
- <para>A set of global properties for the adapter</para>
- </listitem>
- <listitem>
- <para>The configuration for the outbound part of the adapter. This is used for
- creating JMS resources within EE components. </para>
- </listitem>
- <listitem>
- <para>The configuration of the inbound part of the adapter. This is used for
- controlling the consumption of messages via MDBs. </para>
- </listitem>
- </orderedlist>
- <section>
- <title>Global Properties</title>
- <para>The first element you see is <literal>resourceadapter-class</literal> which should
- be left unchanged. This is the ActiveMQ resource adapter class.</para>
- <para>After that there is a list of configuration properties. This will be where most of
- the configuration is done. The first two properties configure the transport used by the adapter
- and the rest configure the connection factory itself.
- </para>
- <note>
- <para>All connection factory properties will use the defaults if they are not provided, except
- for the <literal>reconnectAttempts</literal> which will default to -1. This
- signifies that the connection should attempt to reconnect on connection
- failure indefinitely. This is only used when the adapter is configured to
- connect to a remote server as an InVM connector can never fail.
- </para>
- </note>
- <para>The following table explains what each property is for.</para>
- <table frame="topbot" border="2">
- <title>Global Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>ConnectorClassName</entry>
- <entry>String</entry>
- <entry>The Connector class name (see <xref
- linkend="configuring-transports"/> for more information). If multiple connectors are
- needed this should be provided as a comma separated list.</entry>
- </row>
- <row>
- <entry>ConnectionParameters</entry>
- <entry>String</entry>
- <entry>The transport configuration. These parameters must be in the form of
- <literal>key1=val1;key2=val2;</literal> and will be specific to the connector used. If
- multiple connectors are configured then parameters should be supplied for each connector
- separated by a comma.
- </entry>
- </row>
- <row>
- <entry>ha</entry>
- <entry>boolean</entry>
- <entry>True if high availability is needed.</entry>
- </row>
- <row>
- <entry>useLocalTx</entry>
- <entry>boolean</entry>
- <entry>True will enable local transaction optimisation.</entry>
- </row>
- <row>
- <entry>UserName</entry>
- <entry>String</entry>
- <entry>The user name to use when making a connection </entry>
- </row>
- <row>
- <entry>Password</entry>
- <entry>String</entry>
- <entry>The password to use when making a connection</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.group-address">DiscoveryAddress</link></entry>
- <entry>String</entry>
- <entry>The discovery group address to use to auto-detect a server</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.group-port">DiscoveryPort</link></entry>
- <entry>Integer</entry>
- <entry>The port to use for discovery</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.refresh-timeout">DiscoveryRefreshTimeout</link></entry>
- <entry>Long</entry>
- <entry>The timeout, in milliseconds, to refresh.</entry>
- </row>
- <row>
- <entry>
- DiscoveryInitialWaitTimeout
- </entry>
- <entry>Long</entry>
- <entry>The initial time to wait for discovery.</entry>
- </row>
- <row>
- <entry>
- ConnectionLoadBalancingPolicyClassName
- </entry>
- <entry>String</entry>
- <entry>The load balancing policy class to use.</entry>
- </row>
- <row>
- <entry>
- ConnectionTTL
- </entry>
- <entry>Long</entry>
- <entry>The time to live (in milliseconds) for the connection.</entry>
- </row>
- <row>
- <entry>
- CallTimeout
- </entry>
- <entry>Long</entry>
- <entry>the call timeout (in milliseconds) for each packet sent.</entry>
- </row>
- <row>
- <entry>
- DupsOKBatchSize
- </entry>
- <entry>Integer</entry>
- <entry>the batch size (in bytes) between acknowledgements when using
- DUPS_OK_ACKNOWLEDGE mode</entry>
- </row>
- <row>
- <entry>
- TransactionBatchSize
- </entry>
- <entry>Integer</entry>
- <entry>the batch size (in bytes) between acknowledgements when using a
- transactional session</entry>
- </row>
- <row>
- <entry>
- ConsumerWindowSize
- </entry>
- <entry>Integer</entry>
- <entry>the window size (in bytes) for consumer flow control</entry>
- </row>
- <row>
- <entry>
- ConsumerMaxRate
- </entry>
- <entry>Integer</entry>
- <entry>the fastest rate a consumer may consume messages per second</entry>
- </row>
- <row>
- <entry>
- ConfirmationWindowSize
- </entry>
- <entry>Integer</entry>
- <entry>the window size (in bytes) for reattachment confirmations</entry>
- </row>
- <row>
- <entry>
- ProducerMaxRate
- </entry>
- <entry>Integer</entry>
- <entry>the maximum rate of messages per second that can be sent</entry>
- </row>
- <row>
- <entry>
- MinLargeMessageSize
- </entry>
- <entry>Integer</entry>
- <entry>the size (in bytes) before a message is treated as large </entry>
- </row>
- <row>
- <entry>
- BlockOnAcknowledge
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not messages are acknowledged synchronously</entry>
- </row>
- <row>
- <entry>
- BlockOnNonDurableSend
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not non-durable messages are sent synchronously</entry>
- </row>
- <row>
- <entry>
- BlockOnDurableSend
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not durable messages are sent synchronously</entry>
- </row>
- <row>
- <entry>
- AutoGroup
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not message grouping is automatically used</entry>
- </row>
- <row>
- <entry>
- PreAcknowledge
- </entry>
- <entry>Boolean</entry>
- <entry>whether messages are pre acknowledged by the server before
- sending</entry>
- </row>
- <row>
- <entry>
- ReconnectAttempts
- </entry>
- <entry>Integer</entry>
- <entry>maximum number of retry attempts, default for the resource adapter is -1 (infinite attempts)</entry>
- </row>
- <row>
- <entry>
- RetryInterval
- </entry>
- <entry>Long</entry>
- <entry>the time (in milliseconds) to retry a connection after failing</entry>
- </row>
- <row>
- <entry>
- RetryIntervalMultiplier
- </entry>
- <entry>Double</entry>
- <entry>multiplier to apply to successive retry intervals</entry>
- </row>
- <row>
- <entry>
- FailoverOnServerShutdown
- </entry>
- <entry>Boolean</entry>
- <entry>If true client will reconnect to another server if
- available</entry>
- </row>
- <row>
- <entry>
- ClientID
- </entry>
- <entry>String</entry>
- <entry>the pre-configured client ID for the connection factory</entry>
- </row>
- <row>
- <entry>
- ClientFailureCheckPeriod
- </entry>
- <entry>Long</entry>
- <entry>the period (in ms) after which the client will consider the
- connection failed after not receiving packets from the
- server</entry>
- </row>
- <row>
- <entry>
- UseGlobalPools
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not to use a global thread pool for threads</entry>
- </row>
- <row>
- <entry>
- ScheduledThreadPoolMaxSize
- </entry>
- <entry>Integer</entry>
- <entry>the size of the <emphasis>scheduled thread</emphasis> pool</entry>
- </row>
- <row>
- <entry>
- ThreadPoolMaxSize
- </entry>
- <entry>Integer</entry>
- <entry>the size of the thread pool</entry>
- </row>
- <row>
- <entry>SetupAttempts</entry>
- <entry>Integer</entry>
- <entry>Number of attempts to setup a JMS connection (default is 10, -1 means to attempt infinitely). It is possible
- that the MDB is deployed before the JMS resources are available. In that case, the resource
- adapter will try to setup several times until the resources are available. This applies only for inbound connections</entry>
- </row>
- <row>
- <entry>SetupInterval</entry>
- <entry>Long</entry>
- <entry>Interval in milliseconds between consecutive attempts to setup a JMS connection (default is 2000m). This applies only for inbound connections</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Adapter Outbound Configuration</title>
- <para>The outbound configuration should remain unchanged as they define connection
- factories that are used by Java EE components. These Connection Factories can be
- defined inside a configuration file that matches the name <literal
- >*-ds.xml</literal>. You'll find a default <literal>jms-ds.xml</literal>
- configuration under the <literal>activemq</literal> directory in the JBoss AS
- deployment. The connection factories defined in this file inherit their
- properties from the main <literal>ra.xml</literal> configuration but can also be
- overridden. The following example shows how to override them.</para>
- <note>
- <para>Please note that this configuration only applies when ActiveMQ resource adapter is installed in
- JBoss Application Server. If you are using another JEE application
- server please refer to your application servers documentation for how to do
- this.</para>
- </note>
- <programlisting>
-<tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>jms-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory
-</connection-definition>
-<config-property name="SessionDefaultType" type="String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="String">
- org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
- </config-property>
- <config-property name="ConnectionParameters" type="String">
- port=5445</config-property>
- <max-pool-size>20</max-pool-size>
-</tx-connection-factory></programlisting>
- <warning>
- <title>overriding connectors</title>
- <para>If the connector class name is overridden the all parameters must also be supplied.</para>
- </warning>
- <para>In this example the connection factory will be bound to JNDI with the name
- <literal>RemoteJmsXA</literal> and can be looked up in the usual way using JNDI
- or defined within the EJB or MDB as such:</para>
- <programlisting>
-@Resource(mappedName="java:/RemoteJmsXA")
-private ConnectionFactory connectionFactory;</programlisting>
- <para>The <literal>config-property</literal> elements are what overrides those in the
- <literal>ra.xml</literal> configuration file. Any of the elements pertaining to the
- connection factory can be overridden here.</para>
- <para>The outbound configuration also defines additional properties in addition to the global configuration properties.</para>
-
- <table frame="topbot" border="2">
- <title>Outbound Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>SessionDefaultType</entry>
- <entry>String</entry>
- <entry>the default session type</entry>
- </row>
- <row>
- <entry>UseTryLock</entry>
- <entry>Integer</entry>
- <entry>try to obtain a lock within specified number of seconds. less
- than or equal to 0 disable this functionality</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Adapter Inbound Configuration</title>
- <para>The inbound configuration should again remain unchanged. This controls what
- forwards messages onto MDBs. It is possible to override properties on the MDB by
- adding an activation configuration to the MDB itself. This could be used to
- configure the MDB to consume from a different server.</para>
- <para>The inbound configuration also defines additional properties in addition to the global configuration properties.</para>
-
- <table frame="topbot" border="2">
- <title>Inbound Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Destination</entry>
- <entry>String</entry>
- <entry>JNDI name of the destination</entry>
- </row>
- <row>
- <entry>DestinationType</entry>
- <entry>String</entry>
- <entry>type of the destination, either <literal>javax.jms.Queue</literal> or <literal>javax.jms.Topic</literal>
- (default is javax.jms.Queue)</entry>
- </row>
- <row>
- <entry>AcknowledgeMode</entry>
- <entry>String</entry>
- <entry>The Acknowledgment mode, either <literal>Auto-acknowledge</literal> or <literal>Dups-ok-acknowledge</literal>
- (default is Auto-acknowledge). <literal>AUTO_ACKNOWLEDGE</literal> and <literal>DUPS_OK_ACKNOWLEDGE</literal> are acceptable values.</entry>
- </row>
- <row>
- <entry>JndiParams</entry>
- <entry>String</entry>
- <entry>A semicolon (';') delimited string of name=value pairs which represent the properties to be used for the destination JNDI
- look up. The properties depends on the JNDI implementation of the server hosting ActiveMQ. Typically only be used when the MDB is
- configured to consume from a remote destination and needs to look up a JNDI reference rather than the ActiveMQ name of the
- destination. Only relevant when <literal>useJNDI</literal> is <literal>true</literal> (default is an empty string).</entry>
- </row>
- <row>
- <entry>MaxSession</entry>
- <entry>Integer</entry>
- <entry>Maximum number of session created by this inbound configuration (default is 15)</entry>
- </row>
- <row>
- <entry>MessageSelector</entry>
- <entry>String</entry>
- <entry>the message selector of the consumer</entry>
- </row>
- <row>
- <entry>SubscriptionDurability</entry>
- <entry>String</entry>
- <entry>Type of the subscription, either <literal>Durable</literal> or <literal>NonDurable</literal></entry>
- </row>
- <row>
- <entry>ShareSubscriptions</entry>
- <entry>Boolean</entry>
- <entry>When true, multiple MDBs can share the same <literal>Durable</literal> subscription</entry>
- </row>
- <row>
- <entry>SubscriptionName</entry>
- <entry>String</entry>
- <entry>Name of the subscription</entry>
- </row>
- <row>
- <entry>TransactionTimeout</entry>
- <entry>Long</entry>
- <entry>The transaction timeout in milliseconds (default is 0, the transaction does not timeout)</entry>
- </row>
- <row>
- <entry>UseJNDI</entry>
- <entry>Boolean</entry>
- <entry>Whether or not use JNDI to look up the destination (default is true)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- <section>
- <title>Configuring the adapter to use a standalone ActiveMQ Server</title>
- <para>Sometime you may want your messaging server on a different machine or separate from the application server.
- If this is the case you will only need the activemq client libs installed. This section explains what config to create
- and what jar dependencies are needed.</para>
- <section>
- <para>There are two configuration files needed to do this, one for the incoming adapter used for MDB's
- and one for outgoing connections managed by the JCA managed connection pool used by outgoing JEE components
- wanting outgoing connections.</para>
- <section>
- <title>Configuring the Incoming Adaptor</title>
- <para>Firstly you will need to create directory under the
- <literal>deploy</literal>
- directory ending in
- <literal>.rar.</literal>
- For this example we will name the directory <literal>activemq-ra.rar</literal>. This detail is
- important as
- the name of directory is referred to by the MDB's and the outgoing configuration.
-
- </para>
- <note>
- <para>The jboss default for this is <literal>jms-ra.rar</literal>, If you don't want to have to
- configure your
- MDB's you can use this but you may need to remove the generic adaptor that uses this.
- </para>
- </note>
- <para>Under the
- <literal>activemq-ra.rar</literal>
- directory you will need to create a
- <literal>META-INF</literal>
- directory into which you should create an
- <literal>ra.xml</literal>
- configuration file. You can find a template
- for the
- <literal>ra.xml</literal>
- under the config directory of the ActiveMQ distribution.
- </para>
- <para>To configure MDB's to consume messages from a remote ActiveMQ server you need to edit the
- <literal>ra.xml</literal>
- file under
- <literal>deploy/activemq-ra.rar/META-INF</literal>
- and change the transport type to
- use a netty connector (instead of the invm connector that is defined) and configure its transport
- parameters.
- Heres an example of what this would look like:
- </para>
- <programlisting>
-<resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>host=127.0.0.1;port=5446</config-property-value>
-</config-property></programlisting>
- <para>
- If you want to provide a list of servers that the adapter can connect to you can provide a list of
- connectors, each separated by a comma.
- </para>
-
- <programlisting>
-<resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory,org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>host=127.0.0.1;port=5446,host=127.0.0.2;port=5447</config-property-value>
-</config-property></programlisting>
- <warning>
- <title>provide all parameters</title>
- <para>
- Make sure you provide parameters for each connector configured. The position of the parameters in the
- list maps to each connector provided.
- </para>
- </warning>
- <para>This configures the resource adapter to connect to a server running on localhost listening on port
- 5446
- </para>
- </section>
-
- <section>
- <title>Configuring the outgoing adaptor</title>
- <para>You will also need to configure the outbound connection by creating a <literal>activemq-ds.xml</literal>
- and placing it under any directory that will be deployed under the <literal>deploy</literal> directory.
- In a standard ActiveMQ jboss configuration this would be under <literal>activemq</literal> or <literal>activemq.sar</literal>
- but you can place it where ever you like. Actually as long as it ends in <literal>-ds.xml</literal> you can
- call it anything you like. You can again find a template for this file under the config directory of the
- ActiveMQ distribution but called <literal>jms-ds.xml</literal> which is the jboss default.
- </para>
- <para>The following example shows a sample configuration</para>
- <programlisting>
-<tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>activemq-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
- <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
- <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446</config-property>
- <max-pool-size>20</max-pool-size>
-</tx-connection-factory></programlisting>
- <para>Again you will see that this uses the netty connector type and will connect to the ActiveMQ server
- running on localhost and listening on port 5446. JEE components can access this by using JNDI and looking
- up the connection factory using JNDI using <literal>java:/RemoteJmsXA</literal>, you can see that this
- is defined under the<literal>jndi-name</literal> attribute. You will also note that the outgoing connection
- will be created by the resource adaptor configured under the directory <literal>activemq-ra.rar</literal>
- as explained in the last section.
- </para>
- <para>
- Also if you want to configure multiple connectors do this as a comma separated list as in the ra configuration.
- </para>
- </section>
-
- <section>
- <title>Jar dependencies</title>
- <para>This is a list of the ActiveMQ and third party jars needed</para>
- <table frame="topbot" border="2">
- <title>Jar Dependencies</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Jar Name</entry>
- <entry>Description</entry>
- <entry>Location</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>activemq-ra.jar</entry>
- <entry>The ActiveMQ resource adaptor classes</entry>
- <entry>deploy/activemq-ra.rar or equivalent</entry>
- </row>
- <row>
- <entry>activemq-core-client.jar</entry>
- <entry>The ActiveMQ core client classes</entry>
- <entry>either in the config lib, i.e. default/lib or the common lib dir, i.e. $JBOSS_HOME/common lib </entry>
- </row>
- <row>
- <entry>activemq-jms-client.jar</entry>
- <entry>The ActiveMQ JMS classes</entry>
- <entry>as above</entry>
- </row>
- <row>
- <entry>netty.jar</entry>
- <entry>The Netty transport classes</entry>
- <entry>as above</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- </section>
- </section>
- </section>
- <section>
- <title>Configuring the JBoss Application Server to connect to Remote ActiveMQ Server</title>
- <para>This is a step by step guide on how to configure a JBoss application server that doesn't have ActiveMQ installed
- to use a remote instance of ActiveMQ</para>
- <section>
- <title>Configuring JBoss 5</title>
- <para>Firstly download and install JBoss AS 5 as per the JBoss installation guide and ActiveMQ as per the
- ActiveMQ installation guide. After that the following steps are required</para>
- <itemizedlist>
- <listitem>
- <para>Copy the following jars from the ActiveMQ distribution to the <literal>lib</literal> directory of
- which ever JBossAs configuration you have chosen, i.e. <literal>default</literal>.</para>
- <itemizedlist>
- <listitem>
- <para>activemq-core-client.jar</para>
- </listitem>
- <listitem>
- <para>activemq-jms-client.jar</para>
- </listitem>
- <listitem>
- <para>activemq-ra.jar (this can be found inside the <literal>activemq-ra.rar</literal> archive)</para>
- </listitem>
- <listitem>
- <para>netty.jar</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>create the directories <literal>activemq-ra.rar</literal> and <literal>activemq-ra.rar/META-INF</literal>
- under the <literal>deploy</literal> directory in your JBoss config directory</para>
- </listitem>
- <listitem>
- <para>under the <literal>activemq-ra.rar/META-INF</literal> create a <literal>ra.xml</literal> file or
- copy it from the ActiveMQ distribution (again it can be found in the <literal>activemq-ra.rar</literal> archive)
- and configure it as follows</para>
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-
-<connector xmlns="http://java.sun.com/xml/ns/j2ee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
- version="1.5">
-
- <description>ActiveMQ 2.0 Resource Adapter Alternate Configuration</description>
- <display-name>ActiveMQ 2.0 Resource Adapter Alternate Configuration</display-name>
-
- <vendor-name>Red Hat Middleware LLC</vendor-name>
- <eis-type>JMS 1.1 Server</eis-type>
- <resourceadapter-version>1.0</resourceadapter-version>
-
- <license>
- <description>
-Copyright 2009 Red Hat, Inc.
- Red Hat 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.
- </description>
- <license-required>true</license-required>
- </license>
-
- <resourceadapter>
- <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <emphasis role="bold"> <config-property-value>host=127.0.0.1;port=5445</config-property-value></emphasis>
- </config-property>
-
- <outbound-resourceadapter>
- <connection-definition>
- <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnectionFactory</managedconnectionfactory-class>
-
- <config-property>
- <description>The default session type</description>
- <config-property-name>SessionDefaultType</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>javax.jms.Queue</config-property-value>
- </config-property>
- <config-property>
- <description>Try to obtain a lock within specified number of seconds; less than or equal to 0 disable this functionality</description>
- <config-property-name>UseTryLock</config-property-name>
- <config-property-type>java.lang.Integer</config-property-type>
- <config-property-value>0</config-property-value>
- </config-property>
-
- <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connectionfactory-interface>
- <connectionfactory-impl-class>org.apache.activemq.ra.ActiveMQRAConnectionFactoryImpl</connectionfactory-impl-class>
- <connection-interface>javax.jms.Session</connection-interface>
- <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession</connection-impl-class>
- </connection-definition>
- <transaction-support>XATransaction</transaction-support>
- <authentication-mechanism>
- <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
- <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
- </authentication-mechanism>
- <reauthentication-support>false</reauthentication-support>
- </outbound-resourceadapter>
-
- <inbound-resourceadapter>
- <messageadapter>
- <messagelistener>
- <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
- <activationspec>
- <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec</activationspec-class>
- <required-config-property>
- <config-property-name>destination</config-property-name>
- </required-config-property>
- </activationspec>
- </messagelistener>
- </messageadapter>
- </inbound-resourceadapter>
-
- </resourceadapter>
-</connector></programlisting>
- <para>The important part of this configuration is the part in bold, i.e. <config-property-value>host=127.0.0.1;port=5445</config-property-value>.
- This should be configured to the host and port of the remote ActiveMQ server.</para>
- </listitem>
- </itemizedlist>
- <para>At this point you should be able to now deploy MDB's that consume from the remote server. You will however,
- have to make sure that your MDB's have the annotation <literal>@ResourceAdapter("activemq-ra.rar")</literal>
- added, this is illustrated in the <xref linkend="configuring-mdbs">Configuring Message-Driven Beans</xref> section.
- If you don't want to add this annotation then you can delete the generic resource adapter <literal>jms-ra.rar</literal>
- and rename the <literal>activemq-ra.rar</literal> to this.</para>
- <para>If you also want to use the remote ActiveMQ server for outgoing connections, i.e. sending messages, then
- do the following:</para>
- <itemizedlist>
- <listitem>
- <para>Create a file called <literal>activemq-ds.xml</literal> in the <literal>deploy</literal> directory
- (in fact you can call this anything you want as long as it ends in <literal>-ds.xml</literal>). Then
- add the following:</para>
- <programlisting>
-<connection-factories>
- <!--
- JMS XA Resource adapter, use this for outbound JMS connections.
- Inbound connections are defined at the @MDB activation or at the resource-adapter properties.
- -->
- <tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>activemq-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
- <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
- <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5445</config-property>
- <max-pool-size>20</max-pool-size>
- </tx-connection-factory>
-
-
-</connection-factories></programlisting>
- <para>Again you will see that the host and port are configured here to match the remote ActiveMQ servers
- configuration. The other important attributes are:</para>
- <itemizedlist>
- <listitem>
- <para>jndi-name - This is the name used to look up the JMS connection factory from within your JEE client</para>
- </listitem>
- <listitem>
- <para>rar-name - This should match the directory that you created to hold the Resource Adapter
- configuration</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>Now you should be able to send messages using the JCA JMS connection pooling within an XA transaction.</para>
- </section>
- <section>
- <title>Configuring JBoss 5</title>
- <para>The steps to do this are exactly the same as for JBoss 4, you will have to create a jboss.xml definition
- file for your MDB with the following entry</para>
- <programlisting>
-<message-driven>
- <ejb-name>MyMDB</ejb-name>
- <resource-adapter-name>jms-ra.rar</resource-adapter-name>
- </message-driven></programlisting>
- <para>Also you will need to edit the <literal>standardjboss.xml</literal> and uncomment the section with the
- following 'Uncomment to use JMS message inflow from jmsra.rar' and then comment out the invoker-proxy-binding
- called 'message-driven-bean'</para>
- </section>
- </section>
- <section>
- <title>High Availability JNDI (HA-JNDI)</title>
- <para>If you are using JNDI to look-up JMS queues, topics and connection factories from a
- cluster of servers, it is likely you will want to use HA-JNDI so that your JNDI look-ups
- will continue to work if one or more of the servers in the cluster fail.</para>
- <para>HA-JNDI is a JBoss Application Server service which allows you to use JNDI from
- clients without them having to know the exact JNDI connection details of every server in
- the cluster. This service is only available if using a cluster of JBoss Application
- Server instances.</para>
- <para>To use it use the following properties when connecting to JNDI.</para>
- <programlisting>
-Hashtable<String, String> jndiParameters = new Hashtable<String, String>();
-jndiParameters.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
-jndiParameters.put("java.naming.factory.url.pkgs=", "org.jboss.naming:org.jnp.interfaces");
-
-initialContext = new InitialContext(jndiParameters);</programlisting>
- <para>For more information on using HA-JNDI see the <ulink
- url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html"
- >JBoss Application Server clustering documentation</ulink></para>
- </section>
- <section id="xa-recovery">
- <title>XA Recovery</title>
- <para><emphasis>XA recovery</emphasis> deals with system or application failures to ensure
- that of a transaction are applied consistently to all resources affected by the
- transaction, even if any of the application processes or the machine hosting them crash
- or lose network connectivity. For more information on XA Recovery,please refer to <ulink
- url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
- Transactions</ulink>.</para>
- <para>When ActiveMQ is integrated with JBoss AS, it can take advantage of JBoss Transactions
- to provide recovery of messaging resources. If messages are involved in a XA
- transaction, in the event of a server crash, the recovery manager will ensure that the
- transactions are recovered and the messages will either be committed or rolled back
- (depending on the transaction outcome) when the server is restarted.</para>
- <section>
- <title>XA Recovery Configuration</title>
- <para>To enable ActiveMQ's XA Recovery, the Recovery Manager must be configured to connect
- to ActiveMQ to recover its resources. The following property must be added to the
- <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal>
- of JBoss AS profiles:</para>
- <programlisting>
-<properties depends="arjuna" name="jta">
- ...
-
- <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ActiveMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;[connection configuration]"/>
- <property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
-</properties></programlisting>
- <para>The <literal>[connection configuration]</literal> contains all the information
- required to connect to ActiveMQ node under the form <literal>[connector factory class
- name],[user name], [password], [connector parameters]</literal>. </para>
- <itemizedlist>
- <listitem>
- <para><literal>[connector factory class name]</literal> corresponds to the name
- of the <literal>ConnectorFactory</literal> used to connect to ActiveMQ.
- Values can be <literal
- >org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</literal> or
- <literal
- >org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</literal></para>
- </listitem>
- <listitem>
- <para><literal>[user name]</literal> is the user name to create a client
- session. It is optional</para>
- </listitem>
- <listitem>
- <para><literal>[password]</literal> is the password to create a client session.
- It is mandatory only if the user name is specified</para>
- </listitem>
- <listitem>
- <para><literal>[connector parameters]</literal> is a list of comma-separated
- key=value pair which are passed to the connector factory (see <xref
- linkend="configuring-transports"/> for a list of the transport
- parameters).</para>
- </listitem>
- </itemizedlist>
- <para>Also note the <literal>com.arjuna.ats.jta.xaRecoveryNode</literal> parameter. If you want recovery
- enabled then this must be configured to what ever the tx node id is set to, this is configured in the
- same file by the <literal>com.arjuna.ats.arjuna.xa.nodeIdentifier</literal> property.</para>
- <note>
- <para>ActiveMQ must have a valid acceptor which corresponds to the connector
- specified in <literal>conf/jbossts-properties.xml</literal>.</para>
- </note>
- <section>
- <title>Configuration Settings</title>
- <para>If ActiveMQ is configured with a default in-vm acceptor:</para>
- <programlisting>
-<acceptor name="in-vm">
- <factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory</factory-class>
-</acceptor></programlisting>
- <para>the corresponding configuration in <literal
- >conf/jbossts-properties.xml</literal> is:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory"/></programlisting>
- <para>If it is now configured with a netty acceptor on a non-default port:</para>
- <programlisting>
-<acceptor name="netty">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
- <param key="port" value="8888"/>
-</acceptor></programlisting>
- <para>the corresponding configuration in <literal
- >conf/jbossts-properties.xml</literal> is:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/></programlisting>
- <note>
- <para>Note the additional commas to skip the user and password before connector
- parameters</para>
- </note>
- <para>If the recovery must use <literal>admin, adminpass</literal>, the
- configuration would have been:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/></programlisting>
- <para>Configuring ActiveMQ with an invm acceptor and configuring the Recovery Manager
- with an invm connector is the recommended way to enable XA Recovery.</para>
- </section>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="xa-recovery-example"/> which shows how to configure XA Recovery
- and recover messages after a server crash.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/architecture.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md
new file mode 100644
index 0000000..fe0eb7f
--- /dev/null
+++ b/docs/user-manual/en/architecture.md
@@ -0,0 +1,159 @@
+Architecture
+============
+
+In this section we will give an overview of the ActiveMQ high level
+architecture.
+
+Core Architecture
+=================
+
+ActiveMQ core is designed simply as set of Plain Old Java Objects
+(POJOs) - we hope you like its clean-cut design.
+
+We've also designed it to have as few dependencies on external jars as
+possible. In fact, ActiveMQ core has only one jar dependency, netty.jar,
+other than the standard JDK classes! This is because we use some of the
+netty buffer classes internally.
+
+This allows ActiveMQ to be easily embedded in your own project, or
+instantiated in any dependency injection framework such as JBoss
+Microcontainer, Spring or Google Guice.
+
+Each ActiveMQ server has its own ultra high performance persistent
+journal, which it uses for message and other persistence.
+
+Using a high performance journal allows outrageous persistence message
+performance, something not achievable when using a relational database
+for persistence.
+
+ActiveMQ clients, potentially on different physical machines interact
+with the ActiveMQ server. ActiveMQ currently provides two APIs for
+messaging at the client side:
+
+1. Core client API. This is a simple intuitive Java API that allows the
+ full set of messaging functionality without some of the complexities
+ of JMS.
+
+2. JMS client API. The standard JMS API is available at the client
+ side.
+
+JMS semantics are implemented by a thin JMS facade layer on the client
+side.
+
+The ActiveMQ server does not speak JMS and in fact does not know
+anything about JMS, it is a protocol agnostic messaging server designed
+to be used with multiple different protocols.
+
+When a user uses the JMS API on the client side, all JMS interactions
+are translated into operations on the ActiveMQ core client API before
+being transferred over the wire using the ActiveMQ wire format.
+
+The server always just deals with core API interactions.
+
+A schematic illustrating this relationship is shown in figure 3.1 below:
+
+
+
+Figure 3.1 shows two user applications interacting with a ActiveMQ
+server. User Application 1 is using the JMS API, while User Application
+2 is using the core client API directly.
+
+You can see from the diagram that the JMS API is implemented by a thin
+facade layer on the client side.
+
+ActiveMQ embedded in your own application
+=========================================
+
+ActiveMQ core is designed as a set of simple POJOs so if you have an
+application that requires messaging functionality internally but you
+don't want to expose that as a ActiveMQ server you can directly
+instantiate and embed ActiveMQ servers in your own application.
+
+For more information on embedding ActiveMQ, see ?.
+
+ActiveMQ integrated with a JEE application server
+=================================================
+
+ActiveMQ provides its own fully functional Java Connector Architecture
+(JCA) adaptor which enables it to be integrated easily into any JEE
+compliant application server or servlet engine.
+
+JEE application servers provide Message Driven Beans (MDBs), which are a
+special type of Enterprise Java Beans (EJBs) that can process messages
+from sources such as JMS systems or mail systems.
+
+Probably the most common use of an MDB is to consume messages from a JMS
+messaging system.
+
+According to the JEE specification, a JEE application server uses a JCA
+adapter to integrate with a JMS messaging system so it can consume
+messages for MDBs.
+
+However, the JCA adapter is not only used by the JEE application server
+for *consuming* messages via MDBs, it is also used when sending message
+to the JMS messaging system e.g. from inside an EJB or servlet.
+
+When integrating with a JMS messaging system from inside a JEE
+application server it is always recommended that this is done via a JCA
+adaptor. In fact, communicating with a JMS messaging system directly,
+without using JCA would be illegal according to the JEE specification.
+
+The application server's JCA service provides extra functionality such
+as connection pooling and automatic transaction enlistment, which are
+desirable when using messaging, say, from inside an EJB. It is possible
+to talk to a JMS messaging system directly from an EJB, MDB or servlet
+without going through a JCA adapter, but this is not recommended since
+you will not be able to take advantage of the JCA features, such as
+caching of JMS sessions, which can result in poor performance.
+
+Figure 3.2 below shows a JEE application server integrating with a
+ActiveMQ server via the ActiveMQ JCA adaptor. Note that all
+communication between EJB sessions or entity beans and Message Driven
+beans go through the adaptor and not directly to ActiveMQ.
+
+The large arrow with the prohibited sign shows an EJB session bean
+talking directly to the ActiveMQ server. This is not recommended as
+you'll most likely end up creating a new connection and session every
+time you want to interact from the EJB, which is an anti-pattern.
+
+
+
+For more information on using the JCA adaptor, please see ?.
+
+ActiveMQ stand-alone server
+===========================
+
+ActiveMQ can also be deployed as a stand-alone server. This means a
+fully independent messaging server not dependent on a JEE application
+server.
+
+The standard stand-alone messaging server configuration comprises a core
+messaging server, a JMS service and a JNDI service.
+
+The role of the JMS Service is to deploy any JMS Queue, Topic and
+ConnectionFactory instances from any server side `activemq-jms.xml`
+configuration files. It also provides a simple management API for
+creating and destroying Queues, Topics and ConnectionFactory instances
+which can be accessed via JMX or the connection. It is a separate
+service to the ActiveMQ core server, since the core server is JMS
+agnostic. If you don't want to deploy any JMS Queue, Topic or
+ConnectionFactory instances via server side XML configuration and don't
+require a JMS management API on the server side then you can disable
+this service.
+
+We also include a JNDI server since JNDI is a common requirement when
+using JMS to lookup Queues, Topics and ConnectionFactory instances. If
+you do not require JNDI then this service can also be disabled. ActiveMQ
+allows you to programmatically create JMS and core objects directly on
+the client side as opposed to looking them up from JNDI, so a JNDI
+server is not always a requirement.
+
+The stand-alone server configuration uses JBoss Microcontainer to
+instantiate and enforce dependencies between the components. JBoss
+Microcontainer is a very lightweight POJO bootstrapper.
+
+The stand-alone server architecture is shown in figure 3.3 below:
+
+
+
+For more information on server configuration files see ?. \$
[05/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/rest.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/rest.xml b/docs/user-manual/en/rest.xml
deleted file mode 100644
index 10165e4..0000000
--- a/docs/user-manual/en/rest.xml
+++ /dev/null
@@ -1,2150 +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. -->
-<!-- ============================================================================= -->
-<chapter id="rest">
- <title>REST Interface</title>
-
- <para>The ActiveMQ REST interface allows you to leverage the reliability
- and scalability features of ActiveMQ over a simple REST/HTTP interface.
- Messages are produced and consumed by sending and receiving simple HTTP
- messages that contain the content you want to push around. For instance,
- here's a simple example of posting an order to an order processing queue
- express as an HTTP message:
- </para>
-
- <programlisting>
-POST /queue/orders/create HTTP/1.1
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone 4</item>
- <cost>$199.99</cost>
-</order></programlisting>
-
- <para>As you can see, we're just posting some arbitrary XML
- document to a URL. When the XML is received on the server is it processed
- within ActiveMQ as a JMS message and distributed through core ActiveMQ.
- Simple and easy. Consuming messages from a queue or topic looks very
- similar. We'll discuss the entire interface in detail later in this
- docbook.
- </para>
-
- <section>
- <title>Goals of REST Interface</title>
-
- <para>Why would you want to use ActiveMQ's REST interface? What are the
- goals of the REST interface?
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Easily usable by machine-based (code) clients.</para>
- </listitem>
-
- <listitem>
- <para>Zero client footprint. We want ActiveMQ to be usable by any
- client/programming language that has an adequate HTTP client
- library. You shouldn't have to download, install, and configure a
- special library to interact with ActiveMQ.
- </para>
- </listitem>
-
- <listitem>
- <para>Lightweight interoperability. The HTTP protocol is strong
- enough to be our message exchange protocol. Since interactions are
- RESTful the HTTP uniform interface provides all the interoperability
- you need to communicate between different languages, platforms, and
- even messaging implementations that choose to implement the same
- RESTful interface as ActiveMQ (i.e. the
- <ulink url="http://rest-star.org">REST-*</ulink> effort.)
- </para>
- </listitem>
-
- <listitem>
- <para>No envelope (e.g. SOAP) or feed (e.g. Atom) format
- requirements. You shouldn't have to learn, use, or parse a specific
- XML document format in order to send and receive messages through
- ActiveMQ's REST interface.
- </para>
- </listitem>
-
- <listitem>
- <para>Leverage the reliability, scalability, and clustering features
- of ActiveMQ on the back end without sacrificing the simplicity of a
- REST interface.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
-
- <section id="install">
- <title>Installation and Configuration</title>
-
- <para>ActiveMQ's REST interface is installed as a Web archive (WAR). It
- depends on the
- <ulink url="http://jboss.org/resteasy">RESTEasy</ulink>
- project and can currently only run within a servlet container. Installing
- the ActiveMQ REST interface is a little bit different depending whether
- ActiveMQ is already installed and configured for your environment (e.g.
- you're deploying within JBoss AS 7) or you want the ActiveMQ REST
- WAR to startup and manage the ActiveMQ server (e.g. you're deploying
- within something like Apache Tomcat).
- </para>
-
- <section>
- <title>Installing Within Pre-configured Environment</title>
-
- <para>This section should be used when you want to use the ActiveMQ REST
- interface in an environment that already has ActiveMQ installed and
- running, e.g. JBoss AS 7. You must create a Web archive
- (.WAR) file with the following web.xml settings:
- </para>
-
- <programlisting>
-<web-app>
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.rest.integration.RestMessagingBootstrapListener
- </listener-class>
- </listener>
-
- <filter>
- <filter-name>Rest-Messaging</filter-name>
- <filter-class>
- org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
- </filter-class>
- </filter>
-
- <filter-mapping>
- <filter-name>Rest-Messaging</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
-</web-app></programlisting>
-
- <para>Within your WEB-INF/lib directory you must have the
- activemq-rest.jar file. If RESTEasy is not installed within your
- environment, you must add the RESTEasy jar files within the lib
- directory as well. Here's a sample Maven pom.xml that can build your WAR
- for this case.
- </para>
-
- <programlisting>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.somebody</groupId>
- <artifactId>myapp</artifactId>
- <packaging>war</packaging>
- <name>My App</name>
- <version>0.1-SNAPSHOT</version>
- <repositories>
- <repository>
- <id>jboss</id>
- <url>http://repository.jboss.org/nexus/content/groups/public/</url>
- </repository>
- </repositories>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.6</source>
- <target>1.6</target>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.activemq.rest</groupId>
- <artifactId>activemq-rest</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- </dependencies>
-</project></programlisting>
-
- <note>
- <para>JBoss AS 7 loads classes differently than previous versions.
- To work properly in AS 7 the WAR will need this in its MANIFEST.MF:
- </para>
- <programlisting>Dependencies: org.apache.activemq, org.jboss.netty</programlisting>
- <para>You can add this to the<literal><plugins></literal>
- section of the pom.xml to create this entry automatically:
- </para>
- <programlisting>
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-war-plugin</artifactId>
- <configuration>
- <archive>
- <manifestEntries>
- <Dependencies>org.apache.activemq, org.jboss.netty</Dependencies>
- </manifestEntries>
- </archive>
- </configuration>
-</plugin></programlisting>
- </note>
-
- <para>
- It is worth noting that when deploying a WAR in a Java EE application server
- like AS7 the URL for the resulting application will include the name of the
- WAR by default. For example, if you've constructed a WAR as described above
- named "activemq-rest.war" then clients will access it at, e.g.
- http://localhost:8080/activemq-rest/[queues|topics]. We'll see more about
- this later.
- </para>
- <note>
- <para>
- It is possible to put the WAR file at the "root context" of AS7, but
- that is beyond the scope of this documentation.
- </para>
- </note>
- </section>
-
- <section>
- <title>Bootstrapping ActiveMQ Along with REST</title>
-
- <para>You can bootstrap ActiveMQ within your WAR as well. To do this, you
- must have the ActiveMQ core and JMS jars along with Netty, Resteasy, and
- the ActiveMQ REST jar within your WEB-INF/lib. You must also have a
- activemq-configuration.xml, activemq-jms.xml, and activemq-users.xml config
- files within WEB-INF/classes. The examples that come with the ActiveMQ
- REST distribution show how to do this. You must also add an additional
- listener to your web.xml file. Here's an example:
- </para>
-
- <programlisting>
-<web-app>
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.rest.integration.ActiveMQBootstrapListener
- </listener-class>
- </listener>
-
- <listener>
- <listener-class>
- org.apache.activemq.rest.integration.RestMessagingBootstrapListener
- </listener-class>
- </listener>
-
- <filter>
- <filter-name>Rest-Messaging</filter-name>
- <filter-class>
- org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
- </filter-class>
- </filter>
-
- <filter-mapping>
- <filter-name>Rest-Messaging</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
-</web-app></programlisting>
-
- <para>Here's a Maven pom.xml file for creating a WAR for this
- environment. Make sure your activemq configuration files are within the
- src/main/resources directory so that they are stuffed within the WAR's
- WEB-INF/classes directory!
- </para>
-
- <programlisting>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.somebody</groupId>
- <artifactId>myapp</artifactId>
- <packaging>war</packaging>
- <name>My App</name>
- <version>0.1-SNAPSHOT</version>
- <repositories>
- <repository>
- <id>jboss</id>
- <url>http://repository.jboss.org/nexus/content/groups/public/</url>
- </repository>
- </repositories>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.6</source>
- <target>1.6</target>
- </configuration>
- </plugin>
- </plugins>
- </build>
- <dependencies>
- <dependency>
- <groupId>org.apache.activemq</groupId>
- <artifactId>activemq-core</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- <dependency>
- <groupId>io.netty</groupId>
- <artifactId>netty</artifactId>
- <version>3.4.5.Final</version>
- </dependency>
- <dependency>
- <groupId>org.apache.activemq</groupId>
- <artifactId>activemq-jms</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- <dependency>
- <groupId>org.jboss.spec.javax.jms</groupId>
- <artifactId>jboss-jms-api_2.0_spec</artifactId>
- <version>1.0.0.Final</version>
- </dependency>
- <dependency>
- <groupId>org.apache.activemq.rest</groupId>
- <artifactId>activemq-rest</artifactId>
- <version>2.3.0-SNAPSHOT</version>
- </dependency>
- <dependency>
- <groupId>org.jboss.resteasy</groupId>
- <artifactId>resteasy-jaxrs</artifactId>
- <version>2.3.4.Final</version>
- </dependency>
- <dependency>
- <groupId>org.jboss.resteasy</groupId>
- <artifactId>resteasy-jaxb-provider</artifactId>
- <version>2.3.4.Final</version>
- </dependency>
- </dependencies>
-</project></programlisting>
- </section>
-
- <section id="configuration">
- <title>REST Configuration</title>
-
- <para>The ActiveMQ REST implementation does have some configuration
- options. These are configured via XML configuration file that must be in
- your WEB-INF/classes directory. You must set the web.xml context-param
- <literal>rest.messaging.config.file</literal> to specify the name of the
- configuration file. Below is the format of the XML configuration file
- and the default values for each.
- </para>
-
- <programlisting>
-<rest-messaging>
- <server-in-vm-id>0</server-in-vm-id>
- <use-link-headers>false</use-link-headers>
- <default-durable-send>false</default-durable-send>
- <dups-ok>true</dups-ok>
- <topic-push-store-dir>topic-push-store</topic-push-store-dir>
- <queue-push-store-dir>queue-push-store</queue-push-store-dir>
- <producer-time-to-live>0</producer-time-to-live>
- <producer-session-pool-size>10</producer-session-pool-size>
- <session-timeout-task-interval>1</session-timeout-task-interval>
- <consumer-session-timeout-seconds>300</consumer-session-timeout-seconds>
- <consumer-window-size>-1</consumer-window-size>
-</rest-messaging></programlisting>
-
- <para>Let's give an explanation of each config option.</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>server-in-vm-id</literal>. The ActiveMQ REST
- impl uses the IN-VM transport to communicate with ActiveMQ.
- It uses the default server id, which is "0".
- </para>
- </listitem>
- <listitem>
- <para><literal>use-link-headers</literal>. By default, all
- links (URLs) are published using custom headers. You can
- instead have the ActiveMQ REST implementation publish links
- using the <ulink url="http://tools.ietf.org/html/draft-nottingham-http-link-header-10">
- Link Header specification
- </ulink> instead if you desire.
- </para>
- </listitem>
- <listitem>
- <para><literal>default-durable-send</literal>. Whether a posted
- message should be persisted by default if the user does not
- specify a durable query parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>dups-ok</literal>. If this is true, no duplicate
- detection protocol will be enforced for message posting.
- </para>
- </listitem>
- <listitem>
- <para><literal>topic-push-store-dir</literal>. This must be
- a relative or absolute file system path. This is a directory
- where push registrations for topics are stored. See
- <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>queue-push-store-dir</literal>. This must be
- a relative or absolute file system path. This is a
- directory where push registrations for queues are stored.
- See <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>producer-session-pool-size</literal>. The REST
- implementation pools ActiveMQ sessions for sending messages.
- This is the size of the pool. That number of sessions will
- be created at startup time.
- </para>
- </listitem>
- <listitem>
- <para><literal>producer-time-to-live</literal>. Default time
- to live for posted messages. Default is no ttl.
- </para>
- </listitem>
- <listitem>
- <para><literal>session-timeout-task-interval</literal>. Pull
- consumers and pull subscriptions can time out. This is
- the interval the thread that checks for timed-out sessions
- will run at. A value of 1 means it will run every 1 second.
- </para>
- </listitem>
- <listitem>
- <para><literal>consumer-session-timeout-seconds</literal>.
- Timeout in seconds for pull consumers/subscriptions that
- remain idle for that amount of time.
- </para>
- </listitem>
- <listitem>
- <para><literal>consumer-window-size</literal>. For consumers,
- this config option is the same as the ActiveMQ one of the
- same name. It will be used by sessions created by the
- ActiveMQ REST implementation.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
-
- <section id="basics">
- <title>ActiveMQ REST Interface Basics</title>
-
- <para>The ActiveMQ REST interface publishes a variety of REST resources to
- perform various tasks on a queue or topic. Only the top-level queue and
- topic URI schemes are published to the outside world. You must discover
- all over resources to interact with by looking for and traversing links.
- You'll find published links within custom response headers and embedded in
- published XML representations. Let's look at how this works.
- </para>
-
- <section>
- <title>Queue and Topic Resources</title>
-
- <para>To interact with a queue or topic you do a HEAD or GET request on
- the following relative URI pattern:
- </para>
-
- <programlisting>
-/queues/{name}
-/topics/{name}</programlisting>
-
- <para>The base of the URI is the base URL of the WAR you deployed the
- ActiveMQ REST server within as defined in the
- <link linkend="install">Installation and Configuration</link>
- section of this document. Replace the <literal>{name}</literal>
- string within the above URI pattern with the name of the queue or
- topic you are interested in interacting with. For example if you
- have configured a JMS topic named "foo" within your
- <literal>activemq-jms.xml</literal> file, the URI name should be
- "jms.topic.foo". If you have configured a JMS queue name "bar" within
- your <literal>activemq-jms.xml</literal> file, the URI name should be
- "jms.queue.bar". Internally, ActiveMQ prepends the "jms.topic" or
- "jms.queue" strings to the name of the deployed destination. Next,
- perform your HEAD or GET request on this URI. Here's what a
- request/response would look like.
- </para>
-
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
-msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
-msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers</programlisting>
-
- <note>
- <para>
- You can use the "curl" utility to test this easily. Simply execute
- a command like this:
- </para>
-
- <programlisting>
-curl --head http://example.com/queues/jms.queue.bar</programlisting>
- </note>
-
- <para>The HEAD or GET response contains a number of custom response
- headers that are URLs to additional REST resources that allow you to
- interact with the queue or topic in different ways. It is important not
- to rely on the scheme of the URLs returned within these headers as they
- are an implementation detail. Treat them as opaque and query for them
- each and every time you initially interact (at boot time) with the
- server. If you treat all URLs as opaque then you will be isolated from
- implementation changes as the ActiveMQ REST interface evolves over
- time.
- </para>
- </section>
-
- <section>
- <title>Queue Resource Response Headers</title>
-
- <para>Below is a list of response headers you should expect when
- interacting with a Queue resource.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-create</literal>. This is a URL you POST messages
- to. The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-create-with-id</literal>. This is a URL
- <emphasis>template</emphasis> you can use to POST messages.
- The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. This is a URL for
- creating consumers that will pull from a queue. The semantics
- of this link are described in
- <link linkend="message-pull">Consuming Messages via Pull</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-push-consumers</literal>. This is a URL for
- registering other URLs you want the ActiveMQ REST server to
- push messages to. The semantics of this link are described
- in <link linkend="message-push">Pushing Messages</link>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Topic Resource Response Headers</title>
-
- <para>Below is a list of response headers you should expect when
- interacting with a Topic resource.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-create</literal>. This is a URL you POST
- messages to. The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-create-with-id</literal>. This is a URL
- <emphasis>template</emphasis> you can use to POST messages.
- The semantics of this link are described in
- <link linkend="posting-messages">Posting Messages</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. This is a
- URL for creating subscribers that will pull from a topic.
- The semantics of this link are described in
- <link linkend="message-pull">Consuming Messages via Pull</link>.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-push-subscriptions</literal>. This is a
- URL for registering other URLs you want the ActiveMQ REST
- server to push messages to. The semantics of this link
- are described in <link linkend="message-push">Pushing
- Messages</link>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
-
- <section id="posting-messages">
- <title>Posting Messages</title>
-
- <para>This chapter discusses the protocol for posting messages to a queue
- or a topic. In <link linkend="basics">ActiveMQ REST Interface Basics</link>,
- you saw that a queue or topic resource publishes variable custom headers
- that are links to other RESTful resources. The <literal>msg-create</literal>
- header is a URL you can post a message to. Messages are published to a queue
- or topic by sending a simple HTTP message to the URL published by the
- <literal>msg-create</literal> header. The HTTP message contains whatever
- content you want to publish to the ActiveMQ destination. Here's an example
- scenario:
- </para>
-
- <note>
- <para>You can also post messages to the URL template found in
- <literal>msg-create-with-id</literal>, but this is a more advanced
- use-case involving duplicate detection that we will discuss later in
- this section.
- </para>
- </note>
-
- <orderedlist>
- <listitem>
- <para>Obtain the starting <literal>msg-create</literal> header from
- the queue or topic resource.
- </para>
-
- <para>
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>Do a POST to the URL contained in the <literal>msg-create</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response ---
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create</programlisting>
-
- <note>
- <para>You can use the "curl" utility to test this easily. Simply execute
- a command like this:
- </para>
- <programlisting>
-curl --verbose --data "123" http://example.com/queues/jms.queue.bar/create</programlisting>
- </note>
-
- <para>A successful response will return a 201 response code. Also
- notice that a <literal>msg-create-next</literal> response header
- is sent as well. You must use this URL to POST your next message.
- </para>
- </listitem>
-
- <listitem>
- <para>POST your next message to the queue using the URL returned in
- the <literal>msg-create-next</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Monica</name>
- <item>iPad</item>
- <cost>$499.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create</programlisting>
- <para>Continue using the new <literal>msg-create-next</literal>
- header returned with each response.
- </para>
- </listitem>
- </orderedlist>
-
- <warning>
- <para>It is <emphasis>VERY IMPORTANT</emphasis> that you never re-use returned
- <literal>msg-create-next</literal> headers to post new messages. If the
- <literal>dups-ok</literal> configuration property is set to
- <literal>false</literal> on the server then this URL will be uniquely
- generated for each message and used for duplicate detection. If you lose
- the URL within the <literal>msg-create-next</literal> header, then just
- go back to the queue or topic resource to get the
- <literal>msg-create</literal> URL again.
- </para>
- </warning>
-
- <section>
- <title>Duplicate Detection</title>
-
- <para>Sometimes you might have network problems when posting new
- messages to a queue or topic. You may do a POST and never receive a
- response. Unfortunately, you don't know whether or not the server
- received the message and so a re-post of the message might cause
- duplicates to be posted to the queue or topic. By default, the ActiveMQ
- REST interface is configured to accept and post duplicate messages. You
- can change this by turning on duplicate message detection by setting the
- <literal>dups-ok</literal> config option to <literal>false</literal>
- as described in <link linkend="basics">ActiveMQ REST Interface Basics</link>.
- When you do this, the initial POST to the <literal>msg-create</literal>
- URL will redirect you, using the standard HTTP 307 redirection mechanism
- to a unique URL to POST to. All other interactions remain the same as
- discussed earlier. Here's an example:
- </para>
-
- <orderedlist>
- <listitem>
- <para>Obtain the starting <literal>msg-create</literal> header from
- the queue or topic resource.
- </para>
-
- <para>
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>Do a POST to the URL contained in the <literal>msg-create</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response ---
-HTTP/1.1 307 Redirect
-Location: http://example.com/queues/jms.queue.bar/create/13582001787372</programlisting>
-
- <para>A successful response will return a 307 response code. This
- is standard HTTP protocol. It is telling you that you must re-POST
- to the URL contained within the <literal>Location</literal>
- header.
- </para>
- </listitem>
-
- <listitem>
- <para>re-POST your message to the URL provided within the
- <literal>Location</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create/13582001787372
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</name>
- <cost>$199.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787373</programlisting>
- <para>You should receive a 201 Created response. If there is a
- network failure, just re-POST to the Location header. For new
- messages, use the returned <literal>msg-create-next</literal>
- header returned with each response.
- </para>
- </listitem>
-
- <listitem>
- <para>POST any new message to the returned
- <literal>msg-create-next</literal> header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create/13582001787373
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Monica</name>
- <item>iPad</name>
- <cost>$499.99</cost>
-</order>
-
---- Response --
-HTTP/1.1 201 Created
-msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374</programlisting>
- <para>If there ever is a network problem, just repost to the URL
- provided in the <literal>msg-create-next</literal> header.
- </para>
- </listitem>
- </orderedlist>
-
- <para>How can this work? As you can see, with each successful response,
- the ActiveMQ REST server returns a uniquely generated URL within the
- msg-create-next header. This URL is dedicated to the next new message
- you want to post. Behind the scenes, the code extracts an identify from
- the URL and uses ActiveMQ's duplicate detection mechanism by setting the
- <literal>DUPLICATE_DETECTION_ID</literal> property of the JMS message
- that is actually posted to the system.
- </para>
-
- <para>If you happen to use the same ID more than once you'll see a message
- like this on the server:
- </para>
- <programlisting>
-WARN [org.apache.activemq.core.server] (Thread-3 (ActiveMQ-remoting-threads-ActiveMQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) HQ112098: Duplicate message detected - message will not be routed. Message information:
-ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _HQ_DUPL_ID=42}]]@12835058</programlisting>
-
- <para>An alternative to this approach is to use the <literal>msg-create-with-id</literal>
- header. This is not an invokable URL, but a URL template. The idea is that
- the client provides the <literal>DUPLICATE_DETECTION_ID</literal> and creates
- its own <literal>create-next</literal> URL. The <literal>msg-create-with-id</literal>
- header looks like this (you've see it in previous examples, but we haven't used it):
- </para>
-
- <programlisting>
-msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</programlisting>
-
- <para>You see that it is a regular URL appended with a <literal>{id}</literal>. This
- <literal>{id}</literal> is a pattern matching substring. A client would generate its
- <literal>DUPLICATE_DETECTION_ID</literal> and replace <literal>{id}</literal>
- with that generated id, then POST to the new URL. The URL the client creates
- works exactly like a <literal>create-next</literal> URL described earlier. The
- response of this POST would also return a new <literal>msg-create-next</literal>
- header. The client can continue to generate its own DUPLICATE_DETECTION_ID, or
- use the new URL returned via the <literal>msg-create-nex</literal>t header.
- </para>
-
- <para>The advantage of this approach is that the client does not have to
- repost the message. It also only has to come up with a unique
- <literal>DUPLICATE_DETECTION_ID</literal> once.
- </para>
- </section>
-
- <section>
- <title>Persistent Messages</title>
-
- <para>By default, posted messages are not durable and will not be
- persisted in ActiveMQ's journal. You can create durable messages by
- modifying the default configuration as expressed in Chapter 2 so that
- all messages are persisted when sent. Alternatively, you can set a URL
- query parameter called <literal>durable</literal> to true when you post
- your messages to the URLs returned in the <literal>msg-create</literal>,
- <literal>msg-create-with-id</literal>, or <literal>msg-create-next</literal>
- headers. here's an example of that.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create?durable=true
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</item>
- <cost>$199.99</cost>
-</order></programlisting>
- </section>
-
- <section>
- <title>TTL, Expiration and Priority</title>
-
- <para>You can set the time to live, expiration, and/or the priority of
- the message in the queue or topic by setting an additional query
- parameter. The <literal>expiration</literal> query parameter is an long
- specify the time in milliseconds since epoch (a long date). The
- <literal>ttl</literal> query parameter is a time in milliseconds you
- want the message active. The <literal>priority</literal> is another
- query parameter with an integer value between 0 and 9 expressing the
- priority of the message. i.e.:
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/create?expiration=30000&priority=3
-Host: example.com
-Content-Type: application/xml
-
-<order>
- <name>Bill</name>
- <item>iPhone4</item>
- <cost>$199.99</cost>
-</order></programlisting>
- </section>
- </section>
-
- <section id="message-pull">
- <title>Consuming Messages via Pull</title>
-
- <para>There are two different ways to consume messages from a topic or
- queue. You can wait and have the messaging server push them to you, or you
- can continuously poll the server yourself to see if messages are
- available. This chapter discusses the latter. Consuming messages via a
- pull works almost identically for queues and topics with some minor, but
- important caveats. To start consuming you must create a consumer resource
- on the server that is dedicated to your client. Now, this pretty much
- breaks the stateless principle of REST, but after much prototyping, this
- is the best way to work most effectively with ActiveMQ through a REST
- interface.
- </para>
-
- <para>You create consumer resources by doing a simple POST to the URL
- published by the <literal>msg-pull-consumers</literal>
- response header if you are interacting with a queue, the
- <literal>msg-pull-subscribers</literal> response header if you're
- interacting with a topic. These headers are provided by the main queue or
- topic resource discussed in <link linkend="basics">ActiveMQ REST Interface
- Basics</link>. Doing an empty POST to one of these
- URLs will create a consumer resource that follows an auto-acknowledge
- protocol and, if you are interacting with a topic, creates a temporarily
- subscription to the topic. If you want to use the acknowledgement protocol
- and/or create a durable subscription (topics only), then you must use the
- form parameters (<literal>application/x-www-form-urlencoded</literal>)
- described below.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>autoAck</literal>. A value of <literal>true</literal>
- or <literal>false</literal> can be given. This defaults to
- <literal>true</literal> if you do not pass this parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>durable</literal>. A value of <literal>true</literal>
- or <literal>false</literal> can be given. This defaults to
- <literal>false</literal> if you do not pass this parameter.
- Only available on topics. This specifies whether you want a
- durable subscription or not. A durable subscription persists
- through server restart.
- </para>
- </listitem>
- <listitem>
- <para><literal>name</literal>. This is the name of the durable
- subscription. If you do not provide this parameter, the name
- will be automatically generated by the server. Only usable
- on topics.
- </para>
- </listitem>
- <listitem>
- <para><literal>selector</literal>. This is an optional JMS selector
- string. The ActiveMQ REST interface adds HTTP headers to the
- JMS message for REST produced messages. HTTP headers are
- prefixed with "http_" and every '-' character is converted
- to a '$'.
- </para>
- </listitem>
- <listitem>
- <para><literal>idle-timeout</literal>. For a topic subscription,
- idle time in milliseconds in which the consumer connections
- will be closed if idle.
- </para>
- </listitem>
- <listitem>
- <para><literal>delete-when-idle</literal>. Boolean value, If
- true, a topic subscription will be deleted (even if it is
- durable) when an the idle timeout is reached.
- </para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>If you have multiple pull-consumers active at the same time
- on the same destination be aware that unless the
- <literal>consumer-window-size</literal> is 0 then one consumer
- might buffer messages while the other consumer gets none.
- </para>
- </note>
-
- <section>
- <title>Auto-Acknowledge</title>
-
- <para>This section focuses on the auto-acknowledge protocol for
- consuming messages via a pull. Here's a list of the response
- headers and URLs you'll be interested in.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. The URL of
- a factory resource for creating queue consumer
- resources. You will pull from these created resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. The URL
- of a factory resource for creating topic subscription
- resources. You will pull from the created resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consume-next</literal>. The URL you
- will pull the next message from. This is returned
- with every response.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consumer</literal>. This is a URL
- pointing back to the consumer or subscription
- resource created for the client.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Creating an Auto-Ack Consumer or Subscription</title>
-
- <para>Here is an example of creating an auto-acknowledged
- queue pull consumer.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the pull-consumers URL by doing a HEAD or
- GET request to the base queue resource.
- </para>
-
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
-msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do an empty POST to the URL returned in the
- <literal>msg-pull-consumers</literal>
- header.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
-Host: example.com
-
---- response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- consumer resource that was created on the server. It is good to
- remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Creating an auto-acknowledged consumer for a topic is pretty
- much the same. Here's an example of creating a durable
- auto-acknowledged topic pull subscription.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the
- <literal>pull-subscriptions</literal>
- URL by doing
- a HEAD or GET request to the base topic resource
- </para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.foo/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-subscriptions</literal>
- header passing in a <literal>true</literal>
- value for the <literal>durable</literal>
- form parameter.
- </para>
-
- <programlisting>
-POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-durable=true
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222
-msg-consume-next:
-http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- subscription resource that was created on the server. It is good
- to remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Consuming Messages</title>
-
- <para>After you have created a consumer resource, you are ready to
- start pulling messages from the server. Notice that when you created
- the consumer for either the queue or topic, the response contained a
- <literal>msg-consume-next</literal> response header. POST to the URL
- contained within this header to consume the next message in the queue
- or topic subscription. A successful POST causes the server to extract
- a message from the queue or topic subscription, acknowledge it, and
- return it to the consuming client. If there are no messages in the
- queue or topic subscription, a 503 (Service Unavailable) HTTP code is
- returned.
- </para>
-
- <warning>
- <para>For both successful and unsuccessful posts to the
- msg-consume-next URL, the response will contain a new
- msg-consume-next header. You must ALWAYS use this new URL returned
- within the new msg-consume-next header to consume new
- messages.
- </para>
- </warning>
-
- <para>Here's an example of pulling multiple messages from the consumer
- resource.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Do a POST on the msg-consume-next URL that was returned with
- the consumer or subscription resource discussed earlier.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-Content-Type: application/xml
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2
-msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
-
-<order>...</order></programlisting>
-
- <para>The POST returns the message consumed from the queue. It
- also returns a new msg-consume-next link. Use this new link to get
- the next message. Notice also a msg-consumer response header is
- returned. This is a URL that points back to the consumer or
- subscription resource. You will need that to clean up your
- connection after you are finished using the queue or topic.
- </para>
- </listitem>
-
- <listitem>
- <para>The POST returns the message consumed from the queue. It
- also returns a new msg-consume-next link. Use this new link to get
- the next message.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-2
-Host: example.com
-
---- Response ---
-Http/1.1 503 Service Unavailable
-Retry-After: 5
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2</programlisting>
-
- <para>In this case, there are no messages in the queue, so we get
- a 503 response back. As per the HTTP 1.1 spec, a 503 response may
- return a Retry-After head specifying the time in seconds that you
- should retry a post. Also notice, that another new
- msg-consume-next URL is present. Although it probably is the same
- URL you used last post, get in the habit of using URLs returned in
- response headers as future versions of ActiveMQ REST might be
- redirecting you or adding additional data to the URL after
- timeouts like this.
- </para>
- </listitem>
-
- <listitem>
- <para>POST to the URL within the last
- <literal>msg-consume-next</literal>
- to get the next
- message.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-2
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-Content-Type: application/xml
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
-
-<order>...</order></programlisting>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Recovering From Network Failures</title>
-
- <para>If you experience a network failure and do not know if your post
- to a msg-consume-next URL was successful or not, just re-do your POST.
- A POST to a msg-consume-next URL is idempotent, meaning that it will
- return the same result if you execute on any one msg-consume-next URL
- more than once. Behind the scenes, the consumer resource caches the
- last consumed message so that if there is a message failure and you do
- a re-post, the cached last message will be returned (along with a new
- msg-consume-next URL). This is the reason why the protocol always
- requires you to use the next new msg-consume-next URL returned with
- each response. Information about what state the client is in is
- embedded within the actual URL.
- </para>
- </section>
-
- <section>
- <title>Recovering From Client or Server Crashes</title>
-
- <para>If the server crashes and you do a POST to the msg-consume-next
- URL, the server will return a 412 (Preconditions Failed) response
- code. This is telling you that the URL you are using is out of sync
- with the server. The response will contain a new msg-consume-next
- header to invoke on.
- </para>
-
- <para>If the client crashes there are multiple ways you can recover.
- If you have remembered the last msg-consume-next link, you can just
- re-POST to it. If you have remembered the consumer resource URL, you
- can do a GET or HEAD request to obtain a new msg-consume-next URL. If
- you have created a topic subscription using the name parameter
- discussed earlier, you can re-create the consumer. Re-creation will
- return a msg-consume-next URL you can use. If you cannot do any of
- these things, you will have to create a new consumer.
- </para>
-
- <para>The problem with the auto-acknowledge protocol is that if the
- client or server crashes, it is possible for you to skip messages. The
- scenario would happen if the server crashes after auto-acknowledging a
- message and before the client receives the message. If you want more
- reliable messaging, then you must use the acknowledgement
- protocol.
- </para>
- </section>
- </section>
-
- <section>
- <title>Manual Acknowledgement</title>
-
- <para>The manual acknowledgement protocol is similar to the auto-ack
- protocol except there is an additional round trip to the server to tell
- it that you have received the message and that the server can internally
- ack the message. Here is a list of the response headers you will be
- interested in.
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>msg-pull-consumers</literal>. The URL of a factory resource for creating queue
- consumer
- resources. You will pull from these created resources
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-pull-subscriptions</literal>. The URL of a factory resource for creating topic
- subscription resources. You will pull from the created
- resources.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-acknowledge-next</literal>. URL used to obtain the next message in the queue or
- topic
- subscription. It does not acknowledge the message though.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-acknowledgement</literal>. URL used to acknowledge a message.
- </para>
- </listitem>
- <listitem>
- <para><literal>msg-consumer</literal>. This is a URL pointing back to the consumer or subscription
- resource created for the client.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Creating manually-acknowledged consumers or
- subscriptions
- </title>
-
- <para>Here is an example of creating an auto-acknowledged queue pull
- consumer.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the pull-consumers URL by doing a HEAD or GET request
- to the base queue resource.
- </para>
-
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
-msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-consumers</literal>
- header passing in a
- <literal>false</literal>
- value to the
- <literal>autoAck</literal>
- form parameter .
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-autoAck=false
-
---- response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333
-msg-acknowledge-next: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333/acknowledge-next-1</programlisting>
-
- <para>The
- <literal>Location</literal>
- header points to the JMS
- consumer resource that was created on the server. It is good to
- remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Creating an manually-acknowledged consumer for a topic is pretty
- much the same. Here's an example of creating a durable
- manually-acknowledged topic pull subscription.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Find the
- <literal>pull-subscriptions</literal>
- URL by doing
- a HEAD or GET request to the base topic resource
- </para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.foo/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next do a POST to the URL returned in the
- <literal>msg-pull-subscriptions</literal>
- header passing in a <literal>true</literal>
- value for the <literal>durable</literal>
- form parameter and a <literal>false</literal>
- value to the <literal>autoAck</literal>
- form parameter.
- </para>
-
- <programlisting>
-POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-durable=true&autoAck=false
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222
-msg-acknowledge-next:
-http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222/consume-next-1</programlisting>
-
- <para>The
- <literal>Location</literal> header points to the JMS
- subscription resource that was created on the server. It is good
- to remember this URL, although, as you'll see later, it is
- transmitted with each response just to remind you.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Consuming and Acknowledging a Message</title>
-
- <para>After you have created a consumer resource, you are ready to
- start pulling messages from the server. Notice that when you created
- the consumer for either the queue or topic, the response contained a
- <literal>msg-acknowledge-next</literal> response header. POST to the
- URL contained within this header to consume the next message in the
- queue or topic subscription. If there are no messages in the queue or
- topic subscription, a 503 (Service Unavailable) HTTP code is returned.
- A successful POST causes the server to extract a message from the
- queue or topic subscription and return it to the consuming client. It
- does not acknowledge the message though. The response will contain the
- <literal>acknowledgement</literal>
- header which you will use to
- acknowledge the message.
- </para>
-
- <para>Here's an example of pulling multiple messages from the consumer
- resource.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Do a POST on the msg-acknowledge-next URL that was returned
- with the consumer or subscription resource discussed
- earlier.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-Content-Type: application/xml
-msg-acknowledgement:
-http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledgement/2
-msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
-
-<order>...</order></programlisting>
-
- <para>The POST returns the message consumed from the queue. It
- also returns a<literal>msg-acknowledgemen</literal>t link. You
- will use this new link to acknowledge the message. Notice also a
- <literal>msg-consumer</literal> response header is returned. This
- is a URL that points back to the consumer or subscription
- resource. You will need that to clean up your connection after you
- are finished using the queue or topic.
- </para>
- </listitem>
-
- <listitem>
- <para>Acknowledge or unacknowledge the message by doing a POST to
- the URL contained in the <literal>msg-acknowledgement</literal>
- header. You must pass an <literal>acknowledge</literal>
- form parameter set to <literal>true</literal>
- or <literal>false</literal> depending on whether you want to
- acknowledge or unacknowledge the message on the server.
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/acknowledgement/2
-Host: example.com
-Content-Type: application/x-www-form-urlencoded
-
-acknowledge=true
-
---- Response ---
-Http/1.1 200 Ok
-msg-acknowledge-next:
-http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledge-next-2</programlisting>
-
- <para>Whether you acknowledge or unacknowledge the message, the
- response will contain a new msg-acknowledge-next header that you
- must use to obtain the next message.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Recovering From Network Failures</title>
-
- <para>If you experience a network failure and do not know if your post
- to a
- <literal>msg-acknowledge-next</literal>
- or
- <literal>msg-acknowledgement</literal> URL was successful or not, just
- re-do your POST. A POST to one of these URLs is idempotent, meaning
- that it will return the same result if you re-post. Behind the scenes,
- the consumer resource keeps track of its current state. If the last
- action was a call to<literal>msg-acknowledge-next</literal>, it will
- have the last message cached, so that if a re-post is done, it will
- return the message again. Same goes with re-posting to
- <literal>msg-acknowledgement</literal>. The server remembers its last
- state and will return the same results. If you look at the URLs you'll
- see that they contain information about the expected current state of
- the server. This is how the server knows what the client is
- expecting.
- </para>
- </section>
-
- <section>
- <title>Recovering From Client or Server Crashes</title>
-
- <para>If the server crashes and while you are doing a POST to the
- <literal>msg-acknowledge-next</literal> URL, just re-post. Everything
- should reconnect all right. On the other hand, if the server crashes
- while you are doing a POST to<literal>msg-acknowledgement</literal>,
- the server will return a 412 (Preconditions Failed) response code.
- This is telling you that the URL you are using is out of sync with the
- server and the message you are acknowledging was probably re-enqueued.
- The response will contain a new <literal>msg-acknowledge-next</literal>
- header to invoke on.
- </para>
-
- <para>As long as you have "bookmarked" the consumer resource URL
- (returned from <literal>Location</literal> header on a create, or the
- <literal>msg-consumer</literal> header), you can recover from client
- crashes by doing a GET or HEAD request on the consumer resource to
- obtain what state you are in. If the consumer resource is expecting
- you to acknowledge a message, it will return a
- <literal>msg-acknowledgement</literal> header in the response. If the
- consumer resource is expecting you to pull for the next message, the
- <literal>msg-acknowledge-next</literal> header will be in the
- response. With manual acknowledgement you are pretty much guaranteed
- to avoid skipped messages. For topic subscriptions that were created
- with a name parameter, you do not have to "bookmark" the returned URL.
- Instead, you can re-create the consumer resource with the same exact
- name. The response will contain the same information as if you did a
- GET or HEAD request on the consumer resource.
- </para>
- </section>
- </section>
-
- <section>
- <title>Blocking Pulls with Accept-Wait</title>
-
- <para>Unless your queue or topic has a high rate of message flowing
- though it, if you use the pull protocol, you're going to be receiving a
- lot of 503 responses as you continuously pull the server for new
- messages. To alleviate this problem, the ActiveMQ REST interface provides
- the <literal>Accept-Wait</literal> header. This is a generic HTTP
- request header that is a hint to the server for how long the client is
- willing to wait for a response from the server. The value of this header
- is the time in seconds the client is willing to block for. You would
- send this request header with your pull requests. Here's an
- example:
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/pull-consumers/consume-next-2
-Host: example.com
-Accept-Wait: 30
-
---- Response ---
-HTTP/1.1 200 Ok
-Content-Type: application/xml
-msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
-
-<order>...</order></programlisting>
-
- <para>In this example, we're posting to a msg-consume-next URL and
- telling the server that we would be willing to block for 30
- seconds.
- </para>
- </section>
-
- <section>
- <title>Clean Up Your Consumers!</title>
-
- <para>When the client is done with its consumer or topic subscription it
- should do an HTTP DELETE call on the consumer URL passed back from the
- Location header or the msg-consumer response header. The server will
- time out a consumer with the value of
- <literal>consumer-session-timeout-seconds</literal> configured from
- <link linkend="configuration">REST configuration</link>, so you
- don't have to clean up if you don't want to, but if you are a good kid,
- you will clean up your messes. A consumer timeout for durable
- subscriptions will not delete the underlying durable JMS subscription
- though, only the server-side consumer resource (and underlying JMS
- session).
- </para>
- </section>
- </section>
-
-
- <section id="message-push">
- <title>Pushing Messages</title>
-
- <para>You can configure the ActiveMQ REST server to push messages to a
- registered URL either remotely through the REST interface, or by creating
- a pre-configured XML file for the ActiveMQ REST server to load at boot
- time.
- </para>
-
- <section>
- <title>The Queue Push Subscription XML</title>
-
- <para>Creating a push consumer for a queue first involves creating a
- very simple XML document. This document tells the server if the push
- subscription should survive server reboots (is it durable). It must
- provide a URL to ship the forwarded message to. Finally, you have to
- provide authentication information if the final endpoint requires
- authentication. Here's a simple example:
- </para>
-
- <programlisting>
-<push-registration>
- <durable>false</durable>
- <selector><![CDATA[
- SomeAttribute > 1
- ]]>
- </selector>
- <link rel="push" href="http://somewhere.com" type="application/json" method="PUT"/>
- <maxRetries>5</maxRetries>
- <retryWaitMillis>1000</retryWaitMillis>
- <disableOnFailure>true</disableOnFailure>
-</push-registration></programlisting>
-
- <para>The <literal>durable</literal> element specifies whether the
- registration should be saved to disk so that if there is a server
- restart, the push subscription will still work. This element is not
- required. If left out it defaults to<literal>false</literal>. If
- durable is set to true, an XML file for the push subscription will be
- created within the directory specified by the
- <literal>queue-push-store-dir</literal> config variable defined in
- Chapter 2 (<literal>topic-push-store-dir</literal> for topics).
- </para>
-
- <para>The <literal>selector</literal> element is optional and defines a
- JMS message selector. You should enclose it within CDATA blocks as some
- of the selector characters are illegal XML.
- </para>
-
- <para>The <literal>maxRetries</literal> element specifies how many times
- a the server will try to push a message to a URL if there is a
- connection failure.
- </para>
-
- <para>The <literal>retryWaitMillis</literal> element specifies how long
- to wait before performing a retry.
- </para>
-
- <para>The
- <literal>disableOnFailure</literal> element, if set to true,
- will disable the registration if all retries have failed. It will not
- disable the connection on non-connection-failure issues (like a bad
- request for instance). In these cases, the dead letter queue logic of
- ActiveMQ will take over.
- </para>
-
- <para>The <literal>link</literal> element specifies the basis of the
- interaction. The <literal>href</literal> attribute contains the URL you
- want to interact with. It is the only required attribute. The
- <literal>type</literal> attribute specifies the content-type of what the
- push URL is expecting. The <literal>method</literal> attribute defines
- what HTTP method the server will use when it sends the message to the
- server. If it is not provided it defaults to POST. The
- <literal>rel</literal> attribute is very important and the value of it
- triggers different behavior. Here's the values a rel attribute can
- have:
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>destination</literal>. The href URL is assumed to be a queue or topic resource of
- another ActiveMQ REST server. The push registration will initially
- do a HEAD request to this URL to obtain a msg-create-with-id
- header. It will use this header to push new messages to the
- ActiveMQ REST endpoint reliably. Here's an example:
- </para>
-
- <programlisting>
-<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
-</push-registration></programlisting>
- </listitem>
- <listitem>
- <para><literal>template</literal>. In this case, the server is expecting the link element's
- href attribute to be a URL expression. The URL expression must
- have one and only one URL parameter within it. The server will use
- a unique value to create the endpoint URL. Here's an
- example:
- </para>
-
- <programlisting>
-<push-registration>
- <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
-</push-registration></programlisting>
-
- <para>In this example, the {id} sub-string is the one and only one
- URL parameter.
- </para>
- </listitem>
- <listitem>
- <para><literal>user defined</literal>. If the rel attributes is not destination or template (or is
- empty or missing), then the server will send an HTTP message to
- the href URL using the HTTP method defined in the method
- attribute. Here's an example:
- </para>
-
- <programlisting>
-<push-registration>
- <link href="http://somewhere.com" type="application/json" method="PUT"/>
-</push-registration></programlisting>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>The Topic Push Subscription XML</title>
-
- <para>The push XML for a topic is the same except the root element is
- push-topic-registration. (Also remember the <literal>selector</literal>
- element is optional). The rest of the document is the same. Here's an
- example of a template registration:
- </para>
-
- <programlisting>
-<push-topic-registration>
- <durable>true</durable>
- <selector><![CDATA[
- SomeAttribute > 1
- ]]>
- </selector>
- <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
-</push-topic registration></programlisting>
- </section>
-
- <section>
- <title>Creating a Push Subscription at Runtime</title>
-
- <para>Creating a push subscription at runtime involves getting the
- factory resource URL from the msg-push-consumers header, if the
- destination is a queue, or msg-push-subscriptions header, if the
- destination is a topic. Here's an example of creating a push
- registration for a queue:
- </para>
-
- <orderedlist>
- <listitem>
- <para>First do a HEAD request to the queue resource:</para>
-
- <programlisting>
-HEAD /queues/jms.queue.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/queues/jms.queue.bar/create
-msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
-msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers</programlisting>
- </listitem>
-
- <listitem>
- <para>Next POST your subscription XML to the URL returned from
- msg-push-consumers header
- </para>
-
- <programlisting>
-POST /queues/jms.queue.bar/push-consumers
-Host: example.com
-Content-Type: application/xml
-
-<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
-</push-registration>
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/queues/jms.queue.bar/push-consumers/1-333-1212</programlisting>
-
- <para>The Location header contains the URL for the created resource.
- If you want to unregister this, then do a HTTP DELETE on this
- URL.
- </para>
- </listitem>
- </orderedlist>
-
- <para>Here's an example of creating a push registration for a
- topic:
- </para>
-
- <orderedlist>
- <listitem>
- <para>First do a HEAD request to the topic resource:</para>
-
- <programlisting>
-HEAD /topics/jms.topic.bar HTTP/1.1
-Host: example.com
-
---- Response ---
-HTTP/1.1 200 Ok
-msg-create: http://example.com/topics/jms.topic.bar/create
-msg-pull-subscriptions: http://example.com/topics/jms.topic.bar/pull-subscriptions
-msg-push-subscriptions: http://example.com/topics/jms.topic.bar/push-subscriptions</programlisting>
- </listitem>
-
- <listitem>
- <para>Next POST your subscription XML to the URL returned from
- msg-push-subscriptions header
- </para>
-
- <programlisting>
-POST /topics/jms.topic.bar/push-subscriptions
-Host: example.com
-Content-Type: application/xml
-
-<push-registration>
- <link rel="template" href="http://somewhere.com/resources/{id}"/>
-</push-registration>
-
---- Response ---
-HTTP/1.1 201 Created
-Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212</programlisting>
-
- <para>The Location header contains the URL for the created resource.
- If you want to unregister this, then do a HTTP DELETE on this
- URL.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Creating a Push Subscription by Hand</title>
-
- <para>You can create a push XML file yourself if you do not want to go
- through the REST interface to create a push subscription. There is some
- additional information you need to provide though. First, in the root
- element, you must define a unique id attribute. You must also define a
- destination element to specify the queue you should register a consumer
- with. For a topic, the destination element is the name of the
- subscription that will be created. For a topic, you must also specify the
- topic name within the topic element.
- </para>
-
- <para>Here's an example of a hand-created queue registration. This file
- must go in the directory specified by the queue-push-store-dir config
- variable defined in Chapter 2:
- </para>
-
- <programlisting>
-<push-registration id="111">
- <destination>jms.queue.bar</destination>
- <durable>true</durable>
- <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
-</push-registration></programlisting>
-
- <para>Here's an example of a hand-created topic registration. This file
- must go in the directory specified by the topic-push-store-dir config
- variable defined in Chapter 2:
- </para>
-
- <programlisting>
-<push-topic-registration id="112">
- <destination>my-subscription-1</destination
- <durable>true</durable>
- <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
- <topic>jms.topic.foo</topic>
-</push-topic-registra
<TRUNCATED>
[06/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/queue-attributes.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/queue-attributes.md b/docs/user-manual/en/queue-attributes.md
new file mode 100644
index 0000000..d2dafa5
--- /dev/null
+++ b/docs/user-manual/en/queue-attributes.md
@@ -0,0 +1,182 @@
+Queue Attributes
+================
+
+Queue attributes can be set in one of two ways. Either by configuring
+them using the configuration file or by using the core API. This chapter
+will explain how to configure each attribute and what effect the
+attribute has.
+
+Predefined Queues
+=================
+
+Queues can be predefined via configuration at a core level or at a JMS
+level. Firstly let's look at a JMS level.
+
+The following shows a queue predefined in the `activemq-jms.xml`
+configuration file.
+
+ <queue name="selectorQueue">
+ <entry name="/queue/selectorQueue"/>
+ <selector string="color='red'"/>
+ <durable>true</durable>
+ </queue>
+
+This name attribute of queue defines the name of the queue. When we do
+this at a jms level we follow a naming convention so the actual name of
+the core queue will be `jms.queue.selectorQueue`.
+
+The entry element configures the name that will be used to bind the
+queue to JNDI. This is a mandatory element and the queue can contain
+multiple of these to bind the same queue to different names.
+
+The selector element defines what JMS message selector the predefined
+queue will have. Only messages that match the selector will be added to
+the queue. This is an optional element with a default of null when
+omitted.
+
+The durable element specifies whether the queue will be persisted. This
+again is optional and defaults to true if omitted.
+
+Secondly a queue can be predefined at a core level in the
+`activemq-configuration.xml` file. The following is an example.
+
+ <queues>
+ <queue name="jms.queue.selectorQueue">
+ <address>jms.queue.selectorQueue</address>
+ <filter string="color='red'"/>
+ <durable>true</durable>
+ </queue>
+ </queues>
+
+This is very similar to the JMS configuration, with 3 real differences
+which are.
+
+1. The name attribute of queue is the actual name used for the queue
+ with no naming convention as in JMS.
+
+2. The address element defines what address is used for routing
+ messages.
+
+3. There is no entry element.
+
+4. The filter uses the *Core filter syntax* (described in ?), *not* the
+ JMS selector syntax.
+
+Using the API
+=============
+
+Queues can also be created using the core API or the management API.
+
+For the core API, queues can be created via the
+`org.apache.activemq.api.core.client.ClientSession` interface. There are
+multiple `createQueue` methods that support setting all of the
+previously mentioned attributes. There is one extra attribute that can
+be set via this API which is `temporary`. setting this to true means
+that the queue will be deleted once the session is disconnected.
+
+Take a look at ? for a description of the management API for creating
+queues.
+
+Configuring Queues Via Address Settings
+=======================================
+
+There are some attributes that are defined against an address wildcard
+rather than a specific queue. Here an example of an `address-setting`
+entry that would be found in the `activemq-configuration.xml` file.
+
+ <address-settings>
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ <redelivery-delay>5000</redelivery-delay>
+ <expiry-address>jms.queue.expiryQueue</expiry-address>
+ <last-value-queue>true</last-value-queue>
+ <max-size-bytes>100000</max-size-bytes>
+ <page-size-bytes>20000</page-size-bytes>
+ <redistribution-delay>0</redistribution-delay>
+ <send-to-dla-on-no-route>true</send-to-dla-on-no-route>
+ <address-full-policy>PAGE</address-full-policy>
+ <slow-consumer-threshold>-1</slow-consumer-threshold>
+ <slow-consumer-policy>NOTIFY</slow-consumer-policy>
+ <slow-consumer-check-period>5</slow-consumer-check-period>
+ </address-setting>
+ </address-settings>
+
+The idea with address settings, is you can provide a block of settings
+which will be applied against any addresses that match the string in the
+`match` attribute. In the above example the settings would only be
+applied to any addresses which exactly match the address
+`jms.queue.exampleQueue`, but you can also use wildcards to apply sets
+of configuration against many addresses. The wildcard syntax used is
+described [here](#wildcard-syntax).
+
+For example, if you used the `match` string `jms.queue.#` the settings
+would be applied to all addresses which start with `jms.queue.` which
+would be all JMS queues.
+
+The meaning of the specific settings are explained fully throughout the
+user manual, however here is a brief description with a link to the
+appropriate chapter if available.
+
+`max-delivery-attempts` defines how many time a cancelled message can be
+redelivered before sending to the `dead-letter-address`. A full
+explanation can be found [here](#undelivered-messages.configuring).
+
+`redelivery-delay` defines how long to wait before attempting redelivery
+of a cancelled message. see [here](#undelivered-messages.delay).
+
+`expiry-address` defines where to send a message that has expired. see
+[here](#message-expiry.configuring).
+
+`expiry-delay` defines the expiration time that will be used for
+messages which are using the default expiration time (i.e. 0). For
+example, if `expiry-delay` is set to "10" and a message which is using
+the default expiration time (i.e. 0) arrives then its expiration time of
+"0" will be changed to "10." However, if a message which is using an
+expiration time of "20" arrives then its expiration time will remain
+unchanged. Setting `expiry-delay` to "-1" will disable this feature. The
+default is "-1".
+
+`last-value-queue` defines whether a queue only uses last values or not.
+see [here](#last-value-queues).
+
+`max-size-bytes` and `page-size-bytes` are used to set paging on an
+address. This is explained [here](#paging).
+
+`redistribution-delay` defines how long to wait when the last consumer
+is closed on a queue before redistributing any messages. see
+[here](#clusters).
+
+`send-to-dla-on-no-route`. If a message is sent to an address, but the
+server does not route it to any queues, for example, there might be no
+queues bound to that address, or none of the queues have filters that
+match, then normally that message would be discarded. However if this
+parameter is set to true for that address, if the message is not routed
+to any queues it will instead be sent to the dead letter address (DLA)
+for that address, if it exists.
+
+`address-full-policy`. This attribute can have one of the following
+values: PAGE, DROP, FAIL or BLOCK and determines what happens when an
+address where `max-size-bytes` is specified becomes full. The default
+value is PAGE. If the value is PAGE then further messages will be paged
+to disk. If the value is DROP then further messages will be silently
+dropped. If the value is FAIL then further messages will be dropped and
+an exception will be thrown on the client-side. If the value is BLOCK
+then client message producers will block when they try and send further
+messages. See the following chapters for more info ?, ?.
+
+`slow-consumer-threshold`. The minimum rate of message consumption
+allowed before a consumer is considered "slow." Measured in
+messages-per-second. Default is -1 (i.e. disabled); any other valid
+value must be greater than 0.
+
+`slow-consumer-policy`. What should happen when a slow consumer is
+detected. `KILL` will kill the consumer's connection (which will
+obviously impact any other client threads using that same connection).
+`NOTIFY` will send a CONSUMER\_SLOW management notification which an
+application could receive and take action with. See ? for more details
+on this notification.
+
+`slow-consumer-check-period`. How often to check for slow consumers on a
+particular queue. Measured in minutes. Default is 5. See ? for more
+information about slow consumer detection.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/queue-attributes.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/queue-attributes.xml b/docs/user-manual/en/queue-attributes.xml
deleted file mode 100644
index b6245ed..0000000
--- a/docs/user-manual/en/queue-attributes.xml
+++ /dev/null
@@ -1,171 +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="queue-attributes">
- <title>Queue Attributes</title>
- <para>Queue attributes can be set in one of two ways. Either by configuring them using the
- configuration file or by using the core API. This chapter will explain how to configure each
- attribute and what effect the attribute has.</para>
- <section id="predefined.queues">
- <title>Predefined Queues</title>
- <para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly
- let's look at a JMS level.</para>
- <para>The following shows a queue predefined in the <literal>activemq-jms.xml</literal>
- configuration file.</para>
- <programlisting>
-<queue name="selectorQueue">
- <entry name="/queue/selectorQueue"/>
- <selector string="color='red'"/>
- <durable>true</durable>
-</queue></programlisting>
- <para>This name attribute of queue defines the name of the queue. When we do this at a jms
- level we follow a naming convention so the actual name of the core queue will be
- <literal>jms.queue.selectorQueue</literal>.</para>
- <para>The entry element configures the name that will be used to bind the queue to JNDI.
- This is a mandatory element and the queue can contain multiple of these to bind the same
- queue to different names.</para>
- <para>The selector element defines what JMS message selector the predefined queue will have.
- Only messages that match the selector will be added to the queue. This is an optional
- element with a default of null when omitted.</para>
- <para>The durable element specifies whether the queue will be persisted. This again is
- optional and defaults to true if omitted.</para>
- <para>Secondly a queue can be predefined at a core level in the <literal
- >activemq-configuration.xml</literal> file. The following is an example.</para>
- <programlisting>
-<queues>
- <queue name="jms.queue.selectorQueue">
- <address>jms.queue.selectorQueue</address>
- <filter string="color='red'"/>
- <durable>true</durable>
- </queue>
-</queues></programlisting>
- <para>This is very similar to the JMS configuration, with 3 real differences which
- are.</para>
- <orderedlist>
- <listitem>
- <para>The name attribute of queue is the actual name used for the queue with no
- naming convention as in JMS.</para>
- </listitem>
- <listitem>
- <para>The address element defines what address is used for routing messages.</para>
- </listitem>
- <listitem>
- <para>There is no entry element.</para>
- </listitem>
- <listitem>
- <para>The filter uses the <emphasis>Core filter syntax</emphasis> (described in
- <xref linkend="filter-expressions"/>), <emphasis>not</emphasis> the JMS
- selector syntax.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>Using the API</title>
- <para>Queues can also be created using the core API or the management API.</para>
- <para>For the core API, queues can be created via the <literal
- >org.apache.activemq.api.core.client.ClientSession</literal> interface. There are multiple
- <literal>createQueue</literal> methods that support setting all of the previously
- mentioned attributes. There is one extra attribute that can be set via this API which is
- <literal>temporary</literal>. setting this to true means that the queue will be
- deleted once the session is disconnected.</para>
- <para>Take a look at <xref linkend="management"/> for a description of the management API
- for creating queues.</para>
- </section>
- <section id="queue-attributes.address-settings">
- <title>Configuring Queues Via Address Settings</title>
- <para>There are some attributes that are defined against an address wildcard rather than a
- specific queue. Here an example of an <literal>address-setting</literal> entry that
- would be found in the <literal>activemq-configuration.xml</literal> file.</para>
- <programlisting>
-<address-settings>
- <address-setting match="jms.queue.exampleQueue">
- <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
- <max-delivery-attempts>3</max-delivery-attempts>
- <redelivery-delay>5000</redelivery-delay>
- <expiry-address>jms.queue.expiryQueue</expiry-address>
- <last-value-queue>true</last-value-queue>
- <max-size-bytes>100000</max-size-bytes>
- <page-size-bytes>20000</page-size-bytes>
- <redistribution-delay>0</redistribution-delay>
- <send-to-dla-on-no-route>true</send-to-dla-on-no-route>
- <address-full-policy>PAGE</address-full-policy>
- <slow-consumer-threshold>-1</slow-consumer-threshold>
- <slow-consumer-policy>NOTIFY</slow-consumer-policy>
- <slow-consumer-check-period>5</slow-consumer-check-period>
- </address-setting>
-</address-settings></programlisting>
- <para>The idea with address settings, is you can provide a block of settings which will be
- applied against any addresses that match the string in the <literal>match</literal> attribute. In the
- above example the settings would only be applied to any addresses which exactly match
- the address <literal>jms.queue.exampleQueue</literal>, but you can also use wildcards to apply sets of
- configuration against many addresses. The wildcard syntax used is described <link linkend="wildcard-syntax">here</link>.</para>
- <para>For example, if you used the <literal>match</literal> string <literal>jms.queue.#</literal> the settings would be applied
- to all addresses which start with <literal>jms.queue.</literal> which would be all JMS queues.</para>
- <para>The meaning of the specific settings are explained fully throughout the user manual, however here is a brief
- description with a link to the appropriate chapter if available. </para>
- <para><literal>max-delivery-attempts</literal> defines how many time a cancelled message can
- be redelivered before sending to the <literal>dead-letter-address</literal>. A full
- explanation can be found <link linkend="undelivered-messages.configuring"
- >here</link>.</para>
- <para><literal>redelivery-delay</literal> defines how long to wait before attempting
- redelivery of a cancelled message. see <link linkend="undelivered-messages.delay"
- >here</link>.</para>
- <para><literal>expiry-address</literal> defines where to send a message that has expired.
- see <link linkend="message-expiry.configuring">here</link>.</para>
- <para><literal>expiry-delay</literal> defines the expiration time that will be used for messages which are using
- the default expiration time (i.e. 0). For example, if <literal>expiry-delay</literal> is set to "10" and a
- message which is using the default expiration time (i.e. 0) arrives then its expiration time of "0" will be
- changed to "10." However, if a message which is using an expiration time of "20" arrives then its expiration
- time will remain unchanged. Setting <literal>expiry-delay</literal> to "-1" will disable this feature. The
- default is "-1".</para>
- <para><literal>last-value-queue</literal> defines whether a queue only uses last values or
- not. see <link linkend="last-value-queues">here</link>.</para>
- <para><literal>max-size-bytes</literal> and <literal>page-size-bytes</literal> are used to
- set paging on an address. This is explained <link linkend="paging">here</link>.</para>
- <para><literal>redistribution-delay</literal> defines how long to wait when the last
- consumer is closed on a queue before redistributing any messages. see <link
- linkend="clusters">here</link>.</para>
- <para><literal>send-to-dla-on-no-route</literal>. If a message is sent to an address, but the server does not route it to any queues,
- for example, there might be no queues bound to that address, or none of the queues have filters that match, then normally that message
- would be discarded. However if this parameter is set to true for that address, if the message is not routed to any queues it will instead
- be sent to the dead letter address (DLA) for that address, if it exists.</para>
- <para><literal>address-full-policy</literal>. This attribute can have one of the following values: PAGE, DROP, FAIL or BLOCK and determines what happens when
- an address where <literal>max-size-bytes</literal> is specified becomes full. The default value is PAGE. If the value is PAGE then further messages will be paged to disk.
- If the value is DROP then further messages will be silently dropped.
- If the value is FAIL then further messages will be dropped and an exception will be thrown on the client-side.
- If the value is BLOCK then client message producers will block when they try and send further messages.
-
- See the following chapters for more info <xref linkend="flow-control"/>, <xref linkend="paging"/>.
- </para>
- <para><literal>slow-consumer-threshold</literal>. The minimum rate of message consumption allowed before a
- consumer is considered "slow." Measured in messages-per-second. Default is -1 (i.e. disabled); any other valid
- value must be greater than 0.</para>
- <para><literal>slow-consumer-policy</literal>. What should happen when a slow consumer is detected.
- <literal>KILL</literal> will kill the consumer's connection (which will obviously impact any other client
- threads using that same connection). <literal>NOTIFY</literal> will send a CONSUMER_SLOW management
- notification which an application could receive and take action with. See
- <xref linkend="notification.types.and.headers"/> for more details on this notification.</para>
- <para><literal>slow-consumer-check-period</literal>. How often to check for slow consumers on a particular queue.
- Measured in minutes. Default is 5. See <xref linkend="slow-consumers"/> for more information about slow
- consumer detection.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/rest.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/rest.md b/docs/user-manual/en/rest.md
new file mode 100644
index 0000000..c48ffc1
--- /dev/null
+++ b/docs/user-manual/en/rest.md
@@ -0,0 +1,1570 @@
+REST Interface
+==============
+
+The ActiveMQ REST interface allows you to leverage the reliability and
+scalability features of ActiveMQ over a simple REST/HTTP interface.
+Messages are produced and consumed by sending and receiving simple HTTP
+messages that contain the content you want to push around. For instance,
+here's a simple example of posting an order to an order processing queue
+express as an HTTP message:
+
+ POST /queue/orders/create HTTP/1.1
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone 4</item>
+ <cost>$199.99</cost>
+ </order>
+
+As you can see, we're just posting some arbitrary XML document to a URL.
+When the XML is received on the server is it processed within ActiveMQ
+as a JMS message and distributed through core ActiveMQ. Simple and easy.
+Consuming messages from a queue or topic looks very similar. We'll
+discuss the entire interface in detail later in this docbook.
+
+Goals of REST Interface
+=======================
+
+Why would you want to use ActiveMQ's REST interface? What are the goals
+of the REST interface?
+
+- Easily usable by machine-based (code) clients.
+
+- Zero client footprint. We want ActiveMQ to be usable by any
+ client/programming language that has an adequate HTTP client
+ library. You shouldn't have to download, install, and configure a
+ special library to interact with ActiveMQ.
+
+- Lightweight interoperability. The HTTP protocol is strong enough to
+ be our message exchange protocol. Since interactions are RESTful the
+ HTTP uniform interface provides all the interoperability you need to
+ communicate between different languages, platforms, and even
+ messaging implementations that choose to implement the same RESTful
+ interface as ActiveMQ (i.e. the [REST-\*](http://rest-star.org)
+ effort.)
+
+- No envelope (e.g. SOAP) or feed (e.g. Atom) format requirements. You
+ shouldn't have to learn, use, or parse a specific XML document
+ format in order to send and receive messages through ActiveMQ's REST
+ interface.
+
+- Leverage the reliability, scalability, and clustering features of
+ ActiveMQ on the back end without sacrificing the simplicity of a
+ REST interface.
+
+Installation and Configuration
+==============================
+
+ActiveMQ's REST interface is installed as a Web archive (WAR). It
+depends on the [RESTEasy](http://jboss.org/resteasy) project and can
+currently only run within a servlet container. Installing the ActiveMQ
+REST interface is a little bit different depending whether ActiveMQ is
+already installed and configured for your environment (e.g. you're
+deploying within JBoss AS 7) or you want the ActiveMQ REST WAR to
+startup and manage the ActiveMQ server (e.g. you're deploying within
+something like Apache Tomcat).
+
+Installing Within Pre-configured Environment
+--------------------------------------------
+
+This section should be used when you want to use the ActiveMQ REST
+interface in an environment that already has ActiveMQ installed and
+running, e.g. JBoss AS 7. You must create a Web archive (.WAR) file with
+the following web.xml settings:
+
+ <web-app>
+ <listener>
+ <listener-class>
+ org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.rest.integration.RestMessagingBootstrapListener
+ </listener-class>
+ </listener>
+
+ <filter>
+ <filter-name>Rest-Messaging</filter-name>
+ <filter-class>
+ org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
+ </filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>Rest-Messaging</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ </web-app>
+
+Within your WEB-INF/lib directory you must have the activemq-rest.jar
+file. If RESTEasy is not installed within your environment, you must add
+the RESTEasy jar files within the lib directory as well. Here's a sample
+Maven pom.xml that can build your WAR for this case.
+
+ <project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.somebody</groupId>
+ <artifactId>myapp</artifactId>
+ <packaging>war</packaging>
+ <name>My App</name>
+ <version>0.1-SNAPSHOT</version>
+ <repositories>
+ <repository>
+ <id>jboss</id>
+ <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+ </repository>
+ </repositories>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.activemq.rest</groupId>
+ <artifactId>activemq-rest</artifactId>
+ <version>2.3.0-SNAPSHOT</version>
+ </dependency>
+ </dependencies>
+ </project>
+
+> **Note**
+>
+> JBoss AS 7 loads classes differently than previous versions. To work
+> properly in AS 7 the WAR will need this in its MANIFEST.MF:
+>
+> Dependencies: org.apache.activemq, org.jboss.netty
+>
+> You can add this to the`<plugins>` section of the pom.xml to create
+> this entry automatically:
+>
+> <plugin>
+> <groupId>org.apache.maven.plugins</groupId>
+> <artifactId>maven-war-plugin</artifactId>
+> <configuration>
+> <archive>
+> <manifestEntries>
+> <Dependencies>org.apache.activemq, org.jboss.netty</Dependencies>
+> </manifestEntries>
+> </archive>
+> </configuration>
+> </plugin>
+
+It is worth noting that when deploying a WAR in a Java EE application
+server like AS7 the URL for the resulting application will include the
+name of the WAR by default. For example, if you've constructed a WAR as
+described above named "activemq-rest.war" then clients will access it
+at, e.g. http://localhost:8080/activemq-rest/[queues|topics]. We'll see
+more about this later.
+
+> **Note**
+>
+> It is possible to put the WAR file at the "root context" of AS7, but
+> that is beyond the scope of this documentation.
+
+Bootstrapping ActiveMQ Along with REST
+--------------------------------------
+
+You can bootstrap ActiveMQ within your WAR as well. To do this, you must
+have the ActiveMQ core and JMS jars along with Netty, Resteasy, and the
+ActiveMQ REST jar within your WEB-INF/lib. You must also have a
+activemq-configuration.xml, activemq-jms.xml, and activemq-users.xml
+config files within WEB-INF/classes. The examples that come with the
+ActiveMQ REST distribution show how to do this. You must also add an
+additional listener to your web.xml file. Here's an example:
+
+ <web-app>
+ <listener>
+ <listener-class>
+ org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.rest.integration.ActiveMQBootstrapListener
+ </listener-class>
+ </listener>
+
+ <listener>
+ <listener-class>
+ org.apache.activemq.rest.integration.RestMessagingBootstrapListener
+ </listener-class>
+ </listener>
+
+ <filter>
+ <filter-name>Rest-Messaging</filter-name>
+ <filter-class>
+ org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
+ </filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>Rest-Messaging</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ </web-app>
+
+Here's a Maven pom.xml file for creating a WAR for this environment.
+Make sure your activemq configuration files are within the
+src/main/resources directory so that they are stuffed within the WAR's
+WEB-INF/classes directory!
+
+ <project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.somebody</groupId>
+ <artifactId>myapp</artifactId>
+ <packaging>war</packaging>
+ <name>My App</name>
+ <version>0.1-SNAPSHOT</version>
+ <repositories>
+ <repository>
+ <id>jboss</id>
+ <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+ </repository>
+ </repositories>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.activemq</groupId>
+ <artifactId>activemq-core</artifactId>
+ <version>2.3.0-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>io.netty</groupId>
+ <artifactId>netty</artifactId>
+ <version>3.4.5.Final</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.activemq</groupId>
+ <artifactId>activemq-jms</artifactId>
+ <version>2.3.0-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss.spec.javax.jms</groupId>
+ <artifactId>jboss-jms-api_2.0_spec</artifactId>
+ <version>1.0.0.Final</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.activemq.rest</groupId>
+ <artifactId>activemq-rest</artifactId>
+ <version>2.3.0-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss.resteasy</groupId>
+ <artifactId>resteasy-jaxrs</artifactId>
+ <version>2.3.4.Final</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss.resteasy</groupId>
+ <artifactId>resteasy-jaxb-provider</artifactId>
+ <version>2.3.4.Final</version>
+ </dependency>
+ </dependencies>
+ </project>
+
+REST Configuration
+------------------
+
+The ActiveMQ REST implementation does have some configuration options.
+These are configured via XML configuration file that must be in your
+WEB-INF/classes directory. You must set the web.xml context-param
+`rest.messaging.config.file` to specify the name of the configuration
+file. Below is the format of the XML configuration file and the default
+values for each.
+
+ <rest-messaging>
+ <server-in-vm-id>0</server-in-vm-id>
+ <use-link-headers>false</use-link-headers>
+ <default-durable-send>false</default-durable-send>
+ <dups-ok>true</dups-ok>
+ <topic-push-store-dir>topic-push-store</topic-push-store-dir>
+ <queue-push-store-dir>queue-push-store</queue-push-store-dir>
+ <producer-time-to-live>0</producer-time-to-live>
+ <producer-session-pool-size>10</producer-session-pool-size>
+ <session-timeout-task-interval>1</session-timeout-task-interval>
+ <consumer-session-timeout-seconds>300</consumer-session-timeout-seconds>
+ <consumer-window-size>-1</consumer-window-size>
+ </rest-messaging>
+
+Let's give an explanation of each config option.
+
+- `server-in-vm-id`. The ActiveMQ REST impl uses the IN-VM transport
+ to communicate with ActiveMQ. It uses the default server id, which
+ is "0".
+
+- `use-link-headers`. By default, all links (URLs) are published using
+ custom headers. You can instead have the ActiveMQ REST
+ implementation publish links using the [Link Header
+ specification](http://tools.ietf.org/html/draft-nottingham-http-link-header-10)
+ instead if you desire.
+
+- `default-durable-send`. Whether a posted message should be persisted
+ by default if the user does not specify a durable query parameter.
+
+- `dups-ok`. If this is true, no duplicate detection protocol will be
+ enforced for message posting.
+
+- `topic-push-store-dir`. This must be a relative or absolute file
+ system path. This is a directory where push registrations for topics
+ are stored. See [Pushing Messages](#message-push).
+
+- `queue-push-store-dir`. This must be a relative or absolute file
+ system path. This is a directory where push registrations for queues
+ are stored. See [Pushing Messages](#message-push).
+
+- `producer-session-pool-size`. The REST implementation pools ActiveMQ
+ sessions for sending messages. This is the size of the pool. That
+ number of sessions will be created at startup time.
+
+- `producer-time-to-live`. Default time to live for posted messages.
+ Default is no ttl.
+
+- `session-timeout-task-interval`. Pull consumers and pull
+ subscriptions can time out. This is the interval the thread that
+ checks for timed-out sessions will run at. A value of 1 means it
+ will run every 1 second.
+
+- `consumer-session-timeout-seconds`. Timeout in seconds for pull
+ consumers/subscriptions that remain idle for that amount of time.
+
+- `consumer-window-size`. For consumers, this config option is the
+ same as the ActiveMQ one of the same name. It will be used by
+ sessions created by the ActiveMQ REST implementation.
+
+ActiveMQ REST Interface Basics
+==============================
+
+The ActiveMQ REST interface publishes a variety of REST resources to
+perform various tasks on a queue or topic. Only the top-level queue and
+topic URI schemes are published to the outside world. You must discover
+all over resources to interact with by looking for and traversing links.
+You'll find published links within custom response headers and embedded
+in published XML representations. Let's look at how this works.
+
+Queue and Topic Resources
+-------------------------
+
+To interact with a queue or topic you do a HEAD or GET request on the
+following relative URI pattern:
+
+ /queues/{name}
+ /topics/{name}
+
+The base of the URI is the base URL of the WAR you deployed the ActiveMQ
+REST server within as defined in the [Installation and
+Configuration](#install) section of this document. Replace the `{name}`
+string within the above URI pattern with the name of the queue or topic
+you are interested in interacting with. For example if you have
+configured a JMS topic named "foo" within your `activemq-jms.xml` file,
+the URI name should be "jms.topic.foo". If you have configured a JMS
+queue name "bar" within your `activemq-jms.xml` file, the URI name
+should be "jms.queue.bar". Internally, ActiveMQ prepends the "jms.topic"
+or "jms.queue" strings to the name of the deployed destination. Next,
+perform your HEAD or GET request on this URI. Here's what a
+request/response would look like.
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+ msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+
+> **Note**
+>
+> You can use the "curl" utility to test this easily. Simply execute a
+> command like this:
+>
+> curl --head http://example.com/queues/jms.queue.bar
+
+The HEAD or GET response contains a number of custom response headers
+that are URLs to additional REST resources that allow you to interact
+with the queue or topic in different ways. It is important not to rely
+on the scheme of the URLs returned within these headers as they are an
+implementation detail. Treat them as opaque and query for them each and
+every time you initially interact (at boot time) with the server. If you
+treat all URLs as opaque then you will be isolated from implementation
+changes as the ActiveMQ REST interface evolves over time.
+
+Queue Resource Response Headers
+-------------------------------
+
+Below is a list of response headers you should expect when interacting
+with a Queue resource.
+
+- `msg-create`. This is a URL you POST messages to. The semantics of
+ this link are described in [Posting Messages](#posting-messages).
+
+- `msg-create-with-id`. This is a URL *template* you can use to POST
+ messages. The semantics of this link are described in [Posting
+ Messages](#posting-messages).
+
+- `msg-pull-consumers`. This is a URL for creating consumers that will
+ pull from a queue. The semantics of this link are described in
+ [Consuming Messages via Pull](#message-pull).
+
+- `msg-push-consumers`. This is a URL for registering other URLs you
+ want the ActiveMQ REST server to push messages to. The semantics of
+ this link are described in [Pushing Messages](#message-push).
+
+Topic Resource Response Headers
+-------------------------------
+
+Below is a list of response headers you should expect when interacting
+with a Topic resource.
+
+- `msg-create`. This is a URL you POST messages to. The semantics of
+ this link are described in [Posting Messages](#posting-messages).
+
+- `msg-create-with-id`. This is a URL *template* you can use to POST
+ messages. The semantics of this link are described in [Posting
+ Messages](#posting-messages).
+
+- `msg-pull-subscriptions`. This is a URL for creating subscribers
+ that will pull from a topic. The semantics of this link are
+ described in [Consuming Messages via Pull](#message-pull).
+
+- `msg-push-subscriptions`. This is a URL for registering other URLs
+ you want the ActiveMQ REST server to push messages to. The semantics
+ of this link are described in [Pushing Messages](#message-push).
+
+Posting Messages
+================
+
+This chapter discusses the protocol for posting messages to a queue or a
+topic. In [ActiveMQ REST Interface Basics](#basics), you saw that a
+queue or topic resource publishes variable custom headers that are links
+to other RESTful resources. The `msg-create` header is a URL you can
+post a message to. Messages are published to a queue or topic by sending
+a simple HTTP message to the URL published by the `msg-create` header.
+The HTTP message contains whatever content you want to publish to the
+ActiveMQ destination. Here's an example scenario:
+
+> **Note**
+>
+> You can also post messages to the URL template found in
+> `msg-create-with-id`, but this is a more advanced use-case involving
+> duplicate detection that we will discuss later in this section.
+
+1. Obtain the starting `msg-create` header from the queue or topic
+ resource.
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+
+2. Do a POST to the URL contained in the `msg-create` header.
+
+ POST /queues/jms.queue.bar/create
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone4</name>
+ <cost>$199.99</cost>
+ </order>
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ msg-create-next: http://example.com/queues/jms.queue.bar/create
+
+ > **Note**
+ >
+ > You can use the "curl" utility to test this easily. Simply execute
+ > a command like this:
+ >
+ > curl --verbose --data "123" http://example.com/queues/jms.queue.bar/create
+
+ A successful response will return a 201 response code. Also notice
+ that a `msg-create-next` response header is sent as well. You must
+ use this URL to POST your next message.
+
+3. POST your next message to the queue using the URL returned in the
+ `msg-create-next` header.
+
+ POST /queues/jms.queue.bar/create
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Monica</name>
+ <item>iPad</item>
+ <cost>$499.99</cost>
+ </order>
+
+ --- Response --
+ HTTP/1.1 201 Created
+ msg-create-next: http://example.com/queues/jms.queue.bar/create
+
+ Continue using the new `msg-create-next` header returned with each
+ response.
+
+> **Warning**
+>
+> It is *VERY IMPORTANT* that you never re-use returned
+> `msg-create-next` headers to post new messages. If the `dups-ok`
+> configuration property is set to `false` on the server then this URL
+> will be uniquely generated for each message and used for duplicate
+> detection. If you lose the URL within the `msg-create-next` header,
+> then just go back to the queue or topic resource to get the
+> `msg-create` URL again.
+
+Duplicate Detection
+-------------------
+
+Sometimes you might have network problems when posting new messages to a
+queue or topic. You may do a POST and never receive a response.
+Unfortunately, you don't know whether or not the server received the
+message and so a re-post of the message might cause duplicates to be
+posted to the queue or topic. By default, the ActiveMQ REST interface is
+configured to accept and post duplicate messages. You can change this by
+turning on duplicate message detection by setting the `dups-ok` config
+option to `false` as described in [ActiveMQ REST Interface
+Basics](#basics). When you do this, the initial POST to the `msg-create`
+URL will redirect you, using the standard HTTP 307 redirection mechanism
+to a unique URL to POST to. All other interactions remain the same as
+discussed earlier. Here's an example:
+
+1. Obtain the starting `msg-create` header from the queue or topic
+ resource.
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+
+2. Do a POST to the URL contained in the `msg-create` header.
+
+ POST /queues/jms.queue.bar/create
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone4</name>
+ <cost>$199.99</cost>
+ </order>
+
+ --- Response ---
+ HTTP/1.1 307 Redirect
+ Location: http://example.com/queues/jms.queue.bar/create/13582001787372
+
+ A successful response will return a 307 response code. This is
+ standard HTTP protocol. It is telling you that you must re-POST to
+ the URL contained within the `Location` header.
+
+3. re-POST your message to the URL provided within the `Location`
+ header.
+
+ POST /queues/jms.queue.bar/create/13582001787372
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone4</name>
+ <cost>$199.99</cost>
+ </order>
+
+ --- Response --
+ HTTP/1.1 201 Created
+ msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787373
+
+ You should receive a 201 Created response. If there is a network
+ failure, just re-POST to the Location header. For new messages, use
+ the returned `msg-create-next` header returned with each response.
+
+4. POST any new message to the returned `msg-create-next` header.
+
+ POST /queues/jms.queue.bar/create/13582001787373
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Monica</name>
+ <item>iPad</name>
+ <cost>$499.99</cost>
+ </order>
+
+ --- Response --
+ HTTP/1.1 201 Created
+ msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374
+
+ If there ever is a network problem, just repost to the URL provided
+ in the `msg-create-next` header.
+
+How can this work? As you can see, with each successful response, the
+ActiveMQ REST server returns a uniquely generated URL within the
+msg-create-next header. This URL is dedicated to the next new message
+you want to post. Behind the scenes, the code extracts an identify from
+the URL and uses ActiveMQ's duplicate detection mechanism by setting the
+`DUPLICATE_DETECTION_ID` property of the JMS message that is actually
+posted to the system.
+
+If you happen to use the same ID more than once you'll see a message
+like this on the server:
+
+ WARN [org.apache.activemq.core.server] (Thread-3 (ActiveMQ-remoting-threads-ActiveMQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) HQ112098: Duplicate message detected - message will not be routed. Message information:
+ ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _HQ_DUPL_ID=42}]]@12835058
+
+An alternative to this approach is to use the `msg-create-with-id`
+header. This is not an invokable URL, but a URL template. The idea is
+that the client provides the `DUPLICATE_DETECTION_ID` and creates its
+own `create-next` URL. The `msg-create-with-id` header looks like this
+(you've see it in previous examples, but we haven't used it):
+
+ msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+
+You see that it is a regular URL appended with a `{id}`. This `{id}` is
+a pattern matching substring. A client would generate its
+`DUPLICATE_DETECTION_ID` and replace `{id}` with that generated id, then
+POST to the new URL. The URL the client creates works exactly like a
+`create-next` URL described earlier. The response of this POST would
+also return a new `msg-create-next` header. The client can continue to
+generate its own DUPLICATE\_DETECTION\_ID, or use the new URL returned
+via the `msg-create-nex`t header.
+
+The advantage of this approach is that the client does not have to
+repost the message. It also only has to come up with a unique
+`DUPLICATE_DETECTION_ID` once.
+
+Persistent Messages
+-------------------
+
+By default, posted messages are not durable and will not be persisted in
+ActiveMQ's journal. You can create durable messages by modifying the
+default configuration as expressed in Chapter 2 so that all messages are
+persisted when sent. Alternatively, you can set a URL query parameter
+called `durable` to true when you post your messages to the URLs
+returned in the `msg-create`, `msg-create-with-id`, or `msg-create-next`
+headers. here's an example of that.
+
+ POST /queues/jms.queue.bar/create?durable=true
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone4</item>
+ <cost>$199.99</cost>
+ </order>
+
+TTL, Expiration and Priority
+----------------------------
+
+You can set the time to live, expiration, and/or the priority of the
+message in the queue or topic by setting an additional query parameter.
+The `expiration` query parameter is an long specify the time in
+milliseconds since epoch (a long date). The `ttl` query parameter is a
+time in milliseconds you want the message active. The `priority` is
+another query parameter with an integer value between 0 and 9 expressing
+the priority of the message. i.e.:
+
+ POST /queues/jms.queue.bar/create?expiration=30000&priority=3
+ Host: example.com
+ Content-Type: application/xml
+
+ <order>
+ <name>Bill</name>
+ <item>iPhone4</item>
+ <cost>$199.99</cost>
+ </order>
+
+Consuming Messages via Pull
+===========================
+
+There are two different ways to consume messages from a topic or queue.
+You can wait and have the messaging server push them to you, or you can
+continuously poll the server yourself to see if messages are available.
+This chapter discusses the latter. Consuming messages via a pull works
+almost identically for queues and topics with some minor, but important
+caveats. To start consuming you must create a consumer resource on the
+server that is dedicated to your client. Now, this pretty much breaks
+the stateless principle of REST, but after much prototyping, this is the
+best way to work most effectively with ActiveMQ through a REST
+interface.
+
+You create consumer resources by doing a simple POST to the URL
+published by the `msg-pull-consumers` response header if you are
+interacting with a queue, the `msg-pull-subscribers` response header if
+you're interacting with a topic. These headers are provided by the main
+queue or topic resource discussed in [ActiveMQ REST Interface
+Basics](#basics). Doing an empty POST to one of these URLs will create a
+consumer resource that follows an auto-acknowledge protocol and, if you
+are interacting with a topic, creates a temporarily subscription to the
+topic. If you want to use the acknowledgement protocol and/or create a
+durable subscription (topics only), then you must use the form
+parameters (`application/x-www-form-urlencoded`) described below.
+
+- `autoAck`. A value of `true` or `false` can be given. This defaults
+ to `true` if you do not pass this parameter.
+
+- `durable`. A value of `true` or `false` can be given. This defaults
+ to `false` if you do not pass this parameter. Only available on
+ topics. This specifies whether you want a durable subscription or
+ not. A durable subscription persists through server restart.
+
+- `name`. This is the name of the durable subscription. If you do not
+ provide this parameter, the name will be automatically generated by
+ the server. Only usable on topics.
+
+- `selector`. This is an optional JMS selector string. The ActiveMQ
+ REST interface adds HTTP headers to the JMS message for REST
+ produced messages. HTTP headers are prefixed with "http\_" and every
+ '-' character is converted to a '\$'.
+
+- `idle-timeout`. For a topic subscription, idle time in milliseconds
+ in which the consumer connections will be closed if idle.
+
+- `delete-when-idle`. Boolean value, If true, a topic subscription
+ will be deleted (even if it is durable) when an the idle timeout is
+ reached.
+
+> **Note**
+>
+> If you have multiple pull-consumers active at the same time on the
+> same destination be aware that unless the `consumer-window-size` is 0
+> then one consumer might buffer messages while the other consumer gets
+> none.
+
+Auto-Acknowledge
+----------------
+
+This section focuses on the auto-acknowledge protocol for consuming
+messages via a pull. Here's a list of the response headers and URLs
+you'll be interested in.
+
+- `msg-pull-consumers`. The URL of a factory resource for creating
+ queue consumer resources. You will pull from these created
+ resources.
+
+- `msg-pull-subscriptions`. The URL of a factory resource for creating
+ topic subscription resources. You will pull from the created
+ resources.
+
+- `msg-consume-next`. The URL you will pull the next message from.
+ This is returned with every response.
+
+- `msg-consumer`. This is a URL pointing back to the consumer or
+ subscription resource created for the client.
+
+### Creating an Auto-Ack Consumer or Subscription
+
+Here is an example of creating an auto-acknowledged queue pull consumer.
+
+1. Find the pull-consumers URL by doing a HEAD or GET request to the
+ base queue resource.
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+
+2. Next do an empty POST to the URL returned in the
+ `msg-pull-consumers` header.
+
+ POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
+ Host: example.com
+
+ --- response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333
+ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333/consume-next-1
+
+ The `Location` header points to the JMS consumer resource that was
+ created on the server. It is good to remember this URL, although, as
+ you'll see later, it is transmitted with each response just to
+ remind you.
+
+Creating an auto-acknowledged consumer for a topic is pretty much the
+same. Here's an example of creating a durable auto-acknowledged topic
+pull subscription.
+
+1. Find the `pull-subscriptions` URL by doing a HEAD or GET request to
+ the base topic resource
+
+ HEAD /topics/jms.topic.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/topics/jms.topic.foo/create
+ msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions
+
+2. Next do a POST to the URL returned in the `msg-pull-subscriptions`
+ header passing in a `true` value for the `durable` form parameter.
+
+ POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
+ Host: example.com
+ Content-Type: application/x-www-form-urlencoded
+
+ durable=true
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222
+ msg-consume-next:
+ http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222/consume-next-1
+
+ The `Location` header points to the JMS subscription resource that
+ was created on the server. It is good to remember this URL,
+ although, as you'll see later, it is transmitted with each response
+ just to remind you.
+
+### Consuming Messages
+
+After you have created a consumer resource, you are ready to start
+pulling messages from the server. Notice that when you created the
+consumer for either the queue or topic, the response contained a
+`msg-consume-next` response header. POST to the URL contained within
+this header to consume the next message in the queue or topic
+subscription. A successful POST causes the server to extract a message
+from the queue or topic subscription, acknowledge it, and return it to
+the consuming client. If there are no messages in the queue or topic
+subscription, a 503 (Service Unavailable) HTTP code is returned.
+
+> **Warning**
+>
+> For both successful and unsuccessful posts to the msg-consume-next
+> URL, the response will contain a new msg-consume-next header. You must
+> ALWAYS use this new URL returned within the new msg-consume-next
+> header to consume new messages.
+
+Here's an example of pulling multiple messages from the consumer
+resource.
+
+1. Do a POST on the msg-consume-next URL that was returned with the
+ consumer or subscription resource discussed earlier.
+
+ POST /queues/jms.queue.bar/pull-consumers/consume-next-1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ Content-Type: application/xml
+ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2
+ msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
+
+ <order>...</order>
+
+ The POST returns the message consumed from the queue. It also
+ returns a new msg-consume-next link. Use this new link to get the
+ next message. Notice also a msg-consumer response header is
+ returned. This is a URL that points back to the consumer or
+ subscription resource. You will need that to clean up your
+ connection after you are finished using the queue or topic.
+
+2. The POST returns the message consumed from the queue. It also
+ returns a new msg-consume-next link. Use this new link to get the
+ next message.
+
+ POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ Host: example.com
+
+ --- Response ---
+ Http/1.1 503 Service Unavailable
+ Retry-After: 5
+ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2
+
+ In this case, there are no messages in the queue, so we get a 503
+ response back. As per the HTTP 1.1 spec, a 503 response may return a
+ Retry-After head specifying the time in seconds that you should
+ retry a post. Also notice, that another new msg-consume-next URL is
+ present. Although it probably is the same URL you used last post,
+ get in the habit of using URLs returned in response headers as
+ future versions of ActiveMQ REST might be redirecting you or adding
+ additional data to the URL after timeouts like this.
+
+3. POST to the URL within the last `msg-consume-next` to get the next
+ message.
+
+ POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ Content-Type: application/xml
+ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
+
+ <order>...</order>
+
+### Recovering From Network Failures
+
+If you experience a network failure and do not know if your post to a
+msg-consume-next URL was successful or not, just re-do your POST. A POST
+to a msg-consume-next URL is idempotent, meaning that it will return the
+same result if you execute on any one msg-consume-next URL more than
+once. Behind the scenes, the consumer resource caches the last consumed
+message so that if there is a message failure and you do a re-post, the
+cached last message will be returned (along with a new msg-consume-next
+URL). This is the reason why the protocol always requires you to use the
+next new msg-consume-next URL returned with each response. Information
+about what state the client is in is embedded within the actual URL.
+
+### Recovering From Client or Server Crashes
+
+If the server crashes and you do a POST to the msg-consume-next URL, the
+server will return a 412 (Preconditions Failed) response code. This is
+telling you that the URL you are using is out of sync with the server.
+The response will contain a new msg-consume-next header to invoke on.
+
+If the client crashes there are multiple ways you can recover. If you
+have remembered the last msg-consume-next link, you can just re-POST to
+it. If you have remembered the consumer resource URL, you can do a GET
+or HEAD request to obtain a new msg-consume-next URL. If you have
+created a topic subscription using the name parameter discussed earlier,
+you can re-create the consumer. Re-creation will return a
+msg-consume-next URL you can use. If you cannot do any of these things,
+you will have to create a new consumer.
+
+The problem with the auto-acknowledge protocol is that if the client or
+server crashes, it is possible for you to skip messages. The scenario
+would happen if the server crashes after auto-acknowledging a message
+and before the client receives the message. If you want more reliable
+messaging, then you must use the acknowledgement protocol.
+
+Manual Acknowledgement
+----------------------
+
+The manual acknowledgement protocol is similar to the auto-ack protocol
+except there is an additional round trip to the server to tell it that
+you have received the message and that the server can internally ack the
+message. Here is a list of the response headers you will be interested
+in.
+
+- `msg-pull-consumers`. The URL of a factory resource for creating
+ queue consumer resources. You will pull from these created resources
+
+- `msg-pull-subscriptions`. The URL of a factory resource for creating
+ topic subscription resources. You will pull from the created
+ resources.
+
+- `msg-acknowledge-next`. URL used to obtain the next message in the
+ queue or topic subscription. It does not acknowledge the message
+ though.
+
+- `msg-acknowledgement`. URL used to acknowledge a message.
+
+- `msg-consumer`. This is a URL pointing back to the consumer or
+ subscription resource created for the client.
+
+### Creating manually-acknowledged consumers or subscriptions
+
+Here is an example of creating an auto-acknowledged queue pull consumer.
+
+1. Find the pull-consumers URL by doing a HEAD or GET request to the
+ base queue resource.
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+
+2. Next do a POST to the URL returned in the `msg-pull-consumers`
+ header passing in a `false` value to the `autoAck` form parameter .
+
+ POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
+ Host: example.com
+ Content-Type: application/x-www-form-urlencoded
+
+ autoAck=false
+
+ --- response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333
+ msg-acknowledge-next: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333/acknowledge-next-1
+
+ The `Location` header points to the JMS consumer resource that was
+ created on the server. It is good to remember this URL, although, as
+ you'll see later, it is transmitted with each response just to
+ remind you.
+
+Creating an manually-acknowledged consumer for a topic is pretty much
+the same. Here's an example of creating a durable manually-acknowledged
+topic pull subscription.
+
+1. Find the `pull-subscriptions` URL by doing a HEAD or GET request to
+ the base topic resource
+
+ HEAD /topics/jms.topic.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/topics/jms.topic.foo/create
+ msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions
+
+2. Next do a POST to the URL returned in the `msg-pull-subscriptions`
+ header passing in a `true` value for the `durable` form parameter
+ and a `false` value to the `autoAck` form parameter.
+
+ POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
+ Host: example.com
+ Content-Type: application/x-www-form-urlencoded
+
+ durable=true&autoAck=false
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222
+ msg-acknowledge-next:
+ http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222/consume-next-1
+
+ The `Location` header points to the JMS subscription resource that
+ was created on the server. It is good to remember this URL,
+ although, as you'll see later, it is transmitted with each response
+ just to remind you.
+
+### Consuming and Acknowledging a Message
+
+After you have created a consumer resource, you are ready to start
+pulling messages from the server. Notice that when you created the
+consumer for either the queue or topic, the response contained a
+`msg-acknowledge-next` response header. POST to the URL contained within
+this header to consume the next message in the queue or topic
+subscription. If there are no messages in the queue or topic
+subscription, a 503 (Service Unavailable) HTTP code is returned. A
+successful POST causes the server to extract a message from the queue or
+topic subscription and return it to the consuming client. It does not
+acknowledge the message though. The response will contain the
+`acknowledgement` header which you will use to acknowledge the message.
+
+Here's an example of pulling multiple messages from the consumer
+resource.
+
+1. Do a POST on the msg-acknowledge-next URL that was returned with the
+ consumer or subscription resource discussed earlier.
+
+ POST /queues/jms.queue.bar/pull-consumers/consume-next-1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ Content-Type: application/xml
+ msg-acknowledgement:
+ http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledgement/2
+ msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
+
+ <order>...</order>
+
+ The POST returns the message consumed from the queue. It also
+ returns a`msg-acknowledgemen`t link. You will use this new link to
+ acknowledge the message. Notice also a `msg-consumer` response
+ header is returned. This is a URL that points back to the consumer
+ or subscription resource. You will need that to clean up your
+ connection after you are finished using the queue or topic.
+
+2. Acknowledge or unacknowledge the message by doing a POST to the URL
+ contained in the `msg-acknowledgement` header. You must pass an
+ `acknowledge` form parameter set to `true` or `false` depending on
+ whether you want to acknowledge or unacknowledge the message on the
+ server.
+
+ POST /queues/jms.queue.bar/pull-consumers/acknowledgement/2
+ Host: example.com
+ Content-Type: application/x-www-form-urlencoded
+
+ acknowledge=true
+
+ --- Response ---
+ Http/1.1 200 Ok
+ msg-acknowledge-next:
+ http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledge-next-2
+
+ Whether you acknowledge or unacknowledge the message, the response
+ will contain a new msg-acknowledge-next header that you must use to
+ obtain the next message.
+
+### Recovering From Network Failures
+
+If you experience a network failure and do not know if your post to a
+`msg-acknowledge-next` or `msg-acknowledgement` URL was successful or
+not, just re-do your POST. A POST to one of these URLs is idempotent,
+meaning that it will return the same result if you re-post. Behind the
+scenes, the consumer resource keeps track of its current state. If the
+last action was a call to`msg-acknowledge-next`, it will have the last
+message cached, so that if a re-post is done, it will return the message
+again. Same goes with re-posting to `msg-acknowledgement`. The server
+remembers its last state and will return the same results. If you look
+at the URLs you'll see that they contain information about the expected
+current state of the server. This is how the server knows what the
+client is expecting.
+
+### Recovering From Client or Server Crashes
+
+If the server crashes and while you are doing a POST to the
+`msg-acknowledge-next` URL, just re-post. Everything should reconnect
+all right. On the other hand, if the server crashes while you are doing
+a POST to`msg-acknowledgement`, the server will return a 412
+(Preconditions Failed) response code. This is telling you that the URL
+you are using is out of sync with the server and the message you are
+acknowledging was probably re-enqueued. The response will contain a new
+`msg-acknowledge-next` header to invoke on.
+
+As long as you have "bookmarked" the consumer resource URL (returned
+from `Location` header on a create, or the `msg-consumer` header), you
+can recover from client crashes by doing a GET or HEAD request on the
+consumer resource to obtain what state you are in. If the consumer
+resource is expecting you to acknowledge a message, it will return a
+`msg-acknowledgement` header in the response. If the consumer resource
+is expecting you to pull for the next message, the
+`msg-acknowledge-next` header will be in the response. With manual
+acknowledgement you are pretty much guaranteed to avoid skipped
+messages. For topic subscriptions that were created with a name
+parameter, you do not have to "bookmark" the returned URL. Instead, you
+can re-create the consumer resource with the same exact name. The
+response will contain the same information as if you did a GET or HEAD
+request on the consumer resource.
+
+Blocking Pulls with Accept-Wait
+-------------------------------
+
+Unless your queue or topic has a high rate of message flowing though it,
+if you use the pull protocol, you're going to be receiving a lot of 503
+responses as you continuously pull the server for new messages. To
+alleviate this problem, the ActiveMQ REST interface provides the
+`Accept-Wait` header. This is a generic HTTP request header that is a
+hint to the server for how long the client is willing to wait for a
+response from the server. The value of this header is the time in
+seconds the client is willing to block for. You would send this request
+header with your pull requests. Here's an example:
+
+ POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ Host: example.com
+ Accept-Wait: 30
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ Content-Type: application/xml
+ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
+
+ <order>...</order>
+
+In this example, we're posting to a msg-consume-next URL and telling the
+server that we would be willing to block for 30 seconds.
+
+Clean Up Your Consumers!
+------------------------
+
+When the client is done with its consumer or topic subscription it
+should do an HTTP DELETE call on the consumer URL passed back from the
+Location header or the msg-consumer response header. The server will
+time out a consumer with the value of `consumer-session-timeout-seconds`
+configured from [REST configuration](#configuration), so you don't have
+to clean up if you don't want to, but if you are a good kid, you will
+clean up your messes. A consumer timeout for durable subscriptions will
+not delete the underlying durable JMS subscription though, only the
+server-side consumer resource (and underlying JMS session).
+
+Pushing Messages
+================
+
+You can configure the ActiveMQ REST server to push messages to a
+registered URL either remotely through the REST interface, or by
+creating a pre-configured XML file for the ActiveMQ REST server to load
+at boot time.
+
+The Queue Push Subscription XML
+-------------------------------
+
+Creating a push consumer for a queue first involves creating a very
+simple XML document. This document tells the server if the push
+subscription should survive server reboots (is it durable). It must
+provide a URL to ship the forwarded message to. Finally, you have to
+provide authentication information if the final endpoint requires
+authentication. Here's a simple example:
+
+ <push-registration>
+ <durable>false</durable>
+ <selector><![CDATA[
+ SomeAttribute > 1
+ ]]>
+ </selector>
+ <link rel="push" href="http://somewhere.com" type="application/json" method="PUT"/>
+ <maxRetries>5</maxRetries>
+ <retryWaitMillis>1000</retryWaitMillis>
+ <disableOnFailure>true</disableOnFailure>
+ </push-registration>
+
+The `durable` element specifies whether the registration should be saved
+to disk so that if there is a server restart, the push subscription will
+still work. This element is not required. If left out it defaults
+to`false`. If durable is set to true, an XML file for the push
+subscription will be created within the directory specified by the
+`queue-push-store-dir` config variable defined in Chapter 2
+(`topic-push-store-dir` for topics).
+
+The `selector` element is optional and defines a JMS message selector.
+You should enclose it within CDATA blocks as some of the selector
+characters are illegal XML.
+
+The `maxRetries` element specifies how many times a the server will try
+to push a message to a URL if there is a connection failure.
+
+The `retryWaitMillis` element specifies how long to wait before
+performing a retry.
+
+The `disableOnFailure` element, if set to true, will disable the
+registration if all retries have failed. It will not disable the
+connection on non-connection-failure issues (like a bad request for
+instance). In these cases, the dead letter queue logic of ActiveMQ will
+take over.
+
+The `link` element specifies the basis of the interaction. The `href`
+attribute contains the URL you want to interact with. It is the only
+required attribute. The `type` attribute specifies the content-type of
+what the push URL is expecting. The `method` attribute defines what HTTP
+method the server will use when it sends the message to the server. If
+it is not provided it defaults to POST. The `rel` attribute is very
+important and the value of it triggers different behavior. Here's the
+values a rel attribute can have:
+
+- `destination`. The href URL is assumed to be a queue or topic
+ resource of another ActiveMQ REST server. The push registration will
+ initially do a HEAD request to this URL to obtain a
+ msg-create-with-id header. It will use this header to push new
+ messages to the ActiveMQ REST endpoint reliably. Here's an example:
+
+ <push-registration>
+ <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
+ </push-registration>
+
+- `template`. In this case, the server is expecting the link element's
+ href attribute to be a URL expression. The URL expression must have
+ one and only one URL parameter within it. The server will use a
+ unique value to create the endpoint URL. Here's an example:
+
+ <push-registration>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
+ </push-registration>
+
+ In this example, the {id} sub-string is the one and only one URL
+ parameter.
+
+- `user defined`. If the rel attributes is not destination or template
+ (or is empty or missing), then the server will send an HTTP message
+ to the href URL using the HTTP method defined in the method
+ attribute. Here's an example:
+
+ <push-registration>
+ <link href="http://somewhere.com" type="application/json" method="PUT"/>
+ </push-registration>
+
+The Topic Push Subscription XML
+-------------------------------
+
+The push XML for a topic is the same except the root element is
+push-topic-registration. (Also remember the `selector` element is
+optional). The rest of the document is the same. Here's an example of a
+template registration:
+
+ <push-topic-registration>
+ <durable>true</durable>
+ <selector><![CDATA[
+ SomeAttribute > 1
+ ]]>
+ </selector>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
+ </push-topic registration>
+
+Creating a Push Subscription at Runtime
+---------------------------------------
+
+Creating a push subscription at runtime involves getting the factory
+resource URL from the msg-push-consumers header, if the destination is a
+queue, or msg-push-subscriptions header, if the destination is a topic.
+Here's an example of creating a push registration for a queue:
+
+1. First do a HEAD request to the queue resource:
+
+ HEAD /queues/jms.queue.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/queues/jms.queue.bar/create
+ msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+
+2. Next POST your subscription XML to the URL returned from
+ msg-push-consumers header
+
+ POST /queues/jms.queue.bar/push-consumers
+ Host: example.com
+ Content-Type: application/xml
+
+ <push-registration>
+ <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
+ </push-registration>
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/queues/jms.queue.bar/push-consumers/1-333-1212
+
+ The Location header contains the URL for the created resource. If
+ you want to unregister this, then do a HTTP DELETE on this URL.
+
+Here's an example of creating a push registration for a topic:
+
+1. First do a HEAD request to the topic resource:
+
+ HEAD /topics/jms.topic.bar HTTP/1.1
+ Host: example.com
+
+ --- Response ---
+ HTTP/1.1 200 Ok
+ msg-create: http://example.com/topics/jms.topic.bar/create
+ msg-pull-subscriptions: http://example.com/topics/jms.topic.bar/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/jms.topic.bar/push-subscriptions
+
+2. Next POST your subscription XML to the URL returned from
+ msg-push-subscriptions header
+
+ POST /topics/jms.topic.bar/push-subscriptions
+ Host: example.com
+ Content-Type: application/xml
+
+ <push-registration>
+ <link rel="template" href="http://somewhere.com/resources/{id}"/>
+ </push-registration>
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212
+
+ The Location header contains the URL for the created resource. If
+ you want to unregister this, then do a HTTP DELETE on this URL.
+
+Creating a Push Subscription by Hand
+------------------------------------
+
+You can create a push XML file yourself if you do not want to go through
+the REST interface to create a push subscription. There is some
+additional information you need to provide though. First, in the root
+element, you must define a unique id attribute. You must also define a
+destination element to specify the queue you should register a consumer
+with. For a topic, the destination element is the name of the
+subscription that will be created. For a topic, you must also specify
+the topic name within the topic element.
+
+Here's an example of a hand-created queue registration. This file must
+go in the directory specified by the queue-push-store-dir config
+variable defined in Chapter 2:
+
+ <push-registration id="111">
+ <destination>jms.queue.bar</destination>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
+ </push-registration>
+
+Here's an example of a hand-created topic registration. This file must
+go in the directory specified by the topic-push-store-dir config
+variable defined in Chapter 2:
+
+ <push-topic-registration id="112">
+ <destination>my-subscription-1</destination
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
+ <topic>jms.topic.foo</topic>
+ </push-topic-registration>
+
+Pushing to Authenticated Servers
+--------------------------------
+
+Push subscriptions only support BASIC and DIGEST authentication out of
+the box. Here is an example of adding BASIC authentication:
+
+ <push-topic-registration>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
+ <authentication>
+ <basic-auth>
+ <username>guest</username>
+ <password>geheim</password>
+ </basic-auth>
+ </authentication>
+ </push-topic registration>
+
+For DIGEST, just replace basic-auth with digest-auth.
+
+For other authentication mechanisms, you can register headers you want
+transmitted with each request. Use the header element with the name
+attribute representing the name of the header. Here's what custom
+headers might look like:
+
+ <push-topic-registration>
+ <durable>true</durable>
+ <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
+ <header name="secret-header">jfdiwe3321</header>
+ </push-topic registration>
+
+Creating Destinations
+=====================
+
+You can create a durable queue or topic through the REST interface.
+Currently you cannot create a temporary queue or topic. To create a
+queue you do a POST to the relative URL /queues with an XML
+representation of the queue. The XML syntax is the same queue syntax
+that you would specify in activemq-jms.xml if you were creating a queue
+there. For example:
+
+ POST /queues
+ Host: example.com
+ Content-Type: application/activemq.jms.queue+xml
+
+ <queue name="testQueue">
+ <durable>true</durable>
+ </queue>
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/queues/jms.queue.testQueue
+
+Notice that the Content-Type is application/activemq.jms.queue+xml.
+
+Here's what creating a topic would look like:
+
+ POST /topics
+ Host: example.com
+ Content-Type: application/activemq.jms.topic+xml
+
+ <topic name="testTopic">
+ </topic>
+
+ --- Response ---
+ HTTP/1.1 201 Created
+ Location: http://example.com/topics/jms.topic.testTopic
+
+Securing the ActiveMQ REST Interface
+====================================
+
+Within JBoss Application server
+-------------------------------
+
+Securing the ActiveMQ REST interface is very simple with the JBoss
+Application Server. You turn on authentication for all URLs within your
+WAR's web.xml, and let the user Principal to propagate to ActiveMQ. This
+only works if you are using the JBossSecurityManager with ActiveMQ. See
+the ActiveMQ documentation for more details.
+
+Security in other environments
+------------------------------
+
+To secure the ActiveMQ REST interface in other environments you must
+role your own security by specifying security constraints with your
+web.xml for every path of every queue and topic you have deployed. Here
+is a list of URI patterns:
+
+ -------------------------------------------- -----------------------------------------------------------------------
+ /queues secure the POST operation to secure queue creation
+ /queues/{queue-name} secure the GET HEAD operation to getting information about the queue.
+ /queues/{queue-name}/create/\* secure this URL pattern for producing messages.
+ /queues/{queue-name}/pull-consumers/\* secure this URL pattern for pulling messages.
+ /queues/{queue-name}/push-consumers/\* secure this URL pattern for pushing messages.
+ /topics secure the POST operation to secure topic creation
+ /topics/{topic-name} secure the GET HEAD operation to getting information about the topic.
+ /topics/{topic-name}/create/\* secure this URL pattern for producing messages.
+ /topics/{topic-name}/pull-subscriptions/\* secure this URL pattern for pulling messages.
+ /topics/{topic-name}/push-subscriptions/\* secure this URL pattern for pushing messages.
+ -------------------------------------------- -----------------------------------------------------------------------
+
+Mixing JMS and REST
+===================
+
+The ActiveMQ REST interface supports mixing JMS and REST producers and
+consumers. You can send an ObjectMessage through a JMS Producer, and
+have a REST client consume it. You can have a REST client POST a message
+to a topic and have a JMS Consumer receive it. Some simple
+transformations are supported if you have the correct RESTEasy providers
+installed.
+
+JMS Producers - REST Consumers
+------------------------------
+
+If you have a JMS producer, the ActiveMQ REST interface only supports
+ObjectMessage type. If the JMS producer is aware that there may be REST
+consumers, it should set a JMS property to specify what Content-Type the
+Java object should be translated into by REST clients. The ActiveMQ REST
+server will use RESTEasy content handlers (MessageBodyReader/Writers) to
+transform the Java object to the type desired. Here's an example of a
+JMS producer setting the content type of the message.
+
+ ObjectMessage message = session.createObjectMessage();
+ message.setStringProperty(org.apache.activemq.rest.HttpHeaderProperty.CONTENT_TYPE, "application/xml");
+
+If the JMS producer does not set the content-type, then this information
+must be obtained from the REST consumer. If it is a pull consumer, then
+the REST client should send an Accept header with the desired media
+types it wants to convert the Java object into. If the REST client is a
+push registration, then the type attribute of the link element of the
+push registration should be set to the desired type.
+
+REST Producers - JMS Consumers
+------------------------------
+
+If you have a REST client producing messages and a JMS consumer,
+ActiveMQ REST has a simple helper class for you to transform the HTTP
+body to a Java object. Here's some example code:
+
+ public void onMessage(Message message)
+ {
+ MyType obj = org.apache.activemq.rest.Jms.getEntity(message, MyType.class);
+ }
+
+The way the `getEntity()` method works is that if the message is an
+ObjectMessage, it will try to extract the desired type from it like any
+other JMS message. If a REST producer sent the message, then the method
+uses RESTEasy to convert the HTTP body to the Java object you want. See
+the Javadoc of this class for more helper methods.
[25/25] activemq-6 git commit: Merging #37 on changing docs to MD
Posted by cl...@apache.org.
Merging #37 on changing docs to MD
Project: http://git-wip-us.apache.org/repos/asf/activemq-6/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-6/commit/6309dd04
Tree: http://git-wip-us.apache.org/repos/asf/activemq-6/tree/6309dd04
Diff: http://git-wip-us.apache.org/repos/asf/activemq-6/diff/6309dd04
Branch: refs/heads/master
Commit: 6309dd042c898968efb47080b88af1ac713121fe
Parents: d42481d 4245a6b
Author: Clebert Suconic <cl...@apache.org>
Authored: Mon Dec 8 10:49:04 2014 -0500
Committer: Clebert Suconic <cl...@apache.org>
Committed: Mon Dec 8 10:49:04 2014 -0500
----------------------------------------------------------------------
distribution/activemq/src/main/assembly/dep.xml | 12 -
docs/design-guide/en/Author_Group.xml | 34 -
docs/design-guide/en/Book_Info.xml | 48 -
docs/design-guide/en/HornetQ_Design_Guide.ent | 5 -
docs/design-guide/en/HornetQ_Design_Guide.xml | 30 -
docs/design-guide/en/about.md | 4 +
docs/design-guide/en/about.xml | 28 -
docs/design-guide/en/clustering.md | 23 +
docs/design-guide/en/clustering.xml | 42 -
docs/design-guide/en/notice.md | 17 +
docs/design-guide/en/notice.xml | 41 -
docs/design-guide/pom.xml | 310 ---
docs/diagrams/standard_image.odg | Bin 11094 -> 0 bytes
docs/eap-manual/en/Author_Group.xml | 35 -
docs/eap-manual/en/Book_Info.xml | 49 -
docs/eap-manual/en/HornetQ_EAP_Manual.ent | 7 -
docs/eap-manual/en/HornetQ_EAP_Manual.xml | 29 -
docs/eap-manual/en/clusters.xml | 573 -----
docs/eap-manual/en/diagrams/ha-topologies1.odg | Bin 14529 -> 0 bytes
docs/eap-manual/en/images/simple-colocated.jpg | Bin 94996 -> 0 bytes
docs/eap-manual/en/images/simple-colocated2.jpg | Bin 124592 -> 0 bytes
docs/eap-manual/en/images/simple-colocated3.jpg | Bin 162357 -> 0 bytes
.../en/images/simple-dedicated-jca-remote.jpg | Bin 65959 -> 0 bytes
.../en/images/simple-dedicated-jca.jpg | Bin 100349 -> 0 bytes
docs/eap-manual/en/images/simple-dedicated.jpg | Bin 49812 -> 0 bytes
docs/eap-manual/en/master.xml | 0
docs/eap-manual/pom.xml | 309 ---
docs/pom.xml | 55 -
.../en/ActiveMQ_QuickStart_Guide.ent | 5 -
.../en/ActiveMQ_QuickStart_Guide.xml | 17 -
docs/quickstart-guide/en/Author_Group.xml | 45 -
docs/quickstart-guide/en/Book_Info.xml | 31 -
docs/quickstart-guide/en/README.md | 4 +
docs/quickstart-guide/en/SUMMARY.md | 7 +
docs/quickstart-guide/en/about.md | 49 +
docs/quickstart-guide/en/about.xml | 83 -
docs/quickstart-guide/en/download.md | 36 +
docs/quickstart-guide/en/download.xml | 74 -
docs/quickstart-guide/en/examples.md | 314 +++
docs/quickstart-guide/en/examples.xml | 329 ---
.../en/images/hornetQ_logo_600px.png | Bin 23866 -> 0 bytes
docs/quickstart-guide/en/installation.md | 85 +
docs/quickstart-guide/en/installation.xml | 101 -
docs/quickstart-guide/en/introduction.md | 13 +
docs/quickstart-guide/en/introduction.xml | 32 -
docs/quickstart-guide/en/master.xml | 0
docs/quickstart-guide/en/migrate.sh | 6 +
docs/quickstart-guide/en/notice.md | 17 +
docs/quickstart-guide/en/notice.xml | 40 -
docs/quickstart-guide/en/running.md | 106 +
docs/quickstart-guide/en/running.xml | 124 -
docs/quickstart-guide/pom.xml | 300 ---
docs/user-manual/en/ActiveMQ_User_Manual.ent | 22 -
docs/user-manual/en/ActiveMQ_User_Manual.xml | 79 -
docs/user-manual/en/Author_Group.xml | 86 -
docs/user-manual/en/Book_Info.xml | 48 -
docs/user-manual/en/README.md | 7 +
docs/user-manual/en/SUMMARY.md | 53 +
docs/user-manual/en/aerogear-integration.md | 101 +
docs/user-manual/en/aerogear-integration.xml | 115 -
docs/user-manual/en/appserver-integration.md | 1031 +++++++++
docs/user-manual/en/appserver-integration.xml | 1338 -----------
docs/user-manual/en/architecture.md | 159 ++
docs/user-manual/en/architecture.xml | 151 --
docs/user-manual/en/book.json | 12 +
docs/user-manual/en/client-classpath.md | 32 +
docs/user-manual/en/client-classpath.xml | 51 -
docs/user-manual/en/client-reconnection.md | 149 ++
docs/user-manual/en/client-reconnection.xml | 147 --
docs/user-manual/en/clusters.md | 1059 +++++++++
docs/user-manual/en/clusters.xml | 998 --------
docs/user-manual/en/configuration-index.md | 273 +++
docs/user-manual/en/configuration-index.xml | 396 ----
docs/user-manual/en/configuring-transports.md | 462 ++++
docs/user-manual/en/configuring-transports.xml | 443 ----
docs/user-manual/en/connection-ttl.md | 198 ++
docs/user-manual/en/connection-ttl.xml | 202 --
docs/user-manual/en/core-bridges.md | 225 ++
docs/user-manual/en/core-bridges.xml | 241 --
docs/user-manual/en/diverts.md | 114 +
docs/user-manual/en/diverts.xml | 113 -
docs/user-manual/en/duplicate-detection.md | 161 ++
docs/user-manual/en/duplicate-detection.xml | 148 --
docs/user-manual/en/embedding-activemq.md | 225 ++
docs/user-manual/en/embedding-activemq.xml | 270 ---
docs/user-manual/en/examples.md | 826 +++++++
docs/user-manual/en/examples.xml | 693 ------
docs/user-manual/en/filter-expressions.md | 52 +
docs/user-manual/en/filter-expressions.xml | 86 -
docs/user-manual/en/flow-control.md | 304 +++
docs/user-manual/en/flow-control.xml | 290 ---
docs/user-manual/en/ha.md | 892 ++++++++
docs/user-manual/en/ha.xml | 985 --------
docs/user-manual/en/images/activemq-logo.jpg | Bin 0 -> 6819 bytes
docs/user-manual/en/intercepting-operations.md | 84 +
docs/user-manual/en/intercepting-operations.xml | 99 -
docs/user-manual/en/interoperability.md | 365 +++
docs/user-manual/en/interoperability.xml | 305 ---
docs/user-manual/en/jms-bridge.md | 460 ++++
docs/user-manual/en/jms-bridge.xml | 449 ----
docs/user-manual/en/jms-core-mapping.md | 39 +
docs/user-manual/en/jms-core-mapping.xml | 50 -
docs/user-manual/en/large-messages.md | 275 +++
docs/user-manual/en/large-messages.xml | 285 ---
docs/user-manual/en/last-value-queues.md | 55 +
docs/user-manual/en/last-value-queues.xml | 70 -
docs/user-manual/en/libaio.md | 109 +
docs/user-manual/en/libaio.xml | 129 --
docs/user-manual/en/logging.md | 93 +
docs/user-manual/en/logging.xml | 138 --
docs/user-manual/en/management.md | 1094 +++++++++
docs/user-manual/en/management.xml | 1117 ---------
docs/user-manual/en/message-expiry.md | 85 +
docs/user-manual/en/message-expiry.xml | 100 -
docs/user-manual/en/message-grouping.md | 198 ++
docs/user-manual/en/message-grouping.xml | 195 --
docs/user-manual/en/messaging-concepts.md | 312 +++
docs/user-manual/en/messaging-concepts.xml | 267 ---
docs/user-manual/en/notice.md | 17 +
docs/user-manual/en/notice.xml | 39 -
docs/user-manual/en/paging.md | 160 ++
docs/user-manual/en/paging.xml | 215 --
docs/user-manual/en/perf-tuning.md | 255 +++
docs/user-manual/en/perf-tuning.xml | 304 ---
docs/user-manual/en/persistence.md | 392 ++++
docs/user-manual/en/persistence.xml | 356 ---
docs/user-manual/en/pre-acknowledge.md | 92 +
docs/user-manual/en/pre-acknowledge.xml | 92 -
docs/user-manual/en/preface.md | 52 +
docs/user-manual/en/preface.xml | 86 -
docs/user-manual/en/project-info.md | 50 +
docs/user-manual/en/queue-attributes.md | 182 ++
docs/user-manual/en/queue-attributes.xml | 171 --
docs/user-manual/en/rest.md | 1570 +++++++++++++
docs/user-manual/en/rest.xml | 2150 ------------------
docs/user-manual/en/scheduled-messages.md | 36 +
docs/user-manual/en/scheduled-messages.xml | 53 -
docs/user-manual/en/security.md | 306 +++
docs/user-manual/en/security.xml | 287 ---
docs/user-manual/en/send-guarantees.md | 151 ++
docs/user-manual/en/send-guarantees.xml | 152 --
docs/user-manual/en/slow-consumers.md | 36 +
docs/user-manual/en/slow-consumers.xml | 52 -
docs/user-manual/en/spring-integration.md | 50 +
docs/user-manual/en/spring-integration.xml | 81 -
docs/user-manual/en/thread-pooling.md | 154 ++
docs/user-manual/en/thread-pooling.xml | 150 --
docs/user-manual/en/tools.md | 88 +
docs/user-manual/en/tools.xml | 116 -
docs/user-manual/en/transaction-config.md | 22 +
docs/user-manual/en/transaction-config.xml | 38 -
docs/user-manual/en/undelivered-messages.md | 166 ++
docs/user-manual/en/undelivered-messages.xml | 159 --
docs/user-manual/en/using-core.md | 222 ++
docs/user-manual/en/using-core.xml | 223 --
docs/user-manual/en/using-jms.md | 410 ++++
docs/user-manual/en/using-jms.xml | 364 ---
docs/user-manual/en/using-server.md | 204 ++
docs/user-manual/en/using-server.xml | 208 --
docs/user-manual/en/vertx-integration.md | 91 +
docs/user-manual/en/vertx-integration.xml | 114 -
docs/user-manual/en/wildcard-routing.md | 21 +
docs/user-manual/en/wildcard-routing.xml | 42 -
docs/user-manual/en/wildcard-syntax.md | 28 +
docs/user-manual/en/wildcard-syntax.xml | 43 -
docs/user-manual/pom.xml | 365 ---
docs/user-manual/publican.cfg | 7 -
.../src/main/resources/schemaToTable.xsl | 374 ---
pom.xml | 1 -
169 files changed, 14940 insertions(+), 19136 deletions(-)
----------------------------------------------------------------------
[16/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/connection-ttl.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/connection-ttl.xml b/docs/user-manual/en/connection-ttl.xml
deleted file mode 100644
index dceca73..0000000
--- a/docs/user-manual/en/connection-ttl.xml
+++ /dev/null
@@ -1,202 +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="connection-ttl">
- <title>Detecting Dead Connections</title>
- <para>In this section we will discuss connection time-to-live (TTL) and explain how ActiveMQ
- deals with crashed clients and clients which have exited without cleanly closing their
- resources.</para>
- <section id="dead.connections">
- <title>Cleaning up Dead Connection Resources on the Server</title>
- <para>Before a ActiveMQ client application exits it is considered good practice that it
- should close its resources in a controlled manner, using a <literal>finally</literal>
- block.</para>
- <para>Here's an example of a well behaved core client application closing its session and
- session factory in a finally block:</para>
- <programlisting>
-ServerLocator locator = null;
-ClientSessionFactory sf = null;
-ClientSession session = null;
-
-try
-{
- locator = ActiveMQClient.createServerLocatorWithoutHA(..);
-
- sf = locator.createClientSessionFactory();;
-
- session = sf.createSession(...);
-
- ... do some stuff with the session...
-}
-finally
-{
- if (session != null)
- {
- session.close();
- }
-
- if (sf != null)
- {
- sf.close();
- }
-
- if(locator != null)
- {
- locator.close();
- }
-}</programlisting>
- <para>And here's an example of a well behaved JMS client application:</para>
- <programlisting>
-Connection jmsConnection = null;
-
-try
-{
- ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
-
- jmsConnection = jmsConnectionFactory.createConnection();
-
- ... do some stuff with the connection...
-}
-finally
-{
- if (connection != null)
- {
- connection.close();
- }
-}</programlisting>
- <para>Unfortunately users don't always write well behaved applications, and sometimes
- clients just crash so they don't have a chance to clean up their resources!</para>
- <para>If this occurs then it can leave server side resources, like sessions, hanging on the
- server. If these were not removed they would cause a resource leak on the server and
- over time this result in the server running out of memory or other resources.</para>
- <para>We have to balance the requirement for cleaning up dead client resources with the fact
- that sometimes the network between the client and the server can fail and then come
- back, allowing the client to reconnect. ActiveMQ supports client reconnection, so we
- don't want to clean up "dead" server side resources too soon or this will prevent any
- client from reconnecting, as it won't be able to find its old sessions on the
- server.</para>
- <para>ActiveMQ makes all of this configurable. For each <literal
- >ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
- Basically, the TTL determines how long the server will keep a connection alive in the
- absence of any data arriving from the client. The client will automatically send "ping"
- packets periodically to prevent the server from closing it down. If the server doesn't
- receive any packets on a connection for the connection TTL time, then it will
- automatically close all the sessions on the server that relate to that
- connection.</para>
- <para>If you're using JMS, the connection TTL is defined by the <literal
- >ConnectionTTL</literal> attribute on a <literal>ActiveMQConnectionFactory</literal>
- instance, or if you're deploying JMS connection factory instances direct into JNDI on
- the server side, you can specify it in the xml config, using the parameter <literal
- >connection-ttl</literal>.</para>
- <para>The default value for connection ttl on an "unreliable" connection (e.g. a Netty
- connection) is <literal>60000</literal>ms, i.e. 1 minute. The default value for connection
- ttl on a "reliable" connection (e.g. an in-vm connection) is <literal>-1</literal>. A
- value of <literal>-1</literal> for <literal>ConnectionTTL</literal> means the server
- will never time out the connection on the server side.</para>
- <para id="connection-ttl.override">If you do not wish clients to be able to specify their own connection TTL, you can
- override all values used by a global value set on the server side. This can be done by
- specifying the <literal>connection-ttl-override</literal> attribute in the server side
- configuration. The default value for <literal>connection-ttl-override</literal> is
- <literal>-1</literal> which means "do not override" (i.e. let clients use their own
- values).</para>
- <section>
- <title>Closing core sessions or JMS connections that you have failed to close</title>
- <para>As previously discussed, it's important that all core client sessions and JMS
- connections are always closed explicitly in a <literal>finally</literal> block when
- you are finished using them. </para>
- <para>If you fail to do so, ActiveMQ will detect this at garbage collection time, and log
- a warning similar to the following in the logs (If you are using JMS the warning
- will involve a JMS connection not a client session):</para>
- <programlisting>
-[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] I'm closing a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
-ting them go out of scope!
-[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] The session you didn't close was created here:
-java.lang.Exception
- at org.apache.activemq.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
- at org.acme.yourproject.YourClass (YourClass.java:666)</programlisting>
- <para>ActiveMQ will then close the connection / client session for you.</para>
- <para>Note that the log will also tell you the exact line of your user code where you
- created the JMS connection / client session that you later did not close. This will
- enable you to pinpoint the error in your code and correct it appropriately.</para>
- </section>
- </section>
- <section>
- <title>Detecting failure from the client side.</title>
- <para>In the previous section we discussed how the client sends pings to the server and how
- "dead" connection resources are cleaned up by the server. There's also another reason
- for pinging, and that's for the <emphasis>client</emphasis> to be able to detect that
- the server or network has failed.</para>
- <para>As long as the client is receiving data from the server it will consider the
- connection to be still alive. </para>
- <para>If the client does not receive any packets for <literal
- >client-failure-check-period</literal> milliseconds then it will consider the
- connection failed and will either initiate failover, or call any <literal
- >FailureListener</literal> instances (or <literal>ExceptionListener</literal>
- instances if you are using JMS) depending on how it has been configured.</para>
- <para>If you're using JMS it's defined by the <literal>ClientFailureCheckPeriod</literal>
- attribute on a <literal>ActiveMQConnectionFactory</literal> instance, or if you're
- deploying JMS connection factory instances direct into JNDI on the server side, you can
- specify it in the <literal>activemq-jms.xml </literal> configuration file, using the
- parameter <literal>client-failure-check-period</literal>.</para>
- <para>The default value for client failure check period on an "unreliable" connection (e.g.
- a Netty connection) is <literal>30000</literal>ms, i.e. 30 seconds. The default value
- for client failure check period on a "reliable" connection (e.g. an in-vm connection)
- is <literal>-1</literal>. A value of <literal>-1</literal> means the client will never fail the
- connection on the client side if no data is received from the server. Typically this is
- much lower than connection TTL to allow clients to reconnect in case of transitory
- failure.</para>
- </section>
- <section id="connection-ttl.async-connection-execution">
- <title>Configuring Asynchronous Connection Execution</title>
- <para>Most packets received on the server side are executed on the remoting thread. These packets
- represent short-running operations and are always executed on the remoting thread for
- performance reasons.</para>
- <para>However, by default some kinds of packets are executed using a thread from a
- thread pool so that the remoting thread is not tied up for too long. Please note that
- processing operations asynchronously on another thread adds a little more latency. These packets
- are:</para>
- <itemizedlist>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.RollbackMessage</literal></para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionCloseMessage</literal></para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionCommitMessage</literal></para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXACommitMessage</literal></para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXAPrepareMessage</literal></para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXARollbackMessage</literal></para>
- </listitem>
- </itemizedlist>
- <para>To disable asynchronous connection execution, set the parameter
- <literal>async-connection-execution-enabled</literal> in
- <literal>activemq-configuration.xml</literal> to <literal>false</literal> (default value is
- <literal>true</literal>).</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/core-bridges.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md
new file mode 100644
index 0000000..6b6b90f
--- /dev/null
+++ b/docs/user-manual/en/core-bridges.md
@@ -0,0 +1,225 @@
+Core Bridges
+============
+
+The function of a bridge is to consume messages from a source queue, and
+forward them to a target address, typically on a different ActiveMQ
+server.
+
+The source and target servers do not have to be in the same cluster
+which makes bridging suitable for reliably sending messages from one
+cluster to another, for instance across a WAN, or internet and where the
+connection may be unreliable.
+
+The bridge has built in resilience to failure so if the target server
+connection is lost, e.g. due to network failure, the bridge will retry
+connecting to the target until it comes back online. When it comes back
+online it will resume operation as normal.
+
+In summary, bridges are a way to reliably connect two separate ActiveMQ
+servers together. With a core bridge both source and target servers must
+be ActiveMQ servers.
+
+Bridges can be configured to provide *once and only once* delivery
+guarantees even in the event of the failure of the source or the target
+server. They do this by using duplicate detection (described in ?).
+
+> **Note**
+>
+> Although they have similar function, don't confuse core bridges with
+> JMS bridges!
+>
+> Core bridges are for linking a ActiveMQ node with another ActiveMQ
+> node and do not use the JMS API. A JMS Bridge is used for linking any
+> two JMS 1.1 compliant JMS providers. So, a JMS Bridge could be used
+> for bridging to or from different JMS compliant messaging system. It's
+> always preferable to use a core bridge if you can. Core bridges use
+> duplicate detection to provide *once and only once* guarantees. To
+> provide the same guarantee using a JMS bridge you would have to use XA
+> which has a higher overhead and is more complex to configure.
+
+Configuring Bridges
+===================
+
+Bridges are configured in `activemq-configuration.xml`. Let's kick off
+with an example (this is actually from the bridge example):
+
+ <bridge name="my-bridge">
+ <queue-name>jms.queue.sausage-factory</queue-name>
+ <forwarding-address>jms.queue.mincing-machine</forwarding-address>
+ <filter-string="name='aardvark'"/>
+ <transformer-class-name>
+ org.apache.activemq.jms.example.HatColourChangeTransformer
+ </transformer-class-name>
+ <retry-interval>1000</retry-interval>
+ <ha>true</ha>
+ <retry-interval-multiplier>1.0</retry-interval-multiplier>
+ <initial-connect-attempts>-1</initial-connect-attempts>
+ <reconnect-attempts>-1</reconnect-attempts>
+ <failover-on-server-shutdown>false</failover-on-server-shutdown>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <confirmation-window-size>10000000</confirmation-window-size>
+ <user>foouser</user>
+ <password>foopassword</password>
+ <static-connectors>
+ <connector-ref>remote-connector</connector-ref>
+ </static-connectors>
+ <!-- alternative to static-connectors
+ <discovery-group-ref discovery-group-name="bridge-discovery-group"/>
+ -->
+ </bridge>
+
+In the above example we have shown all the parameters its possible to
+configure for a bridge. In practice you might use many of the defaults
+so it won't be necessary to specify them all explicitly.
+
+Let's take a look at all the parameters in turn:
+
+- `name` attribute. All bridges must have a unique name in the server.
+
+- `queue-name`. This is the unique name of the local queue that the
+ bridge consumes from, it's a mandatory parameter.
+
+ The queue must already exist by the time the bridge is instantiated
+ at start-up.
+
+ > **Note**
+ >
+ > If you're using JMS then normally the JMS configuration
+ > `activemq-jms.xml` is loaded after the core configuration file
+ > `activemq-configuration.xml` is loaded. If your bridge is
+ > consuming from a JMS queue then you'll need to make sure the JMS
+ > queue is also deployed as a core queue in the core configuration.
+ > Take a look at the bridge example for an example of how this is
+ > done.
+
+- `forwarding-address`. This is the address on the target server that
+ the message will be forwarded to. If a forwarding address is not
+ specified, then the original address of the message will be
+ retained.
+
+- `filter-string`. An optional filter string can be supplied. If
+ specified then only messages which match the filter expression
+ specified in the filter string will be forwarded. The filter string
+ follows the ActiveMQ filter expression syntax described in ?.
+
+- `transformer-class-name`. An optional transformer-class-name can be
+ specified. This is the name of a user-defined class which implements
+ the `org.apache.activemq.core.server.cluster.Transformer` interface.
+
+ If this is specified then the transformer's `transform()` method
+ will be invoked with the message before it is forwarded. This gives
+ you the opportunity to transform the message's header or body before
+ forwarding it.
+
+- `ha`. This optional parameter determines whether or not this bridge
+ should support high availability. True means it will connect to any
+ available server in a cluster and support failover. The default
+ value is `false`.
+
+- `retry-interval`. This optional parameter determines the period in
+ milliseconds between subsequent reconnection attempts, if the
+ connection to the target server has failed. The default value is
+ `2000`milliseconds.
+
+- `retry-interval-multiplier`. This optional parameter determines
+ determines a multiplier to apply to the time since the last retry to
+ compute the time to the next retry.
+
+ This allows you to implement an *exponential backoff* between retry
+ attempts.
+
+ Let's take an example:
+
+ If we set `retry-interval`to `1000` ms and we set
+ `retry-interval-multiplier` to `2.0`, then, if the first reconnect
+ attempt fails, we will wait `1000` ms then `2000` ms then `4000` ms
+ between subsequent reconnection attempts.
+
+ The default value is `1.0` meaning each reconnect attempt is spaced
+ at equal intervals.
+
+- `initial-connect-attempts`. This optional parameter determines the
+ total number of initial connect attempts the bridge will make before
+ giving up and shutting down. A value of `-1` signifies an unlimited
+ number of attempts. The default value is `-1`.
+
+- `reconnect-attempts`. This optional parameter determines the total
+ number of reconnect attempts the bridge will make before giving up
+ and shutting down. A value of `-1` signifies an unlimited number of
+ attempts. The default value is `-1`.
+
+- `failover-on-server-shutdown`. This optional parameter determines
+ whether the bridge will attempt to failover onto a backup server (if
+ specified) when the target server is cleanly shutdown rather than
+ crashed.
+
+ The bridge connector can specify both a live and a backup server, if
+ it specifies a backup server and this parameter is set to `true`
+ then if the target server is *cleanly* shutdown the bridge
+ connection will attempt to failover onto its backup. If the bridge
+ connector has no backup server configured then this parameter has no
+ effect.
+
+ Sometimes you want a bridge configured with a live and a backup
+ target server, but you don't want to failover to the backup if the
+ live server is simply taken down temporarily for maintenance, this
+ is when this parameter comes in handy.
+
+ The default value for this parameter is `false`.
+
+- `use-duplicate-detection`. This optional parameter determines
+ whether the bridge will automatically insert a duplicate id property
+ into each message that it forwards.
+
+ Doing so, allows the target server to perform duplicate detection on
+ messages it receives from the source server. If the connection fails
+ or server crashes, then, when the bridge resumes it will resend
+ unacknowledged messages. This might result in duplicate messages
+ being sent to the target server. By enabling duplicate detection
+ allows these duplicates to be screened out and ignored.
+
+ This allows the bridge to provide a *once and only once* delivery
+ guarantee without using heavyweight methods such as XA (see ? for
+ more information).
+
+ The default value for this parameter is `true`.
+
+- `confirmation-window-size`. This optional parameter determines the
+ `confirmation-window-size` to use for the connection used to forward
+ messages to the target node. This attribute is described in section
+ ?
+
+ > **Warning**
+ >
+ > When using the bridge to forward messages to an address which uses
+ > the `BLOCK` `address-full-policy` from a queue which has a
+ > `max-size-bytes` set it's important that
+ > `confirmation-window-size` is less than or equal to
+ > `max-size-bytes` to prevent the flow of messages from ceasing.
+
+- `user`. This optional parameter determines the user name to use when
+ creating the bridge connection to the remote server. If it is not
+ specified the default cluster user specified by `cluster-user` in
+ `activemq-configuration.xml` will be used.
+
+- `password`. This optional parameter determines the password to use
+ when creating the bridge connection to the remote server. If it is
+ not specified the default cluster password specified by
+ `cluster-password` in `activemq-configuration.xml` will be used.
+
+- `static-connectors` or `discovery-group-ref`. Pick either of these
+ options to connect the bridge to the target server.
+
+ The `static-connectors` is a list of `connector-ref` elements
+ pointing to `connector` elements defined elsewhere. A *connector*
+ encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc)
+ as well as the server connection parameters (host, port etc). For
+ more information about what connectors are and how to configure
+ them, please see ?.
+
+ The `discovery-group-ref` element has one attribute -
+ `discovery-group-name`. This attribute points to a `discovery-group`
+ defined elsewhere. For more information about what discovery-groups
+ are and how to configure them, please see ?.
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/core-bridges.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/core-bridges.xml b/docs/user-manual/en/core-bridges.xml
deleted file mode 100644
index 2276a2e..0000000
--- a/docs/user-manual/en/core-bridges.xml
+++ /dev/null
@@ -1,241 +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="core-bridges">
- <title>Core Bridges</title>
- <para>The function of a bridge is to consume messages from a source queue, and forward them to a
- target address, typically on a different ActiveMQ server.</para>
- <para>The source and target servers do not have to be in the same cluster which makes bridging
- suitable for reliably sending messages from one cluster to another, for instance across a
- WAN, or internet and where the connection may be unreliable.</para>
- <para>The bridge has built in resilience to failure so if the target server connection is lost,
- e.g. due to network failure, the bridge will retry connecting to the target until it comes
- back online. When it comes back online it will resume operation as normal.</para>
- <para>In summary, bridges are a way to reliably connect two separate ActiveMQ servers together.
- With a core bridge both source and target servers must be ActiveMQ servers.</para>
- <para>Bridges can be configured to provide <emphasis>once and only once</emphasis> delivery
- guarantees even in the event of the failure of the source or the target server. They do this
- by using duplicate detection (described in <xref linkend="duplicate-detection"/>).</para>
- <note>
- <para>Although they have similar function, don't confuse core bridges with JMS
- bridges!</para>
- <para>Core bridges are for linking a ActiveMQ node with another ActiveMQ node and do not use
- the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant JMS providers.
- So, a JMS Bridge could be used for bridging to or from different JMS compliant messaging
- system. It's always preferable to use a core bridge if you can. Core bridges use
- duplicate detection to provide <emphasis>once and only once</emphasis> guarantees. To
- provide the same guarantee using a JMS bridge you would have to use XA which has a
- higher overhead and is more complex to configure.</para>
- </note>
- <section>
- <title>Configuring Bridges</title>
- <para>Bridges are configured in <literal>activemq-configuration.xml</literal>. Let's kick off
- with an example (this is actually from the bridge example):</para>
- <programlisting>
-<bridge name="my-bridge">
- <queue-name>jms.queue.sausage-factory</queue-name>
- <forwarding-address>jms.queue.mincing-machine</forwarding-address>
- <filter-string="name='aardvark'"/>
- <transformer-class-name>
- org.apache.activemq.jms.example.HatColourChangeTransformer
- </transformer-class-name>
- <retry-interval>1000</retry-interval>
- <ha>true</ha>
- <retry-interval-multiplier>1.0</retry-interval-multiplier>
- <initial-connect-attempts>-1</initial-connect-attempts>
- <reconnect-attempts>-1</reconnect-attempts>
- <failover-on-server-shutdown>false</failover-on-server-shutdown>
- <use-duplicate-detection>true</use-duplicate-detection>
- <confirmation-window-size>10000000</confirmation-window-size>
- <user>foouser</user>
- <password>foopassword</password>
- <static-connectors>
- <connector-ref>remote-connector</connector-ref>
- </static-connectors>
- <!-- alternative to static-connectors
- <discovery-group-ref discovery-group-name="bridge-discovery-group"/>
- -->
-</bridge></programlisting>
- <para>In the above example we have shown all the parameters its possible to configure for a
- bridge. In practice you might use many of the defaults so it won't be necessary to
- specify them all explicitly.</para>
- <para>Let's take a look at all the parameters in turn:</para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> attribute. All bridges must have a unique name in the
- server.</para>
- </listitem>
- <listitem>
- <para><literal>queue-name</literal>. This is the unique name of the local queue that
- the bridge consumes from, it's a mandatory parameter.</para>
- <para>The queue must already exist by the time the bridge is instantiated at
- start-up.</para>
- <note>
- <para>If you're using JMS then normally the JMS configuration <literal
- >activemq-jms.xml</literal> is loaded after the core configuration file
- <literal>activemq-configuration.xml</literal> is loaded. If your bridge
- is consuming from a JMS queue then you'll need to make sure the JMS queue is
- also deployed as a core queue in the core configuration. Take a look at the
- bridge example for an example of how this is done.</para>
- </note>
- </listitem>
- <listitem>
- <para><literal>forwarding-address</literal>. This is the address on the target
- server that the message will be forwarded to. If a forwarding address is not
- specified, then the original address of the message will be retained.</para>
- </listitem>
- <listitem>
- <para><literal>filter-string</literal>. An optional filter string can be supplied.
- If specified then only messages which match the filter expression specified in
- the filter string will be forwarded. The filter string follows the ActiveMQ
- filter expression syntax described in <xref linkend="filter-expressions"
- />.</para>
- </listitem>
- <listitem>
- <para><literal>transformer-class-name</literal>. An optional transformer-class-name
- can be specified. This is the name of a user-defined class which implements the
- <literal>org.apache.activemq.core.server.cluster.Transformer</literal>
- interface.</para>
- <para>If this is specified then the transformer's <literal>transform()</literal>
- method will be invoked with the message before it is forwarded. This gives you
- the opportunity to transform the message's header or body before forwarding
- it.</para>
- </listitem>
- <listitem>
- <para><literal>ha</literal>. This optional parameter determines whether or not this
- bridge should support high availability. True means it will connect to any available
- server in a cluster and support failover. The default value is <literal
- >false</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval</literal>. This optional parameter determines the
- period in milliseconds between subsequent reconnection attempts, if the
- connection to the target server has failed. The default value is <literal
- >2000</literal>milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval-multiplier</literal>. This optional parameter
- determines determines a multiplier to apply to the time since the last retry to
- compute the time to the next retry.</para>
- <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
- between retry attempts.</para>
- <para>Let's take an example:</para>
- <para>If we set <literal>retry-interval</literal>to <literal>1000</literal> ms and
- we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
- then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
- ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
- subsequent reconnection attempts.</para>
- <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
- spaced at equal intervals.</para>
- </listitem>
- <listitem>
- <para><literal>initial-connect-attempts</literal>. This optional parameter determines the
- total number of initial connect attempts the bridge will make before giving up and
- shutting down. A value of <literal>-1</literal> signifies an unlimited number of
- attempts. The default value is <literal>-1</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>reconnect-attempts</literal>. This optional parameter determines the
- total number of reconnect attempts the bridge will make before giving up and
- shutting down. A value of <literal>-1</literal> signifies an unlimited number of
- attempts. The default value is <literal>-1</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>failover-on-server-shutdown</literal>. This optional parameter
- determines whether the bridge will attempt to failover onto a backup server (if
- specified) when the target server is cleanly shutdown rather than
- crashed.</para>
- <para>The bridge connector can specify both a live and a backup server, if it
- specifies a backup server and this parameter is set to <literal>true</literal>
- then if the target server is <emphasis>cleanly</emphasis> shutdown the bridge
- connection will attempt to failover onto its backup. If the bridge connector has
- no backup server configured then this parameter has no effect. </para>
- <para>Sometimes you want a bridge configured with a live and a backup target server,
- but you don't want to failover to the backup if the live server is simply taken
- down temporarily for maintenance, this is when this parameter comes in
- handy.</para>
- <para>The default value for this parameter is <literal>false</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>use-duplicate-detection</literal>. This optional parameter determines
- whether the bridge will automatically insert a duplicate id property into each
- message that it forwards.</para>
- <para>Doing so, allows the target server to perform duplicate detection on messages
- it receives from the source server. If the connection fails or server crashes,
- then, when the bridge resumes it will resend unacknowledged messages. This might
- result in duplicate messages being sent to the target server. By enabling
- duplicate detection allows these duplicates to be screened out and
- ignored.</para>
- <para>This allows the bridge to provide a <emphasis>once and only once</emphasis>
- delivery guarantee without using heavyweight methods such as XA (see <xref
- linkend="duplicate-detection"/> for more information).</para>
- <para>The default value for this parameter is <literal>true</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>confirmation-window-size</literal>. This optional parameter
- determines the <literal>confirmation-window-size</literal> to use for the
- connection used to forward messages to the target node. This attribute is
- described in section <xref linkend="client-reconnection"/></para>
-
- <warning><para>When using the bridge to forward messages to an address which uses
- the <literal>BLOCK</literal> <literal>address-full-policy</literal> from a
- queue which has a <literal>max-size-bytes</literal> set it's important that
- <literal>confirmation-window-size</literal> is less than or equal to
- <literal>max-size-bytes</literal> to prevent the flow of messages from
- ceasing.</para>
- </warning>
-
- </listitem>
- <listitem>
- <para><literal>user</literal>. This optional parameter determines the user name to
- use when creating the bridge connection to the remote server. If it is not
- specified the default cluster user specified by <literal>cluster-user</literal>
- in <literal>activemq-configuration.xml</literal> will be used. </para>
- </listitem>
- <listitem>
- <para><literal>password</literal>. This optional parameter determines the password
- to use when creating the bridge connection to the remote server. If it is not
- specified the default cluster password specified by <literal
- >cluster-password</literal> in <literal>activemq-configuration.xml</literal>
- will be used. </para>
- </listitem>
- <listitem>
- <para><literal>static-connectors</literal> or <literal>discovery-group-ref</literal>.
- Pick either of these options to connect the bridge to the target server.
- </para>
- <para> The <literal>static-connectors</literal> is a list of <literal>connector-ref</literal>
- elements pointing to <literal>connector</literal> elements defined elsewhere.
- A <emphasis>connector</emphasis> encapsulates knowledge of what transport to
- use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port
- etc). For more information about what connectors are and how to configure them,
- please see <xref linkend="configuring-transports"/>.
- </para>
- <para>The <literal>discovery-group-ref</literal> element has one attribute -
- <literal>discovery-group-name</literal>. This attribute points to a
- <literal>discovery-group</literal> defined elsewhere. For more information about
- what discovery-groups are and how to configure them, please see
- <xref linkend="clusters.discovery-groups"/>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/diverts.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/diverts.md b/docs/user-manual/en/diverts.md
new file mode 100644
index 0000000..60b00f7
--- /dev/null
+++ b/docs/user-manual/en/diverts.md
@@ -0,0 +1,114 @@
+Diverting and Splitting Message Flows
+=====================================
+
+ActiveMQ allows you to configure objects called *diverts* with some
+simple server configuration.
+
+Diverts allow you to transparently divert messages routed to one address
+to some other address, without making any changes to any client
+application logic.
+
+Diverts can be *exclusive*, meaning that the message is diverted to the
+new address, and does not go to the old address at all, or they can be
+*non-exclusive* which means the message continues to go the old address,
+and a *copy* of it is also sent to the new address. Non-exclusive
+diverts can therefore be used for *splitting* message flows, e.g. there
+may be a requirement to monitor every order sent to an order queue.
+
+Diverts can also be configured to have an optional message filter. If
+specified then only messages that match the filter will be diverted.
+
+Diverts can also be configured to apply a `Transformer`. If specified,
+all diverted messages will have the opportunity of being transformed by
+the `Transformer`.
+
+A divert will only divert a message to an address on the *same server*,
+however, if you want to divert to an address on a different server, a
+common pattern would be to divert to a local store-and-forward queue,
+then set up a bridge which consumes from that queue and forwards to an
+address on a different server.
+
+Diverts are therefore a very sophisticated concept, which when combined
+with bridges can be used to create interesting and complex routings. The
+set of diverts on a server can be thought of as a type of routing table
+for messages. Combining diverts with bridges allows you to create a
+distributed network of reliable routing connections between multiple
+geographically distributed servers, creating your global messaging mesh.
+
+Diverts are defined as xml in the `activemq-configuration.xml` file.
+There can be zero or more diverts in the file.
+
+Please see ? for a full working example showing you how to configure and
+use diverts.
+
+Let's take a look at some divert examples:
+
+Exclusive Divert
+================
+
+Let's take a look at an exclusive divert. An exclusive divert diverts
+all matching messages that are routed to the old address to the new
+address. Matching messages do not get routed to the old address.
+
+Here's some example xml configuration for an exclusive divert, it's
+taken from the divert example:
+
+ <divert name="prices-divert">
+ <address>jms.topic.priceUpdates</address>
+ <forwarding-address>jms.queue.priceForwarding</forwarding-address>
+ <filter string="office='New York'"/>
+ <transformer-class-name>
+ org.apache.activemq.jms.example.AddForwardingTimeTransformer
+ </transformer-class-name>
+ <exclusive>true</exclusive>
+ </divert>
+
+We define a divert called '`prices-divert`' that will divert any
+messages sent to the address '`jms.topic.priceUpdates`' (this
+corresponds to any messages sent to a JMS Topic called '`priceUpdates`')
+to another local address '`jms.queue.priceForwarding`' (this corresponds
+to a local JMS queue called '`priceForwarding`'
+
+We also specify a message filter string so only messages with the
+message property `office` with value `New York` will get diverted, all
+other messages will continue to be routed to the normal address. The
+filter string is optional, if not specified then all messages will be
+considered matched.
+
+In this example a transformer class is specified. Again this is
+optional, and if specified the transformer will be executed for each
+matching message. This allows you to change the messages body or
+properties before it is diverted. In this example the transformer simply
+adds a header that records the time the divert happened.
+
+This example is actually diverting messages to a local store and forward
+queue, which is configured with a bridge which forwards the message to
+an address on another ActiveMQ server. Please see the example for more
+details.
+
+Non-exclusive Divert
+====================
+
+Now we'll take a look at a non-exclusive divert. Non exclusive diverts
+are the same as exclusive diverts, but they only forward a *copy* of the
+message to the new address. The original message continues to the old
+address
+
+You can therefore think of non-exclusive diverts as *splitting* a
+message flow.
+
+Non exclusive diverts can be configured in the same way as exclusive
+diverts with an optional filter and transformer, here's an example
+non-exclusive divert, again from the divert example:
+
+ <divert name="order-divert">
+ <address>jms.queue.orders</address>
+ <forwarding-address>jms.topic.spyTopic</forwarding-address>
+ <exclusive>false</exclusive>
+ </divert>
+
+The above divert example takes a copy of every message sent to the
+address '`jms.queue.orders`' (Which corresponds to a JMS Queue called
+'`orders`') and sends it to a local address called
+'`jms.topic.SpyTopic`' (which corresponds to a JMS Topic called
+'`SpyTopic`').
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/diverts.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/diverts.xml b/docs/user-manual/en/diverts.xml
deleted file mode 100644
index b83c5c5..0000000
--- a/docs/user-manual/en/diverts.xml
+++ /dev/null
@@ -1,113 +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="diverts">
- <title>Diverting and Splitting Message Flows</title>
- <para>ActiveMQ allows you to configure objects called <emphasis>diverts</emphasis> with
- some simple server configuration.</para>
- <para>Diverts allow you to transparently divert messages routed to one address to some other
- address, without making any changes to any client application logic.</para>
- <para>Diverts can be <emphasis>exclusive</emphasis>, meaning that the message is diverted
- to the new address, and does not go to the old address at all, or they can be
- <emphasis>non-exclusive</emphasis> which means the message continues to go the old
- address, and a <emphasis>copy</emphasis> of it is also sent to the new address.
- Non-exclusive diverts can therefore be used for <emphasis>splitting</emphasis> message
- flows, e.g. there may be a requirement to monitor every order sent to an order queue.</para>
- <para>Diverts can also be configured to have an optional message filter. If specified then only
- messages that match the filter will be diverted.</para>
- <para>Diverts can also be configured to apply a <literal>Transformer</literal>. If specified,
- all diverted messages will have the opportunity of being transformed by the <literal
- >Transformer</literal>.</para>
- <para>A divert will only divert a message to an address on the <emphasis>same server</emphasis>,
- however, if you want to divert to an address on a different server, a common pattern would
- be to divert to a local store-and-forward queue, then set up a bridge which consumes from
- that queue and forwards to an address on a different server.</para>
- <para>Diverts are therefore a very sophisticated concept, which when combined with bridges can
- be used to create interesting and complex routings. The set of diverts on a server can be
- thought of as a type of routing table for messages. Combining diverts with bridges allows
- you to create a distributed network of reliable routing connections between multiple
- geographically distributed servers, creating your global messaging mesh.</para>
- <para>Diverts are defined as xml in the <literal>activemq-configuration.xml</literal> file. There can
- be zero or more diverts in the file.</para>
- <para>Please see <xref linkend="divert-example" /> for a full working
- example showing you how to configure and use diverts.</para>
- <para>Let's take a look at some divert examples:</para>
- <section>
- <title>Exclusive Divert</title>
- <para>Let's take a look at an exclusive divert. An exclusive divert diverts all matching
- messages that are routed to the old address to the new address. Matching messages do not
- get routed to the old address.</para>
- <para>Here's some example xml configuration for an exclusive divert, it's taken from the
- divert example:</para>
- <programlisting>
-<divert name="prices-divert">
- <address>jms.topic.priceUpdates</address>
- <forwarding-address>jms.queue.priceForwarding</forwarding-address>
- <filter string="office='New York'"/>
- <transformer-class-name>
- org.apache.activemq.jms.example.AddForwardingTimeTransformer
- </transformer-class-name>
- <exclusive>true</exclusive>
-</divert></programlisting>
- <para>We define a divert called '<literal>prices-divert</literal>' that will divert any
- messages sent to the address '<literal>jms.topic.priceUpdates</literal>' (this
- corresponds to any messages sent to a JMS Topic called '<literal
- >priceUpdates</literal>') to another local address '<literal
- >jms.queue.priceForwarding</literal>' (this corresponds to a local JMS queue called
- '<literal>priceForwarding</literal>'</para>
- <para>We also specify a message filter string so only messages with the message property
- <literal>office</literal> with value <literal>New York</literal> will get diverted,
- all other messages will continue to be routed to the normal address. The filter string
- is optional, if not specified then all messages will be considered matched.</para>
- <para>In this example a transformer class is specified. Again this is optional, and if
- specified the transformer will be executed for each matching message. This allows you to
- change the messages body or properties before it is diverted. In this example the
- transformer simply adds a header that records the time the divert happened.</para>
- <para>This example is actually diverting messages to a local store and forward queue, which
- is configured with a bridge which forwards the message to an address on another ActiveMQ
- server. Please see the example for more details.</para>
- </section>
- <section>
- <title>Non-exclusive Divert</title>
- <para>Now we'll take a look at a non-exclusive divert. Non exclusive diverts are the same as
- exclusive diverts, but they only forward a <emphasis>copy</emphasis> of the message to
- the new address. The original message continues to the old address</para>
- <para>You can therefore think of non-exclusive diverts as <emphasis>splitting</emphasis> a
- message flow.</para>
- <para>Non exclusive diverts can be configured in the same way as exclusive diverts with an
- optional filter and transformer, here's an example non-exclusive divert, again from the
- divert example:</para>
- <programlisting>
-<divert name="order-divert">
- <address>jms.queue.orders</address>
- <forwarding-address>jms.topic.spyTopic</forwarding-address>
- <exclusive>false</exclusive>
-</divert></programlisting>
- <para>The above divert example takes a copy of every message sent to the address '<literal
- >jms.queue.orders</literal>' (Which corresponds to a JMS Queue called '<literal
- >orders</literal>') and sends it to a local address called '<literal
- >jms.topic.SpyTopic</literal>' (which corresponds to a JMS Topic called '<literal
- >SpyTopic</literal>').</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/duplicate-detection.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/duplicate-detection.md b/docs/user-manual/en/duplicate-detection.md
new file mode 100644
index 0000000..b7776eb
--- /dev/null
+++ b/docs/user-manual/en/duplicate-detection.md
@@ -0,0 +1,161 @@
+Duplicate Message Detection
+===========================
+
+ActiveMQ includes powerful automatic duplicate message detection,
+filtering out duplicate messages without you having to code your own
+fiddly duplicate detection logic at the application level. This chapter
+will explain what duplicate detection is, how ActiveMQ uses it and how
+and where to configure it.
+
+When sending messages from a client to a server, or indeed from a server
+to another server, if the target server or connection fails sometime
+after sending the message, but before the sender receives a response
+that the send (or commit) was processed successfully then the sender
+cannot know for sure if the message was sent successfully to the
+address.
+
+If the target server or connection failed after the send was received
+and processed but before the response was sent back then the message
+will have been sent to the address successfully, but if the target
+server or connection failed before the send was received and finished
+processing then it will not have been sent to the address successfully.
+From the senders point of view it's not possible to distinguish these
+two cases.
+
+When the server recovers this leaves the client in a difficult
+situation. It knows the target server failed, but it does not know if
+the last message reached its destination ok. If it decides to resend the
+last message, then that could result in a duplicate message being sent
+to the address. If each message was an order or a trade then this could
+result in the order being fulfilled twice or the trade being double
+booked. This is clearly not a desirable situation.
+
+Sending the message(s) in a transaction does not help out either. If the
+server or connection fails while the transaction commit is being
+processed it is also indeterminate whether the transaction was
+successfully committed or not!
+
+To solve these issues ActiveMQ provides automatic duplicate messages
+detection for messages sent to addresses.
+
+Using Duplicate Detection for Message Sending
+=============================================
+
+Enabling duplicate message detection for sent messages is simple: you
+just need to set a special property on the message to a unique value.
+You can create the value however you like, as long as it is unique. When
+the target server receives the message it will check if that property is
+set, if it is, then it will check in its in memory cache if it has
+already received a message with that value of the header. If it has
+received a message with the same value before then it will ignore the
+message.
+
+> **Note**
+>
+> Using duplicate detection to move messages between nodes can give you
+> the same *once and only once* delivery guarantees as if you were using
+> an XA transaction to consume messages from source and send them to the
+> target, but with less overhead and much easier configuration than
+> using XA.
+
+If you're sending messages in a transaction then you don't have to set
+the property for *every* message you send in that transaction, you only
+need to set it once in the transaction. If the server detects a
+duplicate message for any message in the transaction, then it will
+ignore the entire transaction.
+
+The name of the property that you set is given by the value of
+`org.apache.activemq.api.core.Message.HDR_DUPLICATE_DETECTION_ID`, which
+is `_HQ_DUPL_ID`
+
+The value of the property can be of type `byte[]` or `SimpleString` if
+you're using the core API. If you're using JMS it must be a `String`,
+and its value should be unique. An easy way of generating a unique id is
+by generating a UUID.
+
+Here's an example of setting the property using the core API:
+
+ ...
+
+ ClientMessage message = session.createMessage(true);
+
+ SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
+
+ ...
+
+And here's an example using the JMS API:
+
+ ...
+
+ Message jmsMessage = session.createMessage();
+
+ String myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
+
+ ...
+
+Configuring the Duplicate ID Cache
+==================================
+
+The server maintains caches of received values of the
+`org.apache.activemq.core.message.impl.HDR_DUPLICATE_DETECTION_ID`
+property sent to each address. Each address has its own distinct cache.
+
+The cache is a circular fixed size cache. If the cache has a maximum
+size of `n` elements, then the `n + 1`th id stored will overwrite the
+`0`th element in the cache.
+
+The maximum size of the cache is configured by the parameter
+`id-cache-size` in `activemq-configuration.xml`, the default value is
+`2000` elements.
+
+The caches can also be configured to persist to disk or not. This is
+configured by the parameter `persist-id-cache`, also in
+`activemq-configuration.xml`. If this is set to `true` then each id will
+be persisted to permanent storage as they are received. The default
+value for this parameter is `true`.
+
+> **Note**
+>
+> When choosing a size of the duplicate id cache be sure to set it to a
+> larger enough size so if you resend messages all the previously sent
+> ones are in the cache not having been overwritten.
+
+Duplicate Detection and Bridges
+===============================
+
+Core bridges can be configured to automatically add a unique duplicate
+id value (if there isn't already one in the message) before forwarding
+the message to it's target. This ensures that if the target server
+crashes or the connection is interrupted and the bridge resends the
+message, then if it has already been received by the target server, it
+will be ignored.
+
+To configure a core bridge to add the duplicate id header, simply set
+the `use-duplicate-detection` to `true` when configuring a bridge in
+`activemq-configuration.xml`.
+
+The default value for this parameter is `true`.
+
+For more information on core bridges and how to configure them, please
+see ?.
+
+Duplicate Detection and Cluster Connections
+===========================================
+
+Cluster connections internally use core bridges to move messages
+reliable between nodes of the cluster. Consequently they can also be
+configured to insert the duplicate id header for each message they move
+using their internal bridges.
+
+To configure a cluster connection to add the duplicate id header, simply
+set the `use-duplicate-detection` to `true` when configuring a cluster
+connection in `activemq-configuration.xml`.
+
+The default value for this parameter is `true`.
+
+For more information on cluster connections and how to configure them,
+please see ?.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/duplicate-detection.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/duplicate-detection.xml b/docs/user-manual/en/duplicate-detection.xml
deleted file mode 100644
index 605107a..0000000
--- a/docs/user-manual/en/duplicate-detection.xml
+++ /dev/null
@@ -1,148 +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="duplicate-detection">
- <title>Duplicate Message Detection</title>
- <para>ActiveMQ includes powerful automatic duplicate message detection, filtering out
- duplicate messages without you having to code your own fiddly duplicate detection logic at
- the application level. This chapter will explain what duplicate detection is, how ActiveMQ
- uses it and how and where to configure it.</para>
- <para>When sending messages from a client to a server, or indeed from a server to another
- server, if the target server or connection fails sometime after sending the message, but
- before the sender receives a response that the send (or commit) was processed successfully
- then the sender cannot know for sure if the message was sent successfully to the
- address.</para>
- <para>If the target server or connection failed after the send was received and processed but
- before the response was sent back then the message will have been sent to the address
- successfully, but if the target server or connection failed before the send was received and
- finished processing then it will not have been sent to the address successfully. From the
- senders point of view it's not possible to distinguish these two cases.</para>
- <para>When the server recovers this leaves the client in a difficult situation. It knows the
- target server failed, but it does not know if the last message reached its destination ok.
- If it decides to resend the last message, then that could result in a duplicate message
- being sent to the address. If each message was an order or a trade then this could result in
- the order being fulfilled twice or the trade being double booked. This is clearly not a
- desirable situation.</para>
- <para>Sending the message(s) in a transaction does not help out either. If the server or
- connection fails while the transaction commit is being processed it is also indeterminate
- whether the transaction was successfully committed or not!</para>
- <para>To solve these issues ActiveMQ provides automatic duplicate messages detection for
- messages sent to addresses.</para>
- <section>
- <title>Using Duplicate Detection for Message Sending</title>
- <para>Enabling duplicate message detection for sent messages is simple: you just need to set
- a special property on the message to a unique value. You can create the value however
- you like, as long as it is unique. When the target server receives the message it will
- check if that property is set, if it is, then it will check in its in memory cache if it
- has already received a message with that value of the header. If it has received a
- message with the same value before then it will ignore the message.</para>
- <note>
- <para>Using duplicate detection to move messages between nodes can give you the same
- <emphasis>once and only once</emphasis> delivery guarantees as if you were using
- an XA transaction to consume messages from source and send them to the target, but
- with less overhead and much easier configuration than using XA.</para>
- </note>
- <para>If you're sending messages in a transaction then you don't have to set the property
- for <emphasis>every</emphasis> message you send in that transaction, you only need to
- set it once in the transaction. If the server detects a duplicate message for any
- message in the transaction, then it will ignore the entire transaction.</para>
- <para>The name of the property that you set is given by the value of <literal
- >org.apache.activemq.api.core.Message.HDR_DUPLICATE_DETECTION_ID</literal>, which
- is <literal>_HQ_DUPL_ID</literal></para>
- <para>The value of the property can be of type <literal>byte[]</literal> or <literal
- >SimpleString</literal> if you're using the core API. If you're using JMS it must be
- a <literal>String</literal>, and its value should be unique. An easy way of generating
- a unique id is by generating a UUID.</para>
- <para>Here's an example of setting the property using the core API:</para>
- <programlisting>
-...
-
-ClientMessage message = session.createMessage(true);
-
-SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this
-
-message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
-
-...</programlisting>
- <para>And here's an example using the JMS API:</para>
- <programlisting>
-...
-
-Message jmsMessage = session.createMessage();
-
-String myUniqueID = "This is my unique id"; // Could use a UUID for this
-
-message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
-
-...</programlisting>
- </section>
- <section id="duplicate.id.cache">
- <title>Configuring the Duplicate ID Cache</title>
- <para>The server maintains caches of received values of the <literal
- >org.apache.activemq.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal> property
- sent to each address. Each address has its own distinct cache.</para>
- <para>The cache is a circular fixed size cache. If the cache has a maximum size of <literal
- >n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite
- the <literal>0</literal>th element in the cache.</para>
- <para>The maximum size of the cache is configured by the parameter <literal
- >id-cache-size</literal> in <literal>activemq-configuration.xml</literal>, the default
- value is <literal>2000</literal> elements.</para>
- <para>The caches can also be configured to persist to disk or not. This is configured by the
- parameter <literal>persist-id-cache</literal>, also in <literal
- >activemq-configuration.xml</literal>. If this is set to <literal>true</literal> then
- each id will be persisted to permanent storage as they are received. The default value
- for this parameter is <literal>true</literal>.</para>
- <note>
- <para>When choosing a size of the duplicate id cache be sure to set it to a larger
- enough size so if you resend messages all the previously sent ones are in the cache
- not having been overwritten.</para>
- </note>
- </section>
- <section>
- <title>Duplicate Detection and Bridges</title>
- <para>Core bridges can be configured to automatically add a unique duplicate id value (if there
- isn't already one in the message) before forwarding the message to it's target. This
- ensures that if the target server crashes or the connection is interrupted and the
- bridge resends the message, then if it has already been received by the target server,
- it will be ignored.</para>
- <para>To configure a core bridge to add the duplicate id header, simply set the <parameter
- >use-duplicate-detection</parameter> to <literal>true</literal> when configuring a
- bridge in <literal>activemq-configuration.xml</literal>.</para>
- <para>The default value for this parameter is <literal>true</literal>.</para>
- <para>For more information on core bridges and how to configure them, please see
- <xref linkend="core-bridges" />.</para>
- </section>
- <section>
- <title>Duplicate Detection and Cluster Connections</title>
- <para>Cluster connections internally use core bridges to move messages reliable between
- nodes of the cluster. Consequently they can also be configured to insert the duplicate
- id header for each message they move using their internal bridges.</para>
- <para>To configure a cluster connection to add the duplicate id header, simply set the
- <parameter>use-duplicate-detection</parameter> to <literal>true</literal> when
- configuring a cluster connection in <literal>activemq-configuration.xml</literal>.</para>
- <para>The default value for this parameter is <literal>true</literal>.</para>
- <para>For more information on cluster connections and how to configure them, please see <xref
- linkend="clusters"/>.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/embedding-activemq.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/embedding-activemq.md b/docs/user-manual/en/embedding-activemq.md
new file mode 100644
index 0000000..0c29d59
--- /dev/null
+++ b/docs/user-manual/en/embedding-activemq.md
@@ -0,0 +1,225 @@
+Embedding ActiveMQ
+==================
+
+ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
+This means ActiveMQ can be instantiated and run in any dependency
+injection framework such as JBoss Microcontainer, Spring or Google
+Guice. It also means that if you have an application that could use
+messaging functionality internally, then it can *directly instantiate*
+ActiveMQ clients and servers in its own application code to perform that
+functionality. We call this *embedding* ActiveMQ.
+
+Examples of applications that might want to do this include any
+application that needs very high performance, transactional, persistent
+messaging but doesn't want the hassle of writing it all from scratch.
+
+Embedding ActiveMQ can be done in very few easy steps. Instantiate the
+configuration object, instantiate the server, start it, and you have a
+ActiveMQ running in your virtual machine. It's as simple and easy as
+that.
+
+Simple Config File Embedding
+============================
+
+The simplest way to embed ActiveMQ is to use the embedded wrapper
+classes and configure ActiveMQ through its configuration files. There
+are two different helper classes for this depending on whether your
+using the ActiveMQ Core API or JMS.
+
+Core API Only
+-------------
+
+For instantiating a core ActiveMQ Server only, the steps are pretty
+simple. The example requires that you have defined a configuration file
+`activemq-configuration.xml` in your classpath:
+
+ import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
+
+ ...
+
+ EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
+ embedded.start();
+
+ ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
+ new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
+
+ ClientSession session = factory.createSession();
+
+ session.createQueue("example", "example", true);
+
+ ClientProducer producer = session.createProducer("example");
+
+ ClientMessage message = session.createMessage(true);
+
+ message.getBody().writeString("Hello");
+
+ producer.send(message);
+
+ session.start();
+
+ ClientConsumer consumer = session.createConsumer("example");
+
+ ClientMessage msgReceived = consumer.receive();
+
+ System.out.println("message = " + msgReceived.getBody().readString());
+
+ session.close();
+
+The `EmbeddedActiveMQ` class has a few additional setter methods that
+allow you to specify a different config file name as well as other
+properties. See the javadocs for this class for more details.
+
+JMS API
+-------
+
+JMS embedding is simple as well. This example requires that you have
+defined the config files `activemq-configuration.xml`,
+`activemq-jms.xml`, and a `activemq-users.xml` if you have security
+enabled. Let's also assume that a queue and connection factory has been
+defined in the `activemq-jms.xml` config file.
+
+ import org.apache.activemq.jms.server.embedded.EmbeddedJMS;
+
+ ...
+
+ EmbeddedJMS jms = new EmbeddedJMS();
+ jms.start();
+
+ // This assumes we have configured activemq-jms.xml with the appropriate config information
+ ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
+ Destination destination = jms.lookup("/example/queue");
+
+ ... regular JMS code ...
+
+By default, the `EmbeddedJMS` class will store component entries defined
+within your `activemq-jms.xml` file in an internal concurrent hash map.
+The `EmbeddedJMS.lookup()` method returns components stored in this map.
+If you want to use JNDI, call the `EmbeddedJMS.setContext()` method with
+the root JNDI context you want your components bound into. See the
+javadocs for this class for more details on other config options.
+
+POJO instantiation - Embedding Programmatically
+===============================================
+
+You can follow this step-by-step guide to programmatically embed the
+core, non-JMS ActiveMQ Server instance:
+
+Create the configuration object - this contains configuration
+information for a ActiveMQ instance. The setter methods of this class
+allow you to programmatically set configuration options as describe in
+the ? section.
+
+The acceptors are configured through `ConfigurationImpl`. Just add the
+`NettyAcceptorFactory` on the transports the same way you would through
+the main configuration file.
+
+ import org.apache.activemq.core.config.Configuration;
+ import org.apache.activemq.core.config.impl.ConfigurationImpl;
+
+ ...
+
+ Configuration config = new ConfigurationImpl();
+ HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
+
+ transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
+ transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
+
+ config.setAcceptorConfigurations(transports);
+
+You need to instantiate an instance of
+`org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ` and add
+the configuration object to it.
+
+ import org.apache.activemq.api.core.server.ActiveMQ;
+ import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
+
+ ...
+
+ EmbeddedActiveMQ server = new EmbeddedActiveMQ();
+ server.setConfiguration(config);
+
+ server.start();
+
+You also have the option of instantiating `ActiveMQServerImpl` directly:
+
+ ActiveMQServer server = new ActiveMQServerImpl(config);
+ server.start();
+
+For JMS POJO instantiation, you work with the EmbeddedJMS class instead
+as described earlier. First you define the configuration
+programmatically for your ConnectionFactory and Destination objects,
+then set the JmsConfiguration property of the EmbeddedJMS class. Here is
+an example of this:
+
+ // Step 1. Create ActiveMQ core configuration, and set the properties accordingly
+ Configuration configuration = new ConfigurationImpl();
+ configuration.setPersistenceEnabled(false);
+ configuration.setSecurityEnabled(false);
+ configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
+
+ // Step 2. Create the JMS configuration
+ JMSConfiguration jmsConfig = new JMSConfigurationImpl();
+
+ // Step 3. Configure the JMS ConnectionFactory
+ TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
+ ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
+ jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
+
+ // Step 4. Configure the JMS Queue
+ JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
+ jmsConfig.getQueueConfigurations().add(queueConfig);
+
+ // Step 5. Start the JMS Server using the ActiveMQ core server and the JMS configuration
+ EmbeddedJMS jmsServer = new EmbeddedJMS();
+ jmsServer.setConfiguration(configuration);
+ jmsServer.setJmsConfiguration(jmsConfig);
+ jmsServer.start();
+
+Please see ? for an example which shows how to setup and run ActiveMQ
+embedded with JMS.
+
+Dependency Frameworks
+=====================
+
+You may also choose to use a dependency injection framework such as
+JBoss Micro Container or Spring Framework. See ? for more details on
+Spring and ActiveMQ, but here's how you would do things with the JBoss
+Micro Container.
+
+ActiveMQ standalone uses JBoss Micro Container as the injection
+framework. `ActiveMQBootstrapServer` and `activemq-beans.xml` which are
+part of the ActiveMQ distribution provide a very complete implementation
+of what's needed to bootstrap the server using JBoss Micro Container.
+
+When using JBoss Micro Container, you need to provide an XML file
+declaring the `ActiveMQServer` and `Configuration` object, you can also
+inject a security manager and a MBean server if you want, but those are
+optional.
+
+A very basic XML Bean declaration for the JBoss Micro Container would
+be:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+ <!-- The core configuration -->
+ <bean name="Configuration"
+ class="org.apache.activemq.core.config.impl.FileConfiguration">
+ </bean>
+
+ <!-- The core server -->
+ <bean name="ActiveMQServer"
+ class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
+ <constructor>
+ <parameter>
+ <inject bean="Configuration"/>
+ </parameter>
+ </constructor>
+ </bean>
+ </deployment>
+
+`ActiveMQBootstrapServer` provides an easy encapsulation of JBoss Micro
+Container.
+
+ ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
+ bootStrap.run();
[09/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/management.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/management.xml b/docs/user-manual/en/management.xml
deleted file mode 100644
index f1b868f..0000000
--- a/docs/user-manual/en/management.xml
+++ /dev/null
@@ -1,1117 +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="management">
- <title>Management</title>
- <para>ActiveMQ has an extensive management API that allows a user to modify a server
- configuration, create new resources (e.g. JMS queues and topics), inspect these resources
- (e.g. how many messages are currently held in a queue) and interact with it (e.g. to remove
- messages from a queue). All the operations allows a client to <emphasis>manage</emphasis>
- ActiveMQ. It also allows clients to subscribe to management notifications.</para>
- <para>There are 3 ways to manage ActiveMQ:</para>
- <itemizedlist>
- <listitem>
- <para>Using JMX -- JMX is the standard way to manage Java applications</para>
- </listitem>
- <listitem>
- <para>Using the core API -- management operations are sent to ActiveMQ server using
- <emphasis>core messages</emphasis></para>
- </listitem>
- <listitem>
- <para>Using the JMS API -- management operations are sent to ActiveMQ server using
- <emphasis>JMS messages</emphasis></para>
- </listitem>
- </itemizedlist>
- <para>Although there are 3 different ways to manage ActiveMQ each API supports the same
- functionality. If it is possible to manage a resource using JMX it is also possible to achieve
- the same result using Core messages or JMS messages.</para>
- <para>This choice depends on your requirements, your application settings and your environment to
- decide which way suits you best.</para>
- <section>
- <title>The Management API</title>
- <para>Regardless of the way you <emphasis>invoke</emphasis> management operations, the
- management API is the same.</para>
- <para>For each <emphasis>managed resource</emphasis>, there exists a Java interface describing
- what can be invoked for this type of resource.</para>
- <para>ActiveMQ exposes its managed resources in 2 packages:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis>Core</emphasis> resources are located in the <literal
- >org.apache.activemq.api.core.management</literal> package</para>
- </listitem>
- <listitem>
- <para><emphasis>JMS</emphasis> resources are located in the <literal
- >org.apache.activemq.api.jms.management</literal> package</para>
- </listitem>
- </itemizedlist>
- <para>The way to invoke a <emphasis>management operations</emphasis> depends whether JMX, core
- messages, or JMS messages are used.</para>
- <note>
- <para>A few management operations requires a <literal>filter</literal> parameter to chose
- which messages are involved by the operation. Passing <literal>null</literal> or an
- empty string means that the management operation will be performed on <emphasis>all
- messages</emphasis>.</para>
- </note>
- <section>
- <title>Core Management API</title>
- <para>ActiveMQ defines a core management API to manage core resources. For full details of
- the API please consult the javadoc. In summary:</para>
- <section id="management.core.server">
- <title>Core Server Management</title>
- <itemizedlist>
- <listitem>
- <para>Listing, creating, deploying and destroying queues</para>
- <para>A list of deployed core queues can be retrieved using the <literal
- >getQueueNames()</literal> method.</para>
- <para>Core queues can be created or destroyed using the management operations
- <literal>createQueue()</literal> or <literal>deployQueue()</literal> or
- <literal>destroyQueue()</literal>)on the <literal
- >ActiveMQServerControl</literal> (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
- >core.server</literal>)</para>
- <para><literal>createQueue</literal> will fail if the queue already exists while
- <literal>deployQueue</literal> will do nothing.</para>
- </listitem>
- <listitem>
- <para>Pausing and resuming Queues</para>
- <para>The <literal>QueueControl</literal> can pause and resume the underlying
- queue. When a queue is paused, it will receive messages but will not deliver
- them. When it's resumed, it'll begin delivering the queued messages, if any.
- </para>
- </listitem>
- <listitem>
- <para>Listing and closing remote connections</para>
- <para>Client's remote addresses can be retrieved using <literal
- >listRemoteAddresses()</literal>. It is also possible to close the
- connections associated with a remote address using the <literal
- >closeConnectionsForAddress()</literal> method.</para>
- <para>Alternatively, connection IDs can be listed using <literal
- >listConnectionIDs()</literal> and all the sessions for a given connection
- ID can be listed using <literal>listSessions()</literal>.</para>
- </listitem>
- <listitem>
- <para>Transaction heuristic operations</para>
- <para>In case of a server crash, when the server restarts, it it possible that
- some transaction requires manual intervention. The <literal
- >listPreparedTransactions()</literal> method lists the transactions which
- are in the prepared states (the transactions are represented as opaque Base64
- Strings.) To commit or rollback a given prepared transaction, the <literal
- >commitPreparedTransaction()</literal> or <literal
- >rollbackPreparedTransaction()</literal> method can be used to resolve
- heuristic transactions. Heuristically completed transactions can be listed
- using the <literal>listHeuristicCommittedTransactions()</literal> and <literal
- >listHeuristicRolledBackTransactions</literal> methods.</para>
- </listitem>
- <listitem>
- <para>Enabling and resetting Message counters</para>
- <para>Message counters can be enabled or disabled using the <literal
- >enableMessageCounters()</literal> or <literal
- >disableMessageCounters()</literal> method. To reset message counters, it is
- possible to invoke <literal>resetAllMessageCounters()</literal> and <literal
- >resetAllMessageCounterHistories()</literal> methods.</para>
- </listitem>
- <listitem>
- <para>Retrieving the server configuration and attributes</para>
- <para>The <literal>ActiveMQServerControl</literal> exposes ActiveMQ server
- configuration through all its attributes (e.g. <literal>getVersion()</literal>
- method to retrieve the server's version, etc.)</para>
- </listitem>
- <listitem>
- <para>Listing, creating and destroying Core bridges and diverts</para>
- <para>A list of deployed core bridges (resp. diverts) can be retrieved using the <literal
- >getBridgeNames()</literal> (resp. <literal>getDivertNames()</literal>) method.</para>
- <para>Core bridges (resp. diverts) can be created or destroyed using the management operations
- <literal>createBridge()</literal> and <literal>destroyBridge()</literal>
- (resp. <literal>createDivert()</literal> and <literal>destroyDivert()</literal>) on the <literal
- >ActiveMQServerControl</literal> (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
- >core.server</literal>).</para>
- </listitem>
- <listitem>
- <para>It is possible to stop the server and force failover to occur with any currently attached clients.</para>
- <para>to do this use the <literal>forceFailover()</literal> on the <literal
- >ActiveMQServerControl</literal> (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
- >core.server</literal>) </para>
- <note>
- <para>Since this method actually stops the server you will probably receive some sort of error
- depending on which management service you use to call it.
- </para>
- </note>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Core Address Management</title>
- <para>Core addresses can be managed using the <literal>AddressControl</literal> class
- (with the ObjectName <literal>org.apache.activemq:module=Core,type=Address,name="<the
- address name>"</literal> or the resource name <literal>core.address.<the
- address name></literal>). </para>
- <itemizedlist>
- <listitem>
- <para>Modifying roles and permissions for an address</para>
- <para>You can add or remove roles associated to a queue using the <literal
- >addRole()</literal> or <literal>removeRole()</literal> methods. You can
- list all the roles associated to the queue with the <literal
- >getRoles()</literal> method</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Core Queue Management</title>
- <para>The bulk of the core management API deals with core queues. The <literal
- >QueueControl</literal> class defines the Core queue management operations (with
- the ObjectName <literal>org.apache.activemq:module=Core,type=Queue,address="<the bound
- address>",name="<the queue name>"</literal> or the resource name <literal
- >core.queue.<the queue name></literal>).</para>
- <para>Most of the management operations on queues take either a single message ID (e.g.
- to remove a single message) or a filter (e.g. to expire all messages with a given
- property.)</para>
- <itemizedlist>
- <listitem>
- <para>Expiring, sending to a dead letter address and moving messages</para>
- <para>Messages can be expired from a queue by using the <literal
- >expireMessages()</literal> method. If an expiry address is defined,
- messages will be sent to it, otherwise they are discarded. The queue's
- expiry address can be set with the <literal>setExpiryAddress()</literal>
- method.</para>
- <para>Messages can also be sent to a dead letter address with the <literal
- >sendMessagesToDeadLetterAddress()</literal> method. It returns the number
- of messages which are sent to the dead letter address. If a dead letter address
- is not defined, message are removed from the queue and discarded. The queue's
- dead letter address can be set with the <literal
- >setDeadLetterAddress()</literal> method.</para>
- <para>Messages can also be moved from a queue to another queue by using the
- <literal>moveMessages()</literal> method.</para>
- </listitem>
- <listitem>
- <para>Listing and removing messages</para>
- <para>Messages can be listed from a queue by using the <literal
- >listMessages()</literal> method which returns an array of <literal
- >Map</literal>, one <literal>Map</literal> for each message.</para>
- <para>Messages can also be removed from the queue by using the <literal
- >removeMessages()</literal> method which returns a <literal
- >boolean</literal> for the single message ID variant or the number of
- removed messages for the filter variant. The <literal
- >removeMessages()</literal> method takes a <literal>filter</literal>
- argument to remove only filtered messages. Setting the filter to an empty
- string will in effect remove all messages.</para>
- </listitem>
- <listitem>
- <para>Counting messages</para>
- <para>The number of messages in a queue is returned by the <literal
- >getMessageCount()</literal> method. Alternatively, the <literal
- >countMessages()</literal> will return the number of messages in the queue
- which <emphasis>match a given filter</emphasis></para>
- </listitem>
- <listitem>
- <para>Changing message priority</para>
- <para>The message priority can be changed by using the <literal
- >changeMessagesPriority()</literal> method which returns a <literal
- >boolean</literal> for the single message ID variant or the number of
- updated messages for the filter variant.</para>
- </listitem>
- <listitem>
- <para>Message counters</para>
- <para>Message counters can be listed for a queue with the <literal
- >listMessageCounter()</literal> and <literal
- >listMessageCounterHistory()</literal> methods (see <xref
- linkend="management.message-counters"/>). The message counters can also be
- reset for a single queue using the <literal>resetMessageCounter()</literal>
- method.</para>
- </listitem>
- <listitem>
- <para>Retrieving the queue attributes</para>
- <para>The <literal>QueueControl</literal> exposes Core queue settings through its
- attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's filter
- if it was created with one, <literal>isDurable()</literal> to know whether the
- queue is durable or not, etc.)</para>
- </listitem>
- <listitem>
- <para>Pausing and resuming Queues</para>
- <para>The <literal>QueueControl</literal> can pause and resume the underlying
- queue. When a queue is paused, it will receive messages but will not deliver
- them. When it's resume, it'll begin delivering the queued messages, if any.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Other Core Resources Management</title>
- <para>ActiveMQ allows to start and stop its remote resources (acceptors, diverts,
- bridges, etc.) so that a server can be taken off line for a given period of time
- without stopping it completely (e.g. if other management operations must be performed
- such as resolving heuristic transactions). These resources are:</para>
- <itemizedlist>
- <listitem>
- <para>Acceptors</para>
- <para>They can be started or stopped using the <literal>start()</literal> or.
- <literal>stop()</literal> method on the <literal>AcceptorControl</literal>
- class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Acceptor,name="<the acceptor
- name>"</literal> or the resource name <literal>core.acceptor.<the
- address name></literal>). The acceptors parameters can be retrieved using
- the <literal>AcceptorControl</literal> attributes (see <xref
- linkend="configuring-transports.acceptors"/>)</para>
- </listitem>
- <listitem>
- <para>Diverts</para>
- <para>They can be started or stopped using the <literal>start()</literal> or
- <literal>stop()</literal> method on the <literal>DivertControl</literal>
- class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Divert,name=<the divert name></literal>
- or the resource name <literal>core.divert.<the divert name></literal>).
- Diverts parameters can be retrieved using the <literal>DivertControl</literal>
- attributes (see <xref linkend="diverts"/>)</para>
- </listitem>
- <listitem>
- <para>Bridges</para>
- <para>They can be started or stopped using the <literal>start()</literal> (resp.
- <literal>stop()</literal>) method on the <literal>BridgeControl</literal>
- class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=Bridge,name="<the bridge
- name>"</literal> or the resource name <literal>core.bridge.<the bridge
- name></literal>). Bridges parameters can be retrieved using the <literal
- >BridgeControl</literal> attributes (see <xref linkend="core-bridges"
- />)</para>
- </listitem>
- <listitem>
- <para>Broadcast groups</para>
- <para>They can be started or stopped using the <literal>start()</literal> or
- <literal>stop()</literal> method on the <literal
- >BroadcastGroupControl</literal> class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=BroadcastGroup,name="<the broadcast group
- name>"</literal> or the resource name <literal
- >core.broadcastgroup.<the broadcast group name></literal>). Broadcast
- groups parameters can be retrieved using the <literal
- >BroadcastGroupControl</literal> attributes (see <xref
- linkend="clusters"/>)</para>
- </listitem>
- <listitem>
- <para>Discovery groups</para>
- <para>They can be started or stopped using the <literal>start()</literal> or
- <literal>stop()</literal> method on the <literal
- >DiscoveryGroupControl</literal> class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=DiscoveryGroup,name="<the discovery group
- name>"</literal> or the resource name <literal>core.discovery.<the
- discovery group name></literal>). Discovery groups parameters can be
- retrieved using the <literal>DiscoveryGroupControl</literal> attributes (see
- <xref linkend="clusters"/>)</para>
- </listitem>
- <listitem>
- <para>Cluster connections</para>
- <para>They can be started or stopped using the <literal>start()</literal> or
- <literal>stop()</literal> method on the <literal
- >ClusterConnectionControl</literal> class (with the ObjectName <literal
- >org.apache.activemq:module=Core,type=ClusterConnection,name="<the cluster
- connection name>"</literal> or the resource name <literal
- >core.clusterconnection.<the cluster connection name></literal>).
- Cluster connections parameters can be retrieved using the <literal
- >ClusterConnectionControl</literal> attributes (see <xref
- linkend="clusters"/>)</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section>
- <title>JMS Management API</title>
- <para>ActiveMQ defines a JMS Management API to manage JMS <emphasis>administrated
- objects</emphasis> (i.e. JMS queues, topics and connection factories).</para>
- <section>
- <title>JMS Server Management</title>
- <para>JMS Resources (connection factories and destinations) can be created using the
- <literal>JMSServerControl</literal> class (with the ObjectName <literal
- >org.apache.activemq:module=JMS,type=Server</literal> or the resource name <literal
- >jms.server</literal>).</para>
- <itemizedlist>
- <listitem>
- <para>Listing, creating, destroying connection factories</para>
- <para>Names of the deployed connection factories can be retrieved by the <literal
- >getConnectionFactoryNames()</literal> method.</para>
- <para>JMS connection factories can be created or destroyed using the <literal
- >createConnectionFactory()</literal> methods or <literal
- >destroyConnectionFactory()</literal> methods. These connection factories
- are bound to JNDI so that JMS clients can look them up. If a graphical console
- is used to create the connection factories, the transport parameters are
- specified in the text field input as a comma-separated list of key=value (e.g.
- <literal>key1=10, key2="value", key3=false</literal>). If there are multiple
- transports defined, you need to enclose the key/value pairs between curly
- braces. For example <literal>{key=10}, {key=20}</literal>. In that case, the
- first <literal>key</literal> will be associated to the first transport
- configuration and the second <literal>key</literal> will be associated to the
- second transport configuration (see <xref linkend="configuring-transports"/>
- for a list of the transport parameters)</para>
- </listitem>
- <listitem>
- <para>Listing, creating, destroying queues</para>
- <para>Names of the deployed JMS queues can be retrieved by the <literal
- >getQueueNames()</literal> method.</para>
- <para>JMS queues can be created or destroyed using the <literal
- >createQueue()</literal> methods or <literal>destroyQueue()</literal>
- methods. These queues are bound to JNDI so that JMS clients can look them
- up</para>
- </listitem>
- <listitem>
- <para>Listing, creating/destroying topics</para>
- <para>Names of the deployed topics can be retrieved by the <literal
- >getTopicNames()</literal> method.</para>
- <para>JMS topics can be created or destroyed using the <literal
- >createTopic()</literal> or <literal>destroyTopic()</literal> methods. These
- topics are bound to JNDI so that JMS clients can look them up</para>
- </listitem>
- <listitem>
- <para>Listing and closing remote connections</para>
- <para>JMS Clients remote addresses can be retrieved using <literal
- >listRemoteAddresses()</literal>. It is also possible to close the
- connections associated with a remote address using the <literal
- >closeConnectionsForAddress()</literal> method.</para>
- <para>Alternatively, connection IDs can be listed using <literal
- >listConnectionIDs()</literal> and all the sessions for a given connection
- ID can be listed using <literal>listSessions()</literal>.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>JMS ConnectionFactory Management</title>
- <para>JMS Connection Factories can be managed using the <literal
- >ConnectionFactoryControl</literal> class (with the ObjectName <literal
- >org.apache.activemq:module=JMS,type=ConnectionFactory,name="<the connection factory
- name>"</literal> or the resource name <literal>jms.connectionfactory.<the
- connection factory name></literal>).</para>
- <itemizedlist>
- <listitem>
- <para>Retrieving connection factory attributes</para>
- <para>The <literal>ConnectionFactoryControl</literal> exposes JMS
- ConnectionFactory configuration through its attributes (e.g. <literal
- >getConsumerWindowSize()</literal> to retrieve the consumer window size for
- flow control, <literal>isBlockOnNonDurableSend()</literal> to know whether the
- producers created from the connection factory will block or not when sending
- non-durable messages, etc.)</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>JMS Queue Management</title>
- <para>JMS queues can be managed using the <literal>JMSQueueControl</literal> class (with
- the ObjectName <literal>org.apache.activemq:module=JMS,type=Queue,name="<the queue
- name>"</literal> or the resource name <literal>jms.queue.<the queue
- name></literal>). </para>
- <para><emphasis>The management operations on a JMS queue are very similar to the
- operations on a core queue. </emphasis></para>
- <itemizedlist>
- <listitem>
- <para>Expiring, sending to a dead letter address and moving messages</para>
- <para>Messages can be expired from a queue by using the <literal
- >expireMessages()</literal> method. If an expiry address is defined,
- messages will be sent to it, otherwise they are discarded. The queue's
- expiry address can be set with the <literal>setExpiryAddress()</literal>
- method.</para>
- <para>Messages can also be sent to a dead letter address with the <literal
- >sendMessagesToDeadLetterAddress()</literal> method. It returns the number
- of messages which are sent to the dead letter address. If a dead letter address
- is not defined, message are removed from the queue and discarded. The queue's
- dead letter address can be set with the <literal
- >setDeadLetterAddress()</literal> method.</para>
- <para>Messages can also be moved from a queue to another queue by using the
- <literal>moveMessages()</literal> method.</para>
- </listitem>
- <listitem>
- <para>Listing and removing messages</para>
- <para>Messages can be listed from a queue by using the <literal
- >listMessages()</literal> method which returns an array of <literal
- >Map</literal>, one <literal>Map</literal> for each message.</para>
- <para>Messages can also be removed from the queue by using the <literal
- >removeMessages()</literal> method which returns a <literal
- >boolean</literal> for the single message ID variant or the number of
- removed messages for the filter variant. The <literal
- >removeMessages()</literal> method takes a <literal>filter</literal>
- argument to remove only filtered messages. Setting the filter to an empty
- string will in effect remove all messages.</para>
- </listitem>
- <listitem>
- <para>Counting messages</para>
- <para>The number of messages in a queue is returned by the <literal
- >getMessageCount()</literal> method. Alternatively, the <literal
- >countMessages()</literal> will return the number of messages in the queue
- which <emphasis>match a given filter</emphasis></para>
- </listitem>
- <listitem>
- <para>Changing message priority</para>
- <para>The message priority can be changed by using the <literal
- >changeMessagesPriority()</literal> method which returns a <literal
- >boolean</literal> for the single message ID variant or the number of
- updated messages for the filter variant.</para>
- </listitem>
- <listitem>
- <para>Message counters</para>
- <para>Message counters can be listed for a queue with the <literal
- >listMessageCounter()</literal> and <literal
- >listMessageCounterHistory()</literal> methods (see <xref
- linkend="management.message-counters"/>)</para>
- </listitem>
- <listitem>
- <para>Retrieving the queue attributes</para>
- <para>The <literal>JMSQueueControl</literal> exposes JMS queue settings through
- its attributes (e.g. <literal>isTemporary()</literal> to know whether the queue
- is temporary or not, <literal>isDurable()</literal> to know whether the queue is
- durable or not, etc.)</para>
- </listitem>
- <listitem>
- <para>Pausing and resuming queues</para>
- <para>The <literal>JMSQueueControl</literal> can pause and resume the underlying
- queue. When the queue is paused it will continue to receive messages but will
- not deliver them. When resumed again it will deliver the enqueued messages, if
- any. </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>JMS Topic Management</title>
- <para>JMS Topics can be managed using the <literal>TopicControl</literal> class (with
- the ObjectName <literal>org.apache.activemq:module=JMS,type=Topic,name="<the topic
- name>"</literal> or the resource name <literal>jms.topic.<the topic
- name></literal>).</para>
- <itemizedlist>
- <listitem>
- <para>Listing subscriptions and messages</para>
- <para>JMS topics subscriptions can be listed using the <literal
- >listAllSubscriptions()</literal>, <literal
- >listDurableSubscriptions()</literal>, <literal
- >listNonDurableSubscriptions()</literal> methods. These methods return
- arrays of <literal>Object</literal> representing the subscriptions information
- (subscription name, client ID, durability, message count, etc.). It is also
- possible to list the JMS messages for a given subscription with the <literal
- >listMessagesForSubscription()</literal> method.</para>
- </listitem>
- <listitem>
- <para>Dropping subscriptions</para>
- <para>Durable subscriptions can be dropped from the topic using the <literal
- >dropDurableSubscription()</literal> method.</para>
- </listitem>
- <listitem>
- <para>Counting subscriptions messages</para>
- <para>The <literal>countMessagesForSubscription()</literal> method can be used to
- know the number of messages held for a given subscription (with an optional
- message selector to know the number of messages matching the selector)</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- </section>
- <section id="management.jmx">
- <title>Using Management Via JMX</title>
- <para>ActiveMQ can be managed using <ulink
- url="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html"
- >JMX</ulink>. </para>
- <para>The management API is exposed by ActiveMQ using MBeans interfaces. ActiveMQ registers its
- resources with the domain <literal>org.apache.activemq</literal>.</para>
- <para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal
- >exampleQueue</literal> is:</para>
- <programlisting>
-org.apache.activemq:module=JMS,type=Queue,name="exampleQueue"</programlisting>
- <para>and the MBean is:</para>
- <programlisting>
-org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
- <para>The MBean's <literal>ObjectName</literal> are built using the helper class <literal
- >org.apache.activemq.api.core.management.ObjectNameBuilder</literal>. You can also use <literal
- >jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to
- manage. </para>
- <para>Managing ActiveMQ using JMX is identical to management of any Java Applications using
- JMX. It can be done by reflection or by creating proxies of the MBeans.</para>
- <section id="management.jmx.configuration">
- <title>Configuring JMX</title>
- <para>By default, JMX is enabled to manage ActiveMQ. It can be disabled by setting <literal
- >jmx-management-enabled</literal> to <literal>false</literal> in <literal
- >activemq-configuration.xml</literal>:</para>
- <programlisting>
-<!-- false to disable JMX management for ActiveMQ -->
-<jmx-management-enabled>false</jmx-management-enabled></programlisting>
- <para>If JMX is enabled, ActiveMQ can be managed locally using <literal>jconsole</literal>.</para>
- <note>
- <para>Remote connections to JMX are not enabled by default for security reasons. Please refer
- to <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html"
- >Java Management guide</ulink> to configure the server for remote management (system
- properties must be set in <literal>run.sh</literal> or <literal>run.bat</literal>
- scripts).</para>
- </note>
- <para>By default, ActiveMQ server uses the JMX domain "org.apache.activemq". To manage several
- ActiveMQ servers from the <emphasis>same</emphasis> MBeanServer, the JMX domain can be
- configured for each individual ActiveMQ server by setting <literal>jmx-domain</literal>
- in <literal>activemq-configuration.xml</literal>: </para>
- <programlisting>
-<!-- use a specific JMX domain for ActiveMQ MBeans -->
-<jmx-domain>my.org.apache.activemq</jmx-domain></programlisting>
- <section>
- <title>MBeanServer configuration</title>
- <para>When ActiveMQ is run in standalone, it uses the Java Virtual Machine's <literal
- >Platform MBeanServer</literal> to register its MBeans. This is configured in
- JBoss Microcontainer Beans file (see <xref
- linkend="server.microcontainer.configuration"/>):</para>
- <programlisting>
-<!-- MBeanServer -->
-<bean name="MBeanServer" class="javax.management.MBeanServer">
- <constructor factoryClass="java.lang.management.ManagementFactory"
- factoryMethod="getPlatformMBeanServer" />
-</bean></programlisting>
- <para>When it is integrated in JBoss AS 5+, it uses the Application Server's own MBean
- Server so that it can be managed using AS 5's jmx-console:</para>
- <programlisting>
-<!-- MBeanServer -->
-<bean name="MBeanServer" class="javax.management.MBeanServer">
- <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
- factoryMethod="locateJBoss" />
-</bean></programlisting>
- </section>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.jmx"/> for an example which shows how to use a remote
- connection to JMX and MBean proxies to manage ActiveMQ.</para>
- </section>
- </section>
- <section>
- <title>Using Management Via Core API</title>
- <para>The core management API in ActiveMQ is called by sending Core messages to a special
- address, the <emphasis>management address</emphasis>.</para>
- <para><emphasis>Management messages</emphasis> are regular Core messages with well-known
- properties that the server needs to understand to interact with the management API:</para>
- <itemizedlist>
- <listitem>
- <para>The name of the managed resource</para>
- </listitem>
- <listitem>
- <para>The name of the management operation</para>
- </listitem>
- <listitem>
- <para>The parameters of the management operation</para>
- </listitem>
- </itemizedlist>
- <para>When such a management message is sent to the management address, ActiveMQ server will
- handle it, extract the information, invoke the operation on the managed resources and send
- a <emphasis>management reply</emphasis> to the management message's reply-to address
- (specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para>
- <para>A <literal>ClientConsumer</literal> can be used to consume the management reply and
- retrieve the result of the operation (if any) stored in the reply's body. For portability,
- results are returned as a <ulink url="http://json.org">JSON</ulink> String rather than Java
- Serialization (the <literal>org.apache.activemq.api.core.management.ManagementHelper</literal> can
- be used to convert the JSON string to Java objects).</para>
- <para>These steps can be simplified to make it easier to invoke management operations using
- Core messages:</para>
- <orderedlist>
- <listitem>
- <para>Create a <literal>ClientRequestor</literal> to send messages to the management
- address and receive replies</para>
- </listitem>
- <listitem>
- <para>Create a <literal>ClientMessage</literal></para>
- </listitem>
- <listitem>
- <para>Use the helper class <literal
- >org.apache.activemq.api.core.management.ManagementHelper</literal> to fill the message
- with the management properties</para>
- </listitem>
- <listitem>
- <para>Send the message using the <literal>ClientRequestor</literal></para>
- </listitem>
- <listitem>
- <para>Use the helper class <literal
- >org.apache.activemq.api.core.management.ManagementHelper</literal> to retrieve the
- operation result from the management reply</para>
- </listitem>
- </orderedlist>
- <para>For example, to find out the number of messages in the core queue <literal
- >exampleQueue</literal>:</para>
- <programlisting>
-ClientSession session = ...
-ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
-ClientMessage message = session.createMessage(false);
-ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
-session.start();
-ClientMessage reply = requestor.request(m);
-int count = (Integer) ManagementHelper.getResult(reply);
-System.out.println("There are " + count + " messages in exampleQueue");</programlisting>
- <para>Management operation name and parameters must conform to the Java interfaces defined in
- the <literal>management</literal> packages.</para>
- <para>Names of the resources are built using the helper class <literal
- >org.apache.activemq.api.core.management.ResourceNames</literal> and are straightforward
- (<literal>core.queue.exampleQueue</literal> for the Core Queue <literal
- >exampleQueue</literal>, <literal>jms.topic.exampleTopic</literal> for the JMS Topic
- <literal>exampleTopic</literal>, etc.).</para>
- <section id="management.core.configuration">
- <title>Configuring Core Management</title>
- <para>The management address to send management messages is configured in <literal
- >activemq-configuration.xml</literal>:</para>
- <programlisting>
-<management-address>jms.queue.activemq.management</management-address></programlisting>
- <para>By default, the address is <literal>jms.queue.activemq.management</literal> (it is
- prepended by "jms.queue" so that JMS clients can also send management messages).</para>
- <para>The management address requires a <emphasis>special</emphasis> user permission
- <literal>manage</literal> to be able to receive and handle management messages. This
- is also configured in activemq-configuration.xml:</para>
- <programlisting>
-<!-- users with the admin role will be allowed to manage -->
-<!-- ActiveMQ using management messages -->
-<security-setting match="jms.queue.activemq.management">
- <permission type="manage" roles="admin" />
-</security-setting></programlisting>
- </section>
- </section>
- <section id="management.jms">
- <title>Using Management Via JMS</title>
- <para>Using JMS messages to manage ActiveMQ is very similar to using core API.</para>
- <para>An important difference is that JMS requires a JMS queue to send the messages to
- (instead of an address for the core API).</para>
- <para>The <emphasis>management queue</emphasis> is a special queue and needs to be
- instantiated directly by the client:</para>
- <programlisting>
-Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");</programlisting>
- <para>All the other steps are the same than for the Core API but they use JMS API
- instead:</para>
- <orderedlist>
- <listitem>
- <para>create a <literal>QueueRequestor</literal> to send messages to the management
- address and receive replies</para>
- </listitem>
- <listitem>
- <para>create a <literal>Message</literal></para>
- </listitem>
- <listitem>
- <para>use the helper class <literal
- >org.apache.activemq.api.jms.management.JMSManagementHelper</literal> to fill the message
- with the management properties</para>
- </listitem>
- <listitem>
- <para>send the message using the <literal>QueueRequestor</literal></para>
- </listitem>
- <listitem>
- <para>use the helper class <literal
- >org.apache.activemq.api.jms.management.JMSManagementHelper</literal> to retrieve the
- operation result from the management reply</para>
- </listitem>
- </orderedlist>
- <para>For example, to know the number of messages in the JMS queue <literal
- >exampleQueue</literal>:</para>
- <programlisting>
-Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
-
-QueueSession session = ...
-QueueRequestor requestor = new QueueRequestor(session, managementQueue);
-connection.start();
-Message message = session.createMessage();
-JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
-Message reply = requestor.request(message);
-int count = (Integer)JMSManagementHelper.getResult(reply);
-System.out.println("There are " + count + " messages in exampleQueue");</programlisting>
- <section>
- <title>Configuring JMS Management</title>
- <para>Whether JMS or the core API is used for management, the configuration steps are the
- same (see <xref linkend="management.core.configuration"/>).</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.management"/> for an example which shows how to use JMS
- messages to manage ActiveMQ server.</para>
- </section>
- </section>
-
- <section id="management.notifications">
- <title>Management Notifications</title>
- <para>ActiveMQ emits <emphasis>notifications</emphasis> to inform listeners of potentially
- interesting events (creation of new resources, security violation, etc.).</para>
- <para>These notifications can be received by 3 different ways:</para>
- <itemizedlist>
- <listitem>
- <para>JMX notifications</para>
- </listitem>
- <listitem>
- <para>Core messages</para>
- </listitem>
- <listitem>
- <para>JMS messages</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>JMX Notifications</title>
- <para>If JMX is enabled (see <xref linkend="management.jmx.configuration"/>), JMX
- notifications can be received by subscribing to 2 MBeans:</para>
- <itemizedlist>
- <listitem>
- <para><literal>org.apache.activemq:module=Core,type=Server</literal> for notifications on
- <emphasis>Core</emphasis> resources</para>
- </listitem>
- <listitem>
- <para><literal>org.apache.activemq:module=JMS,type=Server</literal> for notifications on
- <emphasis>JMS</emphasis> resources</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Core Messages Notifications</title>
- <para>ActiveMQ defines a special <emphasis>management notification address</emphasis>. Core
- queues can be bound to this address so that clients will receive management
- notifications as Core messages</para>
- <para>A Core client which wants to receive management notifications must create a core
- queue bound to the management notification address. It can then receive the
- notifications from its queue.</para>
- <para>Notifications messages are regular core messages with additional properties
- corresponding to the notification (its type, when it occurred, the resources which were
- concerned, etc.).</para>
- <para>Since notifications are regular core messages, it is possible to use message
- selectors to filter out notifications and receives only a subset of all the
- notifications emitted by the server.</para>
- <section id="management.notifications.core.configuration">
- <title>Configuring The Core Management Notification Address</title>
- <para>The management notification address to receive management notifications is
- configured in <literal>activemq-configuration.xml</literal>:</para>
- <programlisting>
-<management-notification-address>activemq.notifications</management-notification-address></programlisting>
- <para>By default, the address is <literal>activemq.notifications</literal>.</para>
- </section>
- </section>
- <section>
- <title>JMS Messages Notifications</title>
- <para>ActiveMQ's notifications can also be received using JMS messages.</para>
- <para>It is similar to receiving notifications using Core API but an important difference
- is that JMS requires a JMS Destination to receive the messages (preferably a
- Topic).</para>
- <para>To use a JMS Destination to receive management notifications, you must change the server's
- management notification address to start with <literal>jms.queue</literal> if it is a JMS Queue
- or <literal>jms.topic</literal> if it is a JMS Topic:</para>
- <programlisting>
-<!-- notifications will be consumed from "notificationsTopic" JMS Topic -->
-<management-notification-address>jms.topic.notificationsTopic</management-notification-address></programlisting>
- <para>Once the notification topic is created, you can receive messages from it or set a
- <literal>MessageListener</literal>:</para>
- <programlisting>
-Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
-
-Session session = ...
-MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
-notificationConsumer.setMessageListener(new MessageListener()
-{
- public void onMessage(Message notif)
- {
- System.out.println("------------------------");
- System.out.println("Received notification:");
- try
- {
- Enumeration propertyNames = notif.getPropertyNames();
- while (propertyNames.hasMoreElements())
- {
- String propertyName = (String)propertyNames.nextElement();
- System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
- }
- }
- catch (JMSException e)
- {
- }
- System.out.println("------------------------");
- }
-});</programlisting>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.management-notifications"/> for an example which shows
- how to use a JMS <literal>MessageListener</literal> to receive management notifications
- from ActiveMQ server.</para>
- </section>
- <section id="notification.types.and.headers">
- <title>Notification Types and Headers</title>
- <para>Below is a list of all the different kinds of notifications as well as which headers are
- on the messages. Every notification has a <literal>_HQ_NotifType</literal> (value noted in parentheses)
- and <literal>_HQ_NotifTimestamp</literal> header. The timestamp is the un-formatted result of a call
- to <literal>java.lang.System.currentTimeMillis()</literal>.</para>
- <itemizedlist>
- <listitem>
- <para><literal>BINDING_ADDED</literal> (0)</para>
- <para><literal>_HQ_Binding_Type</literal>, <literal>_HQ_Address</literal>,
- <literal>_HQ_ClusterName</literal>, <literal>_HQ_RoutingName</literal>,
- <literal>_HQ_Binding_ID</literal>, <literal>_HQ_Distance</literal>,
- <literal>_HQ_FilterString</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>BINDING_REMOVED</literal> (1)</para>
- <para><literal>_HQ_Address</literal>, <literal>_HQ_ClusterName</literal>,
- <literal>_HQ_RoutingName</literal>, <literal>_HQ_Binding_ID</literal>,
- <literal>_HQ_Distance</literal>, <literal>_HQ_FilterString</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>CONSUMER_CREATED</literal> (2)</para>
- <para><literal>_HQ_Address</literal>, <literal>_HQ_ClusterName</literal>,
- <literal>_HQ_RoutingName</literal>, <literal>_HQ_Distance</literal>,
- <literal>_HQ_ConsumerCount</literal>, <literal>_HQ_User</literal>,
- <literal>_HQ_RemoteAddress</literal>, <literal>_HQ_SessionName</literal>,
- <literal>_HQ_FilterString</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>CONSUMER_CLOSED</literal> (3)</para>
- <para><literal>_HQ_Address</literal>, <literal>_HQ_ClusterName</literal>,
- <literal>_HQ_RoutingName</literal>, <literal>_HQ_Distance</literal>,
- <literal>_HQ_ConsumerCount</literal>, <literal>_HQ_User</literal>,
- <literal>_HQ_RemoteAddress</literal>, <literal>_HQ_SessionName</literal>,
- <literal>_HQ_FilterString</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>SECURITY_AUTHENTICATION_VIOLATION</literal> (6)</para>
- <para><literal>_HQ_User</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>SECURITY_PERMISSION_VIOLATION</literal> (7)</para>
- <para><literal>_HQ_Address</literal>, <literal>_HQ_CheckType</literal>,
- <literal>_HQ_User</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>DISCOVERY_GROUP_STARTED</literal> (8)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>DISCOVERY_GROUP_STOPPED</literal> (9)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>BROADCAST_GROUP_STARTED</literal> (10)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>BROADCAST_GROUP_STOPPED</literal> (11)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>BRIDGE_STARTED</literal> (12)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>BRIDGE_STOPPED</literal> (13)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>CLUSTER_CONNECTION_STARTED</literal> (14)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>CLUSTER_CONNECTION_STOPPED</literal> (15)</para>
- <para><literal>name</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>ACCEPTOR_STARTED</literal> (16)</para>
- <para><literal>factory</literal>, <literal>id</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>ACCEPTOR_STOPPED</literal> (17)</para>
- <para><literal>factory</literal>, <literal>id</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>PROPOSAL</literal> (18)</para>
- <para><literal>_JBM_ProposalGroupId</literal>, <literal>_JBM_ProposalValue</literal>,
- <literal>_HQ_Binding_Type</literal>, <literal>_HQ_Address</literal>,
- <literal>_HQ_Distance</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>PROPOSAL_RESPONSE</literal> (19)</para>
- <para><literal>_JBM_ProposalGroupId</literal>, <literal>_JBM_ProposalValue</literal>,
- <literal>_JBM_ProposalAltValue</literal>, <literal>_HQ_Binding_Type</literal>,
- <literal>_HQ_Address</literal>, <literal>_HQ_Distance</literal></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><literal>CONSUMER_SLOW</literal> (21)</para>
- <para><literal>_HQ_Address</literal>, <literal>_HQ_ConsumerCount</literal>,
- <literal>_HQ_RemoteAddress</literal>, <literal>_HQ_ConnectionName</literal>,
- <literal>_HQ_ConsumerName</literal>, <literal>_HQ_SessionName</literal></para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="management.message-counters">
- <title>Message Counters</title>
- <para>Message counters can be used to obtain information on queues <emphasis>over
- time</emphasis> as ActiveMQ keeps a history on queue metrics.</para>
- <para>They can be used to show <emphasis>trends</emphasis> on queues. For example, using the
- management API, it would be possible to query the number of messages in a queue at regular
- interval. However, this would not be enough to know if the queue is used: the number of
- messages can remain constant because nobody is sending or receiving messages from the queue
- or because there are as many messages sent to the queue than messages consumed from it. The
- number of messages in the queue remains the same in both cases but its use is widely
- different.</para>
- <para>Message counters gives additional information about the queues:</para>
- <itemizedlist>
- <listitem>
- <para><literal>count</literal></para>
- <para>The <emphasis>total</emphasis> number of messages added to the queue since the
- server was started</para>
- </listitem>
- <listitem>
- <para><literal>countDelta</literal></para>
- <para>the number of messages added to the queue <emphasis>since the last message counter
- update</emphasis></para>
- </listitem>
- <listitem>
- <para><literal>messageCount</literal></para>
- <para>The <emphasis>current</emphasis> number of messages in the queue</para>
- </listitem>
- <listitem>
- <para><literal>messageCountDelta</literal></para>
- <para>The <emphasis>overall</emphasis> number of messages added/removed from the queue
- <emphasis>since the last message counter update</emphasis>. For example, if
- <literal>messageCountDelta</literal> is equal to <literal>-10</literal> this means that
- overall 10 messages have been removed from the queue (e.g. 2 messages were added and
- 12 were removed)</para>
- </listitem>
- <listitem>
- <para><literal>lastAddTimestamp</literal></para>
- <para>The timestamp of the last time a message was added to the queue</para>
- </listitem>
- <listitem>
- <para><literal>udpateTimestamp</literal></para>
- <para>The timestamp of the last message counter update</para>
- </listitem>
- </itemizedlist>
- <para>These attributes can be used to determine other meaningful data as well. For example, to know
- specifically how many messages were <emphasis>consumed</emphasis> from the queue since the last update
- simply subtract the <literal>messageCountDelta</literal> from <literal>countDelta</literal>.</para>
- <section id="configuring.message.counters">
- <title>Configuring Message Counters</title>
- <para>By default, message counters are disabled as it might have a small negative effect on
- memory.</para>
- <para>To enable message counters, you can set it to <literal>true</literal> in <literal
- >activemq-configuration.xml</literal>:</para>
- <programlisting>
-<message-counter-enabled>true</message-counter-enabled></programlisting>
- <para>Message counters keeps a history of the queue metrics (10 days by default) and
- samples all the queues at regular interval (10 seconds by default). If message counters
- are enabled, these values should be configured to suit your messaging use case in
- <literal>activemq-configuration.xml</literal>:</para>
- <programlisting>
-<!-- keep history for a week -->
-<message-counter-max-day-history>7</message-counter-max-day-history>
-<!-- sample the queues every minute (60000ms) -->
-<message-counter-sample-period>60000</message-counter-sample-period></programlisting>
- <para>Message counters can be retrieved using the Management API. For example, to retrieve
- message counters on a JMS Queue using JMX:</para>
- <programlisting>
-// retrieve a connection to ActiveMQ's MBeanServer
-MBeanServerConnection mbsc = ...
-JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
- on,
- JMSQueueControl.class,
- false);
-// message counters are retrieved as a JSON String
-String counters = queueControl.listMessageCounter();
-// use the MessageCounterInfo helper class to manipulate message counters more easily
-MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
-System.out.format("%s message(s) in the queue (since last sample: %s)\n",
-messageCounter.getMessageCount(),
-messageCounter.getMessageCountDelta());</programlisting>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.message-counters"/> for an example which shows how to use
- message counters to retrieve information on a JMS <literal>Queue</literal>.</para>
- </section>
- </section>
- <section>
- <title>Administering ActiveMQ Resources Using The JBoss AS Admin Console</title>
- <para>Its possible to create and configure ActiveMQ resources via the admin console within the JBoss Application Server.</para>
- <para>The Admin Console will allow you to create destinations (JMS Topics and Queues) and JMS Connection Factories.</para>
- <para>Once logged in to the admin console you will see a JMS Manager item in the left hand tree. All ActiveMQ resources
- will be configured via this. This will have a child items for JMS Queues, Topics and Connection Factories, clicking
- on each node will reveal which resources are currently available. The following sections explain how to create
- and configure each resource in turn.</para>
- <section>
- <title>JMS Queues</title>
- <para>To create a new JMS Queue click on the JMS Queues item to reveal the available queues. On the right hand
- panel you will see an add a new resource button, click on this and then choose the default(JMS Queue) template
- and click continue. The important things to fill in here are the name of the queue and the JNDI name of the
- queue. The JNDI name is what you will use to look up the queue in JNDI from your client. For most queues this
- will be the only info you will need to provide as sensible defaults are provided for the others. You will also
- see a security roles section near the bottom. If you do not provide any roles for this queue then the servers
- default security configuration will be used, after you have created the queue these will be shown in the configuration.
- All configuration values, except the name and JNDI name, can be changed via the configuration tab after clicking
- on the queue in the admin console. The following section explains these in more detail</para>
- <para>After highlighting the configuration you will see the following screen</para>
- <para>
- <graphic fileref="images/console1.png" scalefit="1" width="500" align="center"/>
- </para>
- <para>The name and JNDI name can't be changed, if you want to change these recreate the queue with the appropriate
- settings. The rest of the configuration options, apart from security roles, relate to address settings for a particular
- address. The default address settings are picked up from the servers configuration, if you change any of these
- settings or create a queue via the console a new Address Settings entry will be added. For a full explanation on
- Address Settings see <xref linkend="queue-attributes.address-settings"/></para>
- <para>To delete a queue simply click on the delete button beside the queue name in the main JMS Queues screen.
- This will also delete any address settings or security settings previously created for the queues address</para>
- <para>The last part of the configuration options are security roles. If non are provided on creation then the
- servers default security settings will be shown. If these are changed or updated then new security settings are
- created for the address of this queue. For more information on security setting see <xref linkend="security"/> </para>
- <para>It is also possible via the metrics tab to view statistics for this queue. This will show statistics such
- as message count, consumer count etc.</para>
- <para>Operations can be performed on a queue via the control tab. This will allow you to start and stop the queue,
- list,move,expire and delete messages from the queue and other useful operations. To invoke an operation click on
- the button for the operation you want, this will take you to a screen where you can parameters for the operation can be set.
- Once set clicking the ok button will invoke the operation, results appear at the bottom of the screen.</para>
- </section>
- <section>
- <title>JMS Topics</title>
- <para>Creating and configuring JMS Topics is almost identical to creating queues. The only difference is that the
- configuration will be applied to the queue representing a subscription.</para>
- </section>
- <section>
- <title>JMS Connection Factories</title>
- <para>The format for creating connection factories is the same as for JMS Queues and topics apart from the configuration
- being different. For as list of all the connection factory settings see the configuration index </para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/message-expiry.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/message-expiry.md b/docs/user-manual/en/message-expiry.md
new file mode 100644
index 0000000..a42939c
--- /dev/null
+++ b/docs/user-manual/en/message-expiry.md
@@ -0,0 +1,85 @@
+Message Expiry
+==============
+
+Messages can be set with an optional *time to live* when sending them.
+
+ActiveMQ will not deliver a message to a consumer after it's time to
+live has been exceeded. If the message hasn't been delivered by the time
+that time to live is reached the server can discard it.
+
+ActiveMQ's addresses can be assigned a expiry address so that, when
+messages are expired, they are removed from the queue and sent to the
+expiry address. Many different queues can be bound to an expiry address.
+These *expired* messages can later be consumed for further inspection.
+
+Message Expiry
+==============
+
+Using ActiveMQ Core API, you can set an expiration time directly on the
+message:
+
+ // message will expire in 5000ms from now
+ message.setExpiration(System.currentTimeMillis() + 5000);
+
+JMS MessageProducer allows to set a TimeToLive for the messages it sent:
+
+ // messages sent by this producer will be retained for 5s (5000ms) before expiration
+ producer.setTimeToLive(5000);
+
+Expired messages which are consumed from an expiry address have the
+following properties:
+
+- `_HQ_ORIG_ADDRESS`
+
+ a String property containing the *original address* of the expired
+ message
+
+- `_HQ_ORIG_QUEUE`
+
+ a String property containing the *original queue* of the expired
+ message
+
+- `_HQ_ACTUAL_EXPIRY`
+
+ a Long property containing the *actual expiration time* of the
+ expired message
+
+Configuring Expiry Addresses
+============================
+
+Expiry address are defined in the address-setting configuration:
+
+ <!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
+ <address-setting match="jms.queue.exampleQueue">
+ <expiry-address>jms.queue.expiryQueue</expiry-address>
+ </address-setting>
+
+If messages are expired and no expiry address is specified, messages are
+simply removed from the queue and dropped. Address wildcards can be used
+to configure expiry address for a set of addresses (see ?).
+
+Configuring The Expiry Reaper Thread
+====================================
+
+A reaper thread will periodically inspect the queues to check if
+messages have expired.
+
+The reaper thread can be configured with the following properties in
+`activemq-configuration.xml`
+
+- `message-expiry-scan-period`
+
+ How often the queues will be scanned to detect expired messages (in
+ milliseconds, default is 30000ms, set to `-1` to disable the reaper
+ thread)
+
+- `message-expiry-thread-priority`
+
+ The reaper thread priority (it must be between 0 and 9, 9 being the
+ highest priority, default is 3)
+
+Example
+=======
+
+See ? for an example which shows how message expiry is configured and
+used with JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/message-expiry.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/message-expiry.xml b/docs/user-manual/en/message-expiry.xml
deleted file mode 100644
index f8d9100..0000000
--- a/docs/user-manual/en/message-expiry.xml
+++ /dev/null
@@ -1,100 +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="message-expiry">
- <title>Message Expiry</title>
- <para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending
- them.</para>
- <para>ActiveMQ will not deliver a message to a consumer after it's time to live has been exceeded.
- If the message hasn't been delivered by the time that time to live is reached the server can
- discard it.</para>
- <para>ActiveMQ's addresses can be assigned a expiry address so that, when messages are expired,
- they are removed from the queue and sent to the expiry address. Many different queues can be
- bound to an expiry address. These <emphasis>expired</emphasis> messages can later be consumed
- for further inspection.</para>
- <section>
- <title>Message Expiry</title>
- <para>Using ActiveMQ Core API, you can set an expiration time directly on the message:</para>
- <programlisting>
-// message will expire in 5000ms from now
-message.setExpiration(System.currentTimeMillis() + 5000);</programlisting>
- <para>JMS MessageProducer allows to set a TimeToLive for the messages it sent:</para>
- <programlisting>
-// messages sent by this producer will be retained for 5s (5000ms) before expiration
-producer.setTimeToLive(5000);</programlisting>
- <para>Expired messages which are consumed from an expiry address have the following
- properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>_HQ_ORIG_ADDRESS</literal></para>
- <para>a String property containing the <emphasis>original address</emphasis> of the
- expired message </para>
- </listitem>
- <listitem>
- <para><literal>_HQ_ORIG_QUEUE</literal></para>
- <para>a String property containing the <emphasis>original queue</emphasis> of the
- expired message </para>
- </listitem>
- <listitem>
- <para><literal>_HQ_ACTUAL_EXPIRY</literal></para>
- <para>a Long property containing the <emphasis>actual expiration time</emphasis> of the
- expired message</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="message-expiry.configuring">
- <title>Configuring Expiry Addresses</title>
- <para>Expiry address are defined in the address-setting configuration:</para>
- <programlisting>
-<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
-<address-setting match="jms.queue.exampleQueue">
- <expiry-address>jms.queue.expiryQueue</expiry-address>
-</address-setting></programlisting>
- <para>If messages are expired and no expiry address is specified, messages are simply removed
- from the queue and dropped. Address wildcards can be used to configure expiry address for a
- set of addresses (see <xref linkend="wildcard-syntax"/>).</para>
- </section>
- <section id="configuring.expiry.reaper">
- <title>Configuring The Expiry Reaper Thread</title>
- <para>A reaper thread will periodically inspect the queues to check if messages have
- expired.</para>
- <para>The reaper thread can be configured with the following properties in <literal
- >activemq-configuration.xml</literal></para>
- <itemizedlist>
- <listitem>
- <para><literal>message-expiry-scan-period</literal></para>
- <para>How often the queues will be scanned to detect expired messages (in milliseconds,
- default is 30000ms, set to <literal>-1</literal> to disable the reaper thread)</para>
- </listitem>
- <listitem>
- <para><literal>message-expiry-thread-priority</literal></para>
- <para>The reaper thread priority (it must be between 0 and 9, 9 being the highest
- priority, default is 3)</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.expiry"/> for an example which shows how message expiry is
- configured and used with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/message-grouping.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/message-grouping.md b/docs/user-manual/en/message-grouping.md
new file mode 100644
index 0000000..2a0da9e
--- /dev/null
+++ b/docs/user-manual/en/message-grouping.md
@@ -0,0 +1,198 @@
+Message Grouping
+================
+
+Message groups are sets of messages that have the following
+characteristics:
+
+- Messages in a message group share the same group id, i.e. they have
+ same group identifier property (`JMSXGroupID` for JMS,
+ `_HQ_GROUP_ID` for ActiveMQ Core API).
+
+- Messages in a message group are always consumed by the same
+ consumer, even if there are many consumers on a queue. They pin all
+ messages with the same group id to the same consumer. If that
+ consumer closes another consumer is chosen and will receive all
+ messages with the same group id.
+
+Message groups are useful when you want all messages for a certain value
+of the property to be processed serially by the same consumer.
+
+An example might be orders for a certain stock. You may want orders for
+any particular stock to be processed serially by the same consumer. To
+do this you can create a pool of consumers (perhaps one for each stock,
+but less will work too), then set the stock name as the value of the
+\_HQ\_GROUP\_ID property.
+
+This will ensure that all messages for a particular stock will always be
+processed by the same consumer.
+
+> **Note**
+>
+> Grouped messages can impact the concurrent processing of non-grouped
+> messages due to the underlying FIFO semantics of a queue. For example,
+> if there is a chunk of 100 grouped messages at the head of a queue
+> followed by 1,000 non-grouped messages then all the grouped messages
+> will need to be sent to the appropriate client (which is consuming
+> those grouped messages serially) before any of the non-grouped
+> messages can be consumed. The functional impact in this scenario is a
+> temporary suspension of concurrent message processing while all the
+> grouped messages are processed. This can be a performance bottleneck
+> so keep it in mind when determining the size of your message groups,
+> and consider whether or not you should isolate your grouped messages
+> from your non-grouped messages.
+
+Using Core API
+==============
+
+The property name used to identify the message group is `"_HQ_GROUP_ID"`
+(or the constant `MessageImpl.HDR_GROUP_ID`). Alternatively, you can set
+`autogroup` to true on the `SessionFactory` which will pick a random
+unique id.
+
+Using JMS
+=========
+
+The property name used to identify the message group is `JMSXGroupID`.
+
+ // send 2 messages in the same group to ensure the same
+ // consumer will receive both
+ Message message = ...
+ message.setStringProperty("JMSXGroupID", "Group-0");
+ producer.send(message);
+
+ message = ...
+ message.setStringProperty("JMSXGroupID", "Group-0");
+ producer.send(message);
+
+Alternatively, you can set `autogroup` to true on the
+`ActiveMQConnectonFactory` which will pick a random unique id. This can
+also be set in the JNDI context environment, e.g. `jndi.properties`.
+Here's a simple example using the "ConnectionFactory" connection factory
+which is available in the context by default
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.autoGroup=true
+
+Alternatively you can set the group id via the connection factory. All
+messages sent with producers created via this connection factory will
+set the `JMSXGroupID` to the specified value on all messages sent. This
+can also be set in the JNDI context environment, e.g. `jndi.properties`.
+Here's a simple example using the "ConnectionFactory" connection factory
+which is available in the context by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.groupID=Group-0
+
+Example
+=======
+
+See ? for an example which shows how message groups are configured and
+used with JMS.
+
+Example
+=======
+
+See ? for an example which shows how message groups are configured via a
+connection factory.
+
+Clustered Grouping
+==================
+
+Using message groups in a cluster is a bit more complex. This is because
+messages with a particular group id can arrive on any node so each node
+needs to know about which group id's are bound to which consumer on
+which node. The consumer handling messages for a particular group id may
+be on a different node of the cluster, so each node needs to know this
+information so it can route the message correctly to the node which has
+that consumer.
+
+To solve this there is the notion of a grouping handler. Each node will
+have its own grouping handler and when a messages is sent with a group
+id assigned, the handlers will decide between them which route the
+message should take.
+
+There are 2 types of handlers; Local and Remote. Each cluster should
+choose 1 node to have a local grouping handler and all the other nodes
+should have remote handlers- it's the local handler that actually makes
+the decision as to what route should be used, all the other remote
+handlers converse with this. Here is a sample config for both types of
+handler, this should be configured in the *activemq-configuration.xml*
+file.
+
+ <grouping-handler name="my-grouping-handler">
+ <type>LOCAL</type>
+ <address>jms</address>
+ <timeout>5000</timeout>
+ </grouping-handler>
+
+ <grouping-handler name="my-grouping-handler">
+ <type>REMOTE</type>
+ <address>jms</address>
+ <timeout>5000</timeout>
+ </grouping-handler>
+
+The *address* attribute refers to a [cluster connection and the address
+it uses](#clusters.address), refer to the clustering section on how to
+configure clusters. The *timeout* attribute referees to how long to wait
+for a decision to be made, an exception will be thrown during the send
+if this timeout is reached, this ensures that strict ordering is kept.
+
+The decision as to where a message should be routed to is initially
+proposed by the node that receives the message. The node will pick a
+suitable route as per the normal clustered routing conditions, i.e.
+round robin available queues, use a local queue first and choose a queue
+that has a consumer. If the proposal is accepted by the grouping
+handlers the node will route messages to this queue from that point on,
+if rejected an alternative route will be offered and the node will again
+route to that queue indefinitely. All other nodes will also route to the
+queue chosen at proposal time. Once the message arrives at the queue
+then normal single server message group semantics take over and the
+message is pinned to a consumer on that queue.
+
+You may have noticed that there is a single point of failure with the
+single local handler. If this node crashes then no decisions will be
+able to be made. Any messages sent will be not be delivered and an
+exception thrown. To avoid this happening Local Handlers can be
+replicated on another backup node. Simple create your back up node and
+configure it with the same Local handler.
+
+Clustered Grouping Best Practices
+---------------------------------
+
+Some best practices should be followed when using clustered grouping:
+
+1. Make sure your consumers are distributed evenly across the different
+ nodes if possible. This is only an issue if you are creating and
+ closing consumers regularly. Since messages are always routed to the
+ same queue once pinned, removing a consumer from this queue may
+ leave it with no consumers meaning the queue will just keep
+ receiving the messages. Avoid closing consumers or make sure that
+ you always have plenty of consumers, i.e., if you have 3 nodes have
+ 3 consumers.
+
+2. Use durable queues if possible. If queues are removed once a group
+ is bound to it, then it is possible that other nodes may still try
+ to route messages to it. This can be avoided by making sure that the
+ queue is deleted by the session that is sending the messages. This
+ means that when the next message is sent it is sent to the node
+ where the queue was deleted meaning a new proposal can successfully
+ take place. Alternatively you could just start using a different
+ group id.
+
+3. Always make sure that the node that has the Local Grouping Handler
+ is replicated. These means that on failover grouping will still
+ occur.
+
+4. In case you are using group-timeouts, the remote node should have a
+ smaller group-timeout with at least half of the value on the main
+ coordinator. This is because this will determine how often the
+ last-time-use value should be updated with a round trip for a
+ request to the group between the nodes.
+
+Clustered Grouping Example
+--------------------------
+
+See ? for an example of how to configure message groups with a ActiveMQ
+cluster
[18/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/clusters.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/clusters.xml b/docs/user-manual/en/clusters.xml
deleted file mode 100644
index 2b4aad1..0000000
--- a/docs/user-manual/en/clusters.xml
+++ /dev/null
@@ -1,998 +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="clusters">
- <title>Clusters</title>
- <section>
- <title>Clusters Overview</title>
- <para>ActiveMQ clusters allow groups of ActiveMQ servers to be grouped together in order to
- share message processing load. Each active node in the cluster is an active ActiveMQ
- server which manages its own messages and handles its own connections. </para>
- <note id="clustered-deprecation">
- <para>The <emphasis>clustered</emphasis> parameter is deprecated and no longer needed for
- setting up a cluster. If your configuration contains this parameter it will be ignored and
- a message with the ID <literal>HQ221038</literal> will be logged.</para>
- </note>
- <para>The cluster is formed by each node declaring <emphasis>cluster connections</emphasis>
- to other nodes in the core configuration file <literal
- >activemq-configuration.xml</literal>. When a node forms a cluster connection to
- another node, internally it creates a <emphasis>core bridge</emphasis> (as described in
- <xref linkend="core-bridges"/>) connection between it and the other node, this is
- done transparently behind the scenes - you don't have to declare an explicit bridge for
- each node. These cluster connections allow messages to flow between the nodes of the
- cluster to balance load.</para>
- <para>Nodes can be connected together to form a cluster in many different topologies, we
- will discuss a couple of the more common topologies later in this chapter.</para>
- <para>We'll also discuss client side load balancing, where we can balance client connections
- across the nodes of the cluster, and we'll consider message redistribution where ActiveMQ
- will redistribute messages between nodes to avoid starvation.</para>
- <para>Another important part of clustering is <emphasis>server discovery</emphasis> where
- servers can broadcast their connection details so clients or other servers can connect
- to them with the minimum of configuration.</para>
- <warning id="copy-warning">
- <para>Once a cluster node has been configured it is common to simply copy that configuration
- to other nodes to produce a symmetric cluster. However, care must be taken when copying the
- ActiveMQ files. Do not copy the ActiveMQ <emphasis>data</emphasis> (i.e. the
- <literal>bindings</literal>, <literal>journal</literal>, and <literal>large-messages</literal>
- directories) from one node to another. When a node is started for the first time and initializes
- its journal files it also persists a special identifier to the <literal>journal</literal>
- directory. This id <emphasis>must</emphasis> be unique among nodes in the cluster or the
- cluster will not form properly.</para>
- </warning>
- </section>
- <section id="clusters.server-discovery">
- <title>Server discovery</title>
- <para>Server discovery is a mechanism by which servers can propagate their connection details to:</para>
- <itemizedlist>
- <listitem>
- <para>
- Messaging clients. A messaging client wants to be able to connect
- to the servers of the cluster without having specific knowledge of which servers
- in the cluster are up at any one time.
- </para>
- </listitem>
- <listitem>
- <para>Other servers. Servers in a cluster want to be able to create
- cluster connections to each other without having prior knowledge of all the
- other servers in the cluster.</para>
- </listitem>
- </itemizedlist>
- <para>
- This information, let's call it the Cluster Topology, is actually sent around normal ActiveMQ
- connections to clients and to other servers over cluster connections. This being the case we need a
- way of establishing the initial first connection. This can be done using
- dynamic discovery techniques like <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol" >UDP</ulink>
- and <ulink url="http://www.jgroups.org/">JGroups</ulink>, or by
- providing a list of initial connectors.
- </para>
- <section>
- <title>Dynamic Discovery</title>
- <para>
- Server discovery uses <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol" >UDP</ulink>
- multicast or <ulink url="http://www.jgroups.org/">JGroups</ulink> to broadcast server connection settings.
- </para>
- <section id="clusters.broadcast-groups">
- <title>Broadcast Groups</title>
- <para>A broadcast group is the means by which a server broadcasts connectors over the
- network. A connector defines a way in which a client (or other server) can make
- connections to the server. For more information on what a connector is, please see
- <xref linkend="configuring-transports"/>.</para>
- <para>The broadcast group takes a set of connector pairs, each connector pair contains
- connection settings for a live and backup server (if one exists) and broadcasts them on
- the network. Depending on which broadcasting technique you configure the cluster, it
- uses either UDP or JGroups to broadcast connector pairs information.</para>
- <para>Broadcast groups are defined in the server configuration file <literal
- >activemq-configuration.xml</literal>. There can be many broadcast groups per
- ActiveMQ server. All broadcast groups must be defined in a <literal
- >broadcast-groups</literal> element.</para>
- <para>Let's take a look at an example broadcast group from <literal
- >activemq-configuration.xml</literal> that defines a UDP broadcast group:</para>
- <programlisting>
-<broadcast-groups>
- <broadcast-group name="my-broadcast-group">
- <local-bind-address>172.16.9.3</local-bind-address>
- <local-bind-port>5432</local-bind-port>
- <group-address>231.7.7.7</group-address>
- <group-port>9876</group-port>
- <broadcast-period>2000</broadcast-period>
- <connector-ref connector-name="netty-connector"/>
- </broadcast-group>
-</broadcast-groups></programlisting>
- <para>Some of the broadcast group parameters are optional and you'll normally use the
- defaults, but we specify them all in the above example for clarity. Let's discuss
- each one in turn:</para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> attribute. Each broadcast group in the server must
- have a unique name. </para>
- </listitem>
- <listitem>
- <para><literal>local-bind-address</literal>. This is the local bind address that
- the datagram socket is bound to. If you have multiple network interfaces on
- your server, you would specify which one you wish to use for broadcasts by
- setting this property. If this property is not specified then the socket
- will be bound to the wildcard address, an IP address chosen by the
- kernel. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>local-bind-port</literal>. If you want to specify a local port to
- which the datagram socket is bound you can specify it here. Normally you
- would just use the default value of <literal>-1</literal> which signifies
- that an anonymous port should be used. This parameter is always specified in conjunction with
- <literal>local-bind-address</literal>. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>group-address</literal>. This is the multicast address to which
- the data will be broadcast. It is a class D IP address in the range <literal
- >224.0.0.0</literal> to <literal>239.255.255.255</literal>, inclusive.
- The address <literal>224.0.0.0</literal> is reserved and is not available
- for use. This parameter is mandatory. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>group-port</literal>. This is the UDP port number used for
- broadcasting. This parameter is mandatory. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>broadcast-period</literal>. This is the period in milliseconds
- between consecutive broadcasts. This parameter is optional, the default
- value is <literal>2000</literal> milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>connector-ref</literal>. This specifies the connector and
- optional backup connector that will be broadcasted (see <xref
- linkend="configuring-transports"/> for more information on connectors).
- The connector to be broadcasted is specified by the <literal
- >connector-name</literal> attribute.</para>
- </listitem>
- </itemizedlist>
-
- <para id="clusters.jgroups-example">Here is another example broadcast group that defines a JGroups broadcast group:</para>
- <programlisting>
-<broadcast-groups>
- <broadcast-group name="my-broadcast-group">
- <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
- <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
- <broadcast-period>2000</broadcast-period>
- <connector-ref connector-name="netty-connector"/>
- </broadcast-group>
-</broadcast-groups></programlisting>
- <para>To be able to use JGroups to broadcast, one must specify two attributes, i.e.
- <literal>jgroups-file</literal> and <literal>jgroups-channel</literal>, as discussed
- in details as following:</para>
- <itemizedlist>
- <listitem>
- <para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration
- file. It will be used to initialize JGroups channels. Make sure the file is in the
- java resource path so that ActiveMQ can load it. </para>
- </listitem>
- <listitem>
- <para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect
- to for broadcasting.</para>
- </listitem>
- </itemizedlist>
- <note>
- <para>The JGroups attributes (<literal>jgroups-file</literal> and <literal>jgroups-channel</literal>)
- and UDP specific attributes described above are exclusive of each other. Only one set can be
- specified in a broadcast group configuration. Don't mix them!</para>
- </note>
- <para id="clusters.jgroups-file">
- The following is an example of a JGroups file
- <programlisting>
-<config xmlns="urn:org:jgroups"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/JGroups-3.0.xsd">
- <TCP loopback="true"
- recv_buf_size="20000000"
- send_buf_size="640000"
- discard_incompatible_packets="true"
- max_bundle_size="64000"
- max_bundle_timeout="30"
- enable_bundling="true"
- use_send_queues="false"
- sock_conn_timeout="300"
-
- thread_pool.enabled="true"
- thread_pool.min_threads="1"
- thread_pool.max_threads="10"
- thread_pool.keep_alive_time="5000"
- thread_pool.queue_enabled="false"
- thread_pool.queue_max_size="100"
- thread_pool.rejection_policy="run"
-
- oob_thread_pool.enabled="true"
- oob_thread_pool.min_threads="1"
- oob_thread_pool.max_threads="8"
- oob_thread_pool.keep_alive_time="5000"
- oob_thread_pool.queue_enabled="false"
- oob_thread_pool.queue_max_size="100"
- oob_thread_pool.rejection_policy="run"/>
-
- <FILE_PING location="../file.ping.dir"/>
- <MERGE2 max_interval="30000"
- min_interval="10000"/>
- <FD_SOCK/>
- <FD timeout="10000" max_tries="5" />
- <VERIFY_SUSPECT timeout="1500" />
- <BARRIER />
- <pbcast.NAKACK
- use_mcast_xmit="false"
- retransmit_timeout="300,600,1200,2400,4800"
- discard_delivered_msgs="true"/>
- <UNICAST timeout="300,600,1200" />
- <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
- max_bytes="400000"/>
- <pbcast.GMS print_local_addr="true" join_timeout="3000"
- view_bundling="true"/>
- <FC max_credits="2000000"
- min_threshold="0.10"/>
- <FRAG2 frag_size="60000" />
- <pbcast.STATE_TRANSFER/>
- <pbcast.FLUSH timeout="0"/>
-</config></programlisting>
- </para>
- <para>
- As it shows, the file content defines a jgroups protocol stacks. If you want activemq
- to use this stacks for channel creation, you have to make sure the value of
- <literal>jgroups-file</literal> in your broadcast-group/discovery-group configuration
- to be the name of this jgroups configuration file. For example if the above stacks
- configuration is stored in a file named "jgroups-stacks.xml" then your
- <literal>jgroups-file</literal> should be like
- <programlisting>
-<jgroups-file>jgroups-stacks.xml</jgroups-file></programlisting>
- </para>
- </section>
- <section id="clusters.discovery-groups">
- <title>Discovery Groups</title>
- <para>While the broadcast group defines how connector information is broadcasted from a
- server, a discovery group defines how connector information is received from a
- broadcast endpoint (a UDP multicast address or JGroup channel).</para>
- <para>A discovery group maintains a list of connector pairs - one for each broadcast by
- a different server. As it receives broadcasts on the broadcast endpoint from a
- particular server it updates its entry in the list for that server.</para>
- <para>If it has not received a broadcast from a particular server for a length of time
- it will remove that server's entry from its list.</para>
- <para>Discovery groups are used in two places in ActiveMQ:</para>
- <itemizedlist>
- <listitem>
- <para>By cluster connections so they know how to obtain an initial connection to download the topology</para>
- </listitem>
- <listitem>
- <para>By messaging clients so they know how to obtain an initial connection to download the topology</para>
- </listitem>
- </itemizedlist>
- <para>
- Although a discovery group will always accept broadcasts, its current list of available live and
- backup servers is only ever used when an initial connection is made, from then server discovery is
- done over the normal ActiveMQ connections.
- </para>
- <note>
- <para>
- Each discovery group must be configured with broadcast endpoint (UDP or JGroups) that matches its broadcast
- group counterpart. For example, if broadcast is configured using UDP, the discovery group must also use UDP, and the same
- multicast address.
- </para>
- </note>
- </section>
- <section>
- <title>Defining Discovery Groups on the Server</title>
- <para>For cluster connections, discovery groups are defined in the server side
- configuration file <literal>activemq-configuration.xml</literal>. All discovery
- groups must be defined inside a <literal>discovery-groups</literal> element. There
- can be many discovery groups defined by ActiveMQ server. Let's look at an
- example:</para>
- <programlisting>
-<discovery-groups>
- <discovery-group name="my-discovery-group">
- <local-bind-address>172.16.9.7</local-bind-address>
- <group-address>231.7.7.7</group-address>
- <group-port>9876</group-port>
- <refresh-timeout>10000</refresh-timeout>
- </discovery-group>
-</discovery-groups></programlisting>
- <para>We'll consider each parameter of the discovery group:</para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> attribute. Each discovery group must have a unique
- name per server.</para>
- </listitem>
- <listitem>
- <para><literal>local-bind-address</literal>. If you are running with multiple network interfaces on the same machine, you
- may want to specify that the discovery group listens only only a specific interface. To do this you can specify the interface
- address with this parameter. This parameter is optional. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>group-address</literal>. This is the multicast IP address of the
- group to listen on. It should match the <literal>group-address</literal> in
- the broadcast group that you wish to listen from. This parameter is
- mandatory. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>group-port</literal>. This is the UDP port of the multicast
- group. It should match the <literal>group-port</literal> in the broadcast
- group that you wish to listen from. This parameter is mandatory. This is a UDP specific attribute.</para>
- </listitem>
- <listitem>
- <para><literal>refresh-timeout</literal>. This is the period the discovery group
- waits after receiving the last broadcast from a particular server before
- removing that servers connector pair entry from its list. You would normally
- set this to a value significantly higher than the <literal
- >broadcast-period</literal> on the broadcast group otherwise servers
- might intermittently disappear from the list even though they are still
- broadcasting due to slight differences in timing. This parameter is
- optional, the default value is <literal>10000</literal> milliseconds (10
- seconds).</para>
- </listitem>
- </itemizedlist>
- <para>Here is another example that defines a JGroups discovery group:</para>
- <programlisting>
-<discovery-groups>
- <discovery-group name="my-broadcast-group">
- <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
- <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
- <refresh-timeout>10000</refresh-timeout>
- </discovery-group>
-</discovery-groups></programlisting>
- <para>To receive broadcast from JGroups channels, one must specify two attributes,
- <literal>jgroups-file</literal> and <literal>jgroups-channel</literal>, as discussed
- in details as following:</para>
- <itemizedlist>
- <listitem>
- <para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration
- file. It will be used to initialize JGroups channels. Make sure the file is in the
- java resource path so that ActiveMQ can load it. </para>
- </listitem>
- <listitem>
- <para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect
- to for receiving broadcasts.</para>
- </listitem>
- </itemizedlist>
- <note>
- <para>The JGroups attributes (<literal>jgroups-file</literal> and <literal>jgroups-channel</literal>)
- and UDP specific attributes described above are exclusive of each other. Only one set can be
- specified in a discovery group configuration. Don't mix them!</para>
- </note>
- </section>
- <section id="clusters-discovery.groups.clientside">
- <title>Discovery Groups on the Client Side</title>
- <para>Let's discuss how to configure a ActiveMQ client to use discovery to discover a
- list of servers to which it can connect. The way to do this differs depending on
- whether you're using JMS or the core API.</para>
- <section>
- <title>Configuring client discovery using JMS</title>
- <para>If you're using JMS and you're using JNDI on the client to look up your JMS
- connection factory instances then you can specify these parameters in the JNDI
- context environment. e.g. in <literal>jndi.properties</literal>. Simply ensure the
- host:port combination matches the group-address and group-port from the corresponding
- <literal>broadcast-group</literal> on the server. Let's take a look at an
- example:</para>
- <programlisting>
-java.naming.factory.initial = org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url = udp://231.7.7.7:9876</programlisting>
- <para>The element <literal>discovery-group-ref</literal> specifies the name of a
- discovery group defined in <literal>activemq-configuration.xml</literal>.</para>
- <para>When this connection factory is downloaded from JNDI by a client application
- and JMS connections are created from it, those connections will be load-balanced
- across the list of servers that the discovery group maintains by listening on
- the multicast address specified in the discovery group configuration.</para>
- <para>If you're using JMS, but you're not using JNDI to lookup a connection factory
- - you're instantiating the JMS connection factory directly then you can specify
- the discovery group parameters directly when creating the JMS connection
- factory. Here's an
- example:</para>
- <programlisting>
-final String groupAddress = "231.7.7.7";
-
-final int groupPort = 9876;
-
-ConnectionFactory jmsConnectionFactory =
-ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
- new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF);
-
-Connection jmsConnection1 = jmsConnectionFactory.createConnection();
-
-Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting>
- <para>The <literal>refresh-timeout</literal> can be set directly on the DiscoveryGroupConfiguration
- by using the setter method <literal>setDiscoveryRefreshTimeout()</literal> if you
- want to change the default value.</para>
- <para>There is also a further parameter settable on the DiscoveryGroupConfiguration using the
- setter method <literal>setDiscoveryInitialWaitTimeout()</literal>. If the connection
- factory is used immediately after creation then it may not have had enough time
- to received broadcasts from all the nodes in the cluster. On first usage, the
- connection factory will make sure it waits this long since creation before
- creating the first connection. The default value for this parameter is <literal
- >10000</literal> milliseconds.</para>
- </section>
- <section>
- <title>Configuring client discovery using Core</title>
- <para>If you're using the core API to directly instantiate
- <literal>ClientSessionFactory</literal> instances, then you can specify the
- discovery group parameters directly when creating the session factory. Here's an
- example:</para>
- <programlisting>
-final String groupAddress = "231.7.7.7";
-final int groupPort = 9876;
-ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
- new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
-ClientSessionFactory factory = locator.createSessionFactory();
-ClientSession session1 = factory.createSession();
-ClientSession session2 = factory.createSession();</programlisting>
- <para>The <literal>refresh-timeout</literal> can be set directly on the DiscoveryGroupConfiguration
- by using the setter method <literal>setDiscoveryRefreshTimeout()</literal> if you
- want to change the default value.</para>
- <para>There is also a further parameter settable on the DiscoveryGroupConfiguration using the
- setter method <literal>setDiscoveryInitialWaitTimeout()</literal>. If the session factory
- is used immediately after creation then it may not have had enough time to
- received broadcasts from all the nodes in the cluster. On first usage, the
- session factory will make sure it waits this long since creation before creating
- the first session. The default value for this parameter is <literal
- >10000</literal> milliseconds.</para>
- </section>
- </section>
- </section>
- <section>
- <title>Discovery using static Connectors</title>
- <para>Sometimes it may be impossible to use UDP on the network you are using. In this case its
- possible to configure a connection with an initial list if possible servers. This could be just
- one server that you know will always be available or a list of servers where at least one will
- be available.</para>
- <para>This doesn't mean that you have to know where all your servers are going to be hosted, you
- can configure these servers to use the reliable servers to connect to. Once they are connected
- there connection details will be propagated via the server it connects to</para>
- <section>
- <title>Configuring a Cluster Connection</title>
- <para>For cluster connections there is no extra configuration needed, you just need to make sure that any
- connectors are defined in the usual manner, (see <xref linkend="configuring-transports"/> for more
- information on connectors). These are then referenced by the cluster connection configuration.</para>
- </section>
- <section>
- <title>Configuring a Client Connection</title>
- <para>A static list of possible servers can also be used by a normal client.</para>
- <section>
- <title>Configuring client discovery using JMS</title>
- <para>If you're using JMS and you're using JNDI on the client to look up your JMS
- connection factory instances then you can specify these parameters
- in the JNDI context environment in, e.g. <literal>jndi.properties</literal>:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://myhost:5445,myhost2:5445</programlisting>
- <para>
- The <literal>java.naming.provider.url</literal> contains a list of servers to use for the
- connection factory. When this connection factory used client application and JMS connections
- are created from it, those connections will be load-balanced across the list of servers defined
- by the <literal>java.naming.provider.url</literal>.
- </para>
- <para>
- If you're using JMS, but you're not using JNDI to lookup a connection factory - you're instantiating
- the JMS connection factory directly then you can specify the connector list directly when creating
- the JMS connection factory. Here's an example:
- </para>
- <programlisting>
-HashMap<String, Object> map = new HashMap<String, Object>();
-map.put("host", "myhost");
-map.put("port", "5445");
-TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
-HashMap<String, Object> map2 = new HashMap<String, Object>();
-map2.put("host", "myhost2");
-map2.put("port", "5446");
-TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
-
-ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);</programlisting>
- </section>
- <section>
- <title>Configuring client discovery using Core</title>
- <para>If you are using the core API then the same can be done as follows:</para>
- <programlisting>
-HashMap<String, Object> map = new HashMap<String, Object>();
-map.put("host", "myhost");
-map.put("port", "5445");
-TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
-HashMap<String, Object> map2 = new HashMap<String, Object>();
-map2.put("host", "myhost2");
-map2.put("port", "5446");
-TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
-
-ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
-ClientSessionFactory factory = locator.createSessionFactory();
-ClientSession session = factory.createSession();</programlisting>
- </section>
- </section>
- </section>
- </section>
- <section>
- <title>Server-Side Message Load Balancing</title>
- <para>If cluster connections are defined between nodes of a cluster, then ActiveMQ will load
- balance messages arriving at a particular node from a client.</para>
- <para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a
- <emphasis>symmetric cluster</emphasis> (described in
- <xref linkend="symmetric-cluster"/>). We have a queue called <literal>OrderQueue</literal>
- deployed on each node of the cluster.</para>
- <para>We have client Ca connected to node A, sending orders to the server. We have also have
- order processor clients Pa, Pb, Pc, and Pd connected to each of the nodes A, B, C, D. If
- no cluster connection was defined on node A, then as order messages arrive on node A
- they will all end up in the <literal>OrderQueue</literal> on node A, so will only get
- consumed by the order processor client attached to node A, Pa.</para>
- <para>If we define a cluster connection on node A, then as ordered messages arrive on node A
- instead of all of them going into the local <literal>OrderQueue</literal> instance, they
- are distributed in a round-robin fashion between all the nodes of the cluster. The
- messages are forwarded from the receiving node to other nodes of the cluster. This is
- all done on the server side, the client maintains a single connection to node A.</para>
- <para>For example, messages arriving on node A might be distributed in the following order
- between the nodes: B, D, C, A, B, D, C, A, B, D. The exact order depends on the order
- the nodes started up, but the algorithm used is round robin.</para>
- <para>ActiveMQ cluster connections can be configured to always blindly load balance messages
- in a round robin fashion irrespective of whether there are any matching consumers on
- other nodes, but they can be a bit cleverer than that and also be configured to only
- distribute to other nodes if they have matching consumers. We'll look at both these
- cases in turn with some examples, but first we'll discuss configuring cluster
- connections in general.</para>
- <section id="clusters.cluster-connections">
- <title>Configuring Cluster Connections</title>
- <para>Cluster connections group servers into clusters so that messages can be load
- balanced between the nodes of the cluster. Let's take a look at a typical cluster
- connection. Cluster connections are always defined in <literal
- >activemq-configuration.xml</literal> inside a <literal
- >cluster-connection</literal> element. There can be zero or more cluster
- connections defined per ActiveMQ server.</para>
- <programlisting>
-<cluster-connections>
- <cluster-connection name="my-cluster">
- <address>jms</address>
- <connector-ref>netty-connector</connector-ref>
- <check-period>1000</check-period>
- <connection-ttl>5000</connection-ttl>
- <min-large-message-size>50000</min-large-message-size>
- <call-timeout>5000</call-timeout>
- <retry-interval>500</retry-interval>
- <retry-interval-multiplier>1.0</retry-interval-multiplier>
- <max-retry-interval>5000</max-retry-interval>
- <initial-connect-attempts>-1</initial-connect-attempts>
- <reconnect-attempts>-1</reconnect-attempts>
- <use-duplicate-detection>true</use-duplicate-detection>
- <forward-when-no-consumers>false</forward-when-no-consumers>
- <max-hops>1</max-hops>
- <confirmation-window-size>32000</confirmation-window-size>
- <call-failover-timeout>30000</call-failover-timeout>
- <notification-interval>1000</notification-interval>
- <notification-attempts>2</notification-attempts>
- <discovery-group-ref discovery-group-name="my-discovery-group"/>
- </cluster-connection>
-</cluster-connections></programlisting>
- <para>In the above cluster connection all parameters have been explicitly specified. The following
- shows all the available configuration options</para>
- <itemizedlist>
- <listitem id="clusters.address">
- <para><literal>address</literal> Each cluster connection only applies to addresses that match the
- specified address field. An address is matched on the cluster connection when it begins with the
- string specified in this field. The address field on a cluster connection also supports comma
- separated lists and an exclude syntax '!'. To prevent an address from being matched on this
- cluster connection, prepend a cluster connection address string with '!'.</para>
- <para>In the case shown above the cluster connection will load balance messages sent to
- addresses that start with <literal>jms</literal>. This cluster connection,
- will, in effect apply to all JMS queues and topics since they map to core
- queues that start with the substring "jms".</para>
- <para>The address can be any value and you can have many cluster connections
- with different values of <literal>address</literal>, simultaneously
- balancing messages for those addresses, potentially to different clusters of
- servers. By having multiple cluster connections on different addresses a
- single ActiveMQ Server can effectively take part in multiple clusters
- simultaneously.</para>
- <para>Be careful not to have multiple cluster connections with overlapping
- values of <literal>address</literal>, e.g. "europe" and "europe.news" since
- this could result in the same messages being distributed between more than
- one cluster connection, possibly resulting in duplicate deliveries.</para>
- <para>
- Examples:
- <itemizedlist>
- <listitem><literal>'jms.eu'</literal> matches all addresses starting with 'jms.eu'</listitem>
- <listitem><literal>'!jms.eu'</literal> matches all address except for those starting with
- 'jms.eu'</listitem>
- <listitem><literal>'jms.eu.uk,jms.eu.de'</literal> matches all addresses starting with either
- 'jms.eu.uk' or 'jms.eu.de'</listitem>
- <listitem><literal>'jms.eu,!jms.eu.uk'</literal> matches all addresses starting with 'jms.eu'
- but not those starting with 'jms.eu.uk'</listitem>
- </itemizedlist>
- Notes:
- <itemizedlist>
- <listitem>Address exclusion will always takes precedence over address inclusion.</listitem>
- <listitem>Address matching on cluster connections does not support wild-card matching.
- </listitem>
- </itemizedlist>
- </para>
- <para>This parameter is mandatory.</para>
- </listitem>
- <listitem>
- <para><literal>connector-ref</literal>. This is the connector which will be sent to other nodes in
- the cluster so they have the correct cluster topology.</para>
- <para>This parameter is mandatory.</para>
- </listitem>
- <listitem>
- <para><literal>check-period</literal>. The period (in milliseconds) used to check if the cluster connection
- has failed to receive pings from another server. Default is 30000.</para>
- </listitem>
- <listitem>
- <para><literal>connection-ttl</literal>. This is how long a cluster connection should stay alive if it
- stops receiving messages from a specific node in the cluster. Default is 60000.</para>
- </listitem>
- <listitem>
- <para><literal>min-large-message-size</literal>. If the message size (in bytes) is larger than this
- value then it will be split into multiple segments when sent over the network to other cluster
- members. Default is 102400.</para>
- </listitem>
- <listitem>
- <para><literal>call-timeout</literal>. When a packet is sent via a cluster connection and is a blocking
- call, i.e. for acknowledgements, this is how long it will wait (in milliseconds) for the reply before
- throwing an exception. Default is 30000.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval</literal>. We mentioned before that, internally,
- cluster connections cause bridges to be created between the nodes of the
- cluster. If the cluster connection is created and the target node has not
- been started, or say, is being rebooted, then the cluster connections from
- other nodes will retry connecting to the target until it comes back up, in
- the same way as a bridge does.</para>
- <para>This parameter determines the interval in milliseconds between retry
- attempts. It has the same meaning as the <literal>retry-interval</literal>
- on a bridge (as described in <xref linkend="core-bridges"/>).</para>
- <para>This parameter is optional and its default value is <literal>500</literal>
- milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval-multiplier</literal>. This is a multiplier used to increase the
- <literal>retry-interval</literal> after each reconnect attempt, default is 1.</para>
- </listitem>
- <listitem>
- <para><literal>max-retry-interval</literal>. The maximum delay (in milliseconds) for retries.
- Default is 2000.</para>
- </listitem>
- <listitem>
- <para><literal>initial-connect-attempts</literal>. The number of times the system will
- try to connect a node in the cluster initially. If the max-retry is achieved this
- node will be considered permanently down and the system will not route messages
- to this node. Default is -1 (infinite retries).</para>
- </listitem>
- <listitem>
- <para><literal>reconnect-attempts</literal>. The number of times the system will
- try to reconnect to a node in the cluster. If the max-retry is achieved this node will
- be considered permanently down and the system will stop routing messages to this
- node. Default is -1 (infinite retries).</para>
- </listitem>
- <listitem>
- <para><literal>use-duplicate-detection</literal>. Internally cluster connections
- use bridges to link the nodes, and bridges can be configured to add a
- duplicate id property in each message that is forwarded. If the target node
- of the bridge crashes and then recovers, messages might be resent from the
- source node. By enabling duplicate detection any duplicate messages will be
- filtered out and ignored on receipt at the target node.</para>
- <para>This parameter has the same meaning as <literal>use-duplicate-detection</literal>
- on a bridge. For more information on duplicate detection, please see
- <xref linkend="duplicate-detection"/>. Default is true.</para>
- </listitem>
- <listitem>
- <para><literal>forward-when-no-consumers</literal>. This parameter determines
- whether messages will be distributed round robin between other nodes of the
- cluster <emphasis>regardless</emphasis> of whether or not there are matching or
- indeed any consumers on other nodes. </para>
- <para>If this is set to <literal>true</literal> then each incoming message will
- be round robin'd even though the same queues on the other nodes of the
- cluster may have no consumers at all, or they may have consumers that have
- non matching message filters (selectors). Note that ActiveMQ will
- <emphasis>not</emphasis> forward messages to other nodes if there are no
- <emphasis>queues</emphasis> of the same name on the other nodes, even if
- this parameter is set to <literal>true</literal>.</para>
- <para>If this is set to <literal>false</literal> then ActiveMQ will only forward
- messages to other nodes of the cluster if the address to which they are
- being forwarded has queues which have consumers, and if those consumers have
- message filters (selectors) at least one of those selectors must match the
- message.</para>
- <para>Default is false.</para>
- </listitem>
- <listitem>
- <para><literal>max-hops</literal>. When a cluster connection decides the set of
- nodes to which it might load balance a message, those nodes do not have to
- be directly connected to it via a cluster connection. ActiveMQ can be
- configured to also load balance messages to nodes which might be connected
- to it only indirectly with other ActiveMQ servers as intermediates in a
- chain.</para>
- <para>This allows ActiveMQ to be configured in more complex topologies and still
- provide message load balancing. We'll discuss this more later in this
- chapter.</para>
- <para>The default value for this parameter is <literal>1</literal>, which means
- messages are only load balanced to other ActiveMQ serves which are directly
- connected to this server. This parameter is optional.</para>
- </listitem>
- <listitem>
- <para><literal>confirmation-window-size</literal>. The size (in bytes) of the window
- used for sending confirmations from the server connected to. So once the server has
- received <literal>confirmation-window-size</literal> bytes it notifies its client,
- default is 1048576. A value of -1 means no window.</para>
- </listitem>
- <listitem>
- <para><literal>call-failover-timeout</literal>. Similar to <literal>call-timeout</literal> but used
- when a call is made during a failover attempt. Default is -1 (no timeout).</para>
- </listitem>
- <listitem>
- <para><literal>notification-interval</literal>. How often (in milliseconds) the cluster connection
- should broadcast itself when attaching to the cluster. Default is 1000.</para>
- </listitem>
- <listitem>
- <para><literal>notification-attempts</literal>. How many times the cluster connection should
- broadcast itself when connecting to the cluster. Default is 2.</para>
- </listitem>
- <listitem>
- <para><literal>discovery-group-ref</literal>. This parameter determines which
- discovery group is used to obtain the list of other servers in the cluster
- that this cluster connection will make connections to.</para>
- </listitem>
- </itemizedlist>
- <para>
- Alternatively if you would like your cluster connections to use a static list of
- servers for discovery then you can do it like this.
- </para>
- <programlisting>
-<cluster-connection name="my-cluster">
- ...
- <static-connectors>
- <connector-ref>server0-connector</connector-ref>
- <connector-ref>server1-connector</connector-ref>
- </static-connectors>
-</cluster-connection></programlisting>
- <para>
- Here we have defined 2 servers that we know for sure will that at least one will be available. There may
- be many more servers in the cluster but these will; be discovered via one of these connectors once an
- initial connection has been made.</para>
- </section>
- <section id="clusters.clusteruser">
- <title>Cluster User Credentials</title>
- <para>When creating connections between nodes of a cluster to form a cluster connection,
- ActiveMQ uses a cluster user and cluster password which is defined in <literal
- >activemq-configuration.xml</literal>:</para>
- <programlisting>
-<cluster-user>ACTIVEMQ.CLUSTER.ADMIN.USER</cluster-user>
-<cluster-password>CHANGE ME!!</cluster-password></programlisting>
- <warning>
- <para>It is imperative that these values are changed from their default, or remote
- clients will be able to make connections to the server using the default values.
- If they are not changed from the default, ActiveMQ will detect this and pester
- you with a warning on every start-up.</para>
- </warning>
- </section>
- </section>
- <section id="clusters.client.loadbalancing">
- <title>Client-Side Load balancing</title>
- <para>With ActiveMQ client-side load balancing, subsequent sessions created using a single
- session factory can be connected to different nodes of the cluster. This allows sessions
- to spread smoothly across the nodes of a cluster and not be "clumped" on any particular
- node.</para>
- <para>The load balancing policy to be used by the client factory is configurable. ActiveMQ
- provides four out-of-the-box load balancing policies, and you can also implement your own
- and use that.</para>
- <para>The out-of-the-box policies are</para>
- <itemizedlist>
- <listitem>
- <para>Round Robin. With this policy the first node is chosen randomly then each
- subsequent node is chosen sequentially in the same order.</para>
- <para>For example nodes might be chosen in the order B, C, D, A, B, C, D, A, B or D,
- A, B, C, D, A, B, C, D or C, D, A, B, C, D, A, B, C.</para>
- <para>Use <literal>org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy</literal>
- as the <literal><connection-load-balancing-policy-class-name></literal>.</para>
- </listitem>
- <listitem>
- <para>Random. With this policy each node is chosen randomly.</para>
- <para>Use <literal>org.apache.activemq.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy</literal>
- as the <literal><connection-load-balancing-policy-class-name></literal>.</para>
- </listitem>
- <listitem>
- <para>Random Sticky. With this policy the first node is chosen randomly and then re-used for subsequent
- connections.</para>
- <para>Use <literal>org.apache.activemq.api.core.client.loadbalance.RandomStickyConnectionLoadBalancingPolicy</literal>
- as the <literal><connection-load-balancing-policy-class-name></literal>.</para>
- </listitem>
- <listitem>
- <para>First Element. With this policy the "first" (i.e. 0th) node is always returned.</para>
- <para>Use <literal>org.apache.activemq.api.core.client.loadbalance.FirstElementConnectionLoadBalancingPolicy</literal>
- as the <literal><connection-load-balancing-policy-class-name></literal>.</para>
- </listitem>
- </itemizedlist>
- <para>You can also implement your own policy by implementing the interface <literal
- >org.apache.activemq.api.core.client.loadbalance.ConnectionLoadBalancingPolicy</literal></para>
- <para>Specifying which load balancing policy to use differs whether you are using JMS or the
- core API. If you don't specify a policy then the default will be used which is <literal
- >org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy</literal>.</para>
- <para>If you're using JMS and you're using JNDI on the client to look up your JMS connection factory instances
- then you can specify these parameters in the JNDI context environment in, e.g.
- <literal>jndi.properties</literal>, to specify the load balancing policy directly:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.loadBalancingPolicyClassName=org.apache.activemq.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy</programlisting>
- <para>The above example would instantiate a JMS connection factory that uses the random connection load
- balancing policy. </para>
- <para>If you're using JMS but you're instantiating your connection factory directly on the
- client side then you can set the load balancing policy using the setter on the
- <literal>ActiveMQConnectionFactory</literal> before using it:</para>
- <programlisting>
-ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
-jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting>
- <para>If you're using the core API, you can set the load balancing policy directly on the
- <literal>ServerLocator</literal> instance you are using:</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
-locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting>
- <para>The set of servers over which the factory load balances can be determined in one of
- two ways:</para>
- <itemizedlist>
- <listitem>
- <para>Specifying servers explicitly</para>
- </listitem>
- <listitem>
- <para>Using discovery.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Specifying Members of a Cluster Explicitly</title>
- <para>
- Sometimes you want to explicitly define a cluster more explicitly, that is control which
- server connect to each other in the cluster. This is typically used to form non symmetrical clusters
- such as chain cluster or ring clusters. This can only be done using a static list of connectors and is
- configured as follows:
- </para>
- <programlisting>
-<cluster-connection name="my-cluster">
- <address>jms</address>
- <connector-ref>netty-connector</connector-ref>
- <retry-interval>500</retry-interval>
- <use-duplicate-detection>true</use-duplicate-detection>
- <forward-when-no-consumers>true</forward-when-no-consumers>
- <max-hops>1</max-hops>
- <static-connectors allow-direct-connections-only="true">
- <connector-ref>server1-connector</connector-ref>
- </static-connectors>
-</cluster-connection></programlisting>
- <para>
- In this example we have set the attribute <literal>allow-direct-connections-only</literal> which means that
- the only server that this server can create a cluster connection to is server1-connector. This means you can
- explicitly create any cluster topology you want.
- </para>
- </section>
- <section id="clusters.message-redistribution">
- <title>Message Redistribution</title>
- <para>Another important part of clustering is message redistribution. Earlier we learned how
- server side message load balancing round robins messages across the cluster. If <literal
- >forward-when-no-consumers</literal> is false, then messages won't be forwarded to
- nodes which don't have matching consumers, this is great and ensures that messages don't
- arrive on a queue which has no consumers to consume them, however there is a situation
- it doesn't solve: What happens if the consumers on a queue close after the messages have
- been sent to the node? If there are no consumers on the queue the message won't get
- consumed and we have a <emphasis>starvation</emphasis> situation.</para>
- <para>This is where message redistribution comes in. With message redistribution ActiveMQ can
- be configured to automatically <emphasis>redistribute</emphasis> messages from queues
- which have no consumers back to other nodes in the cluster which do have matching
- consumers.</para>
- <para>Message redistribution can be configured to kick in immediately after the last
- consumer on a queue is closed, or to wait a configurable delay after the last consumer
- on a queue is closed before redistributing. By default message redistribution is
- disabled.</para>
- <para>Message redistribution can be configured on a per address basis, by specifying the
- redistribution delay in the address settings, for more information on configuring
- address settings, please see <xref linkend="queue-attributes"/>.</para>
- <para>Here's an address settings snippet from <literal>activemq-configuration.xml</literal>
- showing how message redistribution is enabled for a set of queues:</para>
- <programlisting>
-<address-settings>
- <address-setting match="jms.#">
- <redistribution-delay>0</redistribution-delay>
- </address-setting>
-</address-settings></programlisting>
- <para>The above <literal>address-settings</literal> block would set a <literal
- >redistribution-delay</literal> of <literal>0</literal> for any queue which is bound
- to an address that starts with "jms.". All JMS queues and topic subscriptions are bound
- to addresses that start with "jms.", so the above would enable instant (no delay)
- redistribution for all JMS queues and topic subscriptions.</para>
- <para>The attribute <literal>match</literal> can be an exact match or it can be a string
- that conforms to the ActiveMQ wildcard syntax (described in <xref
- linkend="wildcard-syntax"/>).</para>
- <para>The element <literal>redistribution-delay</literal> defines the delay in milliseconds
- after the last consumer is closed on a queue before redistributing messages from that
- queue to other nodes of the cluster which do have matching consumers. A delay of zero
- means the messages will be immediately redistributed. A value of <literal>-1</literal>
- signifies that messages will never be redistributed. The default value is <literal
- >-1</literal>.</para>
- <para>It often makes sense to introduce a delay before redistributing as it's a common case
- that a consumer closes but another one quickly is created on the same queue, in such a
- case you probably don't want to redistribute immediately since the new consumer will
- arrive shortly.</para>
- </section>
- <section>
- <title>Cluster topologies</title>
- <para>ActiveMQ clusters can be connected together in many different topologies, let's
- consider the two most common ones here</para>
- <section id="symmetric-cluster">
- <title>Symmetric cluster</title>
- <para>A symmetric cluster is probably the most common cluster topology, and you'll be
- familiar with if you've had experience of JBoss Application Server
- clustering.</para>
- <para>With a symmetric cluster every node in the cluster is connected to every other
- node in the cluster. In other words every node in the cluster is no more than one
- hop away from every other node.</para>
- <para>To form a symmetric cluster every node in the cluster defines a cluster connection
- with the attribute <literal>max-hops</literal> set to <literal>1</literal>.
- Typically the cluster connection will use server discovery in order to know what
- other servers in the cluster it should connect to, although it is possible to
- explicitly define each target server too in the cluster connection if, for example,
- UDP is not available on your network.</para>
- <para>With a symmetric cluster each node knows about all the queues that exist on all
- the other nodes and what consumers they have. With this knowledge it can determine
- how to load balance and redistribute messages around the nodes.</para>
- <para>Don't forget <link linkend="copy-warning">this warning</link> when creating a
- symmetric cluster.</para>
- </section>
- <section>
- <title>Chain cluster</title>
- <para>With a chain cluster, each node in the cluster is not connected to every node in
- the cluster directly, instead the nodes form a chain with a node on each end of the
- chain and all other nodes just connecting to the previous and next nodes in the
- chain.</para>
- <para>An example of this would be a three node chain consisting of nodes A, B and C.
- Node A is hosted in one network and has many producer clients connected to it
- sending order messages. Due to corporate policy, the order consumer clients need to
- be hosted in a different network, and that network is only accessible via a third
- network. In this setup node B acts as a mediator with no producers or consumers on
- it. Any messages arriving on node A will be forwarded to node B, which will in turn
- forward them to node C where they can get consumed. Node A does not need to directly
- connect to C, but all the nodes can still act as a part of the cluster.</para>
- <para>To set up a cluster in this way, node A would define a cluster connection that
- connects to node B, and node B would define a cluster connection that connects to
- node C. In this case we only want cluster connections in one direction since we're
- only moving messages from node A->B->C and never from C->B->A.</para>
- <para>For this topology we would set <literal>max-hops</literal> to <literal
- >2</literal>. With a value of <literal>2</literal> the knowledge of what queues and
- consumers that exist on node C would be propagated from node C to node B to node A.
- Node A would then know to distribute messages to node B when they arrive, even
- though node B has no consumers itself, it would know that a further hop away is node
- C which does have consumers.</para>
- </section>
- </section>
- <section>
- <title>Scaling Down</title>
- <para>ActiveMQ supports scaling down a cluster with no message loss (even for non-durable messages). This is especially
- useful in certain environments (e.g. the cloud) where the size of a cluster may change relatively frequently.
- When scaling up a cluster (i.e. adding nodes) there is no risk of message loss, but when scaling down a cluster
- (i.e. removing nodes) the messages on those nodes would be lost unless the broker sent them to another node in
- the cluster. ActiveMQ can be configured to do just that.</para>
- <para>The simplest way to enable this behavior is to set <literal>scale-down</literal> to
- <literal>true</literal>. If the server is clustered and <literal>scale-down</literal> is
- <literal>true</literal> then when the server is shutdown gracefully (i.e. stopped without crashing) it will find
- another node in the cluster and send <emphasis>all</emphasis> of its messages (both durable and non-durable)
- to that node. The messages are processed in order and go to the <emphasis>back</emphasis> of the respective
- queues on the other node (just as if the messages were sent from an external client for the first time).</para>
- <para>If more control over where the messages go is required then specify <literal>scale-down-group-name</literal>.
- Messages will only be sent to another node in the cluster that uses the same <literal>scale-down-group-name</literal>
- as the server being shutdown.</para>
- <warning>
- <para>If cluster nodes are grouped together with different <literal>scale-down-group-name</literal> values beware.
- If all the nodes in a single group are shut down then the messages from that node/group will be lost.</para>
- </warning>
- <para>If the server is using multiple <literal>cluster-connection</literal> then use <literal>scale-down-clustername</literal>
- to identify the name of the <literal>cluster-connection</literal> which should be used for scaling down.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/configuration-index.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuration-index.md b/docs/user-manual/en/configuration-index.md
new file mode 100644
index 0000000..116bb57
--- /dev/null
+++ b/docs/user-manual/en/configuration-index.md
@@ -0,0 +1,273 @@
+Configuration Reference
+=======================
+
+This section is a quick index for looking up configuration. Click on the
+element name to go to the specific chapter.
+
+Server Configuration
+====================
+
+activemq-configuration.xml
+--------------------------
+
+This is the main core server configuration file.
+
+activemq-jms.xml
+----------------
+
+This is the configuration file used by the server side JMS service to
+load JMS Queues, Topics and Connection Factories.
+
+Using Masked Passwords in Configuration Files
+---------------------------------------------
+
+By default all passwords in ActiveMQ server's configuration files are in
+plain text form. This usually poses no security issues as those files
+should be well protected from unauthorized accessing. However, in some
+circumstances a user doesn't want to expose its passwords to more eyes
+than necessary.
+
+ActiveMQ can be configured to use 'masked' passwords in its
+configuration files. A masked password is an obscure string
+representation of a real password. To mask a password a user will use an
+'encoder'. The encoder takes in the real password and outputs the masked
+version. A user can then replace the real password in the configuration
+files with the new masked password. When ActiveMQ loads a masked
+password, it uses a suitable 'decoder' to decode it into real password.
+
+ActiveMQ provides a default password encoder and decoder. Optionally
+users can use or implement their own encoder and decoder for masking the
+passwords.
+
+### Password Masking in Server Configuration File
+
+#### The password masking property
+
+The server configuration file has a property that defines the default
+masking behaviors over the entire file scope.
+
+`mask-password`: this boolean type property indicates if a password
+should be masked or not. Set it to "true" if you want your passwords
+masked. The default value is "false".
+
+#### Specific masking behaviors
+
+##### cluster-password
+
+The nature of the value of cluster-password is subject to the value of
+property 'mask-password'. If it is true the cluster-password is masked.
+
+##### Passwords in connectors and acceptors
+
+In the server configuration, Connectors and Acceptors sometimes needs to
+specify passwords. For example if a users wants to use an SSL-enabled
+NettyAcceptor, it can specify a key-store-password and a
+trust-store-password. Because Acceptors and Connectors are pluggable
+implementations, each transport will have different password masking
+needs.
+
+When a Connector or Acceptor configuration is initialised, ActiveMQ will
+add the "mask-password" and "password-codec" values to the Connector or
+Acceptors params using the keys `activemq.usemaskedpassword` and
+`activemq.passwordcodec` respectively. The Netty and InVM
+implementations will use these as needed and any other implementations
+will have access to these to use if they so wish.
+
+##### Passwords in Core Bridge configurations
+
+Core Bridges are configured in the server configuration file and so the
+masking of its 'password' properties follows the same rules as that of
+'cluster-password'.
+
+#### Examples
+
+The following table summarizes the relations among the above-mentioned
+properties
+
+ mask-password cluster-password acceptor/connector passwords bridge password
+ --------------- ------------------ ------------------------------ -----------------
+ absent plain text plain text plain text
+ false plain text plain text plain text
+ true masked masked masked
+
+Examples
+
+Note: In the following examples if related attributed or properties are
+absent, it means they are not specified in the configure file.
+
+example 1
+
+ <cluster-password>bbc</cluster-password>
+
+This indicates the cluster password is a plain text value ("bbc").
+
+example 2
+
+ <mask-password>true</mask-password>
+ <cluster-password>80cf731af62c290</cluster-password>
+
+This indicates the cluster password is a masked value and ActiveMQ will
+use its built-in decoder to decode it. All other passwords in the
+configuration file, Connectors, Acceptors and Bridges, will also use
+masked passwords.
+
+### JMS Bridge password masking
+
+The JMS Bridges are configured and deployed as separate beans so they
+need separate configuration to control the password masking. A JMS
+Bridge has two password parameters in its constructor, SourcePassword
+and TargetPassword. It uses the following two optional properties to
+control their masking:
+
+`useMaskedPassword` -- If set to "true" the passwords are masked.
+Default is false.
+
+`passwordCodec` -- Class name and its parameters for the Decoder used to
+decode the masked password. Ignored if `useMaskedPassword` is false. The
+format of this property is a full qualified class name optionally
+followed by key/value pairs, separated by semi-colons. For example:
+
+\<property name="useMaskedPassword"\>true\</property\>
+\<property
+name="passwordCodec"\>com.foo.FooDecoder;key=value\</property\>
+ActiveMQ will load this property and initialize the class with a
+parameter map containing the "key"-\>"value" pair. If `passwordCodec` is
+not specified, the built-in decoder is used.
+
+### Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations
+
+Both ra.xml and MDB activation configuration have a 'password' property
+that can be masked. They are controlled by the following two optional
+Resource Adapter properties in ra.xml:
+
+`UseMaskedPassword` -- If setting to "true" the passwords are masked.
+Default is false.
+
+`PasswordCodec` -- Class name and its parameters for the Decoder used to
+decode the masked password. Ignored if UseMaskedPassword is false. The
+format of this property is a full qualified class name optionally
+followed by key/value pairs. It is the same format as that for JMS
+Bridges. Example:
+
+ <config-property>
+ <config-property-name>UseMaskedPassword</config-property-name>
+ <config-property-type>boolean</config-property-type>
+ <config-property-value>true</config-property-value>
+ </config-property>
+ <config-property>
+ <config-property-name>PasswordCodec</config-property-name>
+ <config-property-type>java.lang.String</config-property-type>
+ <config-property-value>com.foo.ADecoder;key=helloworld</config-property-value>
+ </config-property>
+
+With this configuration, both passwords in ra.xml and all of its MDBs
+will have to be in masked form.
+
+### Masking passwords in activemq-users.xml
+
+ActiveMQ's built-in security manager uses plain configuration files
+where the user passwords are specified in plaintext forms by default. To
+mask those parameters the following two properties are needed:
+
+`mask-password` -- If set to "true" all the passwords are masked.
+Default is false.
+
+`password-codec` -- Class name and its parameters for the Decoder used
+to decode the masked password. Ignored if `mask-password` is false. The
+format of this property is a full qualified class name optionally
+followed by key/value pairs. It is the same format as that for JMS
+Bridges. Example:
+
+ <mask-password>true</mask-password>
+ <password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world</password-codec>
+
+When so configured, the ActiveMQ security manager will initialize a
+DefaultSensitiveStringCodec with the parameters "key"-\>"hello world",
+then use it to decode all the masked passwords in this configuration
+file.
+
+### Choosing a decoder for password masking
+
+As described in the previous sections, all password masking requires a
+decoder. A decoder uses an algorithm to convert a masked password into
+its original clear text form in order to be used in various security
+operations. The algorithm used for decoding must match that for
+encoding. Otherwise the decoding may not be successful.
+
+For user's convenience ActiveMQ provides a default built-in Decoder.
+However a user can if they so wish implement their own.
+
+#### The built-in Decoder
+
+Whenever no decoder is specified in the configuration file, the built-in
+decoder is used. The class name for the built-in decoder is
+org.apache.activemq.utils.DefaultSensitiveStringCodec. It has both
+encoding and decoding capabilities. It uses java.crypto.Cipher utilities
+to encrypt (encode) a plaintext password and decrypt a mask string using
+same algorithm. Using this decoder/encoder is pretty straightforward. To
+get a mask for a password, just run the following in command line:
+
+ java org.apache.activemq.utils.DefaultSensitiveStringCodec "your plaintext password"
+
+Make sure the classpath is correct. You'll get something like
+
+ Encoded password: 80cf731af62c290
+
+Just copy "80cf731af62c290" and replace your plaintext password with it.
+
+#### Using a different decoder
+
+It is possible to use a different decoder rather than the built-in one.
+Simply make sure the decoder is in ActiveMQ's classpath and configure
+the server to use it as follows:
+
+ <password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>
+
+If your decoder needs params passed to it you can do this via key/value
+pairs when configuring. For instance if your decoder needs say a
+"key-location" parameter, you can define like so:
+
+ <password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>
+
+Then configure your cluster-password like this:
+
+ <mask-password>true</mask-password>
+ <cluster-password>masked_password</cluster-password>
+
+When ActiveMQ reads the cluster-password it will initialize the
+NewDecoder and use it to decode "mask\_password". It also process all
+passwords using the new defined decoder.
+
+#### Implementing your own codecs
+
+To use a different decoder than the built-in one, you either pick one
+from existing libraries or you implement it yourself. All decoders must
+implement the `org.apache.activemq.utils.SensitiveDataCodec<T>`
+interface:
+
+ public interface SensitiveDataCodec<T>
+ {
+ T decode(Object mask) throws Exception;
+
+ void init(Map<String, String> params);
+ }
+
+This is a generic type interface but normally for a password you just
+need String type. So a new decoder would be defined like
+
+ public class MyNewDecoder implements SensitiveDataCodec<String>
+ {
+ public String decode(Object mask) throws Exception
+ {
+ //decode the mask into clear text password
+ return "the password";
+ }
+
+ public void init(Map<String, String> params)
+ {
+ //initialization done here. It is called right after the decoder has been created.
+ }
+ }
+
+Last but not least, once you get your own decoder, please add it to the
+classpath. Otherwise ActiveMQ will fail to load it!
[03/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Posted by cl...@apache.org.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/thread-pooling.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/thread-pooling.xml b/docs/user-manual/en/thread-pooling.xml
deleted file mode 100644
index 85a3189..0000000
--- a/docs/user-manual/en/thread-pooling.xml
+++ /dev/null
@@ -1,150 +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="thread-pooling">
- <title>Thread management</title>
- <para>This chapter describes how ActiveMQ uses and pools threads and how you can manage
- them.</para>
- <para>First we'll discuss how threads are managed and used on the server side, then we'll look
- at the client side.</para>
- <section>
- <title>Server-Side Thread Management</title>
- <para>Each ActiveMQ Server maintains a single thread pool for general use, and a scheduled
- thread pool for scheduled use. A Java scheduled thread pool cannot be configured to use
- a standard thread pool, otherwise we could use a single thread pool for both scheduled
- and non scheduled activity.</para>
- <para>A separate thread pool is also used to service connections. ActiveMQ can use "old"
- (blocking) IO or "new" (non-blocking) IO also called NIO. Both of these options use
- a separate thread pool, but each of them behaves uniquely.</para>
- <para>Since old IO requires a thread per connection its thread pool is unbounded. The thread
- pool is created via <literal>
- java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)</literal>. As the
- JavaDoc for this method states:
- <quote>Creates a thread pool that creates new threads as needed, but will reuse previously
- constructed threads when they are available, and uses the provided ThreadFactory to create
- new threads when needed.</quote>
- Threads from this pool which are idle for more than 60 seconds will time out and be
- removed. If old IO connections were serviced from the standard pool the pool would
- easily get exhausted if too many connections were made, resulting in the server "hanging"
- since it has no remaining threads to do anything else. However, even an unbounded thread
- pool can run into trouble if it becomes too large. If you require the server to handle
- many concurrent connections you should use NIO, not old IO.</para>
- <para>When using new IO (NIO), ActiveMQ will, by default, cap its thread pool at three times
- the number of cores (or hyper-threads) as reported by <literal>
- Runtime.getRuntime().availableProcessors()</literal> for processing incoming packets.
- To override this value, you can set the number of threads by specifying the parameter
- <literal>nio-remoting-threads</literal> in the transport configuration. See the
- <xref linkend="configuring-transports"/> for more information on this.</para>
- <para>There are also a small number of other places where threads are used directly, we'll
- discuss each in turn.</para>
- <section id="server.scheduled.thread.pool">
- <title>Server Scheduled Thread Pool</title>
- <para>The server scheduled thread pool is used for most activities on the server side
- that require running periodically or with delays. It maps internally to a <literal
- >java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para>
- <para>The maximum number of thread used by this pool is configure in <literal
- >activemq-configuration.xml</literal> with the <literal
- >scheduled-thread-pool-max-size</literal> parameter. The default value is
- <literal>5</literal> threads. A small number of threads is usually sufficient
- for this pool.</para>
- </section>
- <section>
- <title>General Purpose Server Thread Pool</title>
- <para>This general purpose thread pool is used for most asynchronous actions on the
- server side. It maps internally to a <literal
- >java.util.concurrent.ThreadPoolExecutor</literal> instance.</para>
- <para>The maximum number of thread used by this pool is configure in <literal
- >activemq-configuration.xml</literal> with the <literal
- >thread-pool-max-size</literal> parameter.</para>
- <para>If a value of <literal>-1</literal> is used this signifies that the thread pool
- has no upper bound and new threads will be created on demand if there are not enough
- threads available to satisfy a request. If activity later subsides then threads are
- timed-out and closed.</para>
- <para>If a value of <literal>n</literal> where <literal>n</literal>is a positive integer
- greater than zero is used this signifies that the thread pool is bounded. If more
- requests come in and there are no free threads in the pool and the pool is full then
- requests will block until a thread becomes available. It is recommended that a
- bounded thread pool is used with caution since it can lead to dead-lock situations
- if the upper bound is chosen to be too low.</para>
- <para>The default value for <literal>thread-pool-max-size</literal> is <literal
- >30</literal>.</para>
- <para>See the <ulink
- url="http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.htm"
- >J2SE javadoc</ulink> for more information on unbounded (cached), and bounded
- (fixed) thread pools.</para>
- </section>
- <section>
- <title>Expiry Reaper Thread</title>
- <para>A single thread is also used on the server side to scan for expired messages in
- queues. We cannot use either of the thread pools for this since this thread needs to
- run at its own configurable priority.</para>
- <para>For more information on configuring the reaper, please see <xref
- linkend="message-expiry"/>.</para>
- </section>
- <section>
- <title>Asynchronous IO</title>
- <para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
- native layer. You will find it on a thread dump with the prefix
- ActiveMQ-AIO-poller-pool. ActiveMQ uses one thread per opened file on the journal
- (there is usually one).</para>
- <para>There is also a single thread used to invoke writes on libaio. We do that to avoid
- context switching on libaio that would cause performance issues. You will find this
- thread on a thread dump with the prefix ActiveMQ-AIO-writer-pool.</para>
- </section>
- </section>
- <section id="thread-pooling.client.side">
- <title>Client-Side Thread Management</title>
- <para>On the client side, ActiveMQ maintains a single static scheduled thread pool and a
- single static general thread pool for use by all clients using the same classloader in
- that JVM instance.</para>
- <para>The static scheduled thread pool has a maximum size of <literal>5</literal> threads,
- and the general purpose thread pool has an unbounded maximum size.</para>
- <para>If required ActiveMQ can also be configured so that each <literal
- >ClientSessionFactory</literal> instance does not use these static pools but instead
- maintains its own scheduled and general purpose pool. Any sessions created from that
- <literal>ClientSessionFactory</literal> will use those pools instead.</para>
- <para>To configure a <literal>ClientSessionFactory</literal> instance to use its own pools,
- simply use the appropriate setter methods immediately after creation, for
- example:</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
-ClientSessionFactory myFactory = locator.createClientSessionFactory();
-myFactory.setUseGlobalPools(false);
-myFactory.setScheduledThreadPoolMaxSize(10);
-myFactory.setThreadPoolMaxSize(-1); </programlisting>
- <para>If you're using the JMS API, you can set the same parameters on the
- ClientSessionFactory and use it to create the <literal>ConnectionFactory</literal>
- instance, for example:</para>
- <programlisting>
-ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);</programlisting>
- <para>If you're using JNDI to instantiate <literal>ActiveMQConnectionFactory</literal>
- instances, you can also set these parameters in the JNDI context environment, e.g.
- <literal>jndi.properties</literal>. Here's a simple example using the "ConnectionFactory" connection
- factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.useGlobalPools=false
-connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
-connection.ConnectionFactory.threadPoolMaxSize=-1</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/tools.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/tools.md b/docs/user-manual/en/tools.md
new file mode 100644
index 0000000..a97aa79
--- /dev/null
+++ b/docs/user-manual/en/tools.md
@@ -0,0 +1,88 @@
+Tools
+=====
+
+ActiveMQ ships with several helpful command line tools. All tools are
+available from the activemq-tools-\<version\>-jar-with-dependencies.jar.
+As the name suggests, this Java archive contains ActiveMQ along with all
+of its dependencies. This is done to simplify the execution of the tools
+by eliminating the need so specify a classpath. These tools are:
+
+- **`print-data`**. Used for low-level inspection of the bindings and
+ message journals. It takes two parameters - `bindings-directory` and
+ `journal-directory`. These are the paths to the directories where
+ the bindings and message journals are stored, respectively. For
+ example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar print-data /home/user/activemq/data/bindings /home/user/activemq/data/journal
+
+- **`print-pages`**. Used for low-level inspection of paged message
+ data. It takes two parameters - `paging-directory` and
+ `journal-directory`. These are the paths to the directories where
+ paged messages and the message journals are stored, respectively.
+ For example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar print-pages /home/user/activemq/data/paging-directory /home/user/activemq/data/journal
+
+- **`export`**. Used for exporting all binding and message data
+ (including paged and large messages) as well as JMS destinations and
+ connection factories (including JNDI bindings). The export is
+ structured as XML. This data can then be imported to another server
+ even if the server is a different version than the original. It
+ takes 4 parameters:
+
+ - `bindings-directory` - the path to the bindings directory.
+
+ - `journal-directory` - the path to the journal directory.
+
+ - `paging-directory` - the path to the paging directory.
+
+ - `large-messages-directory` - the path to the large-messages
+ directory.
+
+ Here's an example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar export /home/user/activemq/data/bindings-directory /home/user/activemq/data/journal-directory /home/user/activemq/data/paging-directory /home/user/activemq/data/large-messages
+
+ This tool will export directly to standard out so if the data needs
+ to be stored in a file please redirect as appropriate for the
+ operation system in use. Also, please note that the `export` tool is
+ single threaded so depending on the size of the journal it could
+ take awhile to complete.
+
+- **`import`**. Used for importing data from an XML document generated
+ by the `export` tool. The `import` tool reads the XML document and
+ connects to a ActiveMQ server via Netty to import all the data. It
+ takes 5 parameters:
+
+ - `input-file` - the path to the XML file generated by the
+ `export` tool.
+
+ - `host` - the IP address or hostname of the server where the data
+ should be imported.
+
+ - `port` - the port where ActiveMQ is listening.
+
+ - `transactional` - a `boolean` flag to indicate whether or not to
+ send all the *message* data in a single transaction. Valid
+ values are `true` or `false`.
+
+ - `application-server-compatibility` - a `boolean` flag to
+ indicate whether or not JNDI bindings need special treatment to
+ account for the way JBoss AS7, Wildfly, and JBoss EAP 6 handle
+ JNDI for remote clients. Each of these application servers
+ require a special JNDI binding to allow access from remote
+ clients. If this is `true` then every JNDI binding in the XML
+ will be duplicated in the "java:jboss/exported/" namespace thus
+ allowing both local and remote clients to use the same name when
+ accessing resources via JNDI. Valid values are `true` or
+ `false`.
+
+ Here's an example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false
+
+ Like the `export` tool the `import` tool is single threaded so
+ depending on the size of the XML file it may take awhile for the
+ process to complete.
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/tools.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/tools.xml b/docs/user-manual/en/tools.xml
deleted file mode 100644
index 3bd3148..0000000
--- a/docs/user-manual/en/tools.xml
+++ /dev/null
@@ -1,116 +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="tools">
- <title>Tools</title>
-
- <para>ActiveMQ ships with several helpful command line tools. All tools are available from the activemq-tools-<version>-jar-with-dependencies.jar.
- As the name suggests, this Java archive contains ActiveMQ along with all of its dependencies. This is done to
- simplify the execution of the tools by eliminating the need so specify a classpath. These tools are:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold"><literal>print-data</literal></emphasis>. Used for low-level inspection of the bindings and message journals. It
- takes two parameters - <literal>bindings-directory</literal> and <literal>journal-directory</literal>. These
- are the paths to the directories where the bindings and message journals are stored, respectively. For
- example:
- </para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar print-data /home/user/activemq/data/bindings /home/user/activemq/data/journal</programlisting>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>print-pages</literal></emphasis>. Used for low-level inspection of paged message data. It takes two
- parameters - <literal>paging-directory</literal> and <literal>journal-directory</literal>. These are the
- paths to the directories where paged messages and the message journals are stored, respectively. For
- example:
- </para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar print-pages /home/user/activemq/data/paging-directory /home/user/activemq/data/journal</programlisting>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>export</literal></emphasis>. Used for exporting all binding and message data (including paged and large
- messages) as well as JMS destinations and connection factories (including JNDI bindings). The export is
- structured as XML. This data can then be imported to another server even if the server is a different
- version than the original. It takes 4 parameters:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>bindings-directory</literal> - the path to the bindings directory.</para>
- </listitem>
- <listitem>
- <para><literal>journal-directory</literal> - the path to the journal directory.</para>
- </listitem>
- <listitem>
- <para><literal>paging-directory</literal> - the path to the paging directory.</para>
- </listitem>
- <listitem>
- <para><literal>large-messages-directory</literal> - the path to the large-messages directory.</para>
- </listitem>
- </itemizedlist>
- <para>Here's an example:</para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar export /home/user/activemq/data/bindings-directory /home/user/activemq/data/journal-directory /home/user/activemq/data/paging-directory /home/user/activemq/data/large-messages</programlisting>
- <para>This tool will export directly to standard out so if the data needs to be stored in a file please
- redirect as appropriate for the operation system in use. Also, please note that the <literal>export</literal>
- tool is single threaded so depending on the size of the journal it could take awhile to complete.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>import</literal></emphasis>. Used for importing data from an XML document generated by the
- <literal>export</literal> tool. The <literal>import</literal> tool reads the XML document and connects
- to a ActiveMQ server via Netty to import all the data. It takes 5 parameters:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>input-file</literal> - the path to the XML file generated by the <literal>export</literal>
- tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>host</literal> - the IP address or hostname of the server where the data should be
- imported.
- </para>
- </listitem>
- <listitem>
- <para><literal>port</literal> - the port where ActiveMQ is listening.</para>
- </listitem>
- <listitem>
- <para><literal>transactional</literal> - a <literal>boolean</literal> flag to indicate whether or not to
- send all the <emphasis>message</emphasis> data in a single transaction. Valid values are <literal>true</literal>
- or <literal>false</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>application-server-compatibility</literal> - a <literal>boolean</literal> flag to indicate
- whether or not JNDI bindings need special treatment to account for the way JBoss AS7, Wildfly, and
- JBoss EAP 6 handle JNDI for remote clients. Each of these application servers require a special JNDI
- binding to allow access from remote clients. If this is <literal>true</literal> then every JNDI
- binding in the XML will be duplicated in the "java:jboss/exported/" namespace thus allowing both local
- and remote clients to use the same name when accessing resources via JNDI. Valid values are
- <literal>true</literal> or <literal>false</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>Here's an example:</para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false</programlisting>
- <para>Like the <literal>export</literal> tool the <literal>import</literal> tool is single threaded so
- depending on the size of the XML file it may take awhile for the process to complete.
- </para>
- </listitem>
- </itemizedlist>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/transaction-config.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/transaction-config.md b/docs/user-manual/en/transaction-config.md
new file mode 100644
index 0000000..3bdbbc8
--- /dev/null
+++ b/docs/user-manual/en/transaction-config.md
@@ -0,0 +1,22 @@
+Resource Manager Configuration
+==============================
+
+ActiveMQ has its own Resource Manager for handling the lifespan of JTA
+transactions. When a transaction is started the resource manager is
+notified and keeps a record of the transaction and its current state. It
+is possible in some cases for a transaction to be started but then
+forgotten about. Maybe the client died and never came back. If this
+happens then the transaction will just sit there indefinitely.
+
+To cope with this ActiveMQ can, if configured, scan for old transactions
+and rollback any it finds. The default for this is 3000000 milliseconds
+(5 minutes), i.e. any transactions older than 5 minutes are removed.
+This timeout can be changed by editing the `transaction-timeout`
+property in `activemq-configuration.xml` (value must be in
+milliseconds). The property `transaction-timeout-scan-period` configures
+how often, in milliseconds, to scan for old transactions.
+
+Please note that ActiveMQ will not unilaterally rollback any XA
+transactions in a prepared state - this must be heuristically rolled
+back via the management API if you are sure they will never be resolved
+by the transaction manager.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/transaction-config.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/transaction-config.xml b/docs/user-manual/en/transaction-config.xml
deleted file mode 100644
index 1d4def2..0000000
--- a/docs/user-manual/en/transaction-config.xml
+++ /dev/null
@@ -1,38 +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="transaction-config">
- <title>Resource Manager Configuration</title>
- <para>ActiveMQ has its own Resource Manager for handling the lifespan of JTA transactions. When a
- transaction is started the resource manager is notified and keeps a record of the
- transaction and its current state. It is possible in some cases for a transaction to be
- started but then forgotten about. Maybe the client died and never came back. If this happens
- then the transaction will just sit there indefinitely.</para>
- <para>To cope with this ActiveMQ can, if configured, scan for old transactions and rollback any
- it finds. The default for this is 3000000 milliseconds (5 minutes), i.e. any transactions older
- than 5 minutes are removed. This timeout can be changed by editing the <literal
- >transaction-timeout</literal> property in <literal>activemq-configuration.xml</literal> (value must be in milliseconds).
- The property <literal>transaction-timeout-scan-period</literal> configures how often, in
- milliseconds, to scan for old transactions.</para>
- <para>Please note that ActiveMQ will not unilaterally rollback any XA transactions in a prepared state - this must be heuristically rolled
- back via the management API if you are sure they will never be resolved by the transaction manager.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/undelivered-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/undelivered-messages.md b/docs/user-manual/en/undelivered-messages.md
new file mode 100644
index 0000000..d449102
--- /dev/null
+++ b/docs/user-manual/en/undelivered-messages.md
@@ -0,0 +1,166 @@
+Message Redelivery and Undelivered Messages
+===========================================
+
+Messages can be delivered unsuccessfully (e.g. if the transacted session
+used to consume them is rolled back). Such a message goes back to its
+queue ready to be redelivered. However, this means it is possible for a
+message to be delivered again and again without any success and remain
+in the queue, clogging the system.
+
+There are 2 ways to deal with these undelivered messages:
+
+- Delayed redelivery.
+
+ It is possible to delay messages redelivery to let the client some
+ time to recover from transient failures and not overload its network
+ or CPU resources
+
+- Dead Letter Address.
+
+ It is also possible to configure a dead letter address so that after
+ a specified number of unsuccessful deliveries, messages are removed
+ from the queue and will not be delivered again
+
+Both options can be combined for maximum flexibility.
+
+Delayed Redelivery
+==================
+
+Delaying redelivery can often be useful in the case that clients
+regularly fail or rollback. Without a delayed redelivery, the system can
+get into a "thrashing" state, with delivery being attempted, the client
+rolling back, and delivery being re-attempted ad infinitum in quick
+succession, consuming valuable CPU and network resources.
+
+Configuring Delayed Redelivery
+------------------------------
+
+Delayed redelivery is defined in the address-setting configuration:
+
+ <!-- delay redelivery of messages for 5s -->
+ <address-setting match="jms.queue.exampleQueue">
+ <!-- default is 1.0 -->
+ <redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
+ <!-- default is 0 (no delay) -->
+ <redelivery-delay>5000</redelivery-delay>
+ <!-- default is redelivery-delay * 10 -->
+ <max-redelivery-delay>50000</max-redelivery-delay>
+
+ </address-setting>
+
+If a `redelivery-delay` is specified, ActiveMQ will wait this delay
+before redelivering the messages.
+
+By default, there is no redelivery delay (`redelivery-delay`is set to
+0).
+
+Other subsequent messages will be delivery regularly, only the cancelled
+message will be sent asynchronously back to the queue after the delay.
+
+You can specify a multiplier that will take effect on top of the
+redelivery-delay with a max-redelivery-delay to be taken into account.
+
+The max-redelivery-delay is defaulted to redelivery-delay \* 10
+
+Address wildcards can be used to configure redelivery delay for a set of
+addresses (see ?), so you don't have to specify redelivery delay
+individually for each address.
+
+Example
+-------
+
+See ? for an example which shows how delayed redelivery is configured
+and used with JMS.
+
+Dead Letter Addresses
+=====================
+
+To prevent a client infinitely receiving the same undelivered message
+(regardless of what is causing the unsuccessful deliveries), messaging
+systems define *dead letter addresses*: after a specified unsuccessful
+delivery attempts, the message is removed from the queue and send
+instead to a dead letter address.
+
+Any such messages can then be diverted to queue(s) where they can later
+be perused by the system administrator for action to be taken.
+
+ActiveMQ's addresses can be assigned a dead letter address. Once the
+messages have been unsuccessfully delivered for a given number of
+attempts, they are removed from the queue and sent to the dead letter
+address. These *dead letter* messages can later be consumed for further
+inspection.
+
+Configuring Dead Letter Addresses
+---------------------------------
+
+Dead letter address is defined in the address-setting configuration:
+
+ <!-- undelivered messages in exampleQueue will be sent to the dead letter address
+ deadLetterQueue after 3 unsuccessful delivery attempts -->
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ </address-setting>
+
+If a `dead-letter-address` is not specified, messages will removed after
+`max-delivery-attempts` unsuccessful attempts.
+
+By default, messages are redelivered 10 times at the maximum. Set
+`max-delivery-attempts` to -1 for infinite redeliveries.
+
+For example, a dead letter can be set globally for a set of matching
+addresses and you can set `max-delivery-attempts` to -1 for a specific
+address setting to allow infinite redeliveries only for this address.
+
+Address wildcards can be used to configure dead letter settings for a
+set of addresses (see ?).
+
+Dead Letter Properties
+----------------------
+
+Dead letter messages which are consumed from a dead letter address have
+the following properties:
+
+- `_HQ_ORIG_ADDRESS`
+
+ a String property containing the *original address* of the dead
+ letter message
+
+- `_HQ_ORIG_QUEUE`
+
+ a String property containing the *original queue* of the dead letter
+ message
+
+Example
+-------
+
+See ? for an example which shows how dead letter is configured and used
+with JMS.
+
+Delivery Count Persistence
+==========================
+
+In normal use, ActiveMQ does not update delivery count *persistently*
+until a message is rolled back (i.e. the delivery count is not updated
+*before* the message is delivered to the consumer). In most messaging
+use cases, the messages are consumed, acknowledged and forgotten as soon
+as they are consumed. In these cases, updating the delivery count
+persistently before delivering the message would add an extra persistent
+step *for each message delivered*, implying a significant performance
+penalty.
+
+However, if the delivery count is not updated persistently before the
+message delivery happens, in the event of a server crash, messages might
+have been delivered but that will not have been reflected in the
+delivery count. During the recovery phase, the server will not have
+knowledge of that and will deliver the message with `redelivered` set to
+`false` while it should be `true`.
+
+As this behavior breaks strict JMS semantics, ActiveMQ allows to persist
+delivery count before message delivery but disabled it by default for
+performance implications.
+
+To enable it, set `persist-delivery-count-before-delivery` to `true` in
+`activemq-configuration.xml`:
+
+ <persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/undelivered-messages.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/undelivered-messages.xml b/docs/user-manual/en/undelivered-messages.xml
deleted file mode 100644
index 2f4a6f5..0000000
--- a/docs/user-manual/en/undelivered-messages.xml
+++ /dev/null
@@ -1,159 +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="undelivered-messages">
- <title>Message Redelivery and Undelivered Messages</title>
- <para>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume
- them is rolled back). Such a message goes back to its queue ready to be redelivered. However,
- this means it is possible for a message to be delivered again and again without any success
- and remain in the queue, clogging the system.</para>
- <para>There are 2 ways to deal with these undelivered messages:</para>
- <itemizedlist>
- <listitem>
- <para>Delayed redelivery.</para>
- <para>It is possible to delay messages redelivery to let the client some time to recover
- from transient failures and not overload its network or CPU resources</para>
- </listitem>
- <listitem>
- <para>Dead Letter Address.</para>
- <para>It is also possible to configure a dead letter address so that after a specified
- number of unsuccessful deliveries, messages are removed from the queue and will not be
- delivered again</para>
- </listitem>
- </itemizedlist>
- <para>Both options can be combined for maximum flexibility.</para>
- <section>
- <title>Delayed Redelivery</title>
- <para>Delaying redelivery can often be useful in the case that clients regularly fail or
- rollback. Without a delayed redelivery, the system can get into a "thrashing" state, with
- delivery being attempted, the client rolling back, and delivery being re-attempted ad
- infinitum in quick succession, consuming valuable CPU and network resources.</para>
- <section id="undelivered-messages.delay">
- <title>Configuring Delayed Redelivery</title>
- <para>Delayed redelivery is defined in the address-setting configuration:</para>
- <programlisting>
-<!-- delay redelivery of messages for 5s -->
-<address-setting match="jms.queue.exampleQueue">
- <!-- default is 1.0 -->
- <redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
- <!-- default is 0 (no delay) -->
- <redelivery-delay>5000</redelivery-delay>
- <!-- default is redelivery-delay * 10 -->
- <max-redelivery-delay>50000</max-redelivery-delay>
-
-</address-setting></programlisting>
- <para>If a <literal>redelivery-delay</literal> is specified, ActiveMQ will wait this delay
- before redelivering the messages.</para>
- <para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set
- to 0).</para>
- <para>Other subsequent messages will be delivery regularly, only the cancelled message
- will be sent asynchronously back to the queue after the delay.</para>
- <para>You can specify a multiplier that will take effect on top of the redelivery-delay
- with a max-redelivery-delay to be taken into account.</para>
- <para>The max-redelivery-delay is defaulted to redelivery-delay * 10</para>
- <para>Address wildcards can be used to configure redelivery delay for a set of addresses
- (see <xref linkend="wildcard-syntax"/>), so you don't have to specify redelivery delay
- individually for each address.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.delayed-redelivery"/> for an example which shows how
- delayed redelivery is configured and used with JMS.</para>
- </section>
- </section>
- <section>
- <title>Dead Letter Addresses</title>
- <para>To prevent a client infinitely receiving the same undelivered message (regardless of
- what is causing the unsuccessful deliveries), messaging systems define <emphasis
- role="italic">dead letter addresses</emphasis>: after a specified unsuccessful delivery
- attempts, the message is removed from the queue and send instead to a dead letter address. </para>
- <para>Any such messages can then be diverted to queue(s) where they can later be perused by
- the system administrator for action to be taken.</para>
- <para>ActiveMQ's addresses can be assigned a dead letter address. Once the messages have been
- unsuccessfully delivered for a given number of attempts, they are removed from the queue
- and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can
- later be consumed for further inspection.</para>
- <section id="undelivered-messages.configuring">
- <title>Configuring Dead Letter Addresses</title>
- <para>Dead letter address is defined in the address-setting configuration:</para>
- <programlisting>
-<!-- undelivered messages in exampleQueue will be sent to the dead letter address
- deadLetterQueue after 3 unsuccessful delivery attempts -->
-<address-setting match="jms.queue.exampleQueue">
- <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
- <max-delivery-attempts>3</max-delivery-attempts>
-</address-setting></programlisting>
- <para>If a <literal>dead-letter-address</literal> is not specified, messages will removed
- after <literal>max-delivery-attempts</literal> unsuccessful attempts.</para>
- <para>By default, messages are redelivered 10 times at the maximum. Set <literal
- >max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
- <para>For example, a dead letter can be set globally for a set of matching addresses and
- you can set <literal>max-delivery-attempts</literal> to -1 for a specific address
- setting to allow infinite redeliveries only for this address.</para>
- <para>Address wildcards can be used to configure dead letter settings for a set of
- addresses (see <xref linkend="wildcard-syntax"/>).</para>
- </section>
- <section>
- <title>Dead Letter Properties</title>
- <para>Dead letter messages which are consumed from a dead letter address have the following
- properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>_HQ_ORIG_ADDRESS</literal></para>
- <para>a String property containing the <emphasis>original address</emphasis> of
- the dead letter message</para>
- </listitem>
- <listitem>
- <para><literal>_HQ_ORIG_QUEUE</literal></para>
- <para>a String property containing the <emphasis>original queue</emphasis> of
- the dead letter message</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.dead-letter"/> for an example which shows how dead letter
- is configured and used with JMS.</para>
- </section>
- </section>
- <section id="configuring.delivery.count.persistence">
- <title>Delivery Count Persistence</title>
- <para>In normal use, ActiveMQ does not update delivery count <emphasis>persistently</emphasis>
- until a message is rolled back (i.e. the delivery count is not updated
- <emphasis>before</emphasis> the message is delivered to the consumer). In most messaging
- use cases, the messages are consumed, acknowledged and forgotten as soon as they are
- consumed. In these cases, updating the delivery count persistently before delivering the
- message would add an extra persistent step <emphasis>for each message delivered</emphasis>,
- implying a significant performance penalty.</para>
- <para>However, if the delivery count is not updated persistently before the message delivery
- happens, in the event of a server crash, messages might have been delivered but that will
- not have been reflected in the delivery count. During the recovery phase, the server will
- not have knowledge of that and will deliver the message with <literal>redelivered</literal>
- set to <literal>false</literal> while it should be <literal>true</literal>. </para>
- <para>As this behavior breaks strict JMS semantics, ActiveMQ allows to persist delivery count
- before message delivery but disabled it by default for performance implications.</para>
- <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
- >true</literal> in <literal>activemq-configuration.xml</literal>:</para>
- <programlisting>
-<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery></programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-core.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-core.md b/docs/user-manual/en/using-core.md
new file mode 100644
index 0000000..6c9743f
--- /dev/null
+++ b/docs/user-manual/en/using-core.md
@@ -0,0 +1,222 @@
+Using Core
+==========
+
+ActiveMQ core is a completely JMS-agnostic messaging system with its own
+non-JMS API. We call this the *core API*.
+
+If you don't want to use JMS you can use the core API directly. The core
+API provides all the functionality of JMS but without much of the
+complexity. It also provides features that are not available using JMS.
+
+Core Messaging Concepts
+=======================
+
+Some of the core messaging concepts are similar to JMS concepts, but
+core messaging concepts differ in some ways. In general the core
+messaging API is simpler than the JMS API, since we remove distinctions
+between queues, topics and subscriptions. We'll discuss each of the
+major core messaging concepts in turn, but to see the API in detail,
+please consult the Javadoc.
+
+Message
+-------
+
+- A message is the unit of data which is sent between clients and
+ servers.
+
+- A message has a body which is a buffer containing convenient methods
+ for reading and writing data into it.
+
+- A message has a set of properties which are key-value pairs. Each
+ property key is a string and property values can be of type integer,
+ long, short, byte, byte[], String, double, float or boolean.
+
+- A message has an *address* it is being sent to. When the message
+ arrives on the server it is routed to any queues that are bound to
+ the address - if the queues are bound with any filter, the message
+ will only be routed to that queue if the filter matches. An address
+ may have many queues bound to it or even none. There may also be
+ entities other than queues, like *diverts* bound to addresses.
+
+- Messages can be either durable or non durable. Durable messages in a
+ durable queue will survive a server crash or restart. Non durable
+ messages will never survive a server crash or restart.
+
+- Messages can be specified with a priority value between 0 and 9. 0
+ represents the lowest priority and 9 represents the highest.
+ ActiveMQ will attempt to deliver higher priority messages before
+ lower priority ones.
+
+- Messages can be specified with an optional expiry time. ActiveMQ
+ will not deliver messages after its expiry time has been exceeded.
+
+- Messages also have an optional timestamp which represents the time
+ the message was sent.
+
+- ActiveMQ also supports the sending/consuming of very large messages
+ - much larger than can fit in available RAM at any one time.
+
+Address
+-------
+
+A server maintains a mapping between an address and a set of queues.
+Zero or more queues can be bound to a single address. Each queue can be
+bound with an optional message filter. When a message is routed, it is
+routed to the set of queues bound to the message's address. If any of
+the queues are bound with a filter expression, then the message will
+only be routed to the subset of bound queues which match that filter
+expression.
+
+Other entities, such as *diverts* can also be bound to an address and
+messages will also be routed there.
+
+> **Note**
+>
+> In core, there is no concept of a Topic, Topic is a JMS only term.
+> Instead, in core, we just deal with *addresses* and *queues*.
+>
+> For example, a JMS topic would be implemented by a single address to
+> which many queues are bound. Each queue represents a subscription of
+> the topic. A JMS Queue would be implemented as a single address to
+> which one queue is bound - that queue represents the JMS queue.
+
+Queue
+-----
+
+Queues can be durable, meaning the messages they contain survive a
+server crash or restart, as long as the messages in them are durable.
+Non durable queues do not survive a server restart or crash even if the
+messages they contain are durable.
+
+Queues can also be temporary, meaning they are automatically deleted
+when the client connection is closed, if they are not explicitly deleted
+before that.
+
+Queues can be bound with an optional filter expression. If a filter
+expression is supplied then the server will only route messages that
+match that filter expression to any queues bound to the address.
+
+Many queues can be bound to a single address. A particular queue is only
+bound to a maximum of one address.
+
+ServerLocator
+-------------
+
+Clients use `ServerLocator` instances to create `ClientSessionFactory`
+instances. `ServerLocator` instances are used to locate servers and
+create connections to them.
+
+In JMS terms think of a `ServerLocator` in the same way you would a JMS
+Connection Factory.
+
+`ServerLocator` instances are created using the `ActiveMQClient` factory
+class.
+
+ClientSessionFactory
+--------------------
+
+Clients use `ClientSessionFactory` instances to create `ClientSession`
+instances. `ClientSessionFactory` instances are basically the connection
+to a server
+
+In JMS terms think of them as JMS Connections.
+
+`ClientSessionFactory` instances are created using the `ServerLocator`
+class.
+
+ClientSession
+-------------
+
+A client uses a ClientSession for consuming and producing messages and
+for grouping them in transactions. ClientSession instances can support
+both transactional and non transactional semantics and also provide an
+`XAResource` interface so messaging operations can be performed as part
+of a
+[JTA](http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html)
+transaction.
+
+ClientSession instances group ClientConsumers and ClientProducers.
+
+ClientSession instances can be registered with an optional
+`SendAcknowledgementHandler`. This allows your client code to be
+notified asynchronously when sent messages have successfully reached the
+server. This unique ActiveMQ feature, allows you to have full guarantees
+that sent messages have reached the server without having to block on
+each message sent until a response is received. Blocking on each
+messages sent is costly since it requires a network round trip for each
+message sent. By not blocking and receiving send acknowledgements
+asynchronously you can create true end to end asynchronous systems which
+is not possible using the standard JMS API. For more information on this
+advanced feature please see the section ?.
+
+ClientConsumer
+--------------
+
+Clients use `ClientConsumer` instances to consume messages from a queue.
+Core Messaging supports both synchronous and asynchronous message
+consumption semantics. `ClientConsumer` instances can be configured with
+an optional filter expression and will only consume messages which match
+that expression.
+
+ClientProducer
+--------------
+
+Clients create `ClientProducer` instances on `ClientSession` instances
+so they can send messages. ClientProducer instances can specify an
+address to which all sent messages are routed, or they can have no
+specified address, and the address is specified at send time for the
+message.
+
+> **Warning**
+>
+> Please note that ClientSession, ClientProducer and ClientConsumer
+> instances are *designed to be re-used*.
+>
+> It's an anti-pattern to create new ClientSession, ClientProducer and
+> ClientConsumer instances for each message you produce or consume. If
+> you do this, your application will perform very poorly. This is
+> discussed further in the section on performance tuning ?.
+
+A simple example of using Core
+==============================
+
+Here's a very simple program using the core messaging API to send and
+receive a message. Logically it's comprised of two sections: firstly
+setting up the producer to write a message to an *addresss*, and
+secondly, creating a *queue* for the consumer, creating the consumer and
+*starting* it.
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
+
+ // In this simple example, we just use one session for both producing and receiving
+
+ ClientSessionFactory factory = locator.createClientSessionFactory();
+ ClientSession session = factory.createSession();
+
+ // A producer is associated with an address ...
+
+ ClientProducer producer = session.createProducer("example");
+ ClientMessage message = session.createMessage(true);
+ message.getBodyBuffer().writeString("Hello");
+
+ // We need a queue attached to the address ...
+
+ session.createQueue("example", "example", true);
+
+ // And a consumer attached to the queue ...
+
+ ClientConsumer consumer = session.createConsumer("example");
+
+ // Once we have a queue, we can send the message ...
+
+ producer.send(message);
+
+ // We need to start the session before we can -receive- messages ...
+
+ session.start();
+ ClientMessage msgReceived = consumer.receive();
+
+ System.out.println("message = " + msgReceived.getBodyBuffer().readString());
+
+ session.close();
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-core.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-core.xml b/docs/user-manual/en/using-core.xml
deleted file mode 100644
index f66f6af..0000000
--- a/docs/user-manual/en/using-core.xml
+++ /dev/null
@@ -1,223 +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. -->
-<!-- ============================================================================= -->
-<chapter id="using-core">
- <title>Using Core</title>
- <para>ActiveMQ core is a completely JMS-agnostic messaging system with its own non-JMS API. We
- call this the <emphasis>core API</emphasis>.</para>
- <para>If you don't want to use JMS you can use the core API directly. The core API provides all
- the functionality of JMS but without much of the complexity. It also provides features that
- are not available using JMS.</para>
- <section>
- <title>Core Messaging Concepts</title>
- <para>Some of the core messaging concepts are similar to JMS concepts, but core messaging
- concepts differ in some ways. In general the core messaging API is simpler than the JMS
- API, since we remove distinctions between queues, topics and subscriptions. We'll
- discuss each of the major core messaging concepts in turn, but to see the API in detail,
- please consult the Javadoc.</para>
- <section>
- <title>Message</title>
- <itemizedlist>
- <listitem>
- <para>A message is the unit of data which is sent between clients and
- servers.</para>
- </listitem>
- <listitem>
- <para>A message has a body which is a buffer containing convenient methods for
- reading and writing data into it.</para>
- </listitem>
- <listitem>
- <para>A message has a set of properties which are key-value pairs. Each property
- key is a string and property values can be of type integer, long, short,
- byte, byte[], String, double, float or boolean.</para>
- </listitem>
- <listitem>
- <para>A message has an <emphasis>address</emphasis> it is being sent to. When
- the message arrives on the server it is routed to any queues that are bound
- to the address - if the queues are bound with any filter, the message will
- only be routed to that queue if the filter matches. An address may have many
- queues bound to it or even none. There may also be entities other than
- queues, like <emphasis role="italic">diverts</emphasis> bound to
- addresses.</para>
- </listitem>
- <listitem>
- <para>Messages can be either durable or non durable. Durable messages in a
- durable queue will survive a server crash or restart. Non durable messages
- will never survive a server crash or restart.</para>
- </listitem>
- <listitem>
- <para>Messages can be specified with a priority value between 0 and 9. 0
- represents the lowest priority and 9 represents the highest. ActiveMQ will
- attempt to deliver higher priority messages before lower priority
- ones.</para>
- </listitem>
- <listitem>
- <para>Messages can be specified with an optional expiry time. ActiveMQ will not
- deliver messages after its expiry time has been exceeded.</para>
- </listitem>
- <listitem>
- <para>Messages also have an optional timestamp which represents the time the
- message was sent.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ also supports the sending/consuming of very large messages - much
- larger than can fit in available RAM at any one time.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Address</title>
- <para>A server maintains a mapping between an address and a set of queues. Zero or more
- queues can be bound to a single address. Each queue can be bound with an optional
- message filter. When a message is routed, it is routed to the set of queues bound to
- the message's address. If any of the queues are bound with a filter expression, then
- the message will only be routed to the subset of bound queues which match that
- filter expression.</para>
- <para>Other entities, such as <emphasis role="italic">diverts</emphasis> can also be
- bound to an address and messages will also be routed there.</para>
- <note>
- <para>In core, there is no concept of a Topic, Topic is a JMS only term. Instead, in
- core, we just deal with <emphasis>addresses</emphasis> and
- <emphasis>queues</emphasis>.</para>
- <para>For example, a JMS topic would be implemented by a single address to which
- many queues are bound. Each queue represents a subscription of the topic. A JMS
- Queue would be implemented as a single address to which one queue is bound -
- that queue represents the JMS queue.</para>
- </note>
- </section>
- <section>
- <title>Queue</title>
- <para>Queues can be durable, meaning the messages they contain survive a server crash or
- restart, as long as the messages in them are durable. Non durable queues do not
- survive a server restart or crash even if the messages they contain are
- durable.</para>
- <para>Queues can also be temporary, meaning they are automatically deleted when the
- client connection is closed, if they are not explicitly deleted before that.</para>
- <para>Queues can be bound with an optional filter expression. If a filter expression is
- supplied then the server will only route messages that match that filter expression
- to any queues bound to the address.</para>
- <para>Many queues can be bound to a single address. A particular queue is only bound to
- a maximum of one address.</para>
- </section>
- <section>
- <title>ServerLocator</title>
- <para>Clients use <literal>ServerLocator</literal> instances to create <literal
- >ClientSessionFactory</literal> instances. <literal>ServerLocator</literal>
- instances are used to locate servers and create connections to them. </para>
- <para>In JMS terms think of a <literal>ServerLocator</literal> in the same way you would
- a JMS Connection Factory.</para>
- <para><literal>ServerLocator</literal> instances are created using the <literal
- >ActiveMQClient</literal> factory class.</para>
- </section>
- <section>
- <title>ClientSessionFactory</title>
- <para>Clients use <literal>ClientSessionFactory</literal> instances to create <literal
- >ClientSession</literal> instances. <literal>ClientSessionFactory</literal>
- instances are basically the connection to a server</para>
- <para> In JMS terms think of them as JMS Connections.</para>
- <para><literal>ClientSessionFactory</literal> instances are created using the <literal
- >ServerLocator</literal> class.</para>
- </section>
- <section>
- <title>ClientSession</title>
- <para>A client uses a ClientSession for consuming and producing messages and for
- grouping them in transactions. ClientSession instances can support both
- transactional and non transactional semantics and also provide an <literal
- >XAResource</literal> interface so messaging operations can be performed as part
- of a <ulink url="http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html">JTA</ulink>
- transaction.</para>
- <para>ClientSession instances group ClientConsumers and ClientProducers.</para>
- <para>ClientSession instances can be registered with an optional <literal
- >SendAcknowledgementHandler</literal>. This allows your client code to be
- notified asynchronously when sent messages have successfully reached the server.
- This unique ActiveMQ feature, allows you to have full guarantees that sent messages
- have reached the server without having to block on each message sent until a
- response is received. Blocking on each messages sent is costly since it requires a
- network round trip for each message sent. By not blocking and receiving send
- acknowledgements asynchronously you can create true end to end asynchronous systems
- which is not possible using the standard JMS API. For more information on this
- advanced feature please see the section <xref linkend="send-guarantees"/>.</para>
- </section>
- <section>
- <title>ClientConsumer</title>
- <para>Clients use <literal>ClientConsumer</literal> instances to consume messages from a
- queue. Core Messaging supports both synchronous and asynchronous message consumption
- semantics. <literal>ClientConsumer</literal> instances can be configured with an
- optional filter expression and will only consume messages which match that
- expression.</para>
- </section>
- <section>
- <title>ClientProducer</title>
- <para>Clients create <literal>ClientProducer</literal> instances on <literal
- >ClientSession</literal> instances so they can send messages. ClientProducer
- instances can specify an address to which all sent messages are routed, or they can
- have no specified address, and the address is specified at send time for the
- message.</para>
- </section>
- <warning>
- <para>Please note that ClientSession, ClientProducer and ClientConsumer instances are
- <emphasis>designed to be re-used</emphasis>.</para>
- <para>It's an anti-pattern to create new ClientSession, ClientProducer and
- ClientConsumer instances for each message you produce or consume. If you do this,
- your application will perform very poorly. This is discussed further in the section
- on performance tuning <xref linkend="perf-tuning"/>.</para>
- </warning>
- </section>
- <section>
- <title>A simple example of using Core</title>
- <para>Here's a very simple program using the core messaging API to send and receive a
- message. Logically it's comprised of two sections: firstly setting up the producer to
- write a message to an <emphasis>addresss</emphasis>, and secondly, creating a
- <emphasis>queue</emphasis> for the consumer, creating the consumer and
- <emphasis>starting</emphasis> it.</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
- InVMConnectorFactory.class.getName()));
-
-// In this simple example, we just use one session for both producing and receiving
-
-ClientSessionFactory factory = locator.createClientSessionFactory();
-ClientSession session = factory.createSession();
-
-// A producer is associated with an address ...
-
-ClientProducer producer = session.createProducer("example");
-ClientMessage message = session.createMessage(true);
-message.getBodyBuffer().writeString("Hello");
-
-// We need a queue attached to the address ...
-
-session.createQueue("example", "example", true);
-
-// And a consumer attached to the queue ...
-
-ClientConsumer consumer = session.createConsumer("example");
-
-// Once we have a queue, we can send the message ...
-
-producer.send(message);
-
-// We need to start the session before we can -receive- messages ...
-
-session.start();
-ClientMessage msgReceived = consumer.receive();
-
-System.out.println("message = " + msgReceived.getBodyBuffer().readString());
-
-session.close();</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-jms.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-jms.md b/docs/user-manual/en/using-jms.md
new file mode 100644
index 0000000..595dc0e
--- /dev/null
+++ b/docs/user-manual/en/using-jms.md
@@ -0,0 +1,410 @@
+Using JMS
+=========
+
+Although ActiveMQ provides a JMS agnostic messaging API, many users will
+be more comfortable using JMS.
+
+JMS is a very popular API standard for messaging, and most messaging
+systems provide a JMS API. If you are completely new to JMS we suggest
+you follow the[Sun JMS
+tutorial](http://docs.oracle.com/javaee/1.3/jms/tutorial) - a full JMS
+tutorial is out of scope for this guide.
+
+ActiveMQ also ships with a wide range of examples, many of which
+demonstrate JMS API usage. A good place to start would be to play around
+with the simple JMS Queue and Topic example, but we also provide
+examples for many other parts of the JMS API. A full description of the
+examples is available in ?.
+
+In this section we'll go through the main steps in configuring the
+server for JMS and creating a simple JMS program. We'll also show how to
+configure and use JNDI, and also how to use JMS with ActiveMQ without
+using any JNDI.
+
+A simple ordering system
+========================
+
+For this chapter we're going to use a very simple ordering system as our
+example. It is a somewhat contrived example because of its extreme
+simplicity, but it serves to demonstrate the very basics of setting up
+and using JMS.
+
+We will have a single JMS Queue called `OrderQueue`, and we will have a
+single `MessageProducer` sending an order message to the queue and a
+single `MessageConsumer` consuming the order message from the queue.
+
+The queue will be a `durable` queue, i.e. it will survive a server
+restart or crash. We also want to pre-deploy the queue, i.e. specify the
+queue in the server JMS configuration so it is created automatically
+without us having to explicitly create it from the client.
+
+JNDI Configuration
+==================
+
+The JMS specification establishes the convention that *administered
+objects* (i.e. JMS queue, topic and connection factory instances) are
+made available via the JNDI API. Brokers are free to implement JNDI as
+they see fit assuming the implementation fits the API. ActiveMQ does not
+have a JNDI server. Rather, it uses a client-side JNDI implementation
+that relies on special properties set in the environment to construct
+the appropriate JMS objects. In other words, no objects are stored in
+JNDI on the ActiveMQ server. There are simply instantiated on the client
+based on the provided configuration. Let's look at the different kinds
+of administered objects and how to configure them.
+
+> **Note**
+>
+> The following configuration properties *are strictly required when
+> ActiveMQ is running in stand-alone mode*. When ActiveMQ is integrated
+> to an application server (e.g. Wildfly) the application server itself
+> will almost certainly provide a JNDI client with its own properties.
+
+ConnectionFactory JNDI
+----------------------
+
+A JMS connection factory is used by the client to make connections to
+the server. It knows the location of the server it is connecting to, as
+well as many other configuration parameters.
+
+By default, a `javax.naming.Context` instance created using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory` will
+automatically have the following connection factories available for
+lookup:
+
+- `ConnectionFactory`
+
+- `XAConnectionFactory`
+
+- `QueueConnectionFactory`
+
+- `TopicConnectionFactory`
+
+Here's a simple example of the JNDI context environment for a client
+looking up a connection factory to access an *embedded* instance of
+ActiveMQ:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+
+It's really as simple as that. As noted previously, any JNDI context
+created with the `ActiveMQInitialContextFactory` will have a set of
+default connection factories available. Therefore, only the
+`java.naming.factory.initial` property is required to access an embedded
+broker.
+
+In certain situations there could be multiple server instances running
+within a particular JVM. In that situation each server would typically
+have an InVM acceptor with a unique server-ID. A client using JMS and
+JNDI can account for this by specifying a
+`javax.naming.Context.PROVIDER_URL` (`String` value of
+"java.naming.provider.url") in the JNDI environment like `vm://2` where
+`2` is the server-ID for acceptor.
+
+Here is a list of all the supported URL schemes:
+
+- `vm`
+
+- `tcp`
+
+- `udp`
+
+- `jgroups`
+
+Most clients won't be connecting to an embedded broker. Clients will
+most commonly connect across a network a remote broker. In that case the
+client can use the `javax.naming.Context.PROVIDER_URL` (`String` value
+of "java.naming.provider.url") in the JNDI environment to specify where
+to connect. Here's a simple example of a client configuring a connection
+factory to connect to a remote broker running on myhost:5445:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+
+In the example above the client is using the `tcp` scheme for the
+provider URL. A client may also specify multiple comma-delimited
+host:port combinations in the URL (e.g.
+`tcp://remote-host1:5445,remote-host2:5445`). Whether there is one or
+many host:port combinations in the URL they are treated as the *initial
+connector(s)* for the underlying connection.
+
+The `udp` scheme is also supported which should use an host:port
+combination that matches the `group-address` and `group-port` from the
+corresponding `broadcast-group` configured on the ActiveMQ server(s).
+
+Each scheme has a specific set of properties which can be set using the
+traditional URL query string format (e.g.
+`scheme://host:port?key1=value1&key2=value2`) to customize the
+underlying transport mechanism. For example, if a client wanted to
+connect to a remote server using TCP and SSL it would use a
+`Context.PROVIDER_URL` of `tcp://remote-host:5445?ssl-enabled=true`.
+
+All the properties available for the `tcp` scheme are described in [the
+documentation regarding the Netty
+transport](#configuring-transports.netty).
+
+The `udp` scheme supports 4 properties:
+
+- `local-address` - If you are running with multiple network
+ interfaces on the same machine, you may want to specify that the
+ discovery group listens only only a specific interface. To do this
+ you can specify the interface address with this parameter.
+
+- `local-port` - If you want to specify a local port to which the
+ datagram socket is bound you can specify it here. Normally you would
+ just use the default value of -1 which signifies that an anonymous
+ port should be used. This parameter is always specified in
+ conjunction with `local-address`.
+
+- `refresh-timeout` - This is the period the discovery group waits
+ after receiving the last broadcast from a particular server before
+ removing that servers connector pair entry from its list. You would
+ normally set this to a value significantly higher than the
+ broadcast-period on the broadcast group otherwise servers might
+ intermittently disappear from the list even though they are still
+ broadcasting due to slight differences in timing. This parameter is
+ optional, the default value is 10000 milliseconds (10 seconds).
+
+- `discovery-initial-wait-timeout` - If the connection factory is used
+ immediately after creation then it may not have had enough time to
+ received broadcasts from all the nodes in the cluster. On first
+ usage, the connection factory will make sure it waits this long
+ since creation before creating the first connection. The default
+ value for this parameter is 10000 milliseconds.
+
+Lastly, the `jgroups` scheme is supported which provides an alternative
+to the `udp` scheme for server discovery. The URL pattern is as follows
+`jgroups://<jgroups-xml-conf-filename>` where
+`<jgroups-xml-conf-filename>` refers to an XML file on the classpath
+that contains the JGroups configuration.
+
+The `refresh-timeout` and `discovery-initial-wait-timeout` properties
+are supported just like with `udp`.
+
+Although a `javax.naming.Context` instance created using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory` will
+automatically have some connection factories present, it is possible for
+a client to specify its own connection factories. This is done using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory.CONNECTION_FACTORY_NAMES`
+property (String value of "connectionFactoryNames"). The value for this
+property is a comma delimited String of all the connection factories the
+client wishes to create. For example:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connectionFactoryNames=myConnectionFactory
+
+In this example, the client is creating a connection factory named
+"myConnectionFactory." This replaces all the default connection
+factories so that only the "myConnectionFactory" connection factory is
+available to the client.
+
+Aside from the underlying transport, the underlying connection factory
+implementation can also be configured using special properties. To
+configure a particular connection factory the client would follow this
+pattern for the property name to set in the environment:
+`connection.<connection-factory-name>.<property-name>`. For example, if
+the client wanted to customize the default connection factory
+"ConnectionFactory" to support high-availability then it would do this:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+ connection.ConnectionFactory.ha=true
+
+Any property available on the underlying
+`org.apache.activemq.jms.client.ActiveMQConnectionFactory` can be set
+this way in addition to the `ha` (boolean) and `type` (String)
+properties. Here are the different options for the `type`:
+
+ type interface
+ --------------- ------------------------------------
+ CF (default) javax.jms.ConnectionFactory
+ XA\_CF javax.jms.XAConnectionFactory
+ QUEUE\_CF javax.jms.QueueConnectionFactory
+ QUEUE\_XA\_CF javax.jms.XAQueueConnectionFactory
+ TOPIC\_CF javax.jms.TopicConnectionFactory
+ TOPIC\_XA\_CF javax.jms.XATopicConnectionFactory
+
+ : Configuration for Connection Factory Types
+
+Destination JNDI
+----------------
+
+JMS destinations are also typically looked up via JNDI. As with
+connection factories, destinations can be configured using special
+properties in the JNDI context environment. The property *name* should
+follow the pattern: `queue.<jndi-binding>` or `topic.<jndi-binding>`.
+The property *value* should be the name of the queue hosted by the
+ActiveMQ server. For example, if the server had a JMS queue configured
+like so:
+
+ <queue name="OrderQueue"/>
+
+And if the client wanted to bind this queue to "queues/OrderQueue" then
+the JNDI properties would be configured like so:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+ queue.queues/OrderQueue=OrderQueue
+
+It is also possible to look-up JMS destinations which haven't been
+configured explicitly in the JNDI context environment. This is possible
+using `dynamicQueues/` or `dynamicTopics/` in the look-up string. For
+example, if the client wanted to look-up the aforementioned "OrderQueue"
+it could do so simply by using the string "dynamicQueues/OrderQueue".
+Note, the text that follows `dynamicQueues/` or `dynamicTopics/` must
+correspond *exactly* to the name of the destination on the server.
+
+The code
+--------
+
+Here's the code for the example:
+
+First we'll create a JNDI initial context from which to lookup our JMS
+objects. If the above properties are set in `jndi.properties` and it is
+on the classpath then any new, empty `InitialContext` will be
+initialized using those properties:
+
+ InitialContext ic = new InitialContext();
+
+Now we'll look up the connection factory from which we can create
+connections to myhost:5445:
+
+ ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");
+
+And look up the Queue:
+
+ Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue");
+
+Next we create a JMS connection using the connection factory:
+
+ Connection connection = cf.createConnection();
+
+And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
+acknowledge mode:
+
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+We create a MessageProducer that will send orders to the queue:
+
+ MessageProducer producer = session.createProducer(orderQueue);
+
+And we create a MessageConsumer which will consume orders from the
+queue:
+
+ MessageConsumer consumer = session.createConsumer(orderQueue);
+
+We make sure we start the connection, or delivery won't occur on it:
+
+ connection.start();
+
+We create a simple TextMessage and send it:
+
+ TextMessage message = session.createTextMessage("This is an order");
+ producer.send(message);
+
+And we consume the message:
+
+ TextMessage receivedMessage = (TextMessage)consumer.receive();
+ System.out.println("Got order: " + receivedMessage.getText());
+
+It is as simple as that. For a wide range of working JMS examples please
+see the examples directory in the distribution.
+
+> **Warning**
+>
+> Please note that JMS connections, sessions, producers and consumers
+> are *designed to be re-used*.
+>
+> It is an anti-pattern to create new connections, sessions, producers
+> and consumers for each message you produce or consume. If you do this,
+> your application will perform very poorly. This is discussed further
+> in the section on performance tuning ?.
+
+Directly instantiating JMS Resources without using JNDI
+=======================================================
+
+Although it is a very common JMS usage pattern to lookup JMS
+*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory
+instances) from JNDI, in some cases you just think "Why do I need JNDI?
+Why can't I just instantiate these objects directly?"
+
+With ActiveMQ you can do exactly that. ActiveMQ supports the direct
+instantiation of JMS Queue, Topic and ConnectionFactory instances, so
+you don't have to use JNDI at all.
+
+For a full working example of direct instantiation please see the JMS
+examples in ?.
+
+Here's our simple example, rewritten to not use JNDI at all:
+
+We create the JMS ConnectionFactory object via the ActiveMQJMSClient
+Utility class, note we need to provide connection parameters and specify
+which transport we are using, for more information on connectors please
+see ?.
+
+
+ TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
+ ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
+
+We also create the JMS Queue object via the ActiveMQJMSClient Utility
+class:
+
+ Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");
+
+Next we create a JMS connection using the connection factory:
+
+ Connection connection = cf.createConnection();
+
+And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
+acknowledge mode:
+
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+We create a MessageProducer that will send orders to the queue:
+
+ MessageProducer producer = session.createProducer(orderQueue);
+
+And we create a MessageConsumer which will consume orders from the
+queue:
+
+ MessageConsumer consumer = session.createConsumer(orderQueue);
+
+We make sure we start the connection, or delivery won't occur on it:
+
+ connection.start();
+
+We create a simple TextMessage and send it:
+
+ TextMessage message = session.createTextMessage("This is an order");
+ producer.send(message);
+
+And we consume the message:
+
+ TextMessage receivedMessage = (TextMessage)consumer.receive();
+ System.out.println("Got order: " + receivedMessage.getText());
+
+Setting The Client ID
+=====================
+
+This represents the client id for a JMS client and is needed for
+creating durable subscriptions. It is possible to configure this on the
+connection factory and can be set via the `client-id` element. Any
+connection created by this connection factory will have this set as its
+client id.
+
+Setting The Batch Size for DUPS\_OK
+===================================
+
+When the JMS acknowledge mode is set to `DUPS_OK` it is possible to
+configure the consumer so that it sends acknowledgements in batches
+rather that one at a time, saving valuable bandwidth. This can be
+configured via the connection factory via the `dups-ok-batch-size`
+element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB.
+
+Setting The Transaction Batch Size
+==================================
+
+When receiving messages in a transaction it is possible to configure the
+consumer to send acknowledgements in batches rather than individually
+saving valuable bandwidth. This can be configured on the connection
+factory via the `transaction-batch-size` element and is set in bytes.
+The default is 1024 \* 1024.