activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbert...@apache.org
Subject [37/51] [partial] activemq-6 git commit: ACTIVEMQ6-1 - Initial HornetQ Donation Commit
Date Mon, 10 Nov 2014 16:32:48 GMT
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/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
new file mode 100644
index 0000000..16bdfbf
--- /dev/null
+++ b/docs/user-manual/en/jms-bridge.xml
@@ -0,0 +1,450 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+
+<!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 "HornetQ_User_Manual.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="jms-bridge">
+        <title>The JMS Bridge</title>
+        <para>HornetQ 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 HornetQ 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 HornetQ 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 HornetQ 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>
+&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;deployment xmlns="urn:jboss:bean-deployer:2.0">
+   &lt;bean name="JMSBridge" class="org.hornetq.api.jms.bridge.impl.JMSBridgeImpl">
+      &lt;!-- HornetQ must be started before the bridge -->
+      &lt;depends>HornetQServer&lt;/depends>
+      &lt;constructor>
+         &lt;!-- Source ConnectionFactory Factory -->
+         &lt;parameter>
+            &lt;inject bean="SourceCFF"/>
+         &lt;/parameter>
+         &lt;!-- Target ConnectionFactory Factory -->
+         &lt;parameter>
+            &lt;inject bean="TargetCFF"/>
+         &lt;/parameter>
+         &lt;!-- Source DestinationFactory -->
+         &lt;parameter>
+            &lt;inject bean="SourceDestinationFactory"/>
+         &lt;/parameter>
+         &lt;!-- Target DestinationFactory -->
+         &lt;parameter>
+            &lt;inject bean="TargetDestinationFactory"/>
+         &lt;/parameter>
+         &lt;!-- Source User Name (no username here) -->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Source Password (no password here)-->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Target User Name (no username here)-->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Target Password (no password here)-->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Selector -->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Failure Retry Interval (in ms) -->
+         &lt;parameter>5000&lt;/parameter>
+         &lt;!-- Max Retries -->
+         &lt;parameter>10&lt;/parameter>
+         &lt;!-- Quality Of Service -->
+         &lt;parameter>ONCE_AND_ONLY_ONCE&lt;/parameter>
+         &lt;!-- Max Batch Size -->
+         &lt;parameter>1&lt;/parameter>
+         &lt;!-- Max Batch Time (-1 means infinite) -->
+         &lt;parameter>-1&lt;/parameter>
+         &lt;!-- Subscription name (no subscription name here)-->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Client ID  (no client ID here)-->
+         &lt;parameter>&lt;null />&lt;/parameter>
+         &lt;!-- Add MessageID In Header -->
+         &lt;parameter>true&lt;/parameter>
+         &lt;!-- register the JMS Bridge in the AS MBeanServer -->
+         &lt;parameter>
+            &lt;inject bean="MBeanServer"/>
+         &lt;/parameter>
+         &lt;parameter>org.hornetq:service=JMSBridge&lt;/parameter>
+      &lt;/constructor>
+      &lt;property name="transactionManager">
+         &lt;inject bean="RealTransactionManager"/>
+      &lt;/property>
+   &lt;/bean>
+
+   &lt;!-- SourceCFF describes the ConnectionFactory used to connect to the source destination -->
+   &lt;bean name="SourceCFF"
+       class="org.hornetq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
+      &lt;constructor>
+         &lt;parameter>
+            &lt;inject bean="JNDI" />
+         &lt;/parameter>
+         &lt;parameter>/ConnectionFactory&lt;/parameter>
+      &lt;/constructor>
+   &lt;/bean>
+
+   &lt;!-- TargetCFF describes the ConnectionFactory used to connect to the target destination -->
+   &lt;bean name="TargetCFF"
+       class="org.hornetq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
+      &lt;constructor>
+         &lt;parameter>
+            &lt;inject bean="JNDI" />
+         &lt;/parameter>
+         &lt;parameter>/ConnectionFactory&lt;/parameter>
+      &lt;/constructor>
+   &lt;/bean>
+
+   &lt;!-- SourceDestinationFactory describes the Destination used as the source -->
+   &lt;bean name="SourceDestinationFactory" class="org.hornetq.api.jms.bridge.impl.JNDIDestinationFactory">
+      &lt;constructor>
+         &lt;parameter>
+            &lt;inject bean="JNDI" />
+         &lt;/parameter>
+         &lt;parameter>/queue/source&lt;/parameter>
+      &lt;/constructor>
+   &lt;/bean>
+
+   &lt;!-- TargetDestinationFactory describes the Destination used as the target -->
+   &lt;bean name="TargetDestinationFactory" class="org.hornetq.api.jms.bridge.impl.JNDIDestinationFactory">
+      &lt;constructor>
+         &lt;parameter>
+            &lt;inject bean="JNDI" />
+         &lt;/parameter>
+         &lt;parameter>/queue/target&lt;/parameter>
+      &lt;/constructor>
+   &lt;/bean>
+
+   &lt;!-- JNDI is a Hashtable containing the JNDI properties required -->
+   &lt;!-- to connect to the sources and targets JMS resrouces         -->
+   &lt;bean name="JNDI" class="java.util.Hashtable">
+      &lt;constructor class="java.util.Map">
+         &lt;map class="java.util.Hashtable" keyClass="String"
+                                          valueClass="String">
+            &lt;entry>
+               &lt;key>java.naming.factory.initial&lt;/key>
+               &lt;value>org.jnp.interfaces.NamingContextFactory&lt;/value>
+            &lt;/entry>
+            &lt;entry>
+               &lt;key>java.naming.provider.url&lt;/key>
+               &lt;value>jnp://localhost:1099&lt;/value>
+            &lt;/entry>
+            &lt;entry>
+               &lt;key>java.naming.factory.url.pkgs&lt;/key>
+               &lt;value>org.jboss.naming:org.jnp.interfaces"&lt;/value>
+            &lt;/entry>
+            &lt;entry>
+               &lt;key>jnp.timeout&lt;/key>
+               &lt;value>5000&lt;/value>
+            &lt;/entry>
+            &lt;entry>
+               &lt;key>jnp.sotimeout&lt;/key>
+               &lt;value>5000&lt;/value>
+            &lt;/entry>
+         &lt;/map>
+      &lt;/constructor>
+   &lt;/bean>
+
+   &lt;bean name="MBeanServer" class="javax.management.MBeanServer">
+      &lt;constructor factoryClass="org.jboss.mx.util.MBeanServerLocator" factoryMethod="locateJBoss"/>
+   &lt;/bean>
+&lt;/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>&lt;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
+                            >HORNETQ_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.
+                HornetQ doesn't ship with such an implementation, but one is available in the JBoss
+                Community.  If you are running HornetQ 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 HornetQ's classpath.  If you are running HornetQ 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>&lt;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
+                HornetQ 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.hornetq.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 HornetQ
+                that looks up the destination using JNDI.</para>
+            <para>A new implementation can be provided by implementing <literal
+                    >org.hornetq.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 HornetQ 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 HornetQ servers.</para>
+            </section>
+        </section>
+</chapter>

http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/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
new file mode 100644
index 0000000..bc80b55
--- /dev/null
+++ b/docs/user-manual/en/jms-core-mapping.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+
+<!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 "HornetQ_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 HornetQ addresses.</para>
+    <para>HornetQ 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>
+&lt;!-- expired messages in JMS Queue "orders.europe" will be sent to the JMS Queue "expiry.europe" -->
+&lt;address-setting match="jms.queue.orders.europe">
+   &lt;expiry-address>jms.queue.expiry.europe&lt;/expiry-address>
+   ...
+&lt;/address-setting></programlisting>
+</chapter>

http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/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
new file mode 100644
index 0000000..f28083a
--- /dev/null
+++ b/docs/user-manual/en/large-messages.xml
@@ -0,0 +1,297 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+<!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 "HornetQ_User_Manual.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="large-messages">
+    <title>Large Messages</title>
+    <para>HornetQ 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, HornetQ 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>
+&lt;configuration xmlns="urn:hornetq"
+   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+   xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd">
+...
+&lt;large-messages-directory>/data/large-messages&lt;/large-messages-directory>
+...
+&lt;/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>HornetQ 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 HornetQ 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 HornetQ Core API is used, the minimal large message size is specified by
+                    <literal>ServerLocator.setMinLargeMessageSize</literal>.</para>
+            <programlisting>
+ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName()))
+
+locator.setMinLargeMessageSize(25 * 1024);
+
+ClientSessionFactory factory = HornetQClient.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 look up the connection factory, the minimum large message size
+                is specified in <literal>hornetq-jms.xml</literal></para>
+            <programlisting>...
+&lt;connection-factory name="ConnectionFactory">
+   &lt;connectors>
+      &lt;connector-ref connector-name="netty"/>
+   &lt;/connectors>
+   &lt;entries>
+      &lt;entry name="ConnectionFactory"/>
+      &lt;entry name="XAConnectionFactory"/>
+   &lt;/entries>
+
+   &lt;min-large-message-size>250000&lt;/min-large-message-size>
+&lt;/connection-factory>
+...</programlisting>
+            <para>If the connection factory is being instantiated directly, the minimum large
+                message size is specified by <literal
+                    >HornetQConnectionFactory.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 you use JMS, you can achieve large messages compression by configuring your 
+                connection factories. For example,</para>
+            <programlisting>...
+&lt;connection-factory name="ConnectionFactory">
+   &lt;connectors>
+      &lt;connector-ref connector-name="netty"/>
+   &lt;/connectors>
+...
+   &lt;compress-large-messages>true&lt;/compress-large-messages>
+&lt;/connection-factory>
+...</programlisting>
+            </section>
+        </section>
+    </section>
+    <section>
+        <title>Streaming large messages</title>
+        <para>HornetQ 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.hornetq.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, HornetQ 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 HornetQ 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 &lt; 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 &lt; 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/8ecd255f/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
new file mode 100644
index 0000000..def6115
--- /dev/null
+++ b/docs/user-manual/en/last-value-queues.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+
+<!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 "HornetQ_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>
+&lt;address-setting match="jms.queue.lastValueQueue">
+   &lt;last-value-queue>true&lt;/last-value-queue>
+&lt;/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/8ecd255f/docs/user-manual/en/libaio.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/libaio.xml b/docs/user-manual/en/libaio.xml
new file mode 100644
index 0000000..d0e2c76
--- /dev/null
+++ b/docs/user-manual/en/libaio.xml
@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+
+<!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 "HornetQ_User_Manual.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="libaio">
+    <title>Libaio Native Libraries</title>
+    <para>HornetQ distributes a native library, used as a bridge between HornetQ 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 HornetQ:</para>
+    <itemizedlist>
+        <listitem>
+            <para>libHornetQAIO32.so - x86 32 bits</para>
+        </listitem>
+        <listitem>
+            <para>libHornetQAIO64.so - x86 64 bits</para>
+        </listitem>
+    </itemizedlist>
+    <para>When using libaio, HornetQ 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/libHornetQAIO.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 HornetQ 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/8ecd255f/docs/user-manual/en/logging.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/logging.xml b/docs/user-manual/en/logging.xml
new file mode 100644
index 0000000..b21b587
--- /dev/null
+++ b/docs/user-manual/en/logging.xml
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================= -->
+<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
+<!--                                                                               -->
+<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
+<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
+<!--                                                                               -->
+<!-- An explanation of CC-BY-SA is available at                                    -->
+<!--                                                                               -->
+<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
+<!--                                                                               -->
+<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
+<!-- of it, you must provide the URL for the original version.                     -->
+<!--                                                                               -->
+<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
+<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
+<!-- permitted by applicable law.                                                  -->
+<!-- ============================================================================= -->
+
+<!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 "HornetQ_User_Manual.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="logging">
+    <title>Logging</title>
+    <para>HornetQ 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 HornetQ loggers</entry>
+               </row>
+               <row>
+                   <entry>org.hornetq.core.server</entry>
+                   <entry>Logs the core server</entry>
+               </row>
+               <row>
+                   <entry>org.hornetq.utils</entry>
+                   <entry>Logs utility calls</entry>
+               </row>
+               <row>
+                   <entry>org.hornetq.journal</entry>
+                   <entry>Logs Journal calls</entry>
+               </row>
+               <row>
+                   <entry>org.hornetq.jms</entry>
+                   <entry>Logs JMS calls</entry>
+               </row>
+               <row>
+                   <entry>org.hornetq.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 the distribution make sure the jnp-client.jar is included or if you are using maven add the following
+         dependencies.
+         <programlisting>
+&lt;dependency>
+&lt;groupId>org.jboss.naming&lt;/groupId>
+&lt;artifactId>jnp-client&lt;/artifactId>
+&lt;version>5.0.5.Final&lt;/version>
+   &lt;exclusions>
+      &lt;exclusion>
+         &lt;groupId>org.jboss.logging&lt;/groupId>
+         &lt;artifactId>jboss-logging-spi&lt;/artifactId>
+      &lt;/exclusion>
+   &lt;/exclusions>
+&lt;/dependency>
+&lt;dependency>
+   &lt;groupId>org.jboss.logmanager&lt;/groupId>
+   &lt;artifactId>jboss-logmanager&lt;/artifactId>
+   &lt;version>1.3.1.Final&lt;/version>
+&lt;/dependency>
+&lt;dependency>
+   &lt;groupId>org.hornetq&lt;/groupId>
+   &lt;artifactId>hornetq-core-client&lt;/artifactId>
+   &lt;version>2.3.0.Final&lt;/version>
+&lt;/dependency></programlisting>
+         The first dependency <literal>jnp-client</literal> is not actually needed for logging, however this is needed for
+         using JNDI and imports a previous version JBoss logging which needs to be excluded
+      </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.hornetq.core.server,org.hornetq.utils,org.hornetq.journal,org.hornetq.jms,org.hornetq.ra
+
+# Root logger level
+logger.level=INFO
+# HornetQ logger levels
+logger.org.hornetq.core.server.level=INFO
+logger.org.hornetq.utils.level=INFO
+logger.org.hornetq.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=hornetq.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 HornetQ 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>


Mime
View raw message