activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clebertsuco...@apache.org
Subject [16/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
Date Mon, 08 Dec 2014 15:49:47 GMT
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.&lt;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>
-&lt;bridge name="my-bridge">
-   &lt;queue-name>jms.queue.sausage-factory&lt;/queue-name>
-   &lt;forwarding-address>jms.queue.mincing-machine&lt;/forwarding-address>
-   &lt;filter-string="name='aardvark'"/>
-   &lt;transformer-class-name>
-      org.apache.activemq.jms.example.HatColourChangeTransformer
-   &lt;/transformer-class-name>
-   &lt;retry-interval>1000&lt;/retry-interval>
-   &lt;ha>true&lt;/ha>
-   &lt;retry-interval-multiplier>1.0&lt;/retry-interval-multiplier>
-   &lt;initial-connect-attempts>-1&lt;/initial-connect-attempts>
-   &lt;reconnect-attempts>-1&lt;/reconnect-attempts>
-   &lt;failover-on-server-shutdown>false&lt;/failover-on-server-shutdown>
-   &lt;use-duplicate-detection>true&lt;/use-duplicate-detection>
-   &lt;confirmation-window-size>10000000&lt;/confirmation-window-size>
-   &lt;user>foouser&lt;/user>
-   &lt;password>foopassword&lt;/password>
-   &lt;static-connectors>
-      &lt;connector-ref>remote-connector&lt;/connector-ref>
-   &lt;/static-connectors>
-   &lt;!-- alternative to static-connectors
-   &lt;discovery-group-ref discovery-group-name="bridge-discovery-group"/>
-   -->
-&lt;/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>
-&lt;divert name="prices-divert">
-   &lt;address>jms.topic.priceUpdates&lt;/address>
-   &lt;forwarding-address>jms.queue.priceForwarding&lt;/forwarding-address>
-   &lt;filter string="office='New York'"/>
-   &lt;transformer-class-name>
-      org.apache.activemq.jms.example.AddForwardingTimeTransformer
-   &lt;/transformer-class-name>
-   &lt;exclusive>true&lt;/exclusive>
-&lt;/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>
-&lt;divert name="order-divert">
-    &lt;address>jms.queue.orders&lt;/address>
-    &lt;forwarding-address>jms.topic.spyTopic&lt;/forwarding-address>
-    &lt;exclusive>false&lt;/exclusive>
-&lt;/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();


Mime
View raw message