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:38 UTC
[07/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/perf-tuning.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/perf-tuning.xml b/docs/user-manual/en/perf-tuning.xml
deleted file mode 100644
index d9ee18c..0000000
--- a/docs/user-manual/en/perf-tuning.xml
+++ /dev/null
@@ -1,304 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="perf-tuning">
- <title>Performance Tuning</title>
- <para>In this chapter we'll discuss how to tune ActiveMQ for optimum performance.</para>
- <section>
- <title>Tuning persistence</title>
- <itemizedlist>
- <listitem>
- <para>Put the message journal on its own physical volume. If the disk is shared with
- other processes e.g. transaction co-ordinator, database or other journals which
- are also reading and writing from it, then this may greatly reduce performance
- since the disk head may be skipping all over the place between the different
- files. One of the advantages of an append only journal is that disk head
- movement is minimised - this advantage is destroyed if the disk is shared. If
- you're using paging or large messages make sure they're ideally put on separate
- volumes too.</para>
- </listitem>
- <listitem>
- <para>Minimum number of journal files. Set <literal>journal-min-files</literal> to a
- number of files that would fit your average sustainable rate. If you see new
- files being created on the journal data directory too often, i.e. lots of data
- is being persisted, you need to increase the minimal number of files, this way
- the journal would reuse more files instead of creating new data files.</para>
- </listitem>
- <listitem>
- <para>Journal file size. The journal file size should be aligned to the capacity of
- a cylinder on the disk. The default value 10MiB should be enough on most
- systems.</para>
- </listitem>
- <listitem>
- <para>Use AIO journal. If using Linux, try to keep your journal type as AIO. AIO
- will scale better than Java NIO.</para>
- </listitem>
- <listitem>
- <para>Tune <literal>journal-buffer-timeout</literal>. The timeout can be increased
- to increase throughput at the expense of latency.</para>
- </listitem>
- <listitem>
- <para>If you're running AIO you might be able to get some better performance by
- increasing <literal>journal-max-io</literal>. DO NOT change this parameter if
- you are running NIO.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning JMS</title>
- <para>There are a few areas where some tweaks can be done if you are using the JMS
- API</para>
- <itemizedlist>
- <listitem>
- <para>Disable message id. Use the <literal>setDisableMessageID()</literal> method on
- the <literal>MessageProducer</literal> class to disable message ids if you don't
- need them. This decreases the size of the message and also avoids the overhead
- of creating a unique ID.</para>
- </listitem>
- <listitem>
- <para>Disable message timestamp. Use the <literal
- >setDisableMessageTimeStamp()</literal> method on the <literal
- >MessageProducer</literal> class to disable message timestamps if you don't
- need them.</para>
- </listitem>
- <listitem>
- <para>Avoid <literal>ObjectMessage</literal>. <literal>ObjectMessage</literal> is
- convenient but it comes at a cost. The body of a <literal
- >ObjectMessage</literal> uses Java serialization to serialize it to bytes.
- The Java serialized form of even small objects is very verbose so takes up a lot
- of space on the wire, also Java serialization is slow compared to custom
- marshalling techniques. Only use <literal>ObjectMessage</literal> if you really
- can't use one of the other message types, i.e. if you really don't know the type
- of the payload until run-time.</para>
- </listitem>
- <listitem>
- <para>Avoid <literal>AUTO_ACKNOWLEDGE</literal>. <literal>AUTO_ACKNOWLEDGE</literal>
- mode requires an acknowledgement to be sent from the server for each message
- received on the client, this means more traffic on the network. If you can, use
- <literal>DUPS_OK_ACKNOWLEDGE</literal> or use <literal
- >CLIENT_ACKNOWLEDGE</literal> or a transacted session and batch up many
- acknowledgements with one acknowledge/commit. </para>
- </listitem>
- <listitem>
- <para>Avoid durable messages. By default JMS messages are durable. If you don't
- really need durable messages then set them to be non-durable. Durable messages
- incur a lot more overhead in persisting them to storage.</para>
- </listitem>
- <listitem>
- <para>Batch many sends or acknowledgements in a single transaction. ActiveMQ will
- only require a network round trip on the commit, not on every send or
- acknowledgement.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Other Tunings</title>
- <para>There are various other places in ActiveMQ where we can perform some tuning:</para>
- <itemizedlist>
- <listitem>
- <para>Use Asynchronous Send Acknowledgements. If you need to send durable messages
- non transactionally and you need a guarantee that they have reached the server
- by the time the call to send() returns, don't set durable messages to be sent
- blocking, instead use asynchronous send acknowledgements to get your
- acknowledgements of send back in a separate stream, see <xref
- linkend="send-guarantees"/> for more information on this.</para>
- </listitem>
- <listitem>
- <para>Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged
- <literal>before</literal> they are sent to the client. This reduces the
- amount of acknowledgement traffic on the wire. For more information on this, see
- <xref linkend="pre-acknowledge"/>.</para>
- </listitem>
- <listitem>
- <para>Disable security. You may get a small performance boost by disabling security
- by setting the <literal>security-enabled</literal> parameter to <literal
- >false</literal> in <literal>activemq-configuration.xml</literal>.</para>
- </listitem>
- <listitem>
- <para>Disable persistence. If you don't need message persistence, turn it off
- altogether by setting <literal>persistence-enabled</literal> to false in
- <literal>activemq-configuration.xml</literal>.</para>
- </listitem>
- <listitem>
- <para>Sync transactions lazily. Setting <literal
- >journal-sync-transactional</literal> to <literal>false</literal> in
- <literal>activemq-configuration.xml</literal> can give you better
- transactional persistent performance at the expense of some possibility of loss
- of transactions on failure. See <xref linkend="send-guarantees"/> for more
- information.</para>
- </listitem>
- <listitem>
- <para>Sync non transactional lazily. Setting <literal
- >journal-sync-non-transactional</literal> to <literal>false</literal> in
- <literal>activemq-configuration.xml</literal> can give you better
- non-transactional persistent performance at the expense of some possibility of
- loss of durable messages on failure. See <xref linkend="send-guarantees"/> for
- more information.</para>
- </listitem>
- <listitem>
- <para>Send messages non blocking. Setting <literal>block-on-durable-send</literal>
- and <literal>block-on-non-durable-send</literal> to <literal>false</literal> in
- <literal>activemq-jms.xml</literal> (if you're using JMS and JNDI) or
- directly on the ServerLocator. This means you don't have to wait a whole
- network round trip for every message sent. See <xref linkend="send-guarantees"/>
- for more information.</para>
- </listitem>
- <listitem>
- <para>If you have very fast consumers, you can increase consumer-window-size. This
- effectively disables consumer flow control.</para>
- </listitem>
- <listitem>
- <para>Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking) on the
- server and the client side (see the chapter on configuring transports for more
- information <xref linkend="configuring-transports"/>). NIO is much more scalable
- but can give you some latency hit compared to old blocking IO. If you need to be
- able to service many thousands of connections on the server, then you should
- make sure you're using NIO on the server. However, if don't expect many
- thousands of connections on the server you can keep the server acceptors using
- old IO, and might get a small performance advantage.</para>
- </listitem>
- <listitem>
- <para>Use the core API not JMS. Using the JMS API you will have slightly lower
- performance than using the core API, since all JMS operations need to be
- translated into core operations before the server can handle them. If using the
- core API try to use methods that take <literal>SimpleString</literal> as much as
- possible. <literal>SimpleString</literal>, unlike java.lang.String does not
- require copying before it is written to the wire, so if you re-use <literal
- >SimpleString</literal> instances between calls then you can avoid some
- unnecessary copying.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning Transport Settings</title>
- <itemizedlist>
- <listitem>
- <para>TCP buffer sizes. If you have a fast network and fast machines you may get a
- performance boost by increasing the TCP send and receive buffer sizes. See the
- <xref linkend="configuring-transports"/> for more information on this. </para>
- <note>
- <para> Note that some operating systems like later versions of Linux include TCP
- auto-tuning and setting TCP buffer sizes manually can prevent auto-tune from
- working and actually give you worse performance!</para>
- </note>
- </listitem>
- <listitem>
- <para>Increase limit on file handles on the server. If you expect a lot of
- concurrent connections on your servers, or if clients are rapidly opening and
- closing connections, you should make sure the user running the server has
- permission to create sufficient file handles.</para>
- <para>This varies from operating system to operating system. On Linux systems you
- can increase the number of allowable open file handles in the file <literal
- >/etc/security/limits.conf</literal> e.g. add the lines
- <programlisting>
-serveruser soft nofile 20000
-serveruser hard nofile 20000</programlisting>
- This would allow up to 20000 file handles to be open by the user <literal
- >serveruser</literal>. </para>
- </listitem>
- <listitem>
- <para>Use <literal>batch-delay</literal> and set <literal>direct-deliver</literal>
- to false for the best throughput for very small messages. ActiveMQ comes with a
- preconfigured connector/acceptor pair (<literal>netty-throughput</literal>) in
- <literal>activemq-configuration.xml</literal> and JMS connection factory
- (<literal>ThroughputConnectionFactory</literal>) in <literal
- >activemq-jms.xml</literal>which can be used to give the very best
- throughput, especially for small messages. See the <xref
- linkend="configuring-transports"/> for more information on this.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Tuning the VM</title>
- <para>We highly recommend you use the latest Java JVM for the best performance. We test
- internally using the Sun JVM, so some of these tunings won't apply to JDKs from other
- providers (e.g. IBM or JRockit)</para>
- <itemizedlist>
- <listitem>
- <para>Garbage collection. For smooth server operation we recommend using a parallel
- garbage collection algorithm, e.g. using the JVM argument <literal
- >-XX:+UseParallelOldGC</literal> on Sun JDKs.</para>
- </listitem>
- <listitem id="perf-tuning.memory">
- <para>Memory settings. Give as much memory as you can to the server. ActiveMQ can run
- in low memory by using paging (described in <xref linkend="paging"/>) but if it
- can run with all queues in RAM this will improve performance. The amount of
- memory you require will depend on the size and number of your queues and the
- size and number of your messages. Use the JVM arguments <literal>-Xms</literal>
- and <literal>-Xmx</literal> to set server available RAM. We recommend setting
- them to the same high value.</para>
- </listitem>
- <listitem>
- <para>Aggressive options. Different JVMs provide different sets of JVM tuning
- parameters, for the Sun Hotspot JVM the full list of options is available <ulink
- url="http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html"
- >here</ulink>. We recommend at least using <literal
- >-XX:+AggressiveOpts</literal> and<literal>
- -XX:+UseFastAccessorMethods</literal>. You may get some mileage with the
- other tuning parameters depending on your OS platform and application usage
- patterns.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Avoiding Anti-Patterns</title>
- <itemizedlist>
- <listitem>
- <para>Re-use connections / sessions / consumers / producers. Probably the most
- common messaging anti-pattern we see is users who create a new
- connection/session/producer for every message they send or every message they
- consume. This is a poor use of resources. These objects take time to create and
- may involve several network round trips. Always re-use them.</para>
- <note>
- <para>Some popular libraries such as the Spring JMS Template are known to use
- these anti-patterns. If you're using Spring JMS Template and you're getting
- poor performance you know why. Don't blame ActiveMQ! The Spring JMS Template
- can only safely be used in an app server which caches JMS sessions (e.g.
- using JCA), and only then for sending messages. It cannot be safely be used
- for synchronously consuming messages, even in an app server. </para>
- </note>
- </listitem>
- <listitem>
- <para>Avoid fat messages. Verbose formats such as XML take up a lot of space on the
- wire and performance will suffer as result. Avoid XML in message bodies if you
- can.</para>
- </listitem>
- <listitem>
- <para>Don't create temporary queues for each request. This common anti-pattern
- involves the temporary queue request-response pattern. With the temporary queue
- request-response pattern a message is sent to a target and a reply-to header is
- set with the address of a local temporary queue. When the recipient receives the
- message they process it then send back a response to the address specified in
- the reply-to. A common mistake made with this pattern is to create a new
- temporary queue on each message sent. This will drastically reduce performance.
- Instead the temporary queue should be re-used for many requests.</para>
- </listitem>
- <listitem>
- <para>Don't use Message-Driven Beans for the sake of it. As soon as you start using
- MDBs you are greatly increasing the codepath for each message received compared
- to a straightforward message consumer, since a lot of extra application server
- code is executed. Ask yourself do you really need MDBs? Can you accomplish the
- same task using just a normal message consumer?</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/persistence.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/persistence.md b/docs/user-manual/en/persistence.md
new file mode 100644
index 0000000..e2c6f58
--- /dev/null
+++ b/docs/user-manual/en/persistence.md
@@ -0,0 +1,392 @@
+Persistence
+===========
+
+In this chapter we will describe how persistence works with ActiveMQ and
+how to configure it.
+
+ActiveMQ ships with a high performance journal. Since ActiveMQ handles
+its own persistence, rather than relying on a database or other 3rd
+party persistence engine it is very highly optimised for the specific
+messaging use cases.
+
+A ActiveMQ journal is an *append only* journal. It consists of a set of
+files on disk. Each file is pre-created to a fixed size and initially
+filled with padding. As operations are performed on the server, e.g. add
+message, update message, delete message, records are appended to the
+journal. When one journal file is full we move to the next one.
+
+Because records are only appended, i.e. added to the end of the journal
+we minimise disk head movement, i.e. we minimise random access
+operations which is typically the slowest operation on a disk.
+
+Making the file size configurable means that an optimal size can be
+chosen, i.e. making each file fit on a disk cylinder. Modern disk
+topologies are complex and we are not in control over which cylinder(s)
+the file is mapped onto so this is not an exact science. But by
+minimising the number of disk cylinders the file is using, we can
+minimise the amount of disk head movement, since an entire disk cylinder
+is accessible simply by the disk rotating - the head does not have to
+move.
+
+As delete records are added to the journal, ActiveMQ has a sophisticated
+file garbage collection algorithm which can determine if a particular
+journal file is needed any more - i.e. has all its data been deleted in
+the same or other files. If so, the file can be reclaimed and re-used.
+
+ActiveMQ also has a compaction algorithm which removes dead space from
+the journal and compresses up the data so it takes up less files on
+disk.
+
+The journal also fully supports transactional operation if required,
+supporting both local and XA transactions.
+
+The majority of the journal is written in Java, however we abstract out
+the interaction with the actual file system to allow different pluggable
+implementations. ActiveMQ ships with two implementations:
+
+- Java [NIO](http://en.wikipedia.org/wiki/New_I/O).
+
+ The first implementation uses standard Java NIO to interface with
+ the file system. This provides extremely good performance and runs
+ on any platform where there's a Java 6+ runtime.
+
+- Linux Asynchronous IO
+
+ The second implementation uses a thin native code wrapper to talk to
+ the Linux asynchronous IO library (AIO). With AIO, ActiveMQ will be
+ called back when the data has made it to disk, allowing us to avoid
+ explicit syncs altogether and simply send back confirmation of
+ completion when AIO informs us that the data has been persisted.
+
+ Using AIO will typically provide even better performance than using
+ Java NIO.
+
+ The AIO journal is only available when running Linux kernel 2.6 or
+ later and after having installed libaio (if it's not already
+ installed). For instructions on how to install libaio please see ?.
+
+ Also, please note that AIO will only work with the following file
+ systems: ext2, ext3, ext4, jfs, xfs. With other file systems, e.g.
+ NFS it may appear to work, but it will fall back to a slower
+ synchronous behaviour. Don't put the journal on a NFS share!
+
+ For more information on libaio please see ?.
+
+ libaio is part of the kernel project.
+
+The standard ActiveMQ core server uses two instances of the journal:
+
+- Bindings journal.
+
+ This journal is used to store bindings related data. That includes
+ the set of queues that are deployed on the server and their
+ attributes. It also stores data such as id sequence counters.
+
+ The bindings journal is always a NIO journal as it is typically low
+ throughput compared to the message journal.
+
+ The files on this journal are prefixed as `activemq-bindings`. Each
+ file has a `bindings` extension. File size is `1048576`, and it is
+ located at the bindings folder.
+
+- JMS journal.
+
+ This journal instance stores all JMS related data, This is basically
+ any JMS Queues, Topics and Connection Factories and any JNDI
+ bindings for these resources.
+
+ Any JMS Resources created via the management API will be persisted
+ to this journal. Any resources configured via configuration files
+ will not. The JMS Journal will only be created if JMS is being used.
+
+ The files on this journal are prefixed as `activemq-jms`. Each file
+ has a `jms` extension. File size is `1048576`, and it is located at
+ the bindings folder.
+
+- Message journal.
+
+ This journal instance stores all message related data, including the
+ message themselves and also duplicate-id caches.
+
+ By default ActiveMQ will try and use an AIO journal. If AIO is not
+ available, e.g. the platform is not Linux with the correct kernel
+ version or AIO has not been installed then it will automatically
+ fall back to using Java NIO which is available on any Java platform.
+
+ The files on this journal are prefixed as `activemq-data`. Each file
+ has a `hq` extension. File size is by the default `10485760`
+ (configurable), and it is located at the journal folder.
+
+For large messages, ActiveMQ persists them outside the message journal.
+This is discussed in ?.
+
+ActiveMQ can also be configured to page messages to disk in low memory
+situations. This is discussed in ?.
+
+If no persistence is required at all, ActiveMQ can also be configured
+not to persist any data at all to storage as discussed in ?.
+
+Configuring the bindings journal
+================================
+
+The bindings journal is configured using the following attributes in
+`activemq-configuration.xml`
+
+- `bindings-directory`
+
+ This is the directory in which the bindings journal lives. The
+ default value is `data/bindings`.
+
+- `create-bindings-dir`
+
+ If this is set to `true` then the bindings directory will be
+ automatically created at the location specified in
+ `bindings-directory` if it does not already exist. The default value
+ is `true`
+
+Configuring the jms journal
+===========================
+
+The jms config shares its configuration with the bindings journal.
+
+Configuring the message journal
+===============================
+
+The message journal is configured using the following attributes in
+`activemq-configuration.xml`
+
+- `journal-directory`
+
+ This is the directory in which the message journal lives. The
+ default value is `data/journal`.
+
+ For the best performance, we recommend the journal is located on its
+ own physical volume in order to minimise disk head movement. If the
+ journal is on a volume which is shared with other processes which
+ might be writing other files (e.g. bindings journal, database, or
+ transaction coordinator) then the disk head may well be moving
+ rapidly between these files as it writes them, thus drastically
+ reducing performance.
+
+ When the message journal is stored on a SAN we recommend each
+ journal instance that is stored on the SAN is given its own LUN
+ (logical unit).
+
+- `create-journal-dir`
+
+ If this is set to `true` then the journal directory will be
+ automatically created at the location specified in
+ `journal-directory` if it does not already exist. The default value
+ is `true`
+
+- `journal-type`
+
+ Valid values are `NIO` or `ASYNCIO`.
+
+ Choosing `NIO` chooses the Java NIO journal. Choosing `AIO` chooses
+ the Linux asynchronous IO journal. If you choose `AIO` but are not
+ running Linux or you do not have libaio installed then ActiveMQ will
+ detect this and automatically fall back to using `NIO`.
+
+- `journal-sync-transactional`
+
+ If this is set to true then ActiveMQ will make sure all transaction
+ data is flushed to disk on transaction boundaries (commit, prepare
+ and rollback). The default value is `true`.
+
+- `journal-sync-non-transactional`
+
+ If this is set to true then ActiveMQ will make sure non
+ transactional message data (sends and acknowledgements) are flushed
+ to disk each time. The default value for this is `true`.
+
+- `journal-file-size`
+
+ The size of each journal file in bytes. The default value for this
+ is `10485760` bytes (10MiB).
+
+- `journal-min-files`
+
+ The minimum number of files the journal will maintain. When ActiveMQ
+ starts and there is no initial message data, ActiveMQ will
+ pre-create `journal-min-files` number of files.
+
+ Creating journal files and filling them with padding is a fairly
+ expensive operation and we want to minimise doing this at run-time
+ as files get filled. By pre-creating files, as one is filled the
+ journal can immediately resume with the next one without pausing to
+ create it.
+
+ Depending on how much data you expect your queues to contain at
+ steady state you should tune this number of files to match that
+ total amount of data.
+
+- `journal-max-io`
+
+ Write requests are queued up before being submitted to the system
+ for execution. This parameter controls the maximum number of write
+ requests that can be in the IO queue at any one time. If the queue
+ becomes full then writes will block until space is freed up.
+
+ When using NIO, this value should always be equal to `1`
+
+ When using AIO, the default should be `500`.
+
+ The system maintains different defaults for this parameter depending
+ on whether it's NIO or AIO (default for NIO is 1, default for AIO is
+ 500)
+
+ There is a limit and the total max AIO can't be higher than what is
+ configured at the OS level (/proc/sys/fs/aio-max-nr) usually at
+ 65536.
+
+- `journal-buffer-timeout`
+
+ Instead of flushing on every write that requires a flush, we
+ maintain an internal buffer, and flush the entire buffer either when
+ it is full, or when a timeout expires, whichever is sooner. This is
+ used for both NIO and AIO and allows the system to scale better with
+ many concurrent writes that require flushing.
+
+ This parameter controls the timeout at which the buffer will be
+ flushed if it hasn't filled already. AIO can typically cope with a
+ higher flush rate than NIO, so the system maintains different
+ defaults for both NIO and AIO (default for NIO is 3333333
+ nanoseconds - 300 times per second, default for AIO is 500000
+ nanoseconds - ie. 2000 times per second).
+
+ > **Note**
+ >
+ > By increasing the timeout, you may be able to increase system
+ > throughput at the expense of latency, the default parameters are
+ > chosen to give a reasonable balance between throughput and
+ > latency.
+
+- `journal-buffer-size`
+
+ The size of the timed buffer on AIO. The default value is `490KiB`.
+
+- `journal-compact-min-files`
+
+ The minimal number of files before we can consider compacting the
+ journal. The compacting algorithm won't start until you have at
+ least `journal-compact-min-files`
+
+ The default for this parameter is `10`
+
+- `journal-compact-percentage`
+
+ The threshold to start compacting. When less than this percentage is
+ considered live data, we start compacting. Note also that compacting
+ won't kick in until you have at least `journal-compact-min-files`
+ data files on the journal
+
+ The default for this parameter is `30`
+
+An important note on disabling disk write cache.
+================================================
+
+> **Warning**
+>
+> Most disks contain hardware write caches. A write cache can increase
+> the apparent performance of the disk because writes just go into the
+> cache and are then lazily written to the disk later.
+>
+> This happens irrespective of whether you have executed a fsync() from
+> the operating system or correctly synced data from inside a Java
+> program!
+>
+> By default many systems ship with disk write cache enabled. This means
+> that even after syncing from the operating system there is no
+> guarantee the data has actually made it to disk, so if a failure
+> occurs, critical data can be lost.
+>
+> Some more expensive disks have non volatile or battery backed write
+> caches which won't necessarily lose data on event of failure, but you
+> need to test them!
+>
+> If your disk does not have an expensive non volatile or battery backed
+> cache and it's not part of some kind of redundant array (e.g. RAID),
+> and you value your data integrity you need to make sure disk write
+> cache is disabled.
+>
+> Be aware that disabling disk write cache can give you a nasty shock
+> performance wise. If you've been used to using disks with write cache
+> enabled in their default setting, unaware that your data integrity
+> could be compromised, then disabling it will give you an idea of how
+> fast your disk can perform when acting really reliably.
+>
+> On Linux you can inspect and/or change your disk's write cache
+> settings using the tools `hdparm` (for IDE disks) or `sdparm` or
+> `sginfo` (for SDSI/SATA disks)
+>
+> On Windows you can check / change the setting by right clicking on the
+> disk and clicking properties.
+
+Installing AIO
+==============
+
+The Java NIO journal gives great performance, but If you are running
+ActiveMQ using Linux Kernel 2.6 or later, we highly recommend you use
+the `AIO` journal for the very best persistence performance.
+
+It's not possible to use the AIO journal under other operating systems
+or earlier versions of the Linux kernel.
+
+If you are running Linux kernel 2.6 or later and don't already have
+`libaio` installed, you can easily install it using the following steps:
+
+Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+
+ yum install libaio
+
+Using aptitude, (e.g. on Ubuntu or Debian system):
+
+ apt-get install libaio
+
+Configuring ActiveMQ for Zero Persistence
+=========================================
+
+In some situations, zero persistence is sometimes required for a
+messaging system. Configuring ActiveMQ to perform zero persistence is
+straightforward. Simply set the parameter `persistence-enabled` in
+`activemq-configuration.xml` to `false`.
+
+Please note that if you set this parameter to false, then *zero*
+persistence will occur. That means no bindings data, message data, large
+message data, duplicate id caches or paging data will be persisted.
+
+Import/Export the Journal Data
+==============================
+
+You may want to inspect the existent records on each one of the journals
+used by ActiveMQ, and you can use the export/import tool for that
+purpose. The export/import are classes located at the activemq-core.jar,
+you can export the journal as a text file by using this command:
+
+`java -cp activemq-core.jar org.apache.activemq.core.journal.impl.ExportJournal
+ <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
+ <FileOutput>`
+
+To import the file as binary data on the journal (Notice you also
+require netty.jar):
+
+`java -cp activemq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal
+ <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
+ <FileInput>`
+
+- JournalDirectory: Use the configured folder for your selected
+ folder. Example: ./activemq/data/journal
+
+- JournalPrefix: Use the prefix for your selected journal, as
+ discussed [here](#persistence.journallist)
+
+- FileExtension: Use the extension for your selected journal, as
+ discussed [here](#persistence.journallist)
+
+- FileSize: Use the size for your selected journal, as discussed
+ [here](#persistence.journallist)
+
+- FileOutput: text file that will contain the exported data
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/persistence.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/persistence.xml b/docs/user-manual/en/persistence.xml
deleted file mode 100644
index 473d4a1..0000000
--- a/docs/user-manual/en/persistence.xml
+++ /dev/null
@@ -1,356 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="persistence">
- <title>Persistence</title>
- <para>In this chapter we will describe how persistence works with ActiveMQ and how to configure
- it.</para>
- <para>ActiveMQ ships with a high performance journal. Since ActiveMQ handles its own persistence,
- rather than relying on a database or other 3rd party persistence engine it is very highly
- optimised for the specific messaging use cases.</para>
- <para>A ActiveMQ journal is an <emphasis>append only</emphasis> journal. It consists of a set of
- files on disk. Each file is pre-created to a fixed size and initially filled with padding.
- As operations are performed on the server, e.g. add message, update message, delete message,
- records are appended to the journal. When one journal file is full we move to the next
- one.</para>
- <para>Because records are only appended, i.e. added to the end of the journal we minimise disk
- head movement, i.e. we minimise random access operations which is typically the slowest
- operation on a disk.</para>
- <para>Making the file size configurable means that an optimal size can be chosen, i.e. making
- each file fit on a disk cylinder. Modern disk topologies are complex and we are not in
- control over which cylinder(s) the file is mapped onto so this is not an exact science. But
- by minimising the number of disk cylinders the file is using, we can minimise the amount of
- disk head movement, since an entire disk cylinder is accessible simply by the disk rotating
- - the head does not have to move.</para>
- <para>As delete records are added to the journal, ActiveMQ has a sophisticated file garbage
- collection algorithm which can determine if a particular journal file is needed any more -
- i.e. has all its data been deleted in the same or other files. If so, the file can be
- reclaimed and re-used. </para>
- <para>ActiveMQ also has a compaction algorithm which removes dead space from the journal and
- compresses up the data so it takes up less files on disk.</para>
- <para>The journal also fully supports transactional operation if required, supporting both local
- and XA transactions.</para>
- <para>The majority of the journal is written in Java, however we abstract out the interaction
- with the actual file system to allow different pluggable implementations. ActiveMQ ships with
- two implementations:</para>
- <itemizedlist>
- <listitem>
- <para>Java <ulink url="http://en.wikipedia.org/wiki/New_I/O">NIO</ulink>.</para>
- <para>The first implementation uses standard Java NIO to interface with the file system.
- This provides extremely good performance and runs on any platform where there's a
- Java 6+ runtime.</para>
- </listitem>
- <listitem id="aio-journal">
- <para>Linux Asynchronous IO</para>
- <para>The second implementation uses a thin native code wrapper to talk to the Linux
- asynchronous IO library (AIO). With AIO, ActiveMQ will be called back when the data
- has made it to disk, allowing us to avoid explicit syncs altogether and simply send
- back confirmation of completion when AIO informs us that the data has been
- persisted.</para>
- <para>Using AIO will typically provide even better performance than using Java
- NIO.</para>
- <para>The AIO journal is only available when running Linux kernel 2.6 or later and after
- having installed libaio (if it's not already installed). For instructions on how to
- install libaio please see <xref linkend="installing-aio"/>.</para>
- <para>Also, please note that AIO will only work with the following file systems: ext2,
- ext3, ext4, jfs, xfs. With other file systems, e.g. NFS it may appear to work, but
- it will fall back to a slower synchronous behaviour. Don't put the journal on a NFS
- share!</para>
- <para>For more information on libaio please see <xref linkend="libaio"/>.</para>
- <para>libaio is part of the kernel project.</para>
- </listitem>
- </itemizedlist>
- <para>The standard ActiveMQ core server uses two instances of the journal:</para>
- <itemizedlist id="persistence.journallist">
- <listitem>
- <para>Bindings journal.</para>
- <para>This journal is used to store bindings related data. That includes the set of
- queues that are deployed on the server and their attributes. It also stores data
- such as id sequence counters. </para>
- <para>The bindings journal is always a NIO journal as it is typically low throughput
- compared to the message journal.</para>
- <para>The files on this journal are prefixed as <literal>activemq-bindings</literal>.
- Each file has a <literal>bindings</literal> extension. File size is <literal
- >1048576</literal>, and it is located at the bindings folder.</para>
- </listitem>
- <listitem>
- <para>JMS journal.</para>
- <para>This journal instance stores all JMS related data, This is basically any JMS
- Queues, Topics and Connection Factories and any JNDI bindings for these
- resources.</para>
- <para>Any JMS Resources created via the management API will be persisted to this
- journal. Any resources configured via configuration files will not. The JMS Journal
- will only be created if JMS is being used.</para>
- <para>The files on this journal are prefixed as <literal>activemq-jms</literal>. Each
- file has a <literal>jms</literal> extension. File size is <literal
- >1048576</literal>, and it is located at the bindings folder.</para>
- </listitem>
- <listitem>
- <para>Message journal.</para>
- <para>This journal instance stores all message related data, including the message
- themselves and also duplicate-id caches.</para>
- <para>By default ActiveMQ will try and use an AIO journal. If AIO is not available, e.g.
- the platform is not Linux with the correct kernel version or AIO has not been
- installed then it will automatically fall back to using Java NIO which is available
- on any Java platform.</para>
- <para>The files on this journal are prefixed as <literal>activemq-data</literal>. Each
- file has a <literal>hq</literal> extension. File size is by the default <literal
- >10485760</literal> (configurable), and it is located at the journal
- folder.</para>
- </listitem>
- </itemizedlist>
- <para>For large messages, ActiveMQ persists them outside the message journal. This is discussed
- in <xref linkend="large-messages"/>.</para>
- <para>ActiveMQ can also be configured to page messages to disk in low memory situations. This is
- discussed in <xref linkend="paging"/>.</para>
- <para>If no persistence is required at all, ActiveMQ can also be configured not to persist any
- data at all to storage as discussed in <xref linkend="persistence.enabled"/>.</para>
- <section id="configuring.bindings.journal">
- <title>Configuring the bindings journal</title>
- <para>The bindings journal is configured using the following attributes in <literal
- >activemq-configuration.xml</literal></para>
- <itemizedlist>
- <listitem>
- <para><literal>bindings-directory</literal></para>
- <para>This is the directory in which the bindings journal lives. The default value
- is <literal>data/bindings</literal>.</para>
- </listitem>
- <listitem>
- <para><literal>create-bindings-dir</literal></para>
- <para>If this is set to <literal>true</literal> then the bindings directory will be
- automatically created at the location specified in <literal
- >bindings-directory</literal> if it does not already exist. The default
- value is <literal>true</literal></para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="configuring.bindings.jms">
- <title>Configuring the jms journal</title>
- <para>The jms config shares its configuration with the bindings journal.</para>
- </section>
- <section id="configuring.message.journal">
- <title>Configuring the message journal</title>
- <para>The message journal is configured using the following attributes in <literal
- >activemq-configuration.xml</literal></para>
- <itemizedlist>
- <listitem id="configuring.message.journal.journal-directory">
- <para><literal>journal-directory</literal></para>
- <para>This is the directory in which the message journal lives. The default value is
- <literal>data/journal</literal>.</para>
- <para>For the best performance, we recommend the journal is located on its own
- physical volume in order to minimise disk head movement. If the journal is on a
- volume which is shared with other processes which might be writing other files
- (e.g. bindings journal, database, or transaction coordinator) then the disk head
- may well be moving rapidly between these files as it writes them, thus
- drastically reducing performance.</para>
- <para>When the message journal is stored on a SAN we recommend each journal instance
- that is stored on the SAN is given its own LUN (logical unit).</para>
- </listitem>
- <listitem id="configuring.message.journal.create-journal-dir">
- <para><literal>create-journal-dir</literal></para>
- <para>If this is set to <literal>true</literal> then the journal directory will be
- automatically created at the location specified in <literal
- >journal-directory</literal> if it does not already exist. The default value
- is <literal>true</literal></para>
- </listitem>
- <listitem id="configuring.message.journal.journal-type">
- <para><literal>journal-type</literal></para>
- <para>Valid values are <literal>NIO</literal> or <literal>ASYNCIO</literal>.</para>
- <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
- <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
- choose <literal>AIO</literal> but are not running Linux or you do not have
- libaio installed then ActiveMQ will detect this and automatically fall back to
- using <literal>NIO</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-sync-transactional">
- <para><literal>journal-sync-transactional</literal></para>
- <para>If this is set to true then ActiveMQ will make sure all transaction data is
- flushed to disk on transaction boundaries (commit, prepare and rollback). The
- default value is <literal>true</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-sync-non-transactional">
- <para><literal>journal-sync-non-transactional</literal></para>
- <para>If this is set to true then ActiveMQ will make sure non transactional message
- data (sends and acknowledgements) are flushed to disk each time. The default
- value for this is <literal>true</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-file-size">
- <para><literal>journal-file-size</literal></para>
- <para>The size of each journal file in bytes. The default value for this is <literal
- >10485760</literal> bytes (10MiB).</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-min-files">
- <para><literal>journal-min-files</literal></para>
- <para>The minimum number of files the journal will maintain. When ActiveMQ starts and
- there is no initial message data, ActiveMQ will pre-create <literal
- >journal-min-files</literal> number of files.</para>
- <para>Creating journal files and filling them with padding is a fairly expensive
- operation and we want to minimise doing this at run-time as files get filled. By
- pre-creating files, as one is filled the journal can immediately resume with the
- next one without pausing to create it.</para>
- <para>Depending on how much data you expect your queues to contain at steady state
- you should tune this number of files to match that total amount of data.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-max-io">
- <para><literal>journal-max-io</literal></para>
- <para>Write requests are queued up before being submitted to the system for
- execution. This parameter controls the maximum number of write requests that can
- be in the IO queue at any one time. If the queue becomes full then writes will
- block until space is freed up. </para>
- <para>When using NIO, this value should always be equal to <literal
- >1</literal></para>
- <para>When using AIO, the default should be <literal>500</literal>.</para>
- <para>The system maintains different defaults for this parameter depending on whether
- it's NIO or AIO (default for NIO is 1, default for AIO is 500)</para>
- <para>There is a limit and the total max AIO can't be higher than what is configured
- at the OS level (/proc/sys/fs/aio-max-nr) usually at 65536.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-buffer-timeout">
- <para><literal>journal-buffer-timeout</literal></para>
- <para>Instead of flushing on every write that requires a flush, we maintain an
- internal buffer, and flush the entire buffer either when it is full, or when a
- timeout expires, whichever is sooner. This is used for both NIO and AIO and
- allows the system to scale better with many concurrent writes that require
- flushing.</para>
- <para>This parameter controls the timeout at which the buffer will be flushed if it
- hasn't filled already. AIO can typically cope with a higher flush rate than NIO,
- so the system maintains different defaults for both NIO and AIO (default for NIO
- is 3333333 nanoseconds - 300 times per second, default for AIO is 500000
- nanoseconds - ie. 2000 times per second).</para>
- <note>
- <para>By increasing the timeout, you may be able to increase system throughput
- at the expense of latency, the default parameters are chosen to give a
- reasonable balance between throughput and latency.</para>
- </note>
- </listitem>
- <listitem id="configuring.message.journal.journal-buffer-size">
- <para><literal>journal-buffer-size</literal></para>
- <para>The size of the timed buffer on AIO. The default value is <literal
- >490KiB</literal>.</para>
- </listitem>
- <listitem id="configuring.message.journal.journal-compact-min-files">
- <para><literal>journal-compact-min-files</literal></para>
- <para>The minimal number of files before we can consider compacting the journal. The
- compacting algorithm won't start until you have at least <literal
- >journal-compact-min-files</literal></para>
- <para>The default for this parameter is <literal>10</literal></para>
- </listitem>
- <listitem id="configuring.message.journal.journal-compact-percentage">
- <para><literal>journal-compact-percentage</literal></para>
- <para>The threshold to start compacting. When less than this percentage is
- considered live data, we start compacting. Note also that compacting won't kick
- in until you have at least <literal>journal-compact-min-files</literal> data
- files on the journal</para>
- <para>The default for this parameter is <literal>30</literal></para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="disk-write-cache">
- <title>An important note on disabling disk write cache.</title>
- <warning>
- <para>Most disks contain hardware write caches. A write cache can increase the apparent
- performance of the disk because writes just go into the cache and are then lazily
- written to the disk later. </para>
- <para>This happens irrespective of whether you have executed a fsync() from the
- operating system or correctly synced data from inside a Java program!</para>
- <para>By default many systems ship with disk write cache enabled. This means that even
- after syncing from the operating system there is no guarantee the data has actually
- made it to disk, so if a failure occurs, critical data can be lost.</para>
- <para>Some more expensive disks have non volatile or battery backed write caches which
- won't necessarily lose data on event of failure, but you need to test them!</para>
- <para>If your disk does not have an expensive non volatile or battery backed cache and
- it's not part of some kind of redundant array (e.g. RAID), and you value your data
- integrity you need to make sure disk write cache is disabled.</para>
- <para>Be aware that disabling disk write cache can give you a nasty shock performance
- wise. If you've been used to using disks with write cache enabled in their default
- setting, unaware that your data integrity could be compromised, then disabling it
- will give you an idea of how fast your disk can perform when acting really
- reliably.</para>
- <para>On Linux you can inspect and/or change your disk's write cache settings using the
- tools <literal>hdparm</literal> (for IDE disks) or <literal>sdparm</literal> or
- <literal>sginfo</literal> (for SDSI/SATA disks)</para>
- <para>On Windows you can check / change the setting by right clicking on the disk and
- clicking properties.</para>
- </warning>
- </section>
- <section id="installing-aio">
- <title>Installing AIO</title>
- <para>The Java NIO journal gives great performance, but If you are running ActiveMQ using
- Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
- journal for the very best persistence performance.</para>
- <para>It's not possible to use the AIO journal under other operating systems or earlier
- versions of the Linux kernel.</para>
- <para>If you are running Linux kernel 2.6 or later and don't already have <literal
- >libaio</literal> installed, you can easily install it using the following
- steps:</para>
- <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
- <programlisting>yum install libaio</programlisting></para>
- <para>Using aptitude, (e.g. on Ubuntu or Debian system):
- <programlisting>apt-get install libaio</programlisting></para>
- </section>
- <section id="persistence.enabled">
- <title>Configuring ActiveMQ for Zero Persistence</title>
- <para>In some situations, zero persistence is sometimes required for a messaging system.
- Configuring ActiveMQ to perform zero persistence is straightforward. Simply set the
- parameter <literal>persistence-enabled</literal> in <literal
- >activemq-configuration.xml</literal> to <literal>false</literal>. </para>
- <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
- persistence will occur. That means no bindings data, message data, large message data,
- duplicate id caches or paging data will be persisted.</para>
- </section>
- <section id="persistence.importexport">
- <title>Import/Export the Journal Data</title>
- <para>You may want to inspect the existent records on each one of the journals used by
- ActiveMQ, and you can use the export/import tool for that purpose. The export/import are
- classes located at the activemq-core.jar, you can export the journal as a text file by
- using this command:</para>
- <para><literal>java -cp activemq-core.jar org.apache.activemq.core.journal.impl.ExportJournal
- <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
- <FileOutput></literal></para>
- <para>To import the file as binary data on the journal (Notice you also require
- netty.jar):</para>
- <para><literal>java -cp activemq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal
- <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize>
- <FileInput></literal></para>
- <itemizedlist>
- <listitem>
- <para>JournalDirectory: Use the configured folder for your selected folder. Example:
- ./activemq/data/journal</para>
- </listitem>
- <listitem>
- <para>JournalPrefix: Use the prefix for your selected journal, as discussed
- <link linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileExtension: Use the extension for your selected journal, as discussed
- <link linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileSize: Use the size for your selected journal, as discussed <link
- linkend="persistence.journallist">here</link></para>
- </listitem>
- <listitem>
- <para>FileOutput: text file that will contain the exported data</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/pre-acknowledge.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/pre-acknowledge.md b/docs/user-manual/en/pre-acknowledge.md
new file mode 100644
index 0000000..1bec75e
--- /dev/null
+++ b/docs/user-manual/en/pre-acknowledge.md
@@ -0,0 +1,92 @@
+Extra Acknowledge Modes
+=======================
+
+JMS specifies 3 acknowledgement modes:
+
+- `AUTO_ACKNOWLEDGE`
+
+- `CLIENT_ACKNOWLEDGE`
+
+- `DUPS_OK_ACKNOWLEDGE`
+
+ActiveMQ supports two additional modes: `PRE_ACKNOWLEDGE` and
+`INDIVIDUAL_ACKNOWLEDGE`
+
+In some cases you can afford to lose messages in event of failure, so it
+would make sense to acknowledge the message on the server *before*
+delivering it to the client.
+
+This extra mode is supported by ActiveMQ and will call it
+*pre-acknowledge* mode.
+
+The disadvantage of acknowledging on the server before delivery is that
+the message will be lost if the system crashes *after* acknowledging the
+message on the server but *before* it is delivered to the client. In
+that case, the message is lost and will not be recovered when the system
+restart.
+
+Depending on your messaging case, `pre-acknowledgement` mode can avoid
+extra network traffic and CPU at the cost of coping with message loss.
+
+An example of a use case for pre-acknowledgement is for stock price
+update messages. With these messages it might be reasonable to lose a
+message in event of crash, since the next price update message will
+arrive soon, overriding the previous price.
+
+> **Note**
+>
+> Please note, that if you use pre-acknowledge mode, then you will lose
+> transactional semantics for messages being consumed, since clearly
+> they are being acknowledged first on the server, not when you commit
+> the transaction. This may be stating the obvious but we like to be
+> clear on these things to avoid confusion!
+
+Using PRE\_ACKNOWLEDGE
+======================
+
+This can be configured in a client's JNDI context environment, e.g.
+`jndi.properties`, like this:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.preAcknowledge=true
+
+Alternatively, to use pre-acknowledgement mode using the JMS API, create
+a JMS Session with the `ActiveMQSession.PRE_ACKNOWLEDGE` constant.
+
+ // messages will be acknowledge on the server *before* being delivered to the client
+ Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);
+
+Or you can set pre-acknowledge directly on the
+`ActiveMQConnectionFactory` instance using the setter method.
+
+To use pre-acknowledgement mode using the core API you can set it
+directly on the `ClientSessionFactory` instance using the setter method.
+
+Individual Acknowledge
+======================
+
+A valid use-case for individual acknowledgement would be when you need
+to have your own scheduling and you don't know when your message
+processing will be finished. You should prefer having one consumer per
+thread worker but this is not possible in some circumstances depending
+on how complex is your processing. For that you can use the individual
+Acknowledgement.
+
+You basically setup Individual ACK by creating a session with the
+acknowledge mode with `ActiveMQJMSConstants.INDIVIDUAL_ACKNOWLEDGE`.
+Individual ACK inherits all the semantics from Client Acknowledge, with
+the exception the message is individually acked.
+
+> **Note**
+>
+> Please note, that to avoid confusion on MDB processing, Individual
+> ACKNOWLEDGE is not supported through MDBs (or the inbound resource
+> adapter). this is because you have to finish the process of your
+> message inside the MDB.
+
+Example
+=======
+
+See ? for an example which shows how to use pre-acknowledgement mode
+with JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/pre-acknowledge.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/pre-acknowledge.xml b/docs/user-manual/en/pre-acknowledge.xml
deleted file mode 100644
index d8eec48..0000000
--- a/docs/user-manual/en/pre-acknowledge.xml
+++ /dev/null
@@ -1,92 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
- %BOOK_ENTITIES;
- ]>
-<chapter id="pre-acknowledge">
- <title>Extra Acknowledge Modes</title>
- <para>JMS specifies 3 acknowledgement modes:</para>
- <itemizedlist>
- <listitem>
- <para><literal>AUTO_ACKNOWLEDGE</literal></para>
- </listitem>
- <listitem>
- <para><literal>CLIENT_ACKNOWLEDGE</literal></para>
- </listitem>
- <listitem>
- <para><literal>DUPS_OK_ACKNOWLEDGE</literal></para>
- </listitem>
- </itemizedlist>
- <para>ActiveMQ supports two additional modes: <literal>PRE_ACKNOWLEDGE</literal> and <literal>INDIVIDUAL_ACKNOWLEDGE</literal></para>
- <para>In some cases you can afford
- to lose messages in event of failure, so it would make sense to acknowledge the message on the
- server <emphasis>before</emphasis> delivering it to the client.</para>
- <para>This extra mode is supported by ActiveMQ and will call it
- <emphasis>pre-acknowledge</emphasis> mode.</para>
- <para>The disadvantage of acknowledging on the server before delivery is that the message will be
- lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server
- but <emphasis>before</emphasis> it is delivered to the client. In that case, the message is
- lost and will not be recovered when the system restart.</para>
- <para>Depending on your messaging case, <literal>pre-acknowledgement</literal> mode can avoid
- extra network traffic and CPU at the cost of coping with message loss.</para>
- <para>An example of a use case for pre-acknowledgement is for stock price update messages. With
- these messages it might be reasonable to lose a message in event of crash, since the next
- price update message will arrive soon, overriding the previous price. </para>
- <note>
- <para>Please note, that if you use pre-acknowledge mode, then you will lose transactional
- semantics for messages being consumed, since clearly they are being acknowledged first on
- the server, not when you commit the transaction. This may be stating the obvious but we
- like to be clear on these things to avoid confusion!</para>
- </note>
- <section id="pre-acknowledge.configure">
- <title>Using PRE_ACKNOWLEDGE</title>
- <para>This can be configured in a client's JNDI context environment, e.g. <literal>jndi.properties</literal>,
- like this:</para>
- <programlisting>
-java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
-java.naming.provider.url=tcp://localhost:5445
-connection.ConnectionFactory.preAcknowledge=true</programlisting>
- <para>Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session
- with the <literal>ActiveMQSession.PRE_ACKNOWLEDGE</literal> constant.</para>
- <programlisting>
-// messages will be acknowledge on the server *before* being delivered to the client
-Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);</programlisting>
- <para>Or you can set pre-acknowledge directly on the <literal
- >ActiveMQConnectionFactory</literal> instance using the setter method.</para>
- <para>To use pre-acknowledgement mode using the core API you can set it directly on the
- <literal>ClientSessionFactory</literal> instance using the setter method.</para>
- </section>
- <section id="individual-ack">
- <title>Individual Acknowledge</title>
- <para>A valid use-case for individual acknowledgement would be when you need to have your own scheduling and you don't know when your message processing will be finished. You should prefer having one consumer per thread worker
- but this is not possible in some circumstances depending on how complex is your processing. For that you can use the individual Acknowledgement. </para>
- <para>You basically setup Individual ACK by creating a session with the acknowledge mode with <literal>ActiveMQJMSConstants.INDIVIDUAL_ACKNOWLEDGE</literal>. Individual ACK inherits all the semantics from Client Acknowledge,
- with the exception the message is individually acked.</para>
- <note>
- <para>Please note, that to avoid confusion on MDB processing, Individual ACKNOWLEDGE is not supported through MDBs (or the inbound resource adapter). this is because you have to finish the process of your message inside the MDB.
- </para>
- </note>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.pre-acknowledge"/> for an example which shows how to use
- pre-acknowledgement mode with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/preface.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/preface.md b/docs/user-manual/en/preface.md
new file mode 100644
index 0000000..8cc9717
--- /dev/null
+++ b/docs/user-manual/en/preface.md
@@ -0,0 +1,52 @@
+Preface
+=======
+
+What is ActiveMQ?
+
+- ActiveMQ is an open source project to build a multi-protocol,
+ embeddable, very high performance, clustered, asynchronous messaging
+ system.
+
+- ActiveMQ is an example of Message Oriented Middleware (MoM). For a
+ description of MoMs and other messaging concepts please see the ?.
+
+- For answers to more questions about what ActiveMQ is and what it
+ isn't please visit the [FAQs wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs).
+
+Why use ActiveMQ? Here are just a few of the reasons:
+
+- 100% open source software. ActiveMQ is licensed using the Apache
+ Software License v 2.0 to minimise barriers to adoption.
+
+- ActiveMQ is designed with usability in mind.
+
+- Written in Java. Runs on any platform with a Java 6+ runtime, that's
+ everything from Windows desktops to IBM mainframes.
+
+- Amazing performance. Our ground-breaking high performance journal
+ provides persistent messaging performance at rates normally seen for
+ non-persistent messaging, our non-persistent messaging performance
+ rocks the boat too.
+
+- Full feature set. All the features you'd expect in any serious
+ messaging system, and others you won't find anywhere else.
+
+- Elegant, clean-cut design with minimal third party dependencies. Run
+ ActiveMQ stand-alone, run it in integrated in your favourite JEE
+ application server, or run it embedded inside your own product. It's
+ up to you.
+
+- Seamless high availability. We provide a HA solution with automatic
+ client failover so you can guarantee zero message loss or
+ duplication in event of server failure.
+
+- Hugely flexible clustering. Create clusters of servers that know how
+ to load balance messages. Link geographically distributed clusters
+ over unreliable connections to form a global network. Configure
+ routing of messages in a highly flexible way.
+
+- For a full list of features, please see the [features wiki
+ page](http://www.jboss.org/community/wiki/ActiveMQFeatures) .
+
+
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/preface.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/preface.xml b/docs/user-manual/en/preface.xml
deleted file mode 100644
index 427f5a0..0000000
--- a/docs/user-manual/en/preface.xml
+++ /dev/null
@@ -1,86 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="preface">
- <title>Preface</title>
- <para>What is ActiveMQ?</para>
- <itemizedlist>
- <listitem>
- <para>ActiveMQ is an open source project to build a multi-protocol, embeddable, very high
- performance, clustered, asynchronous messaging system.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ is an example of Message Oriented Middleware (MoM). For a description of
- MoMs and other messaging concepts please see the <xref linkend="messaging-concepts"
- />.</para>
- </listitem>
- <listitem>
- <para>For answers to more questions about what ActiveMQ is and what it isn't please visit
- the <ulink url="http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs">FAQs wiki
- page</ulink>.</para>
- </listitem>
- </itemizedlist>
- <para>Why use ActiveMQ? Here are just a few of the reasons:</para>
- <itemizedlist>
- <listitem>
- <para>100% open source software. ActiveMQ is licensed using the Apache Software License v
- 2.0 to minimise barriers to adoption.</para>
- </listitem>
- <listitem>
- <para>ActiveMQ is designed with usability in mind.</para>
- </listitem>
- <listitem>
- <para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything
- from Windows desktops to IBM mainframes.</para>
- </listitem>
- <listitem>
- <para>Amazing performance. Our ground-breaking high performance journal provides
- persistent messaging performance at rates normally seen for non-persistent
- messaging, our non-persistent messaging performance rocks the boat too.</para>
- </listitem>
- <listitem>
- <para>Full feature set. All the features you'd expect in any serious messaging system,
- and others you won't find anywhere else.</para>
- </listitem>
- <listitem>
- <para>Elegant, clean-cut design with minimal third party dependencies. Run ActiveMQ
- stand-alone, run it in integrated in your favourite JEE application server, or run
- it embedded inside your own product. It's up to you.</para>
- </listitem>
- <listitem>
- <para>Seamless high availability. We provide a HA solution with automatic client
- failover so you can guarantee zero message loss or duplication in event of server
- failure.</para>
- </listitem>
- <listitem>
- <para>Hugely flexible clustering. Create clusters of servers that know how to load
- balance messages. Link geographically distributed clusters over unreliable
- connections to form a global network. Configure routing of messages in a highly
- flexible way.</para>
- </listitem>
- <listitem>
- <para>For a full list of features, please see the <ulink
- url="http://www.jboss.org/community/wiki/ActiveMQFeatures">features wiki
- page</ulink> .</para>
- </listitem>
- </itemizedlist>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/project-info.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/project-info.md b/docs/user-manual/en/project-info.md
new file mode 100644
index 0000000..2465981
--- /dev/null
+++ b/docs/user-manual/en/project-info.md
@@ -0,0 +1,50 @@
+Project Information
+===================
+
+The official ActiveMQ project page is <http://activemq.org/>.
+
+Software Download
+=================
+
+The software can be download from the Download
+page:<http://activemq.org/downloads.html>
+
+Project Information
+===================
+
+- Please take a look at our project
+ [wiki](http://www.jboss.org/community/wiki/ActiveMQ)
+
+- If you have any user questions please use our [user
+ forum](https://community.jboss.org/en/activemq)
+
+- If you have development related questions, please use our [developer
+ forum](https://community.jboss.org/en/activemq/dev)
+
+- Pop in and chat to us in our [IRC
+ channel](irc://irc.freenode.net:6667/activemq)
+
+- Our project [blog](http://activemq.blogspot.com/)
+
+- Follow us on [twitter](http://twitter.com/activemq)
+
+- ActiveMQ Git repository is <https://github.com/activemq/activemq>
+
+- All release tags are available from
+ <https://github.com/activemq/activemq/tags>
+
+Red Hat kindly employs developers to work full time on ActiveMQ, they
+are:
+
+- Clebert Suconic (project lead)
+
+- Andy Taylor
+
+- Howard Gao
+
+- Justin Bertram
+
+And many thanks to all our contributors, both old and new who helped
+create ActiveMQ, for a full list of the people who made it happen, take
+a look at our [team
+page](http://jboss.org.apache.activemq/community/team.html).