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