You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/08 16:49:34 UTC
[03/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/thread-pooling.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/thread-pooling.xml b/docs/user-manual/en/thread-pooling.xml
deleted file mode 100644
index 85a3189..0000000
--- a/docs/user-manual/en/thread-pooling.xml
+++ /dev/null
@@ -1,150 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="thread-pooling">
- <title>Thread management</title>
- <para>This chapter describes how ActiveMQ uses and pools threads and how you can manage
- them.</para>
- <para>First we'll discuss how threads are managed and used on the server side, then we'll look
- at the client side.</para>
- <section>
- <title>Server-Side Thread Management</title>
- <para>Each ActiveMQ Server maintains a single thread pool for general use, and a scheduled
- thread pool for scheduled use. A Java scheduled thread pool cannot be configured to use
- a standard thread pool, otherwise we could use a single thread pool for both scheduled
- and non scheduled activity.</para>
- <para>A separate thread pool is also used to service connections. ActiveMQ can use "old"
- (blocking) IO or "new" (non-blocking) IO also called NIO. Both of these options use
- a separate thread pool, but each of them behaves uniquely.</para>
- <para>Since old IO requires a thread per connection its thread pool is unbounded. The thread
- pool is created via <literal>
- java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)</literal>. As the
- JavaDoc for this method states:
- <quote>Creates a thread pool that creates new threads as needed, but will reuse previously
- constructed threads when they are available, and uses the provided ThreadFactory to create
- new threads when needed.</quote>
- Threads from this pool which are idle for more than 60 seconds will time out and be
- removed. If old IO connections were serviced from the standard pool the pool would
- easily get exhausted if too many connections were made, resulting in the server "hanging"
- since it has no remaining threads to do anything else. However, even an unbounded thread
- pool can run into trouble if it becomes too large. If you require the server to handle
- many concurrent connections you should use NIO, not old IO.</para>
- <para>When using new IO (NIO), ActiveMQ will, by default, cap its thread pool at three times
- the number of cores (or hyper-threads) as reported by <literal>
- Runtime.getRuntime().availableProcessors()</literal> for processing incoming packets.
- To override this value, you can set the number of threads by specifying the parameter
- <literal>nio-remoting-threads</literal> in the transport configuration. See the
- <xref linkend="configuring-transports"/> for more information on this.</para>
- <para>There are also a small number of other places where threads are used directly, we'll
- discuss each in turn.</para>
- <section id="server.scheduled.thread.pool">
- <title>Server Scheduled Thread Pool</title>
- <para>The server scheduled thread pool is used for most activities on the server side
- that require running periodically or with delays. It maps internally to a <literal
- >java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para>
- <para>The maximum number of thread used by this pool is configure in <literal
- >activemq-configuration.xml</literal> with the <literal
- >scheduled-thread-pool-max-size</literal> parameter. The default value is
- <literal>5</literal> threads. A small number of threads is usually sufficient
- for this pool.</para>
- </section>
- <section>
- <title>General Purpose Server Thread Pool</title>
- <para>This general purpose thread pool is used for most asynchronous actions on the
- server side. It maps internally to a <literal
- >java.util.concurrent.ThreadPoolExecutor</literal> instance.</para>
- <para>The maximum number of thread used by this pool is configure in <literal
- >activemq-configuration.xml</literal> with the <literal
- >thread-pool-max-size</literal> parameter.</para>
- <para>If a value of <literal>-1</literal> is used this signifies that the thread pool
- has no upper bound and new threads will be created on demand if there are not enough
- threads available to satisfy a request. If activity later subsides then threads are
- timed-out and closed.</para>
- <para>If a value of <literal>n</literal> where <literal>n</literal>is a positive integer
- greater than zero is used this signifies that the thread pool is bounded. If more
- requests come in and there are no free threads in the pool and the pool is full then
- requests will block until a thread becomes available. It is recommended that a
- bounded thread pool is used with caution since it can lead to dead-lock situations
- if the upper bound is chosen to be too low.</para>
- <para>The default value for <literal>thread-pool-max-size</literal> is <literal
- >30</literal>.</para>
- <para>See the <ulink
- url="http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.htm"
- >J2SE javadoc</ulink> for more information on unbounded (cached), and bounded
- (fixed) thread pools.</para>
- </section>
- <section>
- <title>Expiry Reaper Thread</title>
- <para>A single thread is also used on the server side to scan for expired messages in
- queues. We cannot use either of the thread pools for this since this thread needs to
- run at its own configurable priority.</para>
- <para>For more information on configuring the reaper, please see <xref
- linkend="message-expiry"/>.</para>
- </section>
- <section>
- <title>Asynchronous IO</title>
- <para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
- native layer. You will find it on a thread dump with the prefix
- ActiveMQ-AIO-poller-pool. ActiveMQ uses one thread per opened file on the journal
- (there is usually one).</para>
- <para>There is also a single thread used to invoke writes on libaio. We do that to avoid
- context switching on libaio that would cause performance issues. You will find this
- thread on a thread dump with the prefix ActiveMQ-AIO-writer-pool.</para>
- </section>
- </section>
- <section id="thread-pooling.client.side">
- <title>Client-Side Thread Management</title>
- <para>On the client side, ActiveMQ maintains a single static scheduled thread pool and a
- single static general thread pool for use by all clients using the same classloader in
- that JVM instance.</para>
- <para>The static scheduled thread pool has a maximum size of <literal>5</literal> threads,
- and the general purpose thread pool has an unbounded maximum size.</para>
- <para>If required ActiveMQ can also be configured so that each <literal
- >ClientSessionFactory</literal> instance does not use these static pools but instead
- maintains its own scheduled and general purpose pool. Any sessions created from that
- <literal>ClientSessionFactory</literal> will use those pools instead.</para>
- <para>To configure a <literal>ClientSessionFactory</literal> instance to use its own pools,
- simply use the appropriate setter methods immediately after creation, for
- example:</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
-ClientSessionFactory myFactory = locator.createClientSessionFactory();
-myFactory.setUseGlobalPools(false);
-myFactory.setScheduledThreadPoolMaxSize(10);
-myFactory.setThreadPoolMaxSize(-1); </programlisting>
- <para>If you're using the JMS API, you can set the same parameters on the
- ClientSessionFactory and use it to create the <literal>ConnectionFactory</literal>
- instance, for example:</para>
- <programlisting>
-ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);</programlisting>
- <para>If you're using JNDI to instantiate <literal>ActiveMQConnectionFactory</literal>
- instances, you can also set these parameters in the JNDI context environment, e.g.
- <literal>jndi.properties</literal>. Here's a simple example using the "ConnectionFactory" connection
- factory which is available in the context by default:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.useGlobalPools=false
-connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
-connection.ConnectionFactory.threadPoolMaxSize=-1</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/tools.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/tools.md b/docs/user-manual/en/tools.md
new file mode 100644
index 0000000..a97aa79
--- /dev/null
+++ b/docs/user-manual/en/tools.md
@@ -0,0 +1,88 @@
+Tools
+=====
+
+ActiveMQ ships with several helpful command line tools. All tools are
+available from the activemq-tools-\<version\>-jar-with-dependencies.jar.
+As the name suggests, this Java archive contains ActiveMQ along with all
+of its dependencies. This is done to simplify the execution of the tools
+by eliminating the need so specify a classpath. These tools are:
+
+- **`print-data`**. Used for low-level inspection of the bindings and
+ message journals. It takes two parameters - `bindings-directory` and
+ `journal-directory`. These are the paths to the directories where
+ the bindings and message journals are stored, respectively. For
+ example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar print-data /home/user/activemq/data/bindings /home/user/activemq/data/journal
+
+- **`print-pages`**. Used for low-level inspection of paged message
+ data. It takes two parameters - `paging-directory` and
+ `journal-directory`. These are the paths to the directories where
+ paged messages and the message journals are stored, respectively.
+ For example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar print-pages /home/user/activemq/data/paging-directory /home/user/activemq/data/journal
+
+- **`export`**. Used for exporting all binding and message data
+ (including paged and large messages) as well as JMS destinations and
+ connection factories (including JNDI bindings). The export is
+ structured as XML. This data can then be imported to another server
+ even if the server is a different version than the original. It
+ takes 4 parameters:
+
+ - `bindings-directory` - the path to the bindings directory.
+
+ - `journal-directory` - the path to the journal directory.
+
+ - `paging-directory` - the path to the paging directory.
+
+ - `large-messages-directory` - the path to the large-messages
+ directory.
+
+ Here's an example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar export /home/user/activemq/data/bindings-directory /home/user/activemq/data/journal-directory /home/user/activemq/data/paging-directory /home/user/activemq/data/large-messages
+
+ This tool will export directly to standard out so if the data needs
+ to be stored in a file please redirect as appropriate for the
+ operation system in use. Also, please note that the `export` tool is
+ single threaded so depending on the size of the journal it could
+ take awhile to complete.
+
+- **`import`**. Used for importing data from an XML document generated
+ by the `export` tool. The `import` tool reads the XML document and
+ connects to a ActiveMQ server via Netty to import all the data. It
+ takes 5 parameters:
+
+ - `input-file` - the path to the XML file generated by the
+ `export` tool.
+
+ - `host` - the IP address or hostname of the server where the data
+ should be imported.
+
+ - `port` - the port where ActiveMQ is listening.
+
+ - `transactional` - a `boolean` flag to indicate whether or not to
+ send all the *message* data in a single transaction. Valid
+ values are `true` or `false`.
+
+ - `application-server-compatibility` - a `boolean` flag to
+ indicate whether or not JNDI bindings need special treatment to
+ account for the way JBoss AS7, Wildfly, and JBoss EAP 6 handle
+ JNDI for remote clients. Each of these application servers
+ require a special JNDI binding to allow access from remote
+ clients. If this is `true` then every JNDI binding in the XML
+ will be duplicated in the "java:jboss/exported/" namespace thus
+ allowing both local and remote clients to use the same name when
+ accessing resources via JNDI. Valid values are `true` or
+ `false`.
+
+ Here's an example:
+
+ java -jar activemq-tools-<version>-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false
+
+ Like the `export` tool the `import` tool is single threaded so
+ depending on the size of the XML file it may take awhile for the
+ process to complete.
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/tools.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/tools.xml b/docs/user-manual/en/tools.xml
deleted file mode 100644
index 3bd3148..0000000
--- a/docs/user-manual/en/tools.xml
+++ /dev/null
@@ -1,116 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
- %BOOK_ENTITIES;
- ]>
-<chapter id="tools">
- <title>Tools</title>
-
- <para>ActiveMQ ships with several helpful command line tools. All tools are available from the activemq-tools-<version>-jar-with-dependencies.jar.
- As the name suggests, this Java archive contains ActiveMQ along with all of its dependencies. This is done to
- simplify the execution of the tools by eliminating the need so specify a classpath. These tools are:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold"><literal>print-data</literal></emphasis>. Used for low-level inspection of the bindings and message journals. It
- takes two parameters - <literal>bindings-directory</literal> and <literal>journal-directory</literal>. These
- are the paths to the directories where the bindings and message journals are stored, respectively. For
- example:
- </para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar print-data /home/user/activemq/data/bindings /home/user/activemq/data/journal</programlisting>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>print-pages</literal></emphasis>. Used for low-level inspection of paged message data. It takes two
- parameters - <literal>paging-directory</literal> and <literal>journal-directory</literal>. These are the
- paths to the directories where paged messages and the message journals are stored, respectively. For
- example:
- </para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar print-pages /home/user/activemq/data/paging-directory /home/user/activemq/data/journal</programlisting>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>export</literal></emphasis>. Used for exporting all binding and message data (including paged and large
- messages) as well as JMS destinations and connection factories (including JNDI bindings). The export is
- structured as XML. This data can then be imported to another server even if the server is a different
- version than the original. It takes 4 parameters:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>bindings-directory</literal> - the path to the bindings directory.</para>
- </listitem>
- <listitem>
- <para><literal>journal-directory</literal> - the path to the journal directory.</para>
- </listitem>
- <listitem>
- <para><literal>paging-directory</literal> - the path to the paging directory.</para>
- </listitem>
- <listitem>
- <para><literal>large-messages-directory</literal> - the path to the large-messages directory.</para>
- </listitem>
- </itemizedlist>
- <para>Here's an example:</para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar export /home/user/activemq/data/bindings-directory /home/user/activemq/data/journal-directory /home/user/activemq/data/paging-directory /home/user/activemq/data/large-messages</programlisting>
- <para>This tool will export directly to standard out so if the data needs to be stored in a file please
- redirect as appropriate for the operation system in use. Also, please note that the <literal>export</literal>
- tool is single threaded so depending on the size of the journal it could take awhile to complete.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="bold"><literal>import</literal></emphasis>. Used for importing data from an XML document generated by the
- <literal>export</literal> tool. The <literal>import</literal> tool reads the XML document and connects
- to a ActiveMQ server via Netty to import all the data. It takes 5 parameters:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>input-file</literal> - the path to the XML file generated by the <literal>export</literal>
- tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>host</literal> - the IP address or hostname of the server where the data should be
- imported.
- </para>
- </listitem>
- <listitem>
- <para><literal>port</literal> - the port where ActiveMQ is listening.</para>
- </listitem>
- <listitem>
- <para><literal>transactional</literal> - a <literal>boolean</literal> flag to indicate whether or not to
- send all the <emphasis>message</emphasis> data in a single transaction. Valid values are <literal>true</literal>
- or <literal>false</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>application-server-compatibility</literal> - a <literal>boolean</literal> flag to indicate
- whether or not JNDI bindings need special treatment to account for the way JBoss AS7, Wildfly, and
- JBoss EAP 6 handle JNDI for remote clients. Each of these application servers require a special JNDI
- binding to allow access from remote clients. If this is <literal>true</literal> then every JNDI
- binding in the XML will be duplicated in the "java:jboss/exported/" namespace thus allowing both local
- and remote clients to use the same name when accessing resources via JNDI. Valid values are
- <literal>true</literal> or <literal>false</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>Here's an example:</para>
- <programlisting>java -jar activemq-tools-<version>-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false</programlisting>
- <para>Like the <literal>export</literal> tool the <literal>import</literal> tool is single threaded so
- depending on the size of the XML file it may take awhile for the process to complete.
- </para>
- </listitem>
- </itemizedlist>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/transaction-config.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/transaction-config.md b/docs/user-manual/en/transaction-config.md
new file mode 100644
index 0000000..3bdbbc8
--- /dev/null
+++ b/docs/user-manual/en/transaction-config.md
@@ -0,0 +1,22 @@
+Resource Manager Configuration
+==============================
+
+ActiveMQ has its own Resource Manager for handling the lifespan of JTA
+transactions. When a transaction is started the resource manager is
+notified and keeps a record of the transaction and its current state. It
+is possible in some cases for a transaction to be started but then
+forgotten about. Maybe the client died and never came back. If this
+happens then the transaction will just sit there indefinitely.
+
+To cope with this ActiveMQ can, if configured, scan for old transactions
+and rollback any it finds. The default for this is 3000000 milliseconds
+(5 minutes), i.e. any transactions older than 5 minutes are removed.
+This timeout can be changed by editing the `transaction-timeout`
+property in `activemq-configuration.xml` (value must be in
+milliseconds). The property `transaction-timeout-scan-period` configures
+how often, in milliseconds, to scan for old transactions.
+
+Please note that ActiveMQ will not unilaterally rollback any XA
+transactions in a prepared state - this must be heuristically rolled
+back via the management API if you are sure they will never be resolved
+by the transaction manager.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/transaction-config.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/transaction-config.xml b/docs/user-manual/en/transaction-config.xml
deleted file mode 100644
index 1d4def2..0000000
--- a/docs/user-manual/en/transaction-config.xml
+++ /dev/null
@@ -1,38 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="transaction-config">
- <title>Resource Manager Configuration</title>
- <para>ActiveMQ has its own Resource Manager for handling the lifespan of JTA transactions. When a
- transaction is started the resource manager is notified and keeps a record of the
- transaction and its current state. It is possible in some cases for a transaction to be
- started but then forgotten about. Maybe the client died and never came back. If this happens
- then the transaction will just sit there indefinitely.</para>
- <para>To cope with this ActiveMQ can, if configured, scan for old transactions and rollback any
- it finds. The default for this is 3000000 milliseconds (5 minutes), i.e. any transactions older
- than 5 minutes are removed. This timeout can be changed by editing the <literal
- >transaction-timeout</literal> property in <literal>activemq-configuration.xml</literal> (value must be in milliseconds).
- The property <literal>transaction-timeout-scan-period</literal> configures how often, in
- milliseconds, to scan for old transactions.</para>
- <para>Please note that ActiveMQ will not unilaterally rollback any XA transactions in a prepared state - this must be heuristically rolled
- back via the management API if you are sure they will never be resolved by the transaction manager.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/undelivered-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/undelivered-messages.md b/docs/user-manual/en/undelivered-messages.md
new file mode 100644
index 0000000..d449102
--- /dev/null
+++ b/docs/user-manual/en/undelivered-messages.md
@@ -0,0 +1,166 @@
+Message Redelivery and Undelivered Messages
+===========================================
+
+Messages can be delivered unsuccessfully (e.g. if the transacted session
+used to consume them is rolled back). Such a message goes back to its
+queue ready to be redelivered. However, this means it is possible for a
+message to be delivered again and again without any success and remain
+in the queue, clogging the system.
+
+There are 2 ways to deal with these undelivered messages:
+
+- Delayed redelivery.
+
+ It is possible to delay messages redelivery to let the client some
+ time to recover from transient failures and not overload its network
+ or CPU resources
+
+- Dead Letter Address.
+
+ It is also possible to configure a dead letter address so that after
+ a specified number of unsuccessful deliveries, messages are removed
+ from the queue and will not be delivered again
+
+Both options can be combined for maximum flexibility.
+
+Delayed Redelivery
+==================
+
+Delaying redelivery can often be useful in the case that clients
+regularly fail or rollback. Without a delayed redelivery, the system can
+get into a "thrashing" state, with delivery being attempted, the client
+rolling back, and delivery being re-attempted ad infinitum in quick
+succession, consuming valuable CPU and network resources.
+
+Configuring Delayed Redelivery
+------------------------------
+
+Delayed redelivery is defined in the address-setting configuration:
+
+ <!-- delay redelivery of messages for 5s -->
+ <address-setting match="jms.queue.exampleQueue">
+ <!-- default is 1.0 -->
+ <redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
+ <!-- default is 0 (no delay) -->
+ <redelivery-delay>5000</redelivery-delay>
+ <!-- default is redelivery-delay * 10 -->
+ <max-redelivery-delay>50000</max-redelivery-delay>
+
+ </address-setting>
+
+If a `redelivery-delay` is specified, ActiveMQ will wait this delay
+before redelivering the messages.
+
+By default, there is no redelivery delay (`redelivery-delay`is set to
+0).
+
+Other subsequent messages will be delivery regularly, only the cancelled
+message will be sent asynchronously back to the queue after the delay.
+
+You can specify a multiplier that will take effect on top of the
+redelivery-delay with a max-redelivery-delay to be taken into account.
+
+The max-redelivery-delay is defaulted to redelivery-delay \* 10
+
+Address wildcards can be used to configure redelivery delay for a set of
+addresses (see ?), so you don't have to specify redelivery delay
+individually for each address.
+
+Example
+-------
+
+See ? for an example which shows how delayed redelivery is configured
+and used with JMS.
+
+Dead Letter Addresses
+=====================
+
+To prevent a client infinitely receiving the same undelivered message
+(regardless of what is causing the unsuccessful deliveries), messaging
+systems define *dead letter addresses*: after a specified unsuccessful
+delivery attempts, the message is removed from the queue and send
+instead to a dead letter address.
+
+Any such messages can then be diverted to queue(s) where they can later
+be perused by the system administrator for action to be taken.
+
+ActiveMQ's addresses can be assigned a dead letter address. Once the
+messages have been unsuccessfully delivered for a given number of
+attempts, they are removed from the queue and sent to the dead letter
+address. These *dead letter* messages can later be consumed for further
+inspection.
+
+Configuring Dead Letter Addresses
+---------------------------------
+
+Dead letter address is defined in the address-setting configuration:
+
+ <!-- undelivered messages in exampleQueue will be sent to the dead letter address
+ deadLetterQueue after 3 unsuccessful delivery attempts -->
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ </address-setting>
+
+If a `dead-letter-address` is not specified, messages will removed after
+`max-delivery-attempts` unsuccessful attempts.
+
+By default, messages are redelivered 10 times at the maximum. Set
+`max-delivery-attempts` to -1 for infinite redeliveries.
+
+For example, a dead letter can be set globally for a set of matching
+addresses and you can set `max-delivery-attempts` to -1 for a specific
+address setting to allow infinite redeliveries only for this address.
+
+Address wildcards can be used to configure dead letter settings for a
+set of addresses (see ?).
+
+Dead Letter Properties
+----------------------
+
+Dead letter messages which are consumed from a dead letter address have
+the following properties:
+
+- `_HQ_ORIG_ADDRESS`
+
+ a String property containing the *original address* of the dead
+ letter message
+
+- `_HQ_ORIG_QUEUE`
+
+ a String property containing the *original queue* of the dead letter
+ message
+
+Example
+-------
+
+See ? for an example which shows how dead letter is configured and used
+with JMS.
+
+Delivery Count Persistence
+==========================
+
+In normal use, ActiveMQ does not update delivery count *persistently*
+until a message is rolled back (i.e. the delivery count is not updated
+*before* the message is delivered to the consumer). In most messaging
+use cases, the messages are consumed, acknowledged and forgotten as soon
+as they are consumed. In these cases, updating the delivery count
+persistently before delivering the message would add an extra persistent
+step *for each message delivered*, implying a significant performance
+penalty.
+
+However, if the delivery count is not updated persistently before the
+message delivery happens, in the event of a server crash, messages might
+have been delivered but that will not have been reflected in the
+delivery count. During the recovery phase, the server will not have
+knowledge of that and will deliver the message with `redelivered` set to
+`false` while it should be `true`.
+
+As this behavior breaks strict JMS semantics, ActiveMQ allows to persist
+delivery count before message delivery but disabled it by default for
+performance implications.
+
+To enable it, set `persist-delivery-count-before-delivery` to `true` in
+`activemq-configuration.xml`:
+
+ <persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/undelivered-messages.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/undelivered-messages.xml b/docs/user-manual/en/undelivered-messages.xml
deleted file mode 100644
index 2f4a6f5..0000000
--- a/docs/user-manual/en/undelivered-messages.xml
+++ /dev/null
@@ -1,159 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="undelivered-messages">
- <title>Message Redelivery and Undelivered Messages</title>
- <para>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume
- them is rolled back). Such a message goes back to its queue ready to be redelivered. However,
- this means it is possible for a message to be delivered again and again without any success
- and remain in the queue, clogging the system.</para>
- <para>There are 2 ways to deal with these undelivered messages:</para>
- <itemizedlist>
- <listitem>
- <para>Delayed redelivery.</para>
- <para>It is possible to delay messages redelivery to let the client some time to recover
- from transient failures and not overload its network or CPU resources</para>
- </listitem>
- <listitem>
- <para>Dead Letter Address.</para>
- <para>It is also possible to configure a dead letter address so that after a specified
- number of unsuccessful deliveries, messages are removed from the queue and will not be
- delivered again</para>
- </listitem>
- </itemizedlist>
- <para>Both options can be combined for maximum flexibility.</para>
- <section>
- <title>Delayed Redelivery</title>
- <para>Delaying redelivery can often be useful in the case that clients regularly fail or
- rollback. Without a delayed redelivery, the system can get into a "thrashing" state, with
- delivery being attempted, the client rolling back, and delivery being re-attempted ad
- infinitum in quick succession, consuming valuable CPU and network resources.</para>
- <section id="undelivered-messages.delay">
- <title>Configuring Delayed Redelivery</title>
- <para>Delayed redelivery is defined in the address-setting configuration:</para>
- <programlisting>
-<!-- delay redelivery of messages for 5s -->
-<address-setting match="jms.queue.exampleQueue">
- <!-- default is 1.0 -->
- <redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
- <!-- default is 0 (no delay) -->
- <redelivery-delay>5000</redelivery-delay>
- <!-- default is redelivery-delay * 10 -->
- <max-redelivery-delay>50000</max-redelivery-delay>
-
-</address-setting></programlisting>
- <para>If a <literal>redelivery-delay</literal> is specified, ActiveMQ will wait this delay
- before redelivering the messages.</para>
- <para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set
- to 0).</para>
- <para>Other subsequent messages will be delivery regularly, only the cancelled message
- will be sent asynchronously back to the queue after the delay.</para>
- <para>You can specify a multiplier that will take effect on top of the redelivery-delay
- with a max-redelivery-delay to be taken into account.</para>
- <para>The max-redelivery-delay is defaulted to redelivery-delay * 10</para>
- <para>Address wildcards can be used to configure redelivery delay for a set of addresses
- (see <xref linkend="wildcard-syntax"/>), so you don't have to specify redelivery delay
- individually for each address.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.delayed-redelivery"/> for an example which shows how
- delayed redelivery is configured and used with JMS.</para>
- </section>
- </section>
- <section>
- <title>Dead Letter Addresses</title>
- <para>To prevent a client infinitely receiving the same undelivered message (regardless of
- what is causing the unsuccessful deliveries), messaging systems define <emphasis
- role="italic">dead letter addresses</emphasis>: after a specified unsuccessful delivery
- attempts, the message is removed from the queue and send instead to a dead letter address. </para>
- <para>Any such messages can then be diverted to queue(s) where they can later be perused by
- the system administrator for action to be taken.</para>
- <para>ActiveMQ's addresses can be assigned a dead letter address. Once the messages have been
- unsuccessfully delivered for a given number of attempts, they are removed from the queue
- and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can
- later be consumed for further inspection.</para>
- <section id="undelivered-messages.configuring">
- <title>Configuring Dead Letter Addresses</title>
- <para>Dead letter address is defined in the address-setting configuration:</para>
- <programlisting>
-<!-- undelivered messages in exampleQueue will be sent to the dead letter address
- deadLetterQueue after 3 unsuccessful delivery attempts -->
-<address-setting match="jms.queue.exampleQueue">
- <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
- <max-delivery-attempts>3</max-delivery-attempts>
-</address-setting></programlisting>
- <para>If a <literal>dead-letter-address</literal> is not specified, messages will removed
- after <literal>max-delivery-attempts</literal> unsuccessful attempts.</para>
- <para>By default, messages are redelivered 10 times at the maximum. Set <literal
- >max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
- <para>For example, a dead letter can be set globally for a set of matching addresses and
- you can set <literal>max-delivery-attempts</literal> to -1 for a specific address
- setting to allow infinite redeliveries only for this address.</para>
- <para>Address wildcards can be used to configure dead letter settings for a set of
- addresses (see <xref linkend="wildcard-syntax"/>).</para>
- </section>
- <section>
- <title>Dead Letter Properties</title>
- <para>Dead letter messages which are consumed from a dead letter address have the following
- properties:</para>
- <itemizedlist>
- <listitem>
- <para><literal>_HQ_ORIG_ADDRESS</literal></para>
- <para>a String property containing the <emphasis>original address</emphasis> of
- the dead letter message</para>
- </listitem>
- <listitem>
- <para><literal>_HQ_ORIG_QUEUE</literal></para>
- <para>a String property containing the <emphasis>original queue</emphasis> of
- the dead letter message</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.dead-letter"/> for an example which shows how dead letter
- is configured and used with JMS.</para>
- </section>
- </section>
- <section id="configuring.delivery.count.persistence">
- <title>Delivery Count Persistence</title>
- <para>In normal use, ActiveMQ does not update delivery count <emphasis>persistently</emphasis>
- until a message is rolled back (i.e. the delivery count is not updated
- <emphasis>before</emphasis> the message is delivered to the consumer). In most messaging
- use cases, the messages are consumed, acknowledged and forgotten as soon as they are
- consumed. In these cases, updating the delivery count persistently before delivering the
- message would add an extra persistent step <emphasis>for each message delivered</emphasis>,
- implying a significant performance penalty.</para>
- <para>However, if the delivery count is not updated persistently before the message delivery
- happens, in the event of a server crash, messages might have been delivered but that will
- not have been reflected in the delivery count. During the recovery phase, the server will
- not have knowledge of that and will deliver the message with <literal>redelivered</literal>
- set to <literal>false</literal> while it should be <literal>true</literal>. </para>
- <para>As this behavior breaks strict JMS semantics, ActiveMQ allows to persist delivery count
- before message delivery but disabled it by default for performance implications.</para>
- <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
- >true</literal> in <literal>activemq-configuration.xml</literal>:</para>
- <programlisting>
-<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery></programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-core.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-core.md b/docs/user-manual/en/using-core.md
new file mode 100644
index 0000000..6c9743f
--- /dev/null
+++ b/docs/user-manual/en/using-core.md
@@ -0,0 +1,222 @@
+Using Core
+==========
+
+ActiveMQ core is a completely JMS-agnostic messaging system with its own
+non-JMS API. We call this the *core API*.
+
+If you don't want to use JMS you can use the core API directly. The core
+API provides all the functionality of JMS but without much of the
+complexity. It also provides features that are not available using JMS.
+
+Core Messaging Concepts
+=======================
+
+Some of the core messaging concepts are similar to JMS concepts, but
+core messaging concepts differ in some ways. In general the core
+messaging API is simpler than the JMS API, since we remove distinctions
+between queues, topics and subscriptions. We'll discuss each of the
+major core messaging concepts in turn, but to see the API in detail,
+please consult the Javadoc.
+
+Message
+-------
+
+- A message is the unit of data which is sent between clients and
+ servers.
+
+- A message has a body which is a buffer containing convenient methods
+ for reading and writing data into it.
+
+- A message has a set of properties which are key-value pairs. Each
+ property key is a string and property values can be of type integer,
+ long, short, byte, byte[], String, double, float or boolean.
+
+- A message has an *address* it is being sent to. When the message
+ arrives on the server it is routed to any queues that are bound to
+ the address - if the queues are bound with any filter, the message
+ will only be routed to that queue if the filter matches. An address
+ may have many queues bound to it or even none. There may also be
+ entities other than queues, like *diverts* bound to addresses.
+
+- Messages can be either durable or non durable. Durable messages in a
+ durable queue will survive a server crash or restart. Non durable
+ messages will never survive a server crash or restart.
+
+- Messages can be specified with a priority value between 0 and 9. 0
+ represents the lowest priority and 9 represents the highest.
+ ActiveMQ will attempt to deliver higher priority messages before
+ lower priority ones.
+
+- Messages can be specified with an optional expiry time. ActiveMQ
+ will not deliver messages after its expiry time has been exceeded.
+
+- Messages also have an optional timestamp which represents the time
+ the message was sent.
+
+- ActiveMQ also supports the sending/consuming of very large messages
+ - much larger than can fit in available RAM at any one time.
+
+Address
+-------
+
+A server maintains a mapping between an address and a set of queues.
+Zero or more queues can be bound to a single address. Each queue can be
+bound with an optional message filter. When a message is routed, it is
+routed to the set of queues bound to the message's address. If any of
+the queues are bound with a filter expression, then the message will
+only be routed to the subset of bound queues which match that filter
+expression.
+
+Other entities, such as *diverts* can also be bound to an address and
+messages will also be routed there.
+
+> **Note**
+>
+> In core, there is no concept of a Topic, Topic is a JMS only term.
+> Instead, in core, we just deal with *addresses* and *queues*.
+>
+> For example, a JMS topic would be implemented by a single address to
+> which many queues are bound. Each queue represents a subscription of
+> the topic. A JMS Queue would be implemented as a single address to
+> which one queue is bound - that queue represents the JMS queue.
+
+Queue
+-----
+
+Queues can be durable, meaning the messages they contain survive a
+server crash or restart, as long as the messages in them are durable.
+Non durable queues do not survive a server restart or crash even if the
+messages they contain are durable.
+
+Queues can also be temporary, meaning they are automatically deleted
+when the client connection is closed, if they are not explicitly deleted
+before that.
+
+Queues can be bound with an optional filter expression. If a filter
+expression is supplied then the server will only route messages that
+match that filter expression to any queues bound to the address.
+
+Many queues can be bound to a single address. A particular queue is only
+bound to a maximum of one address.
+
+ServerLocator
+-------------
+
+Clients use `ServerLocator` instances to create `ClientSessionFactory`
+instances. `ServerLocator` instances are used to locate servers and
+create connections to them.
+
+In JMS terms think of a `ServerLocator` in the same way you would a JMS
+Connection Factory.
+
+`ServerLocator` instances are created using the `ActiveMQClient` factory
+class.
+
+ClientSessionFactory
+--------------------
+
+Clients use `ClientSessionFactory` instances to create `ClientSession`
+instances. `ClientSessionFactory` instances are basically the connection
+to a server
+
+In JMS terms think of them as JMS Connections.
+
+`ClientSessionFactory` instances are created using the `ServerLocator`
+class.
+
+ClientSession
+-------------
+
+A client uses a ClientSession for consuming and producing messages and
+for grouping them in transactions. ClientSession instances can support
+both transactional and non transactional semantics and also provide an
+`XAResource` interface so messaging operations can be performed as part
+of a
+[JTA](http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html)
+transaction.
+
+ClientSession instances group ClientConsumers and ClientProducers.
+
+ClientSession instances can be registered with an optional
+`SendAcknowledgementHandler`. This allows your client code to be
+notified asynchronously when sent messages have successfully reached the
+server. This unique ActiveMQ feature, allows you to have full guarantees
+that sent messages have reached the server without having to block on
+each message sent until a response is received. Blocking on each
+messages sent is costly since it requires a network round trip for each
+message sent. By not blocking and receiving send acknowledgements
+asynchronously you can create true end to end asynchronous systems which
+is not possible using the standard JMS API. For more information on this
+advanced feature please see the section ?.
+
+ClientConsumer
+--------------
+
+Clients use `ClientConsumer` instances to consume messages from a queue.
+Core Messaging supports both synchronous and asynchronous message
+consumption semantics. `ClientConsumer` instances can be configured with
+an optional filter expression and will only consume messages which match
+that expression.
+
+ClientProducer
+--------------
+
+Clients create `ClientProducer` instances on `ClientSession` instances
+so they can send messages. ClientProducer instances can specify an
+address to which all sent messages are routed, or they can have no
+specified address, and the address is specified at send time for the
+message.
+
+> **Warning**
+>
+> Please note that ClientSession, ClientProducer and ClientConsumer
+> instances are *designed to be re-used*.
+>
+> It's an anti-pattern to create new ClientSession, ClientProducer and
+> ClientConsumer instances for each message you produce or consume. If
+> you do this, your application will perform very poorly. This is
+> discussed further in the section on performance tuning ?.
+
+A simple example of using Core
+==============================
+
+Here's a very simple program using the core messaging API to send and
+receive a message. Logically it's comprised of two sections: firstly
+setting up the producer to write a message to an *addresss*, and
+secondly, creating a *queue* for the consumer, creating the consumer and
+*starting* it.
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
+
+ // In this simple example, we just use one session for both producing and receiving
+
+ ClientSessionFactory factory = locator.createClientSessionFactory();
+ ClientSession session = factory.createSession();
+
+ // A producer is associated with an address ...
+
+ ClientProducer producer = session.createProducer("example");
+ ClientMessage message = session.createMessage(true);
+ message.getBodyBuffer().writeString("Hello");
+
+ // We need a queue attached to the address ...
+
+ session.createQueue("example", "example", true);
+
+ // And a consumer attached to the queue ...
+
+ ClientConsumer consumer = session.createConsumer("example");
+
+ // Once we have a queue, we can send the message ...
+
+ producer.send(message);
+
+ // We need to start the session before we can -receive- messages ...
+
+ session.start();
+ ClientMessage msgReceived = consumer.receive();
+
+ System.out.println("message = " + msgReceived.getBodyBuffer().readString());
+
+ session.close();
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-core.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-core.xml b/docs/user-manual/en/using-core.xml
deleted file mode 100644
index f66f6af..0000000
--- a/docs/user-manual/en/using-core.xml
+++ /dev/null
@@ -1,223 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-<chapter id="using-core">
- <title>Using Core</title>
- <para>ActiveMQ core is a completely JMS-agnostic messaging system with its own non-JMS API. We
- call this the <emphasis>core API</emphasis>.</para>
- <para>If you don't want to use JMS you can use the core API directly. The core API provides all
- the functionality of JMS but without much of the complexity. It also provides features that
- are not available using JMS.</para>
- <section>
- <title>Core Messaging Concepts</title>
- <para>Some of the core messaging concepts are similar to JMS concepts, but core messaging
- concepts differ in some ways. In general the core messaging API is simpler than the JMS
- API, since we remove distinctions between queues, topics and subscriptions. We'll
- discuss each of the major core messaging concepts in turn, but to see the API in detail,
- please consult the Javadoc.</para>
- <section>
- <title>Message</title>
- <itemizedlist>
- <listitem>
- <para>A message is the unit of data which is sent between clients and
- servers.</para>
- </listitem>
- <listitem>
- <para>A message has a body which is a buffer containing convenient methods for
- reading and writing data into it.</para>
- </listitem>
- <listitem>
- <para>A message has a set of properties which are key-value pairs. Each property
- key is a string and property values can be of type integer, long, short,
- byte, byte[], String, double, float or boolean.</para>
- </listitem>
- <listitem>
- <para>A message has an <emphasis>address</emphasis> it is being sent to. When
- the message arrives on the server it is routed to any queues that are bound
- to the address - if the queues are bound with any filter, the message will
- only be routed to that queue if the filter matches. An address may have many
- queues bound to it or even none. There may also be entities other than
- queues, like <emphasis role="italic">diverts</emphasis> bound to
- addresses.</para>
- </listitem>
- <listitem>
- <para>Messages can be either durable or non durable. Durable messages in a
- durable queue will survive a server crash or restart. Non durable messages
- will never survive a server crash or restart.</para>
- </listitem>
- <listitem>
- <para>Messages can be specified with a priority value between 0 and 9. 0
- represents the lowest priority and 9 represents the highest. ActiveMQ will
- attempt to deliver higher priority messages before lower priority
- ones.</para>
- </listitem>
- <listitem>
- <para>Messages can be specified with an optional expiry time. ActiveMQ will not
- deliver messages after its expiry time has been exceeded.</para>
- </listitem>
- <listitem>
- <para>Messages also have an optional timestamp which represents the time the
- message was sent.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ also supports the sending/consuming of very large messages - much
- larger than can fit in available RAM at any one time.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Address</title>
- <para>A server maintains a mapping between an address and a set of queues. Zero or more
- queues can be bound to a single address. Each queue can be bound with an optional
- message filter. When a message is routed, it is routed to the set of queues bound to
- the message's address. If any of the queues are bound with a filter expression, then
- the message will only be routed to the subset of bound queues which match that
- filter expression.</para>
- <para>Other entities, such as <emphasis role="italic">diverts</emphasis> can also be
- bound to an address and messages will also be routed there.</para>
- <note>
- <para>In core, there is no concept of a Topic, Topic is a JMS only term. Instead, in
- core, we just deal with <emphasis>addresses</emphasis> and
- <emphasis>queues</emphasis>.</para>
- <para>For example, a JMS topic would be implemented by a single address to which
- many queues are bound. Each queue represents a subscription of the topic. A JMS
- Queue would be implemented as a single address to which one queue is bound -
- that queue represents the JMS queue.</para>
- </note>
- </section>
- <section>
- <title>Queue</title>
- <para>Queues can be durable, meaning the messages they contain survive a server crash or
- restart, as long as the messages in them are durable. Non durable queues do not
- survive a server restart or crash even if the messages they contain are
- durable.</para>
- <para>Queues can also be temporary, meaning they are automatically deleted when the
- client connection is closed, if they are not explicitly deleted before that.</para>
- <para>Queues can be bound with an optional filter expression. If a filter expression is
- supplied then the server will only route messages that match that filter expression
- to any queues bound to the address.</para>
- <para>Many queues can be bound to a single address. A particular queue is only bound to
- a maximum of one address.</para>
- </section>
- <section>
- <title>ServerLocator</title>
- <para>Clients use <literal>ServerLocator</literal> instances to create <literal
- >ClientSessionFactory</literal> instances. <literal>ServerLocator</literal>
- instances are used to locate servers and create connections to them. </para>
- <para>In JMS terms think of a <literal>ServerLocator</literal> in the same way you would
- a JMS Connection Factory.</para>
- <para><literal>ServerLocator</literal> instances are created using the <literal
- >ActiveMQClient</literal> factory class.</para>
- </section>
- <section>
- <title>ClientSessionFactory</title>
- <para>Clients use <literal>ClientSessionFactory</literal> instances to create <literal
- >ClientSession</literal> instances. <literal>ClientSessionFactory</literal>
- instances are basically the connection to a server</para>
- <para> In JMS terms think of them as JMS Connections.</para>
- <para><literal>ClientSessionFactory</literal> instances are created using the <literal
- >ServerLocator</literal> class.</para>
- </section>
- <section>
- <title>ClientSession</title>
- <para>A client uses a ClientSession for consuming and producing messages and for
- grouping them in transactions. ClientSession instances can support both
- transactional and non transactional semantics and also provide an <literal
- >XAResource</literal> interface so messaging operations can be performed as part
- of a <ulink url="http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html">JTA</ulink>
- transaction.</para>
- <para>ClientSession instances group ClientConsumers and ClientProducers.</para>
- <para>ClientSession instances can be registered with an optional <literal
- >SendAcknowledgementHandler</literal>. This allows your client code to be
- notified asynchronously when sent messages have successfully reached the server.
- This unique ActiveMQ feature, allows you to have full guarantees that sent messages
- have reached the server without having to block on each message sent until a
- response is received. Blocking on each messages sent is costly since it requires a
- network round trip for each message sent. By not blocking and receiving send
- acknowledgements asynchronously you can create true end to end asynchronous systems
- which is not possible using the standard JMS API. For more information on this
- advanced feature please see the section <xref linkend="send-guarantees"/>.</para>
- </section>
- <section>
- <title>ClientConsumer</title>
- <para>Clients use <literal>ClientConsumer</literal> instances to consume messages from a
- queue. Core Messaging supports both synchronous and asynchronous message consumption
- semantics. <literal>ClientConsumer</literal> instances can be configured with an
- optional filter expression and will only consume messages which match that
- expression.</para>
- </section>
- <section>
- <title>ClientProducer</title>
- <para>Clients create <literal>ClientProducer</literal> instances on <literal
- >ClientSession</literal> instances so they can send messages. ClientProducer
- instances can specify an address to which all sent messages are routed, or they can
- have no specified address, and the address is specified at send time for the
- message.</para>
- </section>
- <warning>
- <para>Please note that ClientSession, ClientProducer and ClientConsumer instances are
- <emphasis>designed to be re-used</emphasis>.</para>
- <para>It's an anti-pattern to create new ClientSession, ClientProducer and
- ClientConsumer instances for each message you produce or consume. If you do this,
- your application will perform very poorly. This is discussed further in the section
- on performance tuning <xref linkend="perf-tuning"/>.</para>
- </warning>
- </section>
- <section>
- <title>A simple example of using Core</title>
- <para>Here's a very simple program using the core messaging API to send and receive a
- message. Logically it's comprised of two sections: firstly setting up the producer to
- write a message to an <emphasis>addresss</emphasis>, and secondly, creating a
- <emphasis>queue</emphasis> for the consumer, creating the consumer and
- <emphasis>starting</emphasis> it.</para>
- <programlisting>
-ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
- InVMConnectorFactory.class.getName()));
-
-// In this simple example, we just use one session for both producing and receiving
-
-ClientSessionFactory factory = locator.createClientSessionFactory();
-ClientSession session = factory.createSession();
-
-// A producer is associated with an address ...
-
-ClientProducer producer = session.createProducer("example");
-ClientMessage message = session.createMessage(true);
-message.getBodyBuffer().writeString("Hello");
-
-// We need a queue attached to the address ...
-
-session.createQueue("example", "example", true);
-
-// And a consumer attached to the queue ...
-
-ClientConsumer consumer = session.createConsumer("example");
-
-// Once we have a queue, we can send the message ...
-
-producer.send(message);
-
-// We need to start the session before we can -receive- messages ...
-
-session.start();
-ClientMessage msgReceived = consumer.receive();
-
-System.out.println("message = " + msgReceived.getBodyBuffer().readString());
-
-session.close();</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/using-jms.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/using-jms.md b/docs/user-manual/en/using-jms.md
new file mode 100644
index 0000000..595dc0e
--- /dev/null
+++ b/docs/user-manual/en/using-jms.md
@@ -0,0 +1,410 @@
+Using JMS
+=========
+
+Although ActiveMQ provides a JMS agnostic messaging API, many users will
+be more comfortable using JMS.
+
+JMS is a very popular API standard for messaging, and most messaging
+systems provide a JMS API. If you are completely new to JMS we suggest
+you follow the[Sun JMS
+tutorial](http://docs.oracle.com/javaee/1.3/jms/tutorial) - a full JMS
+tutorial is out of scope for this guide.
+
+ActiveMQ also ships with a wide range of examples, many of which
+demonstrate JMS API usage. A good place to start would be to play around
+with the simple JMS Queue and Topic example, but we also provide
+examples for many other parts of the JMS API. A full description of the
+examples is available in ?.
+
+In this section we'll go through the main steps in configuring the
+server for JMS and creating a simple JMS program. We'll also show how to
+configure and use JNDI, and also how to use JMS with ActiveMQ without
+using any JNDI.
+
+A simple ordering system
+========================
+
+For this chapter we're going to use a very simple ordering system as our
+example. It is a somewhat contrived example because of its extreme
+simplicity, but it serves to demonstrate the very basics of setting up
+and using JMS.
+
+We will have a single JMS Queue called `OrderQueue`, and we will have a
+single `MessageProducer` sending an order message to the queue and a
+single `MessageConsumer` consuming the order message from the queue.
+
+The queue will be a `durable` queue, i.e. it will survive a server
+restart or crash. We also want to pre-deploy the queue, i.e. specify the
+queue in the server JMS configuration so it is created automatically
+without us having to explicitly create it from the client.
+
+JNDI Configuration
+==================
+
+The JMS specification establishes the convention that *administered
+objects* (i.e. JMS queue, topic and connection factory instances) are
+made available via the JNDI API. Brokers are free to implement JNDI as
+they see fit assuming the implementation fits the API. ActiveMQ does not
+have a JNDI server. Rather, it uses a client-side JNDI implementation
+that relies on special properties set in the environment to construct
+the appropriate JMS objects. In other words, no objects are stored in
+JNDI on the ActiveMQ server. There are simply instantiated on the client
+based on the provided configuration. Let's look at the different kinds
+of administered objects and how to configure them.
+
+> **Note**
+>
+> The following configuration properties *are strictly required when
+> ActiveMQ is running in stand-alone mode*. When ActiveMQ is integrated
+> to an application server (e.g. Wildfly) the application server itself
+> will almost certainly provide a JNDI client with its own properties.
+
+ConnectionFactory JNDI
+----------------------
+
+A JMS connection factory is used by the client to make connections to
+the server. It knows the location of the server it is connecting to, as
+well as many other configuration parameters.
+
+By default, a `javax.naming.Context` instance created using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory` will
+automatically have the following connection factories available for
+lookup:
+
+- `ConnectionFactory`
+
+- `XAConnectionFactory`
+
+- `QueueConnectionFactory`
+
+- `TopicConnectionFactory`
+
+Here's a simple example of the JNDI context environment for a client
+looking up a connection factory to access an *embedded* instance of
+ActiveMQ:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+
+It's really as simple as that. As noted previously, any JNDI context
+created with the `ActiveMQInitialContextFactory` will have a set of
+default connection factories available. Therefore, only the
+`java.naming.factory.initial` property is required to access an embedded
+broker.
+
+In certain situations there could be multiple server instances running
+within a particular JVM. In that situation each server would typically
+have an InVM acceptor with a unique server-ID. A client using JMS and
+JNDI can account for this by specifying a
+`javax.naming.Context.PROVIDER_URL` (`String` value of
+"java.naming.provider.url") in the JNDI environment like `vm://2` where
+`2` is the server-ID for acceptor.
+
+Here is a list of all the supported URL schemes:
+
+- `vm`
+
+- `tcp`
+
+- `udp`
+
+- `jgroups`
+
+Most clients won't be connecting to an embedded broker. Clients will
+most commonly connect across a network a remote broker. In that case the
+client can use the `javax.naming.Context.PROVIDER_URL` (`String` value
+of "java.naming.provider.url") in the JNDI environment to specify where
+to connect. Here's a simple example of a client configuring a connection
+factory to connect to a remote broker running on myhost:5445:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+
+In the example above the client is using the `tcp` scheme for the
+provider URL. A client may also specify multiple comma-delimited
+host:port combinations in the URL (e.g.
+`tcp://remote-host1:5445,remote-host2:5445`). Whether there is one or
+many host:port combinations in the URL they are treated as the *initial
+connector(s)* for the underlying connection.
+
+The `udp` scheme is also supported which should use an host:port
+combination that matches the `group-address` and `group-port` from the
+corresponding `broadcast-group` configured on the ActiveMQ server(s).
+
+Each scheme has a specific set of properties which can be set using the
+traditional URL query string format (e.g.
+`scheme://host:port?key1=value1&key2=value2`) to customize the
+underlying transport mechanism. For example, if a client wanted to
+connect to a remote server using TCP and SSL it would use a
+`Context.PROVIDER_URL` of `tcp://remote-host:5445?ssl-enabled=true`.
+
+All the properties available for the `tcp` scheme are described in [the
+documentation regarding the Netty
+transport](#configuring-transports.netty).
+
+The `udp` scheme supports 4 properties:
+
+- `local-address` - If you are running with multiple network
+ interfaces on the same machine, you may want to specify that the
+ discovery group listens only only a specific interface. To do this
+ you can specify the interface address with this parameter.
+
+- `local-port` - If you want to specify a local port to which the
+ datagram socket is bound you can specify it here. Normally you would
+ just use the default value of -1 which signifies that an anonymous
+ port should be used. This parameter is always specified in
+ conjunction with `local-address`.
+
+- `refresh-timeout` - This is the period the discovery group waits
+ after receiving the last broadcast from a particular server before
+ removing that servers connector pair entry from its list. You would
+ normally set this to a value significantly higher than the
+ broadcast-period on the broadcast group otherwise servers might
+ intermittently disappear from the list even though they are still
+ broadcasting due to slight differences in timing. This parameter is
+ optional, the default value is 10000 milliseconds (10 seconds).
+
+- `discovery-initial-wait-timeout` - If the connection factory is used
+ immediately after creation then it may not have had enough time to
+ received broadcasts from all the nodes in the cluster. On first
+ usage, the connection factory will make sure it waits this long
+ since creation before creating the first connection. The default
+ value for this parameter is 10000 milliseconds.
+
+Lastly, the `jgroups` scheme is supported which provides an alternative
+to the `udp` scheme for server discovery. The URL pattern is as follows
+`jgroups://<jgroups-xml-conf-filename>` where
+`<jgroups-xml-conf-filename>` refers to an XML file on the classpath
+that contains the JGroups configuration.
+
+The `refresh-timeout` and `discovery-initial-wait-timeout` properties
+are supported just like with `udp`.
+
+Although a `javax.naming.Context` instance created using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory` will
+automatically have some connection factories present, it is possible for
+a client to specify its own connection factories. This is done using the
+`org.apache.activemq.jndi.ActiveMQInitialContextFactory.CONNECTION_FACTORY_NAMES`
+property (String value of "connectionFactoryNames"). The value for this
+property is a comma delimited String of all the connection factories the
+client wishes to create. For example:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connectionFactoryNames=myConnectionFactory
+
+In this example, the client is creating a connection factory named
+"myConnectionFactory." This replaces all the default connection
+factories so that only the "myConnectionFactory" connection factory is
+available to the client.
+
+Aside from the underlying transport, the underlying connection factory
+implementation can also be configured using special properties. To
+configure a particular connection factory the client would follow this
+pattern for the property name to set in the environment:
+`connection.<connection-factory-name>.<property-name>`. For example, if
+the client wanted to customize the default connection factory
+"ConnectionFactory" to support high-availability then it would do this:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+ connection.ConnectionFactory.ha=true
+
+Any property available on the underlying
+`org.apache.activemq.jms.client.ActiveMQConnectionFactory` can be set
+this way in addition to the `ha` (boolean) and `type` (String)
+properties. Here are the different options for the `type`:
+
+ type interface
+ --------------- ------------------------------------
+ CF (default) javax.jms.ConnectionFactory
+ XA\_CF javax.jms.XAConnectionFactory
+ QUEUE\_CF javax.jms.QueueConnectionFactory
+ QUEUE\_XA\_CF javax.jms.XAQueueConnectionFactory
+ TOPIC\_CF javax.jms.TopicConnectionFactory
+ TOPIC\_XA\_CF javax.jms.XATopicConnectionFactory
+
+ : Configuration for Connection Factory Types
+
+Destination JNDI
+----------------
+
+JMS destinations are also typically looked up via JNDI. As with
+connection factories, destinations can be configured using special
+properties in the JNDI context environment. The property *name* should
+follow the pattern: `queue.<jndi-binding>` or `topic.<jndi-binding>`.
+The property *value* should be the name of the queue hosted by the
+ActiveMQ server. For example, if the server had a JMS queue configured
+like so:
+
+ <queue name="OrderQueue"/>
+
+And if the client wanted to bind this queue to "queues/OrderQueue" then
+the JNDI properties would be configured like so:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://myhost:5445
+ queue.queues/OrderQueue=OrderQueue
+
+It is also possible to look-up JMS destinations which haven't been
+configured explicitly in the JNDI context environment. This is possible
+using `dynamicQueues/` or `dynamicTopics/` in the look-up string. For
+example, if the client wanted to look-up the aforementioned "OrderQueue"
+it could do so simply by using the string "dynamicQueues/OrderQueue".
+Note, the text that follows `dynamicQueues/` or `dynamicTopics/` must
+correspond *exactly* to the name of the destination on the server.
+
+The code
+--------
+
+Here's the code for the example:
+
+First we'll create a JNDI initial context from which to lookup our JMS
+objects. If the above properties are set in `jndi.properties` and it is
+on the classpath then any new, empty `InitialContext` will be
+initialized using those properties:
+
+ InitialContext ic = new InitialContext();
+
+Now we'll look up the connection factory from which we can create
+connections to myhost:5445:
+
+ ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");
+
+And look up the Queue:
+
+ Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue");
+
+Next we create a JMS connection using the connection factory:
+
+ Connection connection = cf.createConnection();
+
+And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
+acknowledge mode:
+
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+We create a MessageProducer that will send orders to the queue:
+
+ MessageProducer producer = session.createProducer(orderQueue);
+
+And we create a MessageConsumer which will consume orders from the
+queue:
+
+ MessageConsumer consumer = session.createConsumer(orderQueue);
+
+We make sure we start the connection, or delivery won't occur on it:
+
+ connection.start();
+
+We create a simple TextMessage and send it:
+
+ TextMessage message = session.createTextMessage("This is an order");
+ producer.send(message);
+
+And we consume the message:
+
+ TextMessage receivedMessage = (TextMessage)consumer.receive();
+ System.out.println("Got order: " + receivedMessage.getText());
+
+It is as simple as that. For a wide range of working JMS examples please
+see the examples directory in the distribution.
+
+> **Warning**
+>
+> Please note that JMS connections, sessions, producers and consumers
+> are *designed to be re-used*.
+>
+> It is an anti-pattern to create new connections, sessions, producers
+> and consumers for each message you produce or consume. If you do this,
+> your application will perform very poorly. This is discussed further
+> in the section on performance tuning ?.
+
+Directly instantiating JMS Resources without using JNDI
+=======================================================
+
+Although it is a very common JMS usage pattern to lookup JMS
+*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory
+instances) from JNDI, in some cases you just think "Why do I need JNDI?
+Why can't I just instantiate these objects directly?"
+
+With ActiveMQ you can do exactly that. ActiveMQ supports the direct
+instantiation of JMS Queue, Topic and ConnectionFactory instances, so
+you don't have to use JNDI at all.
+
+For a full working example of direct instantiation please see the JMS
+examples in ?.
+
+Here's our simple example, rewritten to not use JNDI at all:
+
+We create the JMS ConnectionFactory object via the ActiveMQJMSClient
+Utility class, note we need to provide connection parameters and specify
+which transport we are using, for more information on connectors please
+see ?.
+
+
+ TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
+ ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
+
+We also create the JMS Queue object via the ActiveMQJMSClient Utility
+class:
+
+ Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");
+
+Next we create a JMS connection using the connection factory:
+
+ Connection connection = cf.createConnection();
+
+And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
+acknowledge mode:
+
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+We create a MessageProducer that will send orders to the queue:
+
+ MessageProducer producer = session.createProducer(orderQueue);
+
+And we create a MessageConsumer which will consume orders from the
+queue:
+
+ MessageConsumer consumer = session.createConsumer(orderQueue);
+
+We make sure we start the connection, or delivery won't occur on it:
+
+ connection.start();
+
+We create a simple TextMessage and send it:
+
+ TextMessage message = session.createTextMessage("This is an order");
+ producer.send(message);
+
+And we consume the message:
+
+ TextMessage receivedMessage = (TextMessage)consumer.receive();
+ System.out.println("Got order: " + receivedMessage.getText());
+
+Setting The Client ID
+=====================
+
+This represents the client id for a JMS client and is needed for
+creating durable subscriptions. It is possible to configure this on the
+connection factory and can be set via the `client-id` element. Any
+connection created by this connection factory will have this set as its
+client id.
+
+Setting The Batch Size for DUPS\_OK
+===================================
+
+When the JMS acknowledge mode is set to `DUPS_OK` it is possible to
+configure the consumer so that it sends acknowledgements in batches
+rather that one at a time, saving valuable bandwidth. This can be
+configured via the connection factory via the `dups-ok-batch-size`
+element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB.
+
+Setting The Transaction Batch Size
+==================================
+
+When receiving messages in a transaction it is possible to configure the
+consumer to send acknowledgements in batches rather than individually
+saving valuable bandwidth. This can be configured on the connection
+factory via the `transaction-batch-size` element and is set in bytes.
+The default is 1024 \* 1024.