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:35 UTC
[04/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/scheduled-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/scheduled-messages.md b/docs/user-manual/en/scheduled-messages.md
new file mode 100644
index 0000000..e8f4cad
--- /dev/null
+++ b/docs/user-manual/en/scheduled-messages.md
@@ -0,0 +1,36 @@
+Scheduled Messages
+==================
+
+Scheduled messages differ from normal messages in that they won't be
+delivered until a specified time in the future, at the earliest.
+
+To do this, a special property is set on the message before sending it.
+
+Scheduled Delivery Property
+===========================
+
+The property name used to identify a scheduled message is
+`"_HQ_SCHED_DELIVERY"` (or the constant
+`Message.HDR_SCHEDULED_DELIVERY_TIME`).
+
+The specified value must be a positive `long` corresponding to the time
+the message must be delivered (in milliseconds). An example of sending a
+scheduled message using the JMS API is as follows.
+
+ TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
+ message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
+ producer.send(message);
+
+ ...
+
+ // message will not be received immediately but 5 seconds later
+ TextMessage messageReceived = (TextMessage) consumer.receive();
+
+Scheduled messages can also be sent using the core API, by setting the
+same property on the core message before sending.
+
+Example
+=======
+
+See ? for an example which shows how scheduled messages can be used with
+JMS.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/scheduled-messages.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/scheduled-messages.xml b/docs/user-manual/en/scheduled-messages.xml
deleted file mode 100644
index 6277e9a..0000000
--- a/docs/user-manual/en/scheduled-messages.xml
+++ /dev/null
@@ -1,53 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="scheduled-messages">
- <title>Scheduled Messages</title>
- <para>Scheduled messages differ from normal messages in that they won't be delivered until a
- specified time in the future, at the earliest.</para>
- <para>To do this, a special property is set on the message before sending it.</para>
- <section>
- <title>Scheduled Delivery Property</title>
- <para>The property name used to identify a scheduled message is <literal
- >"_HQ_SCHED_DELIVERY"</literal> (or the constant <literal
- >Message.HDR_SCHEDULED_DELIVERY_TIME</literal>).</para>
- <para>The specified value must be a positive <literal>long</literal> corresponding to the time the
- message must be delivered (in milliseconds). An example of sending a scheduled message
- using the JMS API is as follows.</para>
- <programlisting>
-TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
-message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
-producer.send(message);
-
-...
-
-// message will not be received immediately but 5 seconds later
-TextMessage messageReceived = (TextMessage) consumer.receive();</programlisting>
- <para>Scheduled messages can also be sent using the core API, by setting the same property on
- the core message before sending.</para>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.scheduled-message"/> for an example which shows how
- scheduled messages can be used with JMS.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/security.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
new file mode 100644
index 0000000..6871334
--- /dev/null
+++ b/docs/user-manual/en/security.md
@@ -0,0 +1,306 @@
+Security
+========
+
+This chapter describes how security works with ActiveMQ and how you can
+configure it. To disable security completely simply set the
+`security-enabled` property to false in the `activemq-configuration.xml`
+file.
+
+For performance reasons security is cached and invalidated every so
+long. To change this period set the property
+`security-invalidation-interval`, which is in milliseconds. The default
+is `10000` ms.
+
+Role based security for addresses
+=================================
+
+ActiveMQ contains a flexible role-based security model for applying
+security to queues, based on their addresses.
+
+As explained in ?, ActiveMQ core consists mainly of sets of queues bound
+to addresses. A message is sent to an address and the server looks up
+the set of queues that are bound to that address, the server then routes
+the message to those set of queues.
+
+ActiveMQ allows sets of permissions to be defined against the queues
+based on their address. An exact match on the address can be used or a
+wildcard match can be used using the wildcard characters '`#`' and
+'`*`'.
+
+Seven different permissions can be given to the set of queues which
+match the address. Those permissions are:
+
+- `createDurableQueue`. This permission allows the user to create a
+ durable queue under matching addresses.
+
+- `deleteDurableQueue`. This permission allows the user to delete a
+ durable queue under matching addresses.
+
+- `createNonDurableQueue`. This permission allows the user to create a
+ non-durable queue under matching addresses.
+
+- `deleteNonDurableQueue`. This permission allows the user to delete a
+ non-durable queue under matching addresses.
+
+- `send`. This permission allows the user to send a message to
+ matching addresses.
+
+- `consume`. This permission allows the user to consume a message from
+ a queue bound to matching addresses.
+
+- `manage`. This permission allows the user to invoke management
+ operations by sending management messages to the management address.
+
+For each permission, a list of roles who are granted that permission is
+specified. If the user has any of those roles, he/she will be granted
+that permission for that set of addresses.
+
+Let's take a simple example, here's a security block from
+`activemq-configuration.xml` or `activemq-queues.xml` file:
+
+ <security-setting match="globalqueues.europe.#">
+ <permission type="createDurableQueue" roles="admin"/>
+ <permission type="deleteDurableQueue" roles="admin"/>
+ <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
+ <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
+ <permission type="send" roles="admin, europe-users"/>
+ <permission type="consume" roles="admin, europe-users"/>
+ </security-setting>
+
+The '`#`' character signifies "any sequence of words". Words are
+delimited by the '`.`' character. For a full description of the wildcard
+syntax please see ?. The above security block applies to any address
+that starts with the string "globalqueues.europe.":
+
+Only users who have the `admin` role can create or delete durable queues
+bound to an address that starts with the string "globalqueues.europe."
+
+Any users with the roles `admin`, `guest`, or `europe-users` can create
+or delete temporary queues bound to an address that starts with the
+string "globalqueues.europe."
+
+Any users with the roles `admin` or `europe-users` can send messages to
+these addresses or consume messages from queues bound to an address that
+starts with the string "globalqueues.europe."
+
+The mapping between a user and what roles they have is handled by the
+security manager. ActiveMQ ships with a user manager that reads user
+credentials from a file on disk, and can also plug into JAAS or JBoss
+Application Server security.
+
+For more information on configuring the security manager, please see ?.
+
+There can be zero or more `security-setting` elements in each xml file.
+Where more than one match applies to a set of addresses the *more
+specific* match takes precedence.
+
+Let's look at an example of that, here's another `security-setting`
+block:
+
+ <security-setting match="globalqueues.europe.orders.#">
+ <permission type="send" roles="europe-users"/>
+ <permission type="consume" roles="europe-users"/>
+ </security-setting>
+
+In this `security-setting` block the match
+'globalqueues.europe.orders.\#' is more specific than the previous match
+'globalqueues.europe.\#'. So any addresses which match
+'globalqueues.europe.orders.\#' will take their security settings *only*
+from the latter security-setting block.
+
+Note that settings are not inherited from the former block. All the
+settings will be taken from the more specific matching block, so for the
+address 'globalqueues.europe.orders.plastics' the only permissions that
+exist are `send` and `consume` for the role europe-users. The
+permissions `createDurableQueue`, `deleteDurableQueue`,
+`createNonDurableQueue`, `deleteNonDurableQueue` are not inherited from
+the other security-setting block.
+
+By not inheriting permissions, it allows you to effectively deny
+permissions in more specific security-setting blocks by simply not
+specifying them. Otherwise it would not be possible to deny permissions
+in sub-groups of addresses.
+
+Secure Sockets Layer (SSL) Transport
+====================================
+
+When messaging clients are connected to servers, or servers are
+connected to other servers (e.g. via bridges) over an untrusted network
+then ActiveMQ allows that traffic to be encrypted using the Secure
+Sockets Layer (SSL) transport.
+
+For more information on configuring the SSL transport, please see ?.
+
+Basic user credentials
+======================
+
+ActiveMQ ships with a security manager implementation that reads user
+credentials, i.e. user names, passwords and role information from an xml
+file on the classpath called `activemq-users.xml`. This is the default
+security manager.
+
+If you wish to use this security manager, then users, passwords and
+roles can easily be added into this file.
+
+Let's take a look at an example file:
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
+
+ <defaultuser name="guest" password="guest">
+ <role name="guest"/>
+ </defaultuser>
+
+ <user name="tim" password="marmite">
+ <role name="admin"/>
+ </user>
+
+ <user name="andy" password="doner_kebab">
+ <role name="admin"/>
+ <role name="guest"/>
+ </user>
+
+ <user name="jeff" password="camembert">
+ <role name="europe-users"/>
+ <role name="guest"/>
+ </user>
+
+ </configuration>
+
+The first thing to note is the element `defaultuser`. This defines what
+user will be assumed when the client does not specify a
+username/password when creating a session. In this case they will be the
+user `guest` and have the role also called `guest`. Multiple roles can
+be specified for a default user.
+
+We then have three more users, the user `tim` has the role `admin`. The
+user `andy` has the roles `admin` and `guest`, and the user `jeff` has
+the roles `europe-users` and `guest`.
+
+Changing the security manager
+=============================
+
+If you do not want to use the default security manager then you can
+specify a different one by editing the file `activemq-beans.xml` (or
+`activemq-jboss-beans.xml` if you're running JBoss Application Server)
+and changing the class for the `ActiveMQSecurityManager` bean.
+
+Let's take a look at a snippet from the default beans file:
+
+
+ <bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ </bean>
+
+The class
+`org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl` is
+the default security manager that is used by the standalone server.
+
+ActiveMQ ships with two other security manager implementations you can
+use off-the-shelf; one a JAAS security manager and another for
+integrating with JBoss Application Sever security, alternatively you
+could write your own implementation by implementing the
+`org.apache.activemq.spi.core.security.ActiveMQSecurityManager`
+interface, and specifying the classname of your implementation in the
+file `activemq-beans.xml` (or `activemq-jboss-beans.xml` if you're
+running JBoss Application Server).
+
+These two implementations are discussed in the next two sections.
+
+JAAS Security Manager
+=====================
+
+JAAS stands for 'Java Authentication and Authorization Service' and is a
+standard part of the Java platform. It provides a common API for
+security authentication and authorization, allowing you to plugin your
+pre-built implementations.
+
+To configure the JAAS security manager to work with your pre-built JAAS
+infrastructure you need to specify the security manager as a
+`JAASSecurityManager` in the beans file. Here's an example:
+
+ <bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+
+ <property name="ConfigurationName">org.apache.activemq.jms.example.ExampleLoginModule</property>
+ <property name="Configuration">
+ <inject bean="ExampleConfiguration"/>
+ </property>
+ <property name="CallbackHandler">
+ <inject bean="ExampleCallbackHandler"/>
+ </property>
+ </bean>
+
+Note that you need to feed the JAAS security manager with three
+properties:
+
+- ConfigurationName: the name of the `LoginModule` implementation that
+ JAAS must use
+
+- Configuration: the `Configuration` implementation used by JAAS
+
+- CallbackHandler: the `CallbackHandler` implementation to use if user
+ interaction are required
+
+Example
+-------
+
+See ? for an example which shows how ActiveMQ can be configured to use
+JAAS.
+
+JBoss AS Security Manager
+=========================
+
+The JBoss AS security manager is used when running ActiveMQ inside the
+JBoss Application server. This allows tight integration with the JBoss
+Application Server's security model.
+
+The class name of this security manager is
+`org.apache.activemq.integration.jboss.security.JBossASSecurityManager`
+
+Take a look at one of the default `activemq-jboss-beans.xml` files for
+JBoss Application Server that are bundled in the distribution for an
+example of how this is configured.
+
+Configuring Client Login
+------------------------
+
+JBoss can be configured to allow client login, basically this is when a
+JEE component such as a Servlet or EJB sets security credentials on the
+current security context and these are used throughout the call. If you
+would like these credentials to be used by ActiveMQ when sending or
+consuming messages then set `allowClientLogin` to true. This will bypass
+ActiveMQ authentication and propagate the provided Security Context. If
+you would like ActiveMQ to authenticate using the propagated security
+then set the `authoriseOnClientLogin` to true also.
+
+There is more info on using the JBoss client login module
+[here](http://community.jboss.org/wiki/ClientLoginModule)
+
+> **Note**
+>
+> If messages are sent non blocking then there is a chance that these
+> could arrive on the server after the calling thread has completed
+> meaning that the security context has been cleared. If this is the
+> case then messages will need to be sent blocking
+
+Changing the Security Domain
+----------------------------
+
+The name of the security domain used by the JBoss AS security manager
+defaults to `java:/jaas/activemq
+ `. This can be changed by specifying `securityDomainName`
+(e.g. java:/jaas/myDomain).
+
+Changing the username/password for clustering
+=============================================
+
+In order for cluster connections to work correctly, each node in the
+cluster must make connections to the other nodes. The username/password
+they use for this should always be changed from the installation default
+to prevent a security risk.
+
+Please see ? for instructions on how to do this.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/security.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/security.xml b/docs/user-manual/en/security.xml
deleted file mode 100644
index 1c287b1..0000000
--- a/docs/user-manual/en/security.xml
+++ /dev/null
@@ -1,287 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="security">
- <title>Security</title>
- <para>This chapter describes how security works with ActiveMQ and how you can configure it. To
- disable security completely simply set the <literal>security-enabled</literal> property to
- false in the <literal>activemq-configuration.xml</literal> file.</para>
- <para>For performance reasons security is cached and invalidated every so long. To change this
- period set the property <literal>security-invalidation-interval</literal>, which is in
- milliseconds. The default is <literal>10000</literal> ms.</para>
- <section id="security.settings.roles">
- <title>Role based security for addresses</title>
- <para>ActiveMQ contains a flexible role-based security model for applying security to queues,
- based on their addresses.</para>
- <para>As explained in <xref linkend="using-core"/>, ActiveMQ core consists mainly of sets of
- queues bound to addresses. A message is sent to an address and the server looks up the
- set of queues that are bound to that address, the server then routes the message to
- those set of queues.</para>
- <para>ActiveMQ allows sets of permissions to be defined against the queues based on their
- address. An exact match on the address can be used or a wildcard match can be used using
- the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
- <para>Seven different permissions can be given to the set of queues which match the address.
- Those permissions are:</para>
- <itemizedlist>
- <listitem>
- <para><literal>createDurableQueue</literal>. This permission allows the user to
- create a durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>deleteDurableQueue</literal>. This permission allows the user to
- delete a durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>createNonDurableQueue</literal>. This permission allows the user to create
- a non-durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>deleteNonDurableQueue</literal>. This permission allows the user to delete
- a non-durable queue under matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>send</literal>. This permission allows the user to send a message to
- matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>consume</literal>. This permission allows the user to consume a
- message from a queue bound to matching addresses.</para>
- </listitem>
- <listitem>
- <para><literal>manage</literal>. This permission allows the user to invoke
- management operations by sending management messages to the management
- address.</para>
- </listitem>
- </itemizedlist>
- <para>For each permission, a list of roles who are granted that permission is specified. If
- the user has any of those roles, he/she will be granted that permission for that set of
- addresses.</para>
- <para>Let's take a simple example, here's a security block from <literal
- >activemq-configuration.xml</literal> or <literal>activemq-queues.xml</literal>
- file:</para>
- <programlisting>
-<security-setting match="globalqueues.europe.#">
- <permission type="createDurableQueue" roles="admin"/>
- <permission type="deleteDurableQueue" roles="admin"/>
- <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
- <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
- <permission type="send" roles="admin, europe-users"/>
- <permission type="consume" roles="admin, europe-users"/>
-</security-setting></programlisting>
- <para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
- delimited by the '<literal>.</literal>' character. For a full description of the
- wildcard syntax please see <xref linkend="wildcard-syntax"/>. The above security block
- applies to any address that starts with the string "globalqueues.europe.":</para>
- <para>Only users who have the <literal>admin</literal> role can create or delete durable
- queues bound to an address that starts with the string "globalqueues.europe."</para>
- <para>Any users with the roles <literal>admin</literal>, <literal>guest</literal>, or
- <literal>europe-users</literal> can create or delete temporary queues bound to an
- address that starts with the string "globalqueues.europe."</para>
- <para>Any users with the roles <literal>admin</literal> or <literal>europe-users</literal>
- can send messages to these addresses or consume messages from queues bound to an address
- that starts with the string "globalqueues.europe."</para>
- <para>The mapping between a user and what roles they have is handled by the security
- manager. ActiveMQ ships with a user manager that reads user credentials from a file on
- disk, and can also plug into JAAS or JBoss Application Server security.</para>
- <para>For more information on configuring the security manager, please see <xref
- linkend="change-security-manager"/>.</para>
- <para>There can be zero or more <literal>security-setting</literal> elements in each xml
- file. Where more than one match applies to a set of addresses the <emphasis>more
- specific</emphasis> match takes precedence.</para>
- <para>Let's look at an example of that, here's another <literal>security-setting</literal>
- block:</para>
- <programlisting>
-<security-setting match="globalqueues.europe.orders.#">
- <permission type="send" roles="europe-users"/>
- <permission type="consume" roles="europe-users"/>
-</security-setting></programlisting>
- <para>In this <literal>security-setting</literal> block the match
- 'globalqueues.europe.orders.#' is more specific than the previous match
- 'globalqueues.europe.#'. So any addresses which match 'globalqueues.europe.orders.#'
- will take their security settings <emphasis>only</emphasis> from the latter
- security-setting block.</para>
- <para>Note that settings are not inherited from the former block. All the settings will be
- taken from the more specific matching block, so for the address
- 'globalqueues.europe.orders.plastics' the only permissions that exist are <literal
- >send</literal> and <literal>consume</literal> for the role europe-users. The
- permissions <literal>createDurableQueue</literal>, <literal
- >deleteDurableQueue</literal>, <literal>createNonDurableQueue</literal>, <literal
- >deleteNonDurableQueue</literal> are not inherited from the other security-setting
- block.</para>
- <para>By not inheriting permissions, it allows you to effectively deny permissions in more
- specific security-setting blocks by simply not specifying them. Otherwise it would not
- be possible to deny permissions in sub-groups of addresses.</para>
- </section>
- <section>
- <title>Secure Sockets Layer (SSL) Transport</title>
- <para>When messaging clients are connected to servers, or servers are connected to other
- servers (e.g. via bridges) over an untrusted network then ActiveMQ allows that traffic to
- be encrypted using the Secure Sockets Layer (SSL) transport.</para>
- <para>For more information on configuring the SSL transport, please see <xref
- linkend="configuring-transports"/>.</para>
- </section>
- <section>
- <title>Basic user credentials</title>
- <para>ActiveMQ ships with a security manager implementation that reads user credentials, i.e.
- user names, passwords and role information from an xml file on the classpath called
- <literal>activemq-users.xml</literal>. This is the default security manager.</para>
- <para>If you wish to use this security manager, then users, passwords and roles can easily
- be added into this file.</para>
- <para>Let's take a look at an example file:</para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
-
- <defaultuser name="guest" password="guest">
- <role name="guest"/>
- </defaultuser>
-
- <user name="tim" password="marmite">
- <role name="admin"/>
- </user>
-
- <user name="andy" password="doner_kebab">
- <role name="admin"/>
- <role name="guest"/>
- </user>
-
- <user name="jeff" password="camembert">
- <role name="europe-users"/>
- <role name="guest"/>
- </user>
-
-</configuration></programlisting>
- <para>The first thing to note is the element <literal>defaultuser</literal>. This defines
- what user will be assumed when the client does not specify a username/password when
- creating a session. In this case they will be the user <literal>guest</literal> and have
- the role also called <literal>guest</literal>. Multiple roles can be specified for a
- default user.</para>
- <para>We then have three more users, the user <literal>tim</literal> has the role <literal
- >admin</literal>. The user <literal>andy</literal> has the roles <literal
- >admin</literal> and <literal>guest</literal>, and the user <literal>jeff</literal>
- has the roles <literal>europe-users</literal> and <literal>guest</literal>.</para>
- </section>
- <section id="change-security-manager">
- <title>Changing the security manager</title>
- <para>If you do not want to use the default security manager then you can specify a
- different one by editing the file <literal>activemq-beans.xml</literal> (or <literal
- >activemq-jboss-beans.xml</literal> if you're running JBoss Application Server) and
- changing the class for the <literal>ActiveMQSecurityManager</literal> bean.</para>
- <para>Let's take a look at a snippet from the default beans file:</para>
- <programlisting>
-<bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
- <start ignored="true"/>
- <stop ignored="true"/>
-</bean></programlisting>
- <para>The class <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl</literal>
- is the default security manager that is used by the standalone server.</para>
- <para>ActiveMQ ships with two other security manager implementations you can use
- off-the-shelf; one a JAAS security manager and another for integrating with JBoss
- Application Sever security, alternatively you could write your own implementation by
- implementing the <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManager</literal>
- interface, and specifying the classname of your implementation in the file <literal
- >activemq-beans.xml</literal> (or <literal>activemq-jboss-beans.xml</literal> if
- you're running JBoss Application Server).</para>
- <para>These two implementations are discussed in the next two sections.</para>
- </section>
- <section>
- <title>JAAS Security Manager</title>
- <para>JAAS stands for 'Java Authentication and Authorization Service' and is a standard part
- of the Java platform. It provides a common API for security authentication and
- authorization, allowing you to plugin your pre-built implementations.</para>
- <para>To configure the JAAS security manager to work with your pre-built JAAS infrastructure
- you need to specify the security manager as a <literal>JAASSecurityManager</literal> in
- the beans file. Here's an example:</para>
- <programlisting>
-<bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
- <start ignored="true"/>
- <stop ignored="true"/>
-
- <property name="ConfigurationName">org.apache.activemq.jms.example.ExampleLoginModule</property>
- <property name="Configuration">
- <inject bean="ExampleConfiguration"/>
- </property>
- <property name="CallbackHandler">
- <inject bean="ExampleCallbackHandler"/>
- </property>
-</bean></programlisting>
- <para>Note that you need to feed the JAAS security manager with three properties:</para>
- <itemizedlist>
- <listitem>
- <para>ConfigurationName: the name of the <literal>LoginModule</literal>
- implementation that JAAS must use</para>
- </listitem>
- <listitem>
- <para>Configuration: the <literal>Configuration</literal> implementation used by
- JAAS</para>
- </listitem>
- <listitem>
- <para>CallbackHandler: the <literal>CallbackHandler</literal> implementation to use
- if user interaction are required</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Example</title>
- <para>See <xref linkend="examples.jaas"/> for an example which shows how ActiveMQ can be
- configured to use JAAS.</para>
- </section>
- </section>
- <section>
- <title>JBoss AS Security Manager</title>
- <para>The JBoss AS security manager is used when running ActiveMQ inside the JBoss
- Application server. This allows tight integration with the JBoss Application Server's
- security model.</para>
- <para>The class name of this security manager is <literal
- >org.apache.activemq.integration.jboss.security.JBossASSecurityManager</literal></para>
- <para>Take a look at one of the default <literal>activemq-jboss-beans.xml</literal> files for
- JBoss Application Server that are bundled in the distribution for an example of how this
- is configured.</para>
- <section>
- <title>Configuring Client Login</title>
- <para>JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet
- or EJB sets security credentials on the current security context and these are used throughout the call.
- If you would like these credentials to be used by ActiveMQ when sending or consuming messages then
- set <literal>allowClientLogin</literal> to true. This will bypass ActiveMQ authentication and propagate the
- provided Security Context. If you would like ActiveMQ to authenticate using the propagated security then set the
- <literal>authoriseOnClientLogin</literal> to true also.</para>
- <para>There is more info on using the JBoss client login module <ulink
- url="http://community.jboss.org/wiki/ClientLoginModule">here</ulink> </para>
- <note><para>If messages are sent non blocking then there is a chance that these could arrive on the server after
- the calling thread has completed meaning that the security context has been cleared. If this is the case then messages
- will need to be sent blocking</para></note>
- </section>
- <section>
- <title>Changing the Security Domain</title>
- <para>The name of the security domain used by the JBoss AS security manager defaults to <literal>java:/jaas/activemq
- </literal>. This can be changed by specifying <literal>securityDomainName</literal> (e.g. java:/jaas/myDomain).
- </para>
- </section>
- </section>
- <section>
- <title>Changing the username/password for clustering</title>
- <para>In order for cluster connections to work correctly, each node in the cluster must make
- connections to the other nodes. The username/password they use for this should always be
- changed from the installation default to prevent a security risk.</para>
- <para>Please see <xref linkend="management"/> for instructions on how to do this.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/send-guarantees.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/send-guarantees.md b/docs/user-manual/en/send-guarantees.md
new file mode 100644
index 0000000..439f70e
--- /dev/null
+++ b/docs/user-manual/en/send-guarantees.md
@@ -0,0 +1,151 @@
+Guarantees of sends and commits
+===============================
+
+Guarantees of Transaction Completion
+====================================
+
+When committing or rolling back a transaction with ActiveMQ, the request
+to commit or rollback is sent to the server, and the call will block on
+the client side until a response has been received from the server that
+the commit or rollback was executed.
+
+When the commit or rollback is received on the server, it will be
+committed to the journal, and depending on the value of the parameter
+`journal-sync-transactional` the server will ensure that the commit or
+rollback is durably persisted to storage before sending the response
+back to the client. If this parameter has the value `false` then commit
+or rollback may not actually get persisted to storage until some time
+after the response has been sent to the client. In event of server
+failure this may mean the commit or rollback never gets persisted to
+storage. The default value of this parameter is `true` so the client can
+be sure all transaction commits or rollbacks have been persisted to
+storage by the time the call to commit or rollback returns.
+
+Setting this parameter to `false` can improve performance at the expense
+of some loss of transaction durability.
+
+This parameter is set in `activemq-configuration.xml`
+
+Guarantees of Non Transactional Message Sends
+=============================================
+
+If you are sending messages to a server using a non transacted session,
+ActiveMQ can be configured to block the call to send until the message
+has definitely reached the server, and a response has been sent back to
+the client. This can be configured individually for durable and
+non-durable messages, and is determined by the following two parameters:
+
+- `BlockOnDurableSend`. If this is set to `true` then all calls to
+ send for durable messages on non transacted sessions will block
+ until the message has reached the server, and a response has been
+ sent back. The default value is `true`.
+
+- `BlockOnNonDurableSend`. If this is set to `true` then all calls to
+ send for non-durable messages on non transacted sessions will block
+ until the message has reached the server, and a response has been
+ sent back. The default value is `false`.
+
+Setting block on sends to `true` can reduce performance since each send
+requires a network round trip before the next send can be performed.
+This means the performance of sending messages will be limited by the
+network round trip time (RTT) of your network, rather than the bandwidth
+of your network. For better performance we recommend either batching
+many messages sends together in a transaction since with a transactional
+session, only the commit / rollback blocks not every send, or, using
+ActiveMQ's advanced *asynchronous send acknowledgements feature*
+described in ?.
+
+If you are using JMS and you're using the JMS service on the server to
+load your JMS connection factory instances into JNDI then these
+parameters can be configured in `activemq-jms.xml` using the elements
+`block-on-durable-send` and `block-on-non-durable-send`. If you're using
+JMS but not using JNDI then you can set these values directly on the
+`ActiveMQConnectionFactory` instance using the appropriate setter
+methods.
+
+If you're using core you can set these values directly on the
+`ClientSessionFactory` instance using the appropriate setter methods.
+
+When the server receives a message sent from a non transactional
+session, and that message is durable and the message is routed to at
+least one durable queue, then the server will persist the message in
+permanent storage. If the journal parameter
+`journal-sync-non-transactional` is set to `true` the server will not
+send a response back to the client until the message has been persisted
+and the server has a guarantee that the data has been persisted to disk.
+The default value for this parameter is `true`.
+
+Guarantees of Non Transactional Acknowledgements
+================================================
+
+If you are acknowledging the delivery of a message at the client side
+using a non transacted session, ActiveMQ can be configured to block the
+call to acknowledge until the acknowledge has definitely reached the
+server, and a response has been sent back to the client. This is
+configured with the parameter `BlockOnAcknowledge`. If this is set to
+`true` then all calls to acknowledge on non transacted sessions will
+block until the acknowledge has reached the server, and a response has
+been sent back. You might want to set this to `true` if you want to
+implement a strict *at most once* delivery policy. The default value is
+`false`
+
+Asynchronous Send Acknowledgements
+==================================
+
+If you are using a non transacted session but want a guarantee that
+every message sent to the server has reached it, then, as discussed in
+?, you can configure ActiveMQ to block the call to send until the server
+has received the message, persisted it and sent back a response. This
+works well but has a severe performance penalty - each call to send
+needs to block for at least the time of a network round trip (RTT) - the
+performance of sending is thus limited by the latency of the network,
+*not* limited by the network bandwidth.
+
+Let's do a little bit of maths to see how severe that is. We'll consider
+a standard 1Gib ethernet network with a network round trip between the
+server and the client of 0.25 ms.
+
+With a RTT of 0.25 ms, the client can send *at most* 1000/ 0.25 = 4000
+messages per second if it blocks on each message send.
+
+If each message is \< 1500 bytes and a standard 1500 bytes MTU size is
+used on the network, then a 1GiB network has a *theoretical* upper limit
+of (1024 \* 1024 \* 1024 / 8) / 1500 = 89478 messages per second if
+messages are sent without blocking! These figures aren't an exact
+science but you can clearly see that being limited by network RTT can
+have serious effect on performance.
+
+To remedy this, ActiveMQ provides an advanced new feature called
+*asynchronous send acknowledgements*. With this feature, ActiveMQ can be
+configured to send messages without blocking in one direction and
+asynchronously getting acknowledgement from the server that the messages
+were received in a separate stream. By de-coupling the send from the
+acknowledgement of the send, the system is not limited by the network
+RTT, but is limited by the network bandwidth. Consequently better
+throughput can be achieved than is possible using a blocking approach,
+while at the same time having absolute guarantees that messages have
+successfully reached the server.
+
+The window size for send acknowledgements is determined by the
+confirmation-window-size parameter on the connection factory or client
+session factory. Please see ? for more info on this.
+
+Asynchronous Send Acknowledgements
+----------------------------------
+
+To use the feature using the core API, you implement the interface
+`org.apache.activemq.api.core.client.SendAcknowledgementHandler` and set
+a handler instance on your `ClientSession`.
+
+Then, you just send messages as normal using your `ClientSession`, and
+as messages reach the server, the server will send back an
+acknowledgement of the send asynchronously, and some time later you are
+informed at the client side by ActiveMQ calling your handler's
+`sendAcknowledged(ClientMessage message)` method, passing in a reference
+to the message that was sent.
+
+To enable asynchronous send acknowledgements you must make sure
+`confirmation-window-size` is set to a positive integer value, e.g.
+10MiB
+
+Please see ? for a full working example.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/send-guarantees.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/send-guarantees.xml b/docs/user-manual/en/send-guarantees.xml
deleted file mode 100644
index a572e14..0000000
--- a/docs/user-manual/en/send-guarantees.xml
+++ /dev/null
@@ -1,152 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="send-guarantees">
- <title>Guarantees of sends and commits</title>
- <section>
- <title>Guarantees of Transaction Completion</title>
- <para>When committing or rolling back a transaction with ActiveMQ, the request to commit or
- rollback is sent to the server, and the call will block on the client side until a
- response has been received from the server that the commit or rollback was
- executed.</para>
- <para>When the commit or rollback is received on the server, it will be committed to the
- journal, and depending on the value of the parameter <literal
- >journal-sync-transactional</literal> the server will ensure that the commit or
- rollback is durably persisted to storage before sending the response back to the client.
- If this parameter has the value <literal>false</literal> then commit or rollback may not
- actually get persisted to storage until some time after the response has been sent to
- the client. In event of server failure this may mean the commit or rollback never gets
- persisted to storage. The default value of this parameter is <literal>true</literal> so
- the client can be sure all transaction commits or rollbacks have been persisted to
- storage by the time the call to commit or rollback returns.</para>
- <para>Setting this parameter to <literal>false</literal> can improve performance at the
- expense of some loss of transaction durability.</para>
- <para>This parameter is set in <literal>activemq-configuration.xml</literal></para>
- </section>
- <section id="non-transactional-sends">
- <title>Guarantees of Non Transactional Message Sends</title>
- <para>If you are sending messages to a server using a non transacted session, ActiveMQ can be
- configured to block the call to send until the message has definitely reached the
- server, and a response has been sent back to the client. This can be configured
- individually for durable and non-durable messages, and is determined by the
- following two parameters:</para>
- <itemizedlist>
- <listitem>
- <para><literal>BlockOnDurableSend</literal>. If this is set to <literal
- >true</literal> then all calls to send for durable messages on non
- transacted sessions will block until the message has reached the server, and a
- response has been sent back. The default value is <literal>true</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>BlockOnNonDurableSend</literal>. If this is set to <literal
- >true</literal> then all calls to send for non-durable messages on non
- transacted sessions will block until the message has reached the server, and a
- response has been sent back. The default value is <literal
- >false</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>Setting block on sends to <literal>true</literal> can reduce performance since each
- send requires a network round trip before the next send can be performed. This means the
- performance of sending messages will be limited by the network round trip time (RTT) of
- your network, rather than the bandwidth of your network. For better performance we
- recommend either batching many messages sends together in a transaction since with a
- transactional session, only the commit / rollback blocks not every send, or, using
- ActiveMQ's advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
- described in <xref linkend="asynchronous-send-acknowledgements"/>.</para>
- <para>If you are using JMS and you're using the JMS service on the server to load your JMS
- connection factory instances into JNDI then these parameters can be configured in
- <literal>activemq-jms.xml</literal> using the elements <literal
- >block-on-durable-send</literal> and <literal
- >block-on-non-durable-send</literal>. If you're using JMS but not using JNDI then
- you can set these values directly on the <literal>ActiveMQConnectionFactory</literal>
- instance using the appropriate setter methods.</para>
- <para>If you're using core you can set these values directly on the <literal
- >ClientSessionFactory</literal> instance using the appropriate setter
- methods.</para>
- <para>When the server receives a message sent from a non transactional session, and that
- message is durable and the message is routed to at least one durable queue, then the
- server will persist the message in permanent storage. If the journal parameter <literal
- >journal-sync-non-transactional</literal> is set to <literal>true</literal> the
- server will not send a response back to the client until the message has been persisted
- and the server has a guarantee that the data has been persisted to disk. The default
- value for this parameter is <literal>true</literal>.</para>
- </section>
- <section id="send-guarantees.nontrans.acks">
- <title>Guarantees of Non Transactional Acknowledgements</title>
- <para>If you are acknowledging the delivery of a message at the client side using a non
- transacted session, ActiveMQ can be configured to block the call to acknowledge until the
- acknowledge has definitely reached the server, and a response has been sent back to the
- client. This is configured with the parameter <literal>BlockOnAcknowledge</literal>. If
- this is set to <literal>true</literal> then all calls to acknowledge on non transacted
- sessions will block until the acknowledge has reached the server, and a response has
- been sent back. You might want to set this to <literal>true</literal> if you want to
- implement a strict <emphasis>at most once</emphasis> delivery policy. The default value
- is <literal>false</literal></para>
- </section>
- <section id="asynchronous-send-acknowledgements">
- <title>Asynchronous Send Acknowledgements</title>
- <para>If you are using a non transacted session but want a guarantee that every message sent
- to the server has reached it, then, as discussed in <xref
- linkend="non-transactional-sends"/>, you can configure ActiveMQ to block the call to
- send until the server has received the message, persisted it and sent back a response.
- This works well but has a severe performance penalty - each call to send needs to block
- for at least the time of a network round trip (RTT) - the performance of sending is thus
- limited by the latency of the network, <emphasis>not</emphasis> limited by the network
- bandwidth.</para>
- <para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
- 1Gib ethernet network with a network round trip between the server and the client of
- 0.25 ms.</para>
- <para>With a RTT of 0.25 ms, the client can send <emphasis>at most</emphasis> 1000/ 0.25 =
- 4000 messages per second if it blocks on each message send.</para>
- <para>If each message is < 1500 bytes and a standard 1500 bytes MTU size is used on the
- network, then a 1GiB network has a <emphasis>theoretical</emphasis> upper limit of (1024
- * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
- blocking! These figures aren't an exact science but you can clearly see that being
- limited by network RTT can have serious effect on performance.</para>
- <para>To remedy this, ActiveMQ provides an advanced new feature called <emphasis>asynchronous
- send acknowledgements</emphasis>. With this feature, ActiveMQ can be configured to
- send messages without blocking in one direction and asynchronously getting
- acknowledgement from the server that the messages were received in a separate stream. By
- de-coupling the send from the acknowledgement of the send, the system is not limited by
- the network RTT, but is limited by the network bandwidth. Consequently better throughput
- can be achieved than is possible using a blocking approach, while at the same time
- having absolute guarantees that messages have successfully reached the server.</para>
- <para>The window size for send acknowledgements is determined by the confirmation-window-size parameter on
- the connection factory or client session factory. Please see <xref linkend="client-reconnection"/> for more info on this.</para>
- <section>
- <title>Asynchronous Send Acknowledgements</title>
- <para>To use the feature using the core API, you implement the interface <literal
- >org.apache.activemq.api.core.client.SendAcknowledgementHandler</literal> and set a handler
- instance on your <literal>ClientSession</literal>.</para>
- <para>Then, you just send messages as normal using your <literal
- >ClientSession</literal>, and as messages reach the server, the server will send
- back an acknowledgement of the send asynchronously, and some time later you are
- informed at the client side by ActiveMQ calling your handler's <literal
- >sendAcknowledged(ClientMessage message)</literal> method, passing in a
- reference to the message that was sent.</para>
- <para>To enable asynchronous send acknowledgements you must make sure <literal>confirmation-window-size</literal> is set to a positive integer value, e.g. 10MiB</para>
- <para>Please see <xref linkend="asynchronous-send-acknowledgements-example"/> for a full
- working example.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/slow-consumers.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/slow-consumers.md b/docs/user-manual/en/slow-consumers.md
new file mode 100644
index 0000000..ae03d30
--- /dev/null
+++ b/docs/user-manual/en/slow-consumers.md
@@ -0,0 +1,36 @@
+Detecting Slow Consumers
+========================
+
+In this section we will discuss how ActiveMQ can be configured to deal
+with slow consumers. A slow consumer with a server-side queue (e.g. JMS
+topic subscriber) can pose a significant problem for broker performance.
+If messages build up in the consumer's server-side queue then memory
+will begin filling up and the broker may enter paging mode which would
+impact performance negatively. However, criteria can be set so that
+consumers which don't acknowledge messages quickly enough can
+potentially be disconnected from the broker which in the case of a
+non-durable JMS subscriber would allow the broker to remove the
+subscription and all of its messages freeing up valuable server
+resources.
+
+Configuration required for detecting slow consumers
+===================================================
+
+By default the server will not detect slow consumers. If slow consumer
+detection is desired then see ? for more details.
+
+The calculation to determine whether or not a consumer is slow only
+inspects the number of messages a particular consumer has
+*acknowledged*. It doesn't take into account whether or not flow control
+has been enabled on the consumer, whether or not the consumer is
+streaming a large message, etc. Keep this in mind when configuring slow
+consumer detection.
+
+Please note that slow consumer checks are performed using the scheduled
+thread pool and that each queue on the broker with slow consumer
+detection enabled will cause a new entry in the internal
+`java.util.concurrent.ScheduledThreadPoolExecutor` instance. If there
+are a high number of queues and the `slow-consumer-check-period` is
+relatively low then there may be delays in executing some of the checks.
+However, this will not impact the accuracy of the calculations used by
+the detection algorithm. See ? for more details about this pool.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/slow-consumers.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/slow-consumers.xml b/docs/user-manual/en/slow-consumers.xml
deleted file mode 100644
index 227fa22..0000000
--- a/docs/user-manual/en/slow-consumers.xml
+++ /dev/null
@@ -1,52 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="slow-consumers">
- <title>Detecting Slow Consumers</title>
- <para>In this section we will discuss how ActiveMQ can be configured to deal with slow consumers. A slow consumer with
- a server-side queue (e.g. JMS topic subscriber) can pose a significant problem for broker performance. If messages
- build up in the consumer's server-side queue then memory will begin filling up and the broker may enter paging
- mode which would impact performance negatively. However, criteria can be set so that consumers which don't
- acknowledge messages quickly enough can potentially be disconnected from the broker which in the case of a
- non-durable JMS subscriber would allow the broker to remove the subscription and all of its messages freeing up
- valuable server resources.
- </para>
- <section id="slow.consumer.configuration">
- <title>Configuration required for detecting slow consumers</title>
- <para>By default the server will not detect slow consumers. If slow consumer detection is desired then see
- <xref linkend="queue-attributes.address-settings"/>
- for more details.
- </para>
- <para>The calculation to determine whether or not a consumer is slow only inspects the number of messages a
- particular consumer has <emphasis>acknowledged</emphasis>. It doesn't take into account whether or not flow
- control has been enabled on the consumer, whether or not the consumer is streaming a large message, etc. Keep
- this in mind when configuring slow consumer detection.
- </para>
- <para>Please note that slow consumer checks are performed using the scheduled thread pool and that each queue on
- the broker with slow consumer detection enabled will cause a new entry in the internal
- <literal>java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance. If there are a high number of
- queues and the <literal>slow-consumer-check-period</literal> is relatively low then there may be delays in
- executing some of the checks. However, this will not impact the accuracy of the calculations used by the
- detection algorithm. See <xref linkend="server.scheduled.thread.pool"/> for more details about this pool.
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/spring-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/spring-integration.md b/docs/user-manual/en/spring-integration.md
new file mode 100644
index 0000000..570eac5
--- /dev/null
+++ b/docs/user-manual/en/spring-integration.md
@@ -0,0 +1,50 @@
+Spring Integration
+==================
+
+ActiveMQ provides a simple bootstrap class,
+`org.apache.activemq.integration.spring.SpringJmsBootstrap`, for
+integration with Spring. To use it, you configure ActiveMQ as you always
+would, through its various configuration files like
+`activemq-configuration.xml`, `activemq-jms.xml`, and
+`activemq-users.xml`. The Spring helper class starts the ActiveMQ server
+and adds any factories or destinations configured within
+`activemq-jms.xml` directly into the namespace of the Spring context.
+Let's take this `activemq-jms.xml` file for instance:
+
+ <configuration xmlns="urn:activemq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:activemq /schema/activemq-jms.xsd">
+
+ <!--the queue used by the example-->
+ <queue name="exampleQueue"/>
+ </configuration>
+
+Here we've specified a `javax.jms.ConnectionFactory` we want bound to a
+`ConnectionFactory` entry as well as a queue destination bound to a
+`/queue/exampleQueue` entry. Using the `SpringJmsBootStrap` bean will
+automatically populate the Spring context with references to those beans
+so that you can use them. Below is an example Spring JMS bean file
+taking advantage of this feature:
+
+ <beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
+
+ <bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
+
+ <bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
+
+ <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
+ <property name="connectionFactory" ref="ConnectionFactory"/>
+ <property name="destination" ref="/queue/exampleQueue"/>
+ <property name="messageListener" ref="listener"/>
+ </bean>
+ </beans>
+
+As you can see, the `listenerContainer` bean references the components
+defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class
+extends the EmbeddedJMS class talked about in ? and the same defaults
+and configuration options apply. Also notice that an `init-method` must
+be declared with a start value so that the bean's lifecycle is executed.
+See the javadocs for more details on other properties of the bean class.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/spring-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/spring-integration.xml b/docs/user-manual/en/spring-integration.xml
deleted file mode 100644
index b516871..0000000
--- a/docs/user-manual/en/spring-integration.xml
+++ /dev/null
@@ -1,81 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd"> -->
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="spring.integration">
- <title>Spring Integration</title>
-
- <para>ActiveMQ provides a simple bootstrap class,
- <literal>org.apache.activemq.integration.spring.SpringJmsBootstrap</literal>, for
- integration with Spring. To use it, you configure ActiveMQ as you always
- would, through its various configuration files like
- <literal>activemq-configuration.xml</literal>,
- <literal>activemq-jms.xml</literal>, and
- <literal>activemq-users.xml</literal>. The Spring helper class starts the
- ActiveMQ server and adds any factories or destinations configured within
- <literal>activemq-jms.xml</literal> directly into the namespace of the Spring
- context. Let's take this <literal>activemq-jms.xml</literal> file for
- instance: </para>
- <programlisting>
-<configuration xmlns="urn:activemq"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:activemq /schema/activemq-jms.xsd">
-
- <!--the queue used by the example-->
- <queue name="exampleQueue"/>
-</configuration></programlisting>
- <para>Here we've specified a
- <literal>javax.jms.ConnectionFactory</literal> we want bound to a
- <literal>ConnectionFactory</literal> entry as well as a queue destination
- bound to a <literal>/queue/exampleQueue</literal> entry. Using the
- <literal>SpringJmsBootStrap</literal> bean will automatically populate the
- Spring context with references to those beans so that you can use them.
- Below is an example Spring JMS bean file taking advantage of this
- feature:</para>
- <programlisting>
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
-
- <bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
-
- <bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
-
- <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
- <property name="connectionFactory" ref="ConnectionFactory"/>
- <property name="destination" ref="/queue/exampleQueue"/>
- <property name="messageListener" ref="listener"/>
- </bean>
-</beans></programlisting>
- <para>As you can see, the
- <literal>listenerContainer</literal> bean references the components defined
- in the <literal>activemq-jms.xml</literal> file. The
- <literal>SpringJmsBootstrap</literal> class extends the EmbeddedJMS class
- talked about in <xref
- linkend="simple.embedded.jms" /> and the same defaults and
- configuration options apply. Also notice that an
- <literal>init-method</literal> must be declared with a start value so that
- the bean's lifecycle is executed. See the javadocs for more details on other
- properties of the bean class.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/thread-pooling.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/thread-pooling.md b/docs/user-manual/en/thread-pooling.md
new file mode 100644
index 0000000..3dee1ea
--- /dev/null
+++ b/docs/user-manual/en/thread-pooling.md
@@ -0,0 +1,154 @@
+Thread management
+=================
+
+This chapter describes how ActiveMQ uses and pools threads and how you
+can manage them.
+
+First we'll discuss how threads are managed and used on the server side,
+then we'll look at the client side.
+
+Server-Side Thread Management
+=============================
+
+Each ActiveMQ Server maintains a single thread pool for general use, and
+a scheduled thread pool for scheduled use. A Java scheduled thread pool
+cannot be configured to use a standard thread pool, otherwise we could
+use a single thread pool for both scheduled and non scheduled activity.
+
+A separate thread pool is also used to service connections. ActiveMQ can
+use "old" (blocking) IO or "new" (non-blocking) IO also called NIO. Both
+of these options use a separate thread pool, but each of them behaves
+uniquely.
+
+Since old IO requires a thread per connection its thread pool is
+unbounded. The thread pool is created via `
+ java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)`.
+As the JavaDoc for this method states: “Creates a thread pool that
+creates new threads as needed, but will reuse previously constructed
+threads when they are available, and uses the provided ThreadFactory to
+create new threads when needed.” Threads from this pool which are idle
+for more than 60 seconds will time out and be removed. If old IO
+connections were serviced from the standard pool the pool would easily
+get exhausted if too many connections were made, resulting in the server
+"hanging" since it has no remaining threads to do anything else.
+However, even an unbounded thread pool can run into trouble if it
+becomes too large. If you require the server to handle many concurrent
+connections you should use NIO, not old IO.
+
+When using new IO (NIO), ActiveMQ will, by default, cap its thread pool
+at three times the number of cores (or hyper-threads) as reported by `
+ Runtime.getRuntime().availableProcessors()` for processing
+incoming packets. To override this value, you can set the number of
+threads by specifying the parameter `nio-remoting-threads` in the
+transport configuration. See the ? for more information on this.
+
+There are also a small number of other places where threads are used
+directly, we'll discuss each in turn.
+
+Server Scheduled Thread Pool
+----------------------------
+
+The server scheduled thread pool is used for most activities on the
+server side that require running periodically or with delays. It maps
+internally to a `java.util.concurrent.ScheduledThreadPoolExecutor`
+instance.
+
+The maximum number of thread used by this pool is configure in
+`activemq-configuration.xml` with the `scheduled-thread-pool-max-size`
+parameter. The default value is `5` threads. A small number of threads
+is usually sufficient for this pool.
+
+General Purpose Server Thread Pool
+----------------------------------
+
+This general purpose thread pool is used for most asynchronous actions
+on the server side. It maps internally to a
+`java.util.concurrent.ThreadPoolExecutor` instance.
+
+The maximum number of thread used by this pool is configure in
+`activemq-configuration.xml` with the `thread-pool-max-size` parameter.
+
+If a value of `-1` is used this signifies that the thread pool has no
+upper bound and new threads will be created on demand if there are not
+enough threads available to satisfy a request. If activity later
+subsides then threads are timed-out and closed.
+
+If a value of `n` where `n`is a positive integer greater than zero is
+used this signifies that the thread pool is bounded. If more requests
+come in and there are no free threads in the pool and the pool is full
+then requests will block until a thread becomes available. It is
+recommended that a bounded thread pool is used with caution since it can
+lead to dead-lock situations if the upper bound is chosen to be too low.
+
+The default value for `thread-pool-max-size` is `30`.
+
+See the [J2SE
+javadoc](http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.htm)
+for more information on unbounded (cached), and bounded (fixed) thread
+pools.
+
+Expiry Reaper Thread
+--------------------
+
+A single thread is also used on the server side to scan for expired
+messages in queues. We cannot use either of the thread pools for this
+since this thread needs to run at its own configurable priority.
+
+For more information on configuring the reaper, please see ?.
+
+Asynchronous IO
+---------------
+
+Asynchronous IO has a thread pool for receiving and dispatching events
+out of the native layer. You will find it on a thread dump with the
+prefix ActiveMQ-AIO-poller-pool. ActiveMQ uses one thread per opened
+file on the journal (there is usually one).
+
+There is also a single thread used to invoke writes on libaio. We do
+that to avoid context switching on libaio that would cause performance
+issues. You will find this thread on a thread dump with the prefix
+ActiveMQ-AIO-writer-pool.
+
+Client-Side Thread Management
+=============================
+
+On the client side, ActiveMQ maintains a single static scheduled thread
+pool and a single static general thread pool for use by all clients
+using the same classloader in that JVM instance.
+
+The static scheduled thread pool has a maximum size of `5` threads, and
+the general purpose thread pool has an unbounded maximum size.
+
+If required ActiveMQ can also be configured so that each
+`ClientSessionFactory` instance does not use these static pools but
+instead maintains its own scheduled and general purpose pool. Any
+sessions created from that `ClientSessionFactory` will use those pools
+instead.
+
+To configure a `ClientSessionFactory` instance to use its own pools,
+simply use the appropriate setter methods immediately after creation,
+for example:
+
+ ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
+ ClientSessionFactory myFactory = locator.createClientSessionFactory();
+ myFactory.setUseGlobalPools(false);
+ myFactory.setScheduledThreadPoolMaxSize(10);
+ myFactory.setThreadPoolMaxSize(-1);
+
+If you're using the JMS API, you can set the same parameters on the
+ClientSessionFactory and use it to create the `ConnectionFactory`
+instance, for example:
+
+ ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
+
+If you're using JNDI to instantiate `ActiveMQConnectionFactory`
+instances, you can also set these parameters in the JNDI context
+environment, e.g. `jndi.properties`. Here's a simple example using the
+"ConnectionFactory" connection factory which is available in the context
+by default:
+
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
+ java.naming.provider.url=tcp://localhost:5445
+ connection.ConnectionFactory.useGlobalPools=false
+ connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
+ connection.ConnectionFactory.threadPoolMaxSize=-1