Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

This closes #1943

This commit is contained in:
Clebert Suconic 2018-03-08 22:47:10 -05:00
parent 524ca73a3f 86c9e7267b
commit 27a4a1dfc5
46 changed files with 801 additions and 712 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
docs/user-manual/en/address-model.md
View File

@ -1,4 +1,4 @@
# Apache ActiveMQ Artemis Addressing and Queues # Addressing Model
Apache ActiveMQ Artemis has a unique addressing model that is both powerful and flexible and that offers great performance. The addressing model comprises three main concepts: addresses, queues and routing types. Apache ActiveMQ Artemis has a unique addressing model that is both powerful and flexible and that offers great performance. The addressing model comprises three main concepts: addresses, queues and routing types.
@ -32,9 +32,9 @@ When a message is received on an address using anycast, Apache ActiveMQ Artemis
![Point to Point](images/addressing-model-p2p.png) ![Point to Point](images/addressing-model-p2p.png)
Figure 1. Point to Point Messaging Figure 1. Point to Point Messaging
#### Configuring an Address to Use the Anycast Routing Type #### Using the Anycast Routing Type
Open the file <broker-instance>/etc/broker.xml for editing. Open the file `<broker-instance>/etc/broker.xml` for editing.
Add an address configuration element and its associated queue if they do not exist already. Add an address configuration element and its associated queue if they do not exist already.
@ -62,7 +62,7 @@ To configure an address with publish-subscribe semantics, create an address with
![Publish Subscribe](images/addressing-model-pubsub.png) ![Publish Subscribe](images/addressing-model-pubsub.png)
Figure 2. Publish-Subscribe Figure 2. Publish-Subscribe
#### Configuring an Address to Use the Multicast Routing Type #### Using the Multicast Routing Type
Open the file <broker-instance>/etc/broker.xml for editing. Open the file <broker-instance>/etc/broker.xml for editing.
@ -185,8 +185,7 @@ follow JMS example shows how to consumer filters work.
```xml ```xml
<address name="filter"> <address name="filter">
<queue name="filter"> <queue name="filter"/>
</queue>
</address> </address>
``` ```
@ -222,7 +221,7 @@ The resulting queue would now be
green, green, green green, green, green
``` ```
## Creating and Deleting Addresses and Queues Automatically ## Automatic Address/Queue Management
You can configure Apache ActiveMQ Artemis to automatically create addresses and queues, and then delete them when they are no longer in use. This saves you from having to preconfigure each address and queue before a client can connect to it. Automatic creation and deletion is configured on a per address basis and is controlled by following: You can configure Apache ActiveMQ Artemis to automatically create addresses and queues, and then delete them when they are no longer in use. This saves you from having to preconfigure each address and queue before a client can connect to it. Automatic creation and deletion is configured on a per address basis and is controlled by following:
@ -232,17 +231,17 @@ You can configure Apache ActiveMQ Artemis to automatically create addresses and
| auto-delete-addresses | When set to true, the broker will be delete any **auto-created** adddress once all of it’s queues have been deleted. The default is true | | auto-delete-addresses | When set to true, the broker will be delete any **auto-created** adddress once all of it’s queues have been deleted. The default is true |
|default-address-routing-type | The routing type to use if the client does not specify one. Possible values are MULTICAST and ANYCAST. See earlier in this chapter for more information about routing types. The default value is MULTICAST. | |default-address-routing-type | The routing type to use if the client does not specify one. Possible values are MULTICAST and ANYCAST. See earlier in this chapter for more information about routing types. The default value is MULTICAST. |
### Configuring an Address to be Automatically Created ### Auto Address Creation
Edit the file <broker-instance>/etc/broker.xml and add the auto-create-addresses element to the address-setting you want the broker to automatically create. - Edit the file `<broker-instance>/etc/broker.xml` and add the `auto-create-addresses` element to the `address-setting` you want the broker to automatically create.
(Optional) Add the address-setting if it does not exits. Use the match parameter and the The Apache ActiveMQ Artemis Wildcard Syntax to match more than one specific address. - (Optional) Add the `address-setting` if it does not exits. Use the match parameter and the [wildcard syntax](wildcard-syntax.md) to match more than one specific address.
Set auto-create-addresses to true - Set `auto-create-addresses` to `true`
(Optional) Assign MULTICAST or ANYCAST as the default routing type for the address. - (Optional) Assign `MULTICAST` or `ANYCAST` as the default routing type for the address.
The example below configures an address-setting to be automatically created by the broker. The default routing type to be used if not specified by the client is MULTICAST. Note that wildcard syntax is used. Any address starting with /news/politics/ will be automatically created by the broker. The example below configures an `address-setting` to be automatically created by the broker. The default routing type to be used if not specified by the client is MULTICAST. Note that wildcard syntax is used. Any address starting with /news/politics/ will be automatically created by the broker.
```xml ```xml
<configuration ...> <configuration ...>
@ -259,15 +258,15 @@ The example below configures an address-setting to be automatically created by t
</configuration> </configuration>
``` ```
### Configuring an Address to be Automatically Deleted ### Auto Address Deletion
Edit the file <broker-instance>/etc/broker.xml and add the auto-delete-addresses element to the address-setting you want the broker to automatically create. Edit the file `<broker-instance>/etc/broker.xml` and add the `auto-delete-addresses` element to the `address-setting` you want the broker to automatically create.
(Optional) Add the address-setting if it does not exits. Use the match parameter and the The Apache ActiveMQ Artemis Wildcard Syntax to match more than one specific address. (Optional) Add the `address-setting` if it does not exits. Use the match parameter and the [wildcard syntax](wildcard-syntax.md) to match more than one specific address.
Set auto-delete-addresses to true Set `auto-delete-addresses` to `true`
The example below configures an address-setting to be automatically deleted by the broker. Note that wildcard syntax is used. Any address request by the client that starts with /news/politics/ is configured to be automatically deleted by the broker. The example below configures an `address-setting` to be automatically deleted by the broker. Note that wildcard syntax is used. Any address request by the client that starts with `/news/politics/` is configured to be automatically deleted by the broker.
```xml ```xml
<configuration ...> <configuration ...>
@ -284,12 +283,11 @@ The example below configures an address-setting to be automatically deleted by t
</configuration> </configuration>
``` ```
## Fully Qualified Queue Names ## "Fully Qualified" Queue Names
Internally the broker maps a client’s request for an address to specific queues. The broker decides on behalf of the client which queues to send messages to or from which queue to receive messages. However, more advanced use cases might require that the client specify a queue directly. In these situations the client and use a fully qualified queue name, by specifying both the address name and the queue name, separated by a ::. Internally the broker maps a client’s request for an address to specific queues. The broker decides on behalf of the client which queues to send messages to or from which queue to receive messages. However, more advanced use cases might require that the client specify a queue directly. In these situations the client and use a fully qualified queue name, by specifying both the address name and the queue name, separated by a ::.
Currently Artemis supports fully qualified queue names on Core, AMQP, JMS, OpenWire, MQTT and Stomp protocols for Currently Artemis supports fully qualified queue names on Core, AMQP, JMS, OpenWire, MQTT and Stomp protocols for receiving messages only.
receiving messages only.
### Specifying a Fully Qualified Queue Name ### Specifying a Fully Qualified Queue Name
In this example, the address foo is configured with two queues q1, q2 as shown in the configuration below. In this example, the address foo is configured with two queues q1, q2 as shown in the configuration below.
@ -318,15 +316,15 @@ Queue q1 session.createQueue(FQQN);
MessageConsumer consumer = session.createConsumer(q1); MessageConsumer consumer = session.createConsumer(q1);
``` ```
## Configuring a Prefix to Connect to a Specific Routing Type ## Using Prefixes to Determine Routing Type
Normally, if a Apache ActiveMQ Artemis receivs a message sent to a particular address, that has both anycast and multicast routing types enable, Apache ActiveMQ Artemis will route a copy of the message to **one** of the anycast queues and to **all** of the multicast queues. Normally, if the broker receives a message sent to a particular address, that has both `ANYCAST` and `MULTICAST` routing types enable, it will route a copy of the message to **one** of the `ANYCAST` queues and to **all** of the `MULTICAST` queues.
However, clients can specify a special prefix when connecting to an address to specify whether to connect using anycast or multicast. The prefixes are custom values that are designated using the anycastPrefix and multicastPrefix parameters within the URL of an acceptor. However, clients can specify a special prefix when connecting to an address to indicate which kind of routing type to use. The prefixes are custom values that are designated using the anycastPrefix and multicastPrefix parameters within the URL of an acceptor.
### Configuring an Anycast Prefix ### Configuring an Anycast Prefix
In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the desired acceptor. In the example below, the acceptor is configured to use anycast:// for the anycastPrefix. Client code can specify anycast://foo/ if the client needs to send a message to only one of the anycast queues. In `<broker-instance>/etc/broker.xml`, add the `anycastPrefix` to the URL of the desired acceptor. In the example below, the acceptor is configured to use `anycast://` for the `anycastPrefix`. Client code can specify `anycast://foo/` if the client needs to send a message to only one of the `ANYCAST` queues.
```xml ```xml
<configuration ...> <configuration ...>
@ -342,7 +340,7 @@ In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the des
### Configuring a Multicast Prefix ### Configuring a Multicast Prefix
In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the desired acceptor. In the example below, the acceptor is configured to use multicast:// for the multicastPrefix. Client code can specify multicast://foo/ if the client needs the message sent to only the multicast queues of the address. In `<broker-instance>/etc/broker.xml`, add the `multicastPrefix` to the URL of the desired acceptor. In the example below, the acceptor is configured to use `multicast://` for the `multicastPrefix`. Client code can specify `multicast://foo/` if the client needs to send a message to only one of the `MULTICAST` queues.
```xml ```xml
<configuration ...> <configuration ...>
@ -358,17 +356,17 @@ In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the des
## Advanced Address Configuration ## Advanced Address Configuration
### Pre-configuring subscription queue semantics ### Static Subscription Queues
In most cases it’s not necessary to pre-create subscription queues. The relevant protocol managers take care of creating subscription queues when clients request to subscribe to an address. The type of subscription queue created, depends on what properties the client request. E.g. durable, non-shared, shared etc... Protocol managers uses special queue names to identify which queues below to which consumers and users need not worry about the details. In most cases it’s not necessary to statically configure subscription queues. The relevant protocol managers take care of dynamically creating subscription queues when clients request to subscribe to an address. The type of subscription queue created depends on what properties the client request. For example, durable, non-shared, shared etc. Protocol managers use special queue naming conventions to identify which queues belong to which consumers and users need not worry about the details.
However, there are scenarios where a user may want to use broker side configuration to pre-configure a subscription. And later connect to that queue directly using a [Fully Qualified Queue name](#fully-qualified-queue-names). The examples below show how to use broker side configuration to pre-configure a queue with publish subscribe behavior for shared, non-shared, durable and non-durable subscription behavior. However, there are scenarios where a user may want to use broker side configuration to statically configure a subscription and later connect to that queue directly using a [Fully Qualified Queue name](#fully-qualified-queue-names). The examples below show how to use broker side configuration to statically configure a queue with publish subscribe behavior for shared, non-shared, durable and non-durable subscription behavior.
#### Configuring a shared durable subscription queue with up to 10 concurrent consumers #### Shared, Durable Subscription Queue using max-consumers
The default behavior for queues is to not limit the number connected queue consumers. The **max-consumers** parameter of the queue element can be used to limit the number of connected consumers allowed at any one time. The default behavior for queues is to not limit the number connected queue consumers. The **max-consumers** parameter of the queue element can be used to limit the number of connected consumers allowed at any one time.
Open the file <broker-instance>/etc/broker.xml for editing. Open the file `<broker-instance>/etc/broker.xml` for editing.
```xml ```xml
<configuration ...> <configuration ...>
@ -386,7 +384,7 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</configuration> </configuration>
``` ```
#### Configuring a non-shared durable subscription #### Non-shared, Durable Subscription Queue
The broker can be configured to prevent more than one consumer from connecting to a queue at any one time. The subscriptions to queues configured this way are therefore "non-shared". To do this simply set the **max-consumers** parameter to "1" The broker can be configured to prevent more than one consumer from connecting to a queue at any one time. The subscriptions to queues configured this way are therefore "non-shared". To do this simply set the **max-consumers** parameter to "1"
@ -406,13 +404,13 @@ The broker can be configured to prevent more than one consumer from connecting t
</configuration> </configuration>
``` ```
#### Pre-configuring a queue as a non-durable subscription queue #### Non-durable Subscription Queue
Non-durable subscriptions are again usually managed by the relevant protocol manager, by creating and deleting temporary queues. Non-durable subscriptions are again usually managed by the relevant protocol manager, by creating and deleting temporary queues.
If a user requires to pre-create a queue that behaves like a non-durable subscription queue the **purge-on-no-consumers** flag can be enabled on the queue. When **purge-on-no-consumers** is set to **true**. The queue will not start receiving messages until a consumer is attached. When the last consumer is detached from the queue. The queue is purged (it's messages are removed) and will not receive any more messages until a new consumer is attached. If a user requires to pre-create a queue that behaves like a non-durable subscription queue the **purge-on-no-consumers** flag can be enabled on the queue. When **purge-on-no-consumers** is set to **true**. The queue will not start receiving messages until a consumer is attached. When the last consumer is detached from the queue. The queue is purged (it's messages are removed) and will not receive any more messages until a new consumer is attached.
Open the file <broker-instance>/etc/broker.xml for editing. Open the file `<broker-instance>/etc/broker.xml` for editing.
```xml ```xml
<configuration ...> <configuration ...>
@ -427,14 +425,15 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</configuration> </configuration>
``` ```
#### Pre-configuring a queue as an exclusive consumer queue #### Exclusive Consumer Queue
If a user requires to pre-create a queue that routes exclusively to one active consumer the **exclusive** flag can be enabled on the queue. If a user requires to statically configure a queue that routes exclusively to one active consumer the **exclusive** flag can be enabled on the queue.
When **exclusive** is set to **true**. The queue will route messages to the a single active consumer. When the active consumer that is being routed to is detached from the queue, if another active consumer exist, one will be chosen and routing will now be exclusive to it.
When **exclusive** is set to **true** the queue will route messages to the a single active consumer. When the active consumer that is being routed to is detached from the queue, if another active consumer exist, one will be chosen and routing will now be exclusive to it.
See [Exclusive Queue](exclusive-queues.md) for further information. See [Exclusive Queue](exclusive-queues.md) for further information.
Open the file <broker-instance>/etc/broker.xml for editing. Open the file `<broker-instance>/etc/broker.xml` for editing.
```xml ```xml
<configuration ...> <configuration ...>
@ -449,16 +448,16 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</configuration> </configuration>
``` ```
## Additional Information: Protocol Managers, Address ## Protocol Managers
A protocol manager maps protocol specific concepts down to the Apache ActiveMQ Artemis core model of addresses, queues and routing types. For example, when a client sends a MQTT subscription packet with the addresses A "protocol manager" maps protocol-specific concepts down to the core addressing model (using addresses, queues and routing types). For example, when a client sends a MQTT subscription packet with the addresses:
``` ```
/house/room1/lights /house/room1/lights
/house/room2/lights /house/room2/lights
``` ```
The MQTT protocol manager understands that the two addresses require multicast semantics. The protocol manager will therefore first look to ensure that multicast is enabled for both addresses. If not, it will attempt to dynamically create them. If successful, the protocol manager will then create special subscription queues with special names, for each subscription requested by the client. The MQTT protocol manager understands that the two addresses require `MULTICAST` semantics. The protocol manager will therefore first look to ensure that `MULTICAST` is enabled for both addresses. If not, it will attempt to dynamically create them. If successful, the protocol manager will then create special subscription queues with special names, for each subscription requested by the client.
The special name allows the protocol manager to quickly identify the required client subscription queues should the client disconnect and reconnect at a later date. If the subscription is temporary the protocol manager will delete the queue once the client disconnects. The special name allows the protocol manager to quickly identify the required client subscription queues should the client disconnect and reconnect at a later date. If the subscription is temporary the protocol manager will delete the queue once the client disconnects.
@ -472,6 +471,7 @@ There are some attributes that are defined against an address wildcard
rather than a specific address/queue. Here an example of an `address-setting` rather than a specific address/queue. Here an example of an `address-setting`
entry that would be found in the `broker.xml` file. entry that would be found in the `broker.xml` file.
```xml
<address-settings> <address-settings>
<address-setting match="order.foo"> <address-setting match="order.foo">
<dead-letter-address>DLA</dead-letter-address> <dead-letter-address>DLA</dead-letter-address>
@ -489,6 +489,7 @@ entry that would be found in the `broker.xml` file.
<slow-consumer-check-period>5</slow-consumer-check-period> <slow-consumer-check-period>5</slow-consumer-check-period>
</address-setting> </address-setting>
</address-settings> </address-settings>
```
The idea with address settings, is you can provide a block of settings The idea with address settings, is you can provide a block of settings
which will be applied against any addresses that match the string in the which will be applied against any addresses that match the string in the
@ -616,4 +617,3 @@ Default is `true`.
on config reload, by delete policy: `OFF` or `FORCE`. on config reload, by delete policy: `OFF` or `FORCE`.
See [config-reload](config-reload.md) for more details. See [config-reload](config-reload.md) for more details.
Default is `OFF`. Default is `OFF`.

30
docs/user-manual/en/architecture.md
View File

@ -1,9 +1,4 @@
# Architecture # Core Architecture
In this section we will give an overview of the Apache ActiveMQ Artemis high level
architecture.
## Core Architecture
Apache ActiveMQ Artemis core is designed simply as set of Plain Old Java Objects Apache ActiveMQ Artemis core is designed simply as set of Plain Old Java Objects
(POJOs) - we hope you like its clean-cut design. (POJOs) - we hope you like its clean-cut design.
@ -35,8 +30,7 @@ Apache ActiveMQ Artemis also provides different protocol implementations on the
6. CORE (Artemis CORE protocol) 6. CORE (Artemis CORE protocol)
JMS semantics are implemented by a JMS facade layer on the client JMS semantics are implemented by a JMS facade layer on the client side.
side.
The Apache ActiveMQ Artemis server does not speak JMS and in fact does not know The Apache ActiveMQ Artemis server does not speak JMS and in fact does not know
anything about JMS, it is a protocol agnostic messaging server designed anything about JMS, it is a protocol agnostic messaging server designed
@ -59,32 +53,32 @@ server. User Application 1 is using the JMS API, while User Application
You can see from the diagram that the JMS API is implemented by a thin You can see from the diagram that the JMS API is implemented by a thin
facade layer on the client side. facade layer on the client side.
## Apache ActiveMQ Artemis stand-alone server ## Stand-alone Broker
The standard stand-alone messaging server configuration comprises a core The normal stand-alone messaging broker configuration comprises a core
messaging server and a number of protocol managers that provide support for messaging broker and a number of protocol managers that provide support for
the various protocol mentioned earlier. Protocol managers are plugable the various protocol mentioned earlier. Protocol managers are pluggable
if you if you
The stand-alone server configuration uses [Airline](https://github.com/airlift/airline) The stand-alone broker configuration uses [Airline](https://github.com/airlift/airline)
for bootstrapping the Broker. for bootstrapping the Broker.
The stand-alone server architecture is shown in figure 3.3 below: The stand-alone broker architecture is shown in figure 3.3 below:
![ActiveMQ Artemis architecture3](images/architecture3.jpg) ![ActiveMQ Artemis architecture3](images/architecture3.jpg)
For more information on server configuration files see [Server Configuration](configuration-index.md) For more information on server configuration files see [Server Configuration](configuration-index.md)
## Apache ActiveMQ Artemis embedded in your own application ## Embedded Broker
Apache ActiveMQ Artemis core is designed as a set of simple POJOs so if you have an Apache ActiveMQ Artemis core is designed as a set of simple POJOs so if you have an
application that requires messaging functionality internally but you application that requires messaging functionality internally but you
don't want to expose that as an Apache ActiveMQ Artemis server you can directly don't want to expose that as an Apache ActiveMQ Artemis broker you can directly
instantiate and embed Apache ActiveMQ Artemis servers in your own application. instantiate and embed Apache ActiveMQ Artemis brokers in your own application.
For more information on embedding Apache ActiveMQ Artemis, see [Embedding Apache ActiveMQ Artemis](embedding-activemq.md). For more information on embedding Apache ActiveMQ Artemis, see [Embedding Apache ActiveMQ Artemis](embedding-activemq.md).
## Apache ActiveMQ Artemis integrated with a Java EE application server ## Integrated with a Java EE application server
Apache ActiveMQ Artemis provides its own fully functional Java Connector Architecture Apache ActiveMQ Artemis provides its own fully functional Java Connector Architecture
(JCA) adaptor which enables it to be integrated easily into any Java EE (JCA) adaptor which enables it to be integrated easily into any Java EE

4
docs/user-manual/en/clusters.md
View File

@ -1,6 +1,6 @@
# Clusters # Clusters
## Clusters Overview ## Overview
Apache ActiveMQ Artemis clusters allow groups of Apache ActiveMQ Artemis servers to be grouped Apache ActiveMQ Artemis clusters allow groups of Apache ActiveMQ Artemis servers to be grouped
together in order to share message processing load. Each active node in together in order to share message processing load. Each active node in
@ -91,6 +91,7 @@ Apache ActiveMQ Artemis server. All broadcast groups must be defined in a
Let's take a look at an example broadcast group from Let's take a look at an example broadcast group from
`broker.xml` that defines a UDP broadcast group: `broker.xml` that defines a UDP broadcast group:
```xml
<broadcast-groups> <broadcast-groups>
<broadcast-group name="my-broadcast-group"> <broadcast-group name="my-broadcast-group">
<local-bind-address>172.16.9.3</local-bind-address> <local-bind-address>172.16.9.3</local-bind-address>
@ -101,6 +102,7 @@ Let's take a look at an example broadcast group from
<connector-ref>netty-connector</connector-ref> <connector-ref>netty-connector</connector-ref>
</broadcast-group> </broadcast-group>
</broadcast-groups> </broadcast-groups>
```
Some of the broadcast group parameters are optional and you'll normally Some of the broadcast group parameters are optional and you'll normally
use the defaults, but we specify them all in the above example for use the defaults, but we specify them all in the above example for

20
docs/user-manual/en/config-reload.md
View File

@ -27,7 +27,7 @@ By default both settings are OFF as such address & queues won't be removed upon
When OFF You may execute explicit CLI or Management operations to remove address & queues. When OFF You may execute explicit CLI or Management operations to remove address & queues.
## Configuration Parameters that are reloaded at runtime ## Reloadable Parameters
The broker configuration file has 2 main parts, `<core>` and `<jms>`. Some of the parameters in the 2 parts are monitored and, The broker configuration file has 2 main parts, `<core>` and `<jms>`. Some of the parameters in the 2 parts are monitored and,
if modified, reloaded into the broker at runtime. if modified, reloaded into the broker at runtime.
@ -39,9 +39,9 @@ Please note that elements under `<jms>` are deprecated. Users are encouraged to
> that won’t take any effect unless you restarting the broker. > that won’t take any effect unless you restarting the broker.
> Such parameters are specifically indicated in the following text. > Such parameters are specifically indicated in the following text.
### Parameters in `<core>` that can be reloaded at runtime ### `<core>`
#### Parameters under `<security-settings>` #### `<security-settings>`
* `<security-setting>` element * `<security-setting>` element
@ -77,7 +77,7 @@ attribute `roles` | N/A* | X* | Changing the ‘roles’ value means updating th
> * `N/A` means this operation is not applicable. > * `N/A` means this operation is not applicable.
> * `X` means this operation is not allowed. > * `X` means this operation is not allowed.
#### Parameters under `<address-settings>` #### `<address-settings>`
* `<address-settings>` element * `<address-settings>` element
@ -130,7 +130,7 @@ attribute `match` | N/A | X | Changing this value is same as deleting the whole
`<default-address-routing-type>` | X (no more than one can be present) | The configured default-address-routing-type will be removed from running broker after reloading. | The default-address-routing-type will be updated after reloading. `<default-address-routing-type>` | X (no more than one can be present) | The configured default-address-routing-type will be removed from running broker after reloading. | The default-address-routing-type will be updated after reloading.
#### Parameters under `<diverts>` #### `<diverts>`
All `<divert>` elements will be reloaded. Each `<divert>` element All `<divert>` elements will be reloaded. Each `<divert>` element
has a ‘name’ and several sub-elements that defines the properties of a divert. has a ‘name’ and several sub-elements that defines the properties of a divert.
@ -157,7 +157,7 @@ attribute `name` | N/A | X | A new divert with the name will be deployed. (if it
`<filter>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker) `<filter>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
`<routing-type>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker) `<routing-type>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
#### Parameters under `<addresses>` #### `<addresses>`
The `<addresses>` element contains a list `<address>` elements. Once changed, all `<address>` elements The `<addresses>` element contains a list `<address>` elements. Once changed, all `<address>` elements
in `<addresses>` will be reloaded. in `<addresses>` will be reloaded.
@ -184,7 +184,7 @@ attribute `name` | N/A | X | After reloading the address of the old name will be
`<multicast>` | X(no more than one is present) | The multicast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A `<multicast>` | X(no more than one is present) | The multicast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A
`<queue>`(under `<multicast>`) | A multicast queue will be deployed after reloading | The multicast queue will be undeployed | For updating queues please see next section `<queues>` `<queue>`(under `<multicast>`) | A multicast queue will be deployed after reloading | The multicast queue will be undeployed | For updating queues please see next section `<queues>`
#### Parameters under `<queues>` #### `<queues>`
The `<queues>` element contains a list `<queue>` elements. Once changed, all `<queue>` elements in `<queues>` will be reloaded. The `<queues>` element contains a list `<queue>` elements. Once changed, all `<queue>` elements in `<queues>` will be reloaded.
@ -210,9 +210,9 @@ attribute `address` | N/A | No effect unless starting broker | No effect unless
attribute `filter` | N/A | No effect unless starting broker | No effect unless starting broker attribute `filter` | N/A | No effect unless starting broker | No effect unless starting broker
attribute `durable` | N/A | No effect unless starting broker | No effect unless starting broker attribute `durable` | N/A | No effect unless starting broker | No effect unless starting broker
### Parameters in `<jms>` that can be reloaded at runtime *(Deprecated)* ### `<jms>` *(Deprecated)*
#### The `<queue>` elements #### `<queue>`
Changes to any `<queue>` elements will be reloaded to the running broker. Changes to any `<queue>` elements will be reloaded to the running broker.
@ -228,7 +228,7 @@ attribute `<name>` | N/A | X | A jms queue of the new name will be deployed afte
`<selector>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker `<selector>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker
`<durable>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker `<durable>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker
#### The `<topic>` elements #### `<topic>`
Changes to any `<topic>` elements will be reloaded to the running broker. Changes to any `<topic>` elements will be reloaded to the running broker.

24
docs/user-manual/en/configuring-transports.md
View File

@ -3,15 +3,17 @@
In this chapter we'll describe the concepts required for understanding In this chapter we'll describe the concepts required for understanding
Apache ActiveMQ Artemis transports and where and how they're configured. Apache ActiveMQ Artemis transports and where and how they're configured.
## Understanding Acceptors ## Acceptors
One of the most important concepts in Apache ActiveMQ Artemis transports is the One of the most important concepts in Apache ActiveMQ Artemis transports is the
*acceptor*. Let's dive straight in and take a look at an acceptor *acceptor*. Let's dive straight in and take a look at an acceptor
defined in xml in the configuration file `broker.xml`. defined in xml in the configuration file `broker.xml`.
```xml
<acceptors> <acceptors>
<acceptor name="netty">tcp://localhost:61617</acceptor> <acceptor name="netty">tcp://localhost:61617</acceptor>
</acceptors> </acceptors>
```
Acceptors are always defined inside an `acceptors` element. There can be Acceptors are always defined inside an `acceptors` element. There can be
one or more acceptors defined in the `acceptors` element. There's no one or more acceptors defined in the `acceptors` element. There's no
@ -37,18 +39,22 @@ valid key=value pairs depends on the specific transport be used and are
passed straight through to the underlying transport. These are set on the passed straight through to the underlying transport. These are set on the
`URL` as part of the query, like so: `URL` as part of the query, like so:
```xml
<acceptor name="netty">tcp://localhost:61617?sslEnabled=true&keyStorePath=/path</acceptor> <acceptor name="netty">tcp://localhost:61617?sslEnabled=true&keyStorePath=/path</acceptor>
```
## Understanding Connectors ## Connectors
Whereas acceptors are used on the server to define how we accept Whereas acceptors are used on the server to define how we accept
connections, connectors are used to define how to connect to a server. connections, connectors are used to define how to connect to a server.
Let's look at a connector defined in our `broker.xml` file: Let's look at a connector defined in our `broker.xml` file:
```xml
<connectors> <connectors>
<connector name="netty">tcp://localhost:61617</connector> <connector name="netty">tcp://localhost:61617</connector>
</connectors> </connectors>
```
Connectors can be defined inside a `connectors` element. There can be Connectors can be defined inside a `connectors` element. There can be
one or more connectors defined in the `connectors` element. There's no one or more connectors defined in the `connectors` element. There's no
@ -62,7 +68,7 @@ A `connector` is used when the server acts as a client itself, e.g.:
In these cases the server needs to know how to connect to other servers. In these cases the server needs to know how to connect to other servers.
That's defined by `connectors`. That's defined by `connectors`.
## Configuring the transport directly from the client side. ## Configuring the Transport Directly from the Client
How do we configure a core `ClientSessionFactory` with the information How do we configure a core `ClientSessionFactory` with the information
that it needs to connect with a server? that it needs to connect with a server?
@ -105,7 +111,7 @@ straightforward TCP sockets, SSL, or to tunnel over HTTP or HTTPS..
We believe this caters for the vast majority of transport requirements. We believe this caters for the vast majority of transport requirements.
## Single Port Support ### Single Port Support
Apache ActiveMQ Artemis supports using a single port for all Apache ActiveMQ Artemis supports using a single port for all
protocols, Apache ActiveMQ Artemis will automatically detect which protocol is being protocols, Apache ActiveMQ Artemis will automatically detect which protocol is being
@ -116,9 +122,11 @@ Sockets are being used and also use the appropriate decoders
It is possible to limit which protocols are supported by using the It is possible to limit which protocols are supported by using the
`protocols` parameter on the Acceptor like so: `protocols` parameter on the Acceptor like so:
```xml
<acceptor name="netty">tcp://localhost:61617?protocols=CORE,AMQP</acceptor> <acceptor name="netty">tcp://localhost:61617?protocols=CORE,AMQP</acceptor>
```
## Configuring Netty TCP ### Configuring Netty TCP
Netty TCP is a simple unencrypted TCP sockets based transport. If you're Netty TCP is a simple unencrypted TCP sockets based transport. If you're
running connections across an untrusted network please bear in running connections across an untrusted network please bear in
@ -264,7 +272,7 @@ Netty for simple TCP:
negative integer this feature is turned off. Changing value needs negative integer this feature is turned off. Changing value needs
to restart server to take effect. to restart server to take effect.
## Configuring Netty Native Transport ### Configuring Netty Native Transport
Netty Native Transport support exists for selected OS platforms. Netty Native Transport support exists for selected OS platforms.
This allows Apache ActiveMQ Artemis to use native sockets/io instead of Java NIO. This allows Apache ActiveMQ Artemis to use native sockets/io instead of Java NIO.
@ -301,7 +309,7 @@ The following properties are specific to this native transport:
Setting this to `false` will force the use of Java NIO instead of kqueue. Default is `true` Setting this to `false` will force the use of Java NIO instead of kqueue. Default is `true`
## Configuring Netty SSL ### Configuring Netty SSL
Netty SSL is similar to the Netty TCP transport but it provides Netty SSL is similar to the Netty TCP transport but it provides
additional security by encrypting TCP connections using the Secure additional security by encrypting TCP connections using the Secure
@ -455,7 +463,7 @@ following additional properties:
## Configuring Netty HTTP ### Configuring Netty HTTP
Netty HTTP tunnels packets over the HTTP protocol. It can be useful in Netty HTTP tunnels packets over the HTTP protocol. It can be useful in
scenarios where firewalls only allow HTTP traffic to pass. scenarios where firewalls only allow HTTP traffic to pass.

6
docs/user-manual/en/connection-ttl.md
View File

@ -4,7 +4,7 @@ In this section we will discuss connection time-to-live (TTL) and
explain how Apache ActiveMQ Artemis deals with crashed clients and clients which have explain how Apache ActiveMQ Artemis deals with crashed clients and clients which have
exited without cleanly closing their resources. exited without cleanly closing their resources.
## Cleaning up Dead Connection Resources on the Server ## Cleaning up Resources on the Server
Before an Apache ActiveMQ Artemis client application exits it is considered good Before an Apache ActiveMQ Artemis client application exits it is considered good
practice that it should close its resources in a controlled manner, practice that it should close its resources in a controlled manner,
@ -131,7 +131,7 @@ the broker. By default, the checks are done every 2,000 milliseconds.
However, this can be changed if necessary by using the However, this can be changed if necessary by using the
`connection-ttl-check-interval` attribute. `connection-ttl-check-interval` attribute.
## Closing core sessions or JMS connections that you have failed to close ## Closing Forgotten Resources
As previously discussed, it's important that all core client sessions As previously discussed, it's important that all core client sessions
and JMS connections are always closed explicitly in a `finally` block and JMS connections are always closed explicitly in a `finally` block
@ -147,7 +147,7 @@ where you created the JMS connection / client session that you later did
not close. This will enable you to pinpoint the error in your code and not close. This will enable you to pinpoint the error in your code and
correct it appropriately. correct it appropriately.
## Detecting failure from the client side. ## Detecting Failure from the Client
In the previous section we discussed how the client sends pings to the In the previous section we discussed how the client sends pings to the
server and how "dead" connection resources are cleaned up by the server. server and how "dead" connection resources are cleaned up by the server.

2
docs/user-manual/en/core-bridges.md
View File

@ -41,6 +41,7 @@ server. They do this by using duplicate detection (described in [Duplicate Detec
Bridges are configured in `broker.xml`. Let's kick off Bridges are configured in `broker.xml`. Let's kick off
with an example (this is actually from the bridge example): with an example (this is actually from the bridge example):
```xml
<bridge name="my-bridge"> <bridge name="my-bridge">
<queue-name>sausage-factory</queue-name> <queue-name>sausage-factory</queue-name>
<forwarding-address>mincing-machine</forwarding-address> <forwarding-address>mincing-machine</forwarding-address>
@ -65,6 +66,7 @@ with an example (this is actually from the bridge example):
<discovery-group-ref discovery-group-name="bridge-discovery-group"/> <discovery-group-ref discovery-group-name="bridge-discovery-group"/>
--> -->
</bridge> </bridge>
```
In the above example we have shown all the parameters its possible to In the above example we have shown all the parameters its possible to
configure for a bridge. In practice you might use many of the defaults configure for a bridge. In practice you might use many of the defaults

2
docs/user-manual/en/critical-analysis.md
View File

@ -32,7 +32,7 @@ The default for critical-analyzer-policy is `LOG`, however the generated broker.
The broker on the distribution will then have it set to `HALT`, but if you use it in any other way the default will be `LOG`. The broker on the distribution will then have it set to `HALT`, but if you use it in any other way the default will be `LOG`.
## What would you expect ## What to Expect
- You will see some logs - You will see some logs

4
docs/user-manual/en/diverts.md
View File

@ -68,6 +68,7 @@ address. Matching messages do not get routed to the old address.
Here's some example xml configuration for an exclusive divert, it's Here's some example xml configuration for an exclusive divert, it's
taken from the divert example: taken from the divert example:
```xml
<divert name="prices-divert"> <divert name="prices-divert">
<address>priceUpdates</address> <address>priceUpdates</address>
<forwarding-address>priceForwarding</forwarding-address> <forwarding-address>priceForwarding</forwarding-address>
@ -77,6 +78,7 @@ taken from the divert example:
</transformer-class-name> </transformer-class-name>
<exclusive>true</exclusive> <exclusive>true</exclusive>
</divert> </divert>
```
We define a divert called `prices-divert` that will divert any We define a divert called `prices-divert` that will divert any
messages sent to the address `priceUpdates` to another local address messages sent to the address `priceUpdates` to another local address
@ -113,11 +115,13 @@ Non exclusive diverts can be configured in the same way as exclusive
diverts with an optional filter and transformer, here's an example diverts with an optional filter and transformer, here's an example
non-exclusive divert, again from the divert example: non-exclusive divert, again from the divert example:
```xml
<divert name="order-divert"> <divert name="order-divert">
<address>orders</address> <address>orders</address>
<forwarding-address>spyTopic</forwarding-address> <forwarding-address>spyTopic</forwarding-address>
<exclusive>false</exclusive> <exclusive>false</exclusive>
</divert> </divert>
```
The above divert example takes a copy of every message sent to the The above divert example takes a copy of every message sent to the
address '`orders`' and sends it to a local address called address '`orders`' and sends it to a local address called

11
docs/user-manual/en/examples.md
View File

@ -7,17 +7,16 @@ The examples are available in both the binary and source distribution under the
by the following source tree: by the following source tree:
- features - Examples containing broker specific features. - features - Examples containing broker specific features.
- ha - examples showing failover and reconnection capabilities.
- clustered - examples showing load balancing and distribution capabilities. - clustered - examples showing load balancing and distribution capabilities.
- ha - examples showing failover and reconnection capabilities.
- perf - examples allowing you to run a few performance tests on the server - perf - examples allowing you to run a few performance tests on the server
- standard - examples demonstrating various broker features.
- sub-modules - examples of integrated external modules. - sub-modules - examples of integrated external modules.
- protocols - Protocol specific examples - protocols - Protocol specific examples
- openwire
- mqtt
- stomp
- amqp - amqp
- mqtt
A set of Java EE examples are also provided which need WildFly installed to be able to run. - openwire
- stomp
Running the Examples Running the Examples
===================== =====================

10
docs/user-manual/en/exclusive-queues.md
View File

@ -16,7 +16,7 @@ Here we advise that you look at message groups first.
## Configuring Exclusive Queues ## Configuring Exclusive Queues
Exclusive queues can be pre configured at the address queue level Exclusive queues can be statically configured using the `exclusive` boolean property:
```xml ```xml
<configuration ...> <configuration ...>
@ -35,17 +35,21 @@ Specified on creating a Queue by using the CORE api specifying the parameter `ex
Or on auto-create when using the JMS Client by using address parameters when creating the destination used by the consumer. Or on auto-create when using the JMS Client by using address parameters when creating the destination used by the consumer.
```java
Queue queue = session.createQueue("my.destination.name?exclusive=true"); Queue queue = session.createQueue("my.destination.name?exclusive=true");
Topic topic = session.createTopic("my.destination.name?exclusive=true"); Topic topic = session.createTopic("my.destination.name?exclusive=true");
```
Also the default for all queues under and address can be defaulted using the address-setting configuration: Also the default for all queues under and address can be defaulted using the address-setting configuration:
```xml
<address-setting match="lastValueQueue"> <address-setting match="lastValueQueue">
<default-exclusive-queue>true</default-exclusive-queue> <default-exclusive-queue>true</default-exclusive-queue>
</address-setting> </address-setting>
```
By default, `exclusive-queue` is false. Address wildcards can be used By default, `default-exclusive-queue` is `false`. Address wildcards can be used
to configure Exclusive queues for a set of addresses (see [here](wildcard-syntax.md)). to configure exclusive queues for a set of addresses (see [here](wildcard-syntax.md)).
## Example ## Example

10
docs/user-manual/en/flow-control.md
View File

@ -137,7 +137,7 @@ The window size therefore determines the amount of bytes that can be
in-flight at any one time before more need to be requested - this in-flight at any one time before more need to be requested - this
prevents the remoting connection from getting overloaded. prevents the remoting connection from getting overloaded.
#### Blocking producer window based flow control using CORE protocol #### Blocking CORE Producers
When using the CORE protocol (used by both the Artemis Core Client and Artemis JMS Client) When using the CORE protocol (used by both the Artemis Core Client and Artemis JMS Client)
the server will always aim give the same number of credits as have been requested. the server will always aim give the same number of credits as have been requested.
@ -149,7 +149,9 @@ producer be associated with the same address and so it is theoretically possible
that more credits are allocated across total producers than what is available. that more credits are allocated across total producers than what is available.
It is therefore possible to go over the address limit by approximately: It is therefore possible to go over the address limit by approximately:
'''total number of producers on address * producer window size''' ```
total number of producers on address * producer window size
```
For example, if I have a queue called "myqueue", I could set the For example, if I have a queue called "myqueue", I could set the
maximum memory size to 10MiB, and the the server will control the number maximum memory size to 10MiB, and the the server will control the number
@ -180,12 +182,14 @@ memory of all subscriptions in the topic won't exceed max-size-bytes.
Here's an example: Here's an example:
```xml
<address-settings> <address-settings>
<address-setting match="exampleQueue"> <address-setting match="exampleQueue">
<max-size-bytes>100000</max-size-bytes> <max-size-bytes>100000</max-size-bytes>
<address-full-policy>BLOCK</address-full-policy> <address-full-policy>BLOCK</address-full-policy>
</address-setting> </address-setting>
</address-settings> </address-settings>
```
The above example would set the max size of the queue "exampleQueue" The above example would set the max size of the queue "exampleQueue"
to be 100000 bytes and would block any producers sending to that address to be 100000 bytes and would block any producers sending to that address
@ -212,7 +216,7 @@ control.
> a misbehaving client to ignore the flow control credits issued by the broker > a misbehaving client to ignore the flow control credits issued by the broker
> and continue sending with out sufficient credit. > and continue sending with out sufficient credit.
#### Blocking producer window based flow control using AMQP #### Blocking AMQP Producers
Apache ActiveMQ Artemis ships with out of the box with 2 protocols that support flow control. Artemis CORE protocol and Apache ActiveMQ Artemis ships with out of the box with 2 protocols that support flow control. Artemis CORE protocol and
AMQP. Both protocols implement flow control slightly differently and therefore address full BLOCK policy behaves slightly AMQP. Both protocols implement flow control slightly differently and therefore address full BLOCK policy behaves slightly

55
docs/user-manual/en/ha.md
View File

@ -32,17 +32,20 @@ Apache ActiveMQ Artemis supports two different strategies for backing up a serve
*shared store* and *replication*. Which is configured via the *shared store* and *replication*. Which is configured via the
`ha-policy` configuration element. `ha-policy` configuration element.
```xml
<ha-policy> <ha-policy>
<replication/> <replication/>
</ha-policy> </ha-policy>
```
or or
```xml
<ha-policy> <ha-policy>
<shared-store/> <shared-store/>
</ha-policy> </ha-policy>
```
As well as these 2 strategies there is also a 3rd called `live-only`. As well as these 2 strategies there is also a 3rd called `live-only`.
This of course means there will be no Backup Strategy and is the default This of course means there will be no Backup Strategy and is the default
@ -67,30 +70,33 @@ element is configured how a server should behave within the cluster,
either as a master (live), slave (backup) or colocated (both live and either as a master (live), slave (backup) or colocated (both live and
backup). This would look something like: backup). This would look something like:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<master/> <master/>
</replication> </replication>
</ha-policy> </ha-policy>
```
or or
```xml
<ha-policy> <ha-policy>
<shared-store/> <shared-store>
<slave/> <slave/>
</shared-store/> </shared-store>
</ha-policy> </ha-policy>
```
or or
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<colocated/> <colocated/>
</replication> </replication>
</ha-policy> </ha-policy>
```
### Data Replication ### Data Replication
@ -205,26 +211,29 @@ reconnecting with the live. This avoids a split brain situation.
To configure the live and backup servers to be a replicating pair, To configure the live and backup servers to be a replicating pair,
configure the live server in ' `broker.xml` to have: configure the live server in ' `broker.xml` to have:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<master/> <master/>
</replication> </replication>
</ha-policy> </ha-policy>
. ...
<cluster-connections> <cluster-connections>
<cluster-connection name="my-cluster"> <cluster-connection name="my-cluster">
... ...
</cluster-connection> </cluster-connection>
</cluster-connections> </cluster-connections>
```
The backup server must be similarly configured but as a `slave` The backup server must be similarly configured but as a `slave`
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<slave/> <slave/>
</replication> </replication>
</ha-policy> </ha-policy>
```
#### All Replication Configuration #### All Replication Configuration
@ -365,27 +374,29 @@ on amount of data).
To configure the live and backup servers to share their store, configure To configure the live and backup servers to share their store, configure
id via the `ha-policy` configuration in `broker.xml`: id via the `ha-policy` configuration in `broker.xml`:
```xml
<ha-policy> <ha-policy>
<shared-store> <shared-store>
<master/> <master/>
</shared-store> </shared-store>
</ha-policy> </ha-policy>
. ...
<cluster-connections> <cluster-connections>
<cluster-connection name="my-cluster"> <cluster-connection name="my-cluster">
... ...
</cluster-connection> </cluster-connection>
</cluster-connections> </cluster-connections>
```
The backup server must also be configured as a backup. The backup server must also be configured as a backup.
```xml
<ha-policy> <ha-policy>
<shared-store> <shared-store>
<slave/> <slave/>
</shared-store> </shared-store>
</ha-policy> </ha-policy>
```
In order for live - backup groups to operate properly with a shared In order for live - backup groups to operate properly with a shared
store, both servers must have configured the location of journal store, both servers must have configured the location of journal
@ -413,6 +424,7 @@ Alternatively you can set `allow-fail-back` to `true` on the slave
config which will force the backup that has become live to automatically config which will force the backup that has become live to automatically
stop. This configuration would look like: stop. This configuration would look like:
```xml
<ha-policy> <ha-policy>
<shared-store> <shared-store>
<slave> <slave>
@ -420,6 +432,7 @@ stop. This configuration would look like:
</slave> </slave>
</shared-store> </shared-store>
</ha-policy> </ha-policy>
```
In replication HA mode you need to set an extra property In replication HA mode you need to set an extra property
`check-for-live-server` to `true` in the `master` configuration. If set `check-for-live-server` to `true` in the `master` configuration. If set
@ -435,6 +448,7 @@ and if there was if the server that took its duties is still running or
not. To configure this option at your `broker.xml` not. To configure this option at your `broker.xml`
configuration file as follows: configuration file as follows:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<master> <master>
@ -442,6 +456,7 @@ configuration file as follows:
</master> </master>
</replication> </replication>
</ha-policy> </ha-policy>
```
> **Warning** > **Warning**
> >
@ -455,6 +470,7 @@ occur on normal server shutdown, to enable this set the following
property to true in the `ha-policy` configuration on either the `master` property to true in the `ha-policy` configuration on either the `master`
or `slave` like so: or `slave` like so:
```xml
<ha-policy> <ha-policy>
<shared-store> <shared-store>
<master> <master>
@ -462,6 +478,7 @@ or `slave` like so:
</master> </master>
</shared-store> </shared-store>
</ha-policy> </ha-policy>
```
By default this is set to false, if by some chance you have set this to By default this is set to false, if by some chance you have set this to
false but still want to stop the server normally and cause failover then false but still want to stop the server normally and cause failover then
@ -472,6 +489,7 @@ server comes back up allowing the original live server to take over
automatically by setting the following property in the automatically by setting the following property in the
`broker.xml` configuration file as follows: `broker.xml` configuration file as follows:
```xml
<ha-policy> <ha-policy>
<shared-store> <shared-store>
<slave> <slave>
@ -479,6 +497,7 @@ automatically by setting the following property in the
</slave> </slave>
</shared-store> </shared-store>
</ha-policy> </ha-policy>
```
#### All Shared Store Configuration #### All Shared Store Configuration
@ -563,6 +582,7 @@ can evenly distribute backups around the cluster. This is configured via
the `ha-policy` element in the `broker.xml` file like the `ha-policy` element in the `broker.xml` file like
so: so:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<colocated> <colocated>
@ -575,6 +595,7 @@ so:
</colocated> </colocated>
</replication> </replication>
</ha-policy> </ha-policy>
```
the above example is configured to use replication, in this case the the above example is configured to use replication, in this case the
@ -605,6 +626,7 @@ Connector used by the cluster connection to do quorum voting for a
replicated backup server, these can be omitted from being offset by replicated backup server, these can be omitted from being offset by
adding them to the `ha-policy` configuration like so: adding them to the `ha-policy` configuration like so:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<colocated> <colocated>
@ -613,6 +635,7 @@ adding them to the `ha-policy` configuration like so:
</excludes> </excludes>
......... .........
</ha-policy> </ha-policy>
```
#### Configuring Directories #### Configuring Directories
@ -684,6 +707,7 @@ so server 1 could have messages 1,3,5,7,9 and server 2 would have
The configuration for a live server to scale down would be something The configuration for a live server to scale down would be something
like: like:
```xml
<ha-policy> <ha-policy>
<live-only> <live-only>
<scale-down> <scale-down>
@ -693,6 +717,7 @@ like:
</scale-down> </scale-down>
</live-only> </live-only>
</ha-policy> </ha-policy>
```
In this instance the server is configured to use a specific connector to In this instance the server is configured to use a specific connector to
@ -701,6 +726,7 @@ connector is chosen, this is to make scale down fromm a backup server
easy to configure. It is also possible to use discovery to scale down, easy to configure. It is also possible to use discovery to scale down,
this would look like: this would look like:
```xml
<ha-policy> <ha-policy>
<live-only> <live-only>
<scale-down> <scale-down>
@ -708,7 +734,7 @@ this would look like:
</scale-down> </scale-down>
</live-only> </live-only>
</ha-policy> </ha-policy>
```
#### Scale Down with groups #### Scale Down with groups
@ -716,6 +742,7 @@ It is also possible to configure servers to only scale down to servers
that belong in the same group. This is done by configuring the group that belong in the same group. This is done by configuring the group
like so: like so:
```xml
<ha-policy> <ha-policy>
<live-only> <live-only>
<scale-down> <scale-down>
@ -724,7 +751,7 @@ like so:
</scale-down> </scale-down>
</live-only> </live-only>
</ha-policy> </ha-policy>
```
In this scenario only servers that belong to the group `my-group` will In this scenario only servers that belong to the group `my-group` will
be scaled down to be scaled down to
@ -740,6 +767,7 @@ they will automatically be backed up by server and as live servers are
shutdown, there messages are made available on another live server. A shutdown, there messages are made available on another live server. A
typical configuration would look like: typical configuration would look like:
```xml
<ha-policy> <ha-policy>
<replication> <replication>
<colocated> <colocated>
@ -768,6 +796,7 @@ typical configuration would look like:
</colocated> </colocated>
</replication> </replication>
</ha-policy> </ha-policy>
```
#### Scale Down and Clients #### Scale Down and Clients

2
docs/user-manual/en/intercepting-operations.md
View File

@ -57,6 +57,7 @@ The returned boolean value is important:
Both incoming and outgoing interceptors are configured in Both incoming and outgoing interceptors are configured in
`broker.xml`: `broker.xml`:
```xml
<remoting-incoming-interceptors> <remoting-incoming-interceptors>
<class-name>org.apache.activemq.artemis.jms.example.LoginInterceptor</class-name> <class-name>org.apache.activemq.artemis.jms.example.LoginInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name> <class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
@ -66,6 +67,7 @@ Both incoming and outgoing interceptors are configured in
<class-name>org.apache.activemq.artemis.jms.example.LogoutInterceptor</class-name> <class-name>org.apache.activemq.artemis.jms.example.LogoutInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name> <class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-outgoing-interceptors> </remoting-outgoing-interceptors>
```
See the documentation on [adding runtime dependencies](using-server.md) to See the documentation on [adding runtime dependencies](using-server.md) to
understand how to make your interceptor available to the broker. understand how to make your interceptor available to the broker.

10
docs/user-manual/en/large-messages.md
View File

@ -31,6 +31,7 @@ The configuration property `large-messages-directory` specifies where
large messages are stored. For JDBC persistence the `large-message-table` large messages are stored. For JDBC persistence the `large-message-table`
should be configured. should be configured.
```xml
<configuration xmlns="urn:activemq" <configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:activemq /schema/artemis-server.xsd"> xsi:schemaLocation="urn:activemq /schema/artemis-server.xsd">
@ -38,6 +39,7 @@ should be configured.
<large-messages-directory>/data/large-messages</large-messages-directory> <large-messages-directory>/data/large-messages</large-messages-directory>
... ...
</configuration </configuration
```
By default the large message directory is `data/largemessages` and `large-message-table` is By default the large message directory is `data/largemessages` and `large-message-table` is
configured as "LARGE_MESSAGE_TABLE". configured as "LARGE_MESSAGE_TABLE".
@ -45,7 +47,7 @@ configured as "LARGE_MESSAGE_TABLE".
For the best performance we recommend using file store with large messages directory stored For the best performance we recommend using file store with large messages directory stored
on a different physical volume to the message journal or paging directory. on a different physical volume to the message journal or paging directory.
## Configuring Parameters ## Configuring the Client
Any message larger than a certain size is considered a large message. Any message larger than a certain size is considered a large message.
Large messages will be split up and sent in fragments. This is Large messages will be split up and sent in fragments. This is
@ -66,13 +68,11 @@ The default value is 100KiB.
will provide more information on how to instantiate the core session factory will provide more information on how to instantiate the core session factory
or JMS connection factory. or JMS connection factory.
### Compressed Large Messages ## Compressed Large Messages
You can choose to send large messages in compressed form using You can choose to send large messages in compressed form using
`compressLargeMessages` URL parameter. `compressLargeMessages` URL parameter.
#### `compressLargeMessages`
If you specify the boolean URL parameter `compressLargeMessages` as true, If you specify the boolean URL parameter `compressLargeMessages` as true,
The system will use the ZIP algorithm to compress the message body as The system will use the ZIP algorithm to compress the message body as
the message is transferred to the server's side. Notice that there's no the message is transferred to the server's side. Notice that there's no
@ -220,7 +220,7 @@ messageReceived.setObjectProperty("JMS_AMQ_OutputStream", bufferedOutput);
> When using JMS, Streaming large messages are only supported on > When using JMS, Streaming large messages are only supported on
> `StreamMessage` and `BytesMessage`. > `StreamMessage` and `BytesMessage`.
## Streaming Alternative ### Streaming Alternative
If you choose not to use the `InputStream` or `OutputStream` capability If you choose not to use the `InputStream` or `OutputStream` capability
of Apache ActiveMQ Artemis You could still access the data directly in an alternative of Apache ActiveMQ Artemis You could still access the data directly in an alternative

9
docs/user-manual/en/last-value-queues.md
View File

@ -8,9 +8,10 @@ last value.
A typical example for Last-Value queue is for stock prices, where you A typical example for Last-Value queue is for stock prices, where you
are only interested by the latest value for a particular stock. are only interested by the latest value for a particular stock.
## Configuring Last-Value Queues ## Configuration
Last-Value queues can be pre configured at the address queue level Last-Value queues can be statically configured via the `last-value`
boolean property:
```xml ```xml
<configuration ...> <configuration ...>
@ -34,9 +35,11 @@ Or on auto-create when using the JMS Client by using address parameters when cre
Also the default for all queues under and address can be defaulted using the address-setting configuration: Also the default for all queues under and address can be defaulted using the address-setting configuration:
```xml
<address-setting match="lastValueQueue"> <address-setting match="lastValueQueue">
<default-last-value-queue>true</default-last-value-queue> <default-last-value-queue>true</default-last-value-queue>
</address-setting> </address-setting>
```
By default, `default-last-value-queue` is false. By default, `default-last-value-queue` is false.
Address wildcards can be used to configure Last-Value queues Address wildcards can be used to configure Last-Value queues
@ -44,7 +47,7 @@ for a set of addresses (see [here](wildcard-syntax.md)).
Note that address-setting `last-value-queue` config is deprecated, please use `default-last-value-queue` instead. Note that address-setting `last-value-queue` config is deprecated, please use `default-last-value-queue` instead.
## Using Last-Value Property ## Last-Value Property
The property name used to identify the last value is `"_AMQ_LVQ_NAME"` The property name used to identify the last value is `"_AMQ_LVQ_NAME"`
(or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API). (or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API).

2
docs/user-manual/en/management-console.md
View File

@ -73,7 +73,7 @@ Under the address you can expand to find the `queues` for the address exposing a
### Key Apache ActiveMQ Artemis Operations ### Key Operations
#### Creating a new Address #### Creating a new Address

18
docs/user-manual/en/management.md
View File

@ -49,11 +49,11 @@ with the word `Control` at the end.
The way to invoke management operations depends on whether JMX, Core The way to invoke management operations depends on whether JMX, Core
messages, or Core JMS messages are used. messages, or Core JMS messages are used.
### Apache ActiveMQ Artemis Management API ### Management API
For full details of the API please consult the Javadoc. In summary: For full details of the API please consult the Javadoc. In summary:
#### Apache ActiveMQ Artemis Server Management #### Server Management
The `ActiveMQServerControl` interface is the entry point for broker management. The `ActiveMQServerControl` interface is the entry point for broker management.
@ -456,8 +456,10 @@ To manage several Apache ActiveMQ Artemis servers from the *same* MBeanServer, t
domain can be configured for each individual Apache ActiveMQ Artemis server by setting domain can be configured for each individual Apache ActiveMQ Artemis server by setting
`jmx-domain` in `broker.xml`: `jmx-domain` in `broker.xml`:
```xml
<!-- use a specific JMX domain for ActiveMQ Artemis MBeans --> <!-- use a specific JMX domain for ActiveMQ Artemis MBeans -->
<jmx-domain>my.org.apache.activemq</jmx-domain> <jmx-domain>my.org.apache.activemq</jmx-domain>
```
### Example ### Example
@ -488,9 +490,9 @@ You can configure multiple roles by changing this to `-Dhawtio.roles=amq,view,up
If a user doesn't have the correct role to invoke a specific operation then this will display an authorisation exception If a user doesn't have the correct role to invoke a specific operation then this will display an authorisation exception
in the console. in the console.
## Using Management Via Apache ActiveMQ Artemis API ## Using Management Message API
The management API in ActiveMQ Artemis is accessed by sending Core Client messages The management message API in ActiveMQ Artemis is accessed by sending Core Client messages
to a special address, the *management address*. to a special address, the *management address*.
*Management messages* are regular Core Client messages with well-known *Management messages* are regular Core Client messages with well-known
@ -574,11 +576,13 @@ The management address requires a *special* user permission `manage` to
be able to receive and handle management messages. This is also be able to receive and handle management messages. This is also
configured in broker.xml: configured in broker.xml:
```xml
<!-- users with the admin role will be allowed to manage --> <!-- users with the admin role will be allowed to manage -->
<!-- Apache ActiveMQ Artemis using management messages --> <!-- Apache ActiveMQ Artemis using management messages -->
<security-setting match="activemq.management"> <security-setting match="activemq.management">
<permission type="manage" roles="admin" /> <permission type="manage" roles="admin" />
</security-setting> </security-setting>
```
### Example ### Example
@ -626,7 +630,9 @@ of all the notifications emitted by the server.
The management notification address to receive management notifications The management notification address to receive management notifications
is configured in `broker.xml`: is configured in `broker.xml`:
```xml
<management-notification-address>activemq.notifications</management-notification-address> <management-notification-address>activemq.notifications</management-notification-address>
```
By default, the address is `activemq.notifications`. By default, the address is `activemq.notifications`.
@ -819,7 +825,9 @@ negative effect on memory.
To enable message counters, you can set it to `true` in To enable message counters, you can set it to `true` in
`broker.xml`: `broker.xml`:
```xml
<message-counter-enabled>true</message-counter-enabled> <message-counter-enabled>true</message-counter-enabled>
```
Message counters keep a history of the queue metrics (10 days by Message counters keep a history of the queue metrics (10 days by
default) and sample all the queues at regular interval (10 seconds by default) and sample all the queues at regular interval (10 seconds by
@ -827,10 +835,12 @@ default). If message counters are enabled, these values should be
configured to suit your messaging use case in configured to suit your messaging use case in
`broker.xml`: `broker.xml`:
```xml
<!-- keep history for a week --> <!-- keep history for a week -->
<message-counter-max-day-history>7</message-counter-max-day-history> <message-counter-max-day-history>7</message-counter-max-day-history>
<!-- sample the queues every minute (60000ms) --> <!-- sample the queues every minute (60000ms) -->
<message-counter-sample-period>60000</message-counter-sample-period> <message-counter-sample-period>60000</message-counter-sample-period>
```
Message counters can be retrieved using the Management API. For example, Message counters can be retrieved using the Management API. For example,
to retrieve message counters on a queue using JMX: to retrieve message counters on a queue using JMX:

23
docs/user-manual/en/masking-passwords.md
View File

@ -32,7 +32,7 @@ universally supported in every password configuration in Artemis.
The other way is to use a `mask-password` attribute to tell that a password The other way is to use a `mask-password` attribute to tell that a password
in a configuration file should be treated as 'masked'. For example: in a configuration file should be treated as 'masked'. For example:
``` ```xml
<mask-password>true</mask-password> <mask-password>true</mask-password>
<cluster-password>xyz</cluster-password> <cluster-password>xyz</cluster-password>
``` ```
@ -63,7 +63,7 @@ If it is specified in ENC() syntax it will be treated as masked, or
If `mask-password` is `true` the `cluster-password` will be treated as masked. If `mask-password` is `true` the `cluster-password` will be treated as masked.
##### Passwords in connectors and acceptors ##### Connectors & Acceptors
In broker.xml `connector` and `acceptor` configurations sometimes needs to In broker.xml `connector` and `acceptor` configurations sometimes needs to
specify passwords. For example, if a user wants to use an `acceptor` with specify passwords. For example, if a user wants to use an `acceptor` with
@ -80,13 +80,13 @@ these to use if they so wish.
The preferred way, however, is to use the ENC() syntax. The preferred way, however, is to use the ENC() syntax.
##### Passwords in bridge configurations ##### Core Bridges
Core Bridges are configured in the server configuration file and so the Core Bridges are configured in the server configuration file and so the
masking of its `password` properties follows the same rules as that of masking of its `password` properties follows the same rules as that of
`cluster-password`. It supports ENC() syntax. `cluster-password`. It supports ENC() syntax.
For using 'mask-password' property, the following table summarizes the For using `mask-password` property, the following table summarizes the
relations among the above-mentioned properties relations among the above-mentioned properties
mask-password | cluster-password | acceptor/connector passwords | bridge password mask-password | cluster-password | acceptor/connector passwords | bridge password
@ -95,7 +95,7 @@ relations among the above-mentioned properties
false | plain text | plain text | plain text false | plain text | plain text | plain text
true | masked | masked | masked true | masked | masked | masked
It is recommended that you use the ENC() syntax for new applications/deployments. It is recommended that you use the `ENC()` syntax for new applications/deployments.
#### Examples #### Examples
@ -152,7 +152,7 @@ other than the default one. For example
</web> </web>
``` ```
### Masking passwords in ActiveMQ Artemis JCA ResourceAdapter and MDB activation configurations ### Passwords for the JCA Resource Adapter
Both ra.xml and MDB activation configuration have a `password` property Both ra.xml and MDB activation configuration have a `password` property
that can be masked preferably using ENC() syntax. that can be masked preferably using ENC() syntax.
@ -209,7 +209,7 @@ Example 2 Using the "UseMaskedPassword" property:
With this configuration, both passwords in ra.xml and all of its MDBs With this configuration, both passwords in ra.xml and all of its MDBs
will have to be in masked form. will have to be in masked form.
### Masking passwords in artemis-users.properties ### Passwords in artemis-users.properties
Apache ActiveMQ Artemis's built-in security manager uses plain properties files Apache ActiveMQ Artemis's built-in security manager uses plain properties files
where the user passwords are specified in a hashed form by default. Note, the passwords where the user passwords are specified in a hashed form by default. Note, the passwords
@ -231,7 +231,7 @@ Passwords in `artemis-users.properties` are automatically detected as hashed or
by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does not need by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does not need
to be `true` to use hashed passwords here. to be `true` to use hashed passwords here.
### Masking password in JAAS login config file (login.config) ### Password in login.config
Artemis supports LDAP login modules to be configured in JAAS configuration Artemis supports LDAP login modules to be configured in JAAS configuration
file (default name is `login.config`). When connecting to a LDAP server usually file (default name is `login.config`). When connecting to a LDAP server usually
@ -331,7 +331,7 @@ When Apache ActiveMQ Artemis reads the cluster-password it will initialize the
NewDecoder and use it to decode "mask\_password". It also process all NewDecoder and use it to decode "mask\_password". It also process all
passwords using the new defined decoder. passwords using the new defined decoder.
#### Implementing your own codecs #### Implementing Custom Codecs
To use a different decoder than the built-in one, you either pick one To use a different decoder than the built-in one, you either pick one
from existing libraries or you implement it yourself. All decoders must from existing libraries or you implement it yourself. All decoders must
@ -366,6 +366,5 @@ public class MyNewDecoder implements SensitiveDataCodec<String>
} }
``` ```
Last but not least, once you get your own decoder, please add it to the Last but not least, once you get your own decoder please [add it to the
classpath by packaging it in a JAR file and putting the JAR file in the `lib` classpath](using-server.md#adding-runtime-dependencies) otherwise the broker will fail to load it!
directory. Otherwise Apache ActiveMQ Artemis will fail to load it!

8
docs/user-manual/en/message-expiry.md
View File

@ -11,18 +11,22 @@ messages are expired, they are removed from the queue and sent to the
expiry address. Many different queues can be bound to an expiry address. expiry address. Many different queues can be bound to an expiry address.
These *expired* messages can later be consumed for further inspection. These *expired* messages can later be consumed for further inspection.
## Message Expiry ## Core API
Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly on the Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly on the
message: message:
```java
// message will expire in 5000ms from now // message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000); message.setExpiration(System.currentTimeMillis() + 5000);
```
JMS MessageProducer allows to set a TimeToLive for the messages it sent: JMS MessageProducer allows to set a TimeToLive for the messages it sent:
```java
// messages sent by this producer will be retained for 5s (5000ms) before expiration // messages sent by this producer will be retained for 5s (5000ms) before expiration
producer.setTimeToLive(5000); producer.setTimeToLive(5000);
```
Expired messages which are consumed from an expiry address have the Expired messages which are consumed from an expiry address have the
following properties: following properties:
@ -46,10 +50,12 @@ following properties:
Expiry address are defined in the address-setting configuration: Expiry address are defined in the address-setting configuration:
```xml
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue --> <!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
<address-setting match="exampleQueue"> <address-setting match="exampleQueue">
<expiry-address>expiryQueue</expiry-address> <expiry-address>expiryQueue</expiry-address>
</address-setting> </address-setting>
```
If messages are expired and no expiry address is specified, messages are If messages are expired and no expiry address is specified, messages are
simply removed from the queue and dropped. Address wildcards can be used simply removed from the queue and dropped. Address wildcards can be used

2
docs/user-manual/en/message-grouping.md
View File

@ -102,6 +102,7 @@ message should take.
Here is a sample config for each type of handler. This should be Here is a sample config for each type of handler. This should be
configured in `broker.xml`. configured in `broker.xml`.
```xml
<grouping-handler name="my-grouping-handler"> <grouping-handler name="my-grouping-handler">
<type>LOCAL</type> <type>LOCAL</type>
<address>jms</address> <address>jms</address>
@ -113,6 +114,7 @@ configured in `broker.xml`.
<address>jms</address> <address>jms</address>
<timeout>5000</timeout> <timeout>5000</timeout>
</grouping-handler> </grouping-handler>
```
- `type` two types of handlers are supported - `LOCAL` and `REMOTE`. - `type` two types of handlers are supported - `LOCAL` and `REMOTE`.
Each cluster should choose 1 node to have a `LOCAL` grouping handler Each cluster should choose 1 node to have a `LOCAL` grouping handler

6
docs/user-manual/en/messaging-concepts.md
View File

@ -12,7 +12,7 @@ about in the messaging world.
If you're already familiar with what a messaging system is and what it's If you're already familiar with what a messaging system is and what it's
capable of, then you can skip this chapter. capable of, then you can skip this chapter.
## Messaging Concepts ## General Concepts
Messaging systems allow you to loosely couple heterogeneous systems Messaging systems allow you to loosely couple heterogeneous systems
together, whilst typically providing reliability, transactions and many together, whilst typically providing reliability, transactions and many
@ -57,7 +57,7 @@ messaging (also known as *point-to-point messaging*) and [publish
subscribe](https://en.wikipedia.org/wiki/Publish_subscribe) messaging. subscribe](https://en.wikipedia.org/wiki/Publish_subscribe) messaging.
We'll summarise them briefly here: We'll summarise them briefly here:
### The Message Queue Pattern ### Point-to-Point
With this type of messaging you send a message to a queue. The message With this type of messaging you send a message to a queue. The message
is then typically persisted to provide a guarantee of delivery, then is then typically persisted to provide a guarantee of delivery, then
@ -97,7 +97,7 @@ forgotten about. Often the send to the warehouse system, update in
database and acknowledgement will be completed in a single transaction database and acknowledgement will be completed in a single transaction
to ensure [ACID](https://en.wikipedia.org/wiki/ACID) properties. to ensure [ACID](https://en.wikipedia.org/wiki/ACID) properties.
### The Publish-Subscribe Pattern ### Publish-Subscribe
With publish-subscribe messaging many senders can send messages to an With publish-subscribe messaging many senders can send messages to an
entity on the server, often called a *topic* (e.g. in the JMS world). entity on the server, often called a *topic* (e.g. in the JMS world).

6
docs/user-manual/en/paging.md
View File

@ -35,7 +35,7 @@ Consumers with selectors will also navigate through the page-files and it will i
## Configuration ### Configuration
You can configure the location of the paging folder You can configure the location of the paging folder
@ -68,11 +68,12 @@ that address alone goes into page mode.
> total overall size of all matching addresses is limited to > total overall size of all matching addresses is limited to
> max-size-bytes. > max-size-bytes.
## Configuration ### Configuration
Configuration is done at the address settings, done at the main Configuration is done at the address settings, done at the main
configuration file (`broker.xml`). configuration file (`broker.xml`).
```xml
<address-settings> <address-settings>
<address-setting match="jms.someaddress"> <address-setting match="jms.someaddress">
<max-size-bytes>104857600</max-size-bytes> <max-size-bytes>104857600</max-size-bytes>
@ -80,6 +81,7 @@ configuration file (`broker.xml`).
<address-full-policy>PAGE</address-full-policy> <address-full-policy>PAGE</address-full-policy>
</address-setting> </address-setting>
</address-settings> </address-settings>
```
This is the list of available parameters on the address settings. This is the list of available parameters on the address settings.

41
docs/user-manual/en/persistence.md
View File

@ -1,16 +1,14 @@
# Persistence # Persistence
In this chapter we will describe how persistence works with Apache ActiveMQ Artemis and Apache ActiveMQ Artemis ships with two persistence options. The file journal which is
how to configure it. highly optimized for the messaging use case and gives great performance, and also the
JDBC Store, which uses JDBC to connect to a database of your choice. The JDBC Store is
still under development, but it is possible to use it's journal features, (essentially
everything except for paging and large messages).
Apache ActiveMQ Artemis ships with two persistence options. The Apache ActiveMQ Artemis File journal ## File Journal (Default)
which is highly optimized for the messaging use case and gives great performance, and also Apache Artemis
JDBC Store, which uses JDBC to connect to a database of your choice. The JDBC Store is still under development,
but it is possible to use it's journal features, (essentially everything except for paging and large messages).
## Apache ActiveMQ Artemis File Journal (Default) The file journal is an *append only* journal. It consists of a set of
An Apache ActiveMQ Artemis file journal is an *append only* journal. It consists of a set of
files on disk. Each file is pre-created to a fixed size and initially files on disk. Each file is pre-created to a fixed size and initially
filled with padding. As operations are performed on the server, e.g. add filled with padding. As operations are performed on the server, e.g. add
message, update message, delete message, records are appended to the message, update message, delete message, records are appended to the
@ -45,13 +43,13 @@ The majority of the journal is written in Java, however we abstract out
the interaction with the actual file system to allow different pluggable the interaction with the actual file system to allow different pluggable
implementations. Apache ActiveMQ Artemis ships with two implementations: implementations. Apache ActiveMQ Artemis ships with two implementations:
- Java [NIO](https://en.wikipedia.org/wiki/New_I/O). ### Java [NIO](https://en.wikipedia.org/wiki/New_I/O)
The first implementation uses standard Java NIO to interface with The first implementation uses standard Java NIO to interface with
the file system. This provides extremely good performance and runs the file system. This provides extremely good performance and runs
on any platform where there's a Java 6+ runtime. on any platform where there's a Java 6+ runtime.
- Linux Asynchronous IO ### Linux Asynchronous IO
The second implementation uses a thin native code wrapper to talk to The second implementation uses a thin native code wrapper to talk to
the Linux asynchronous IO library (AIO). With AIO, Apache ActiveMQ Artemis will be the Linux asynchronous IO library (AIO). With AIO, Apache ActiveMQ Artemis will be
@ -59,8 +57,7 @@ implementations. Apache ActiveMQ Artemis ships with two implementations:
explicit syncs altogether and simply send back confirmation of explicit syncs altogether and simply send back confirmation of
completion when AIO informs us that the data has been persisted. completion when AIO informs us that the data has been persisted.
Using AIO will typically provide even better performance than using Using AIO will typically provide even better performance than using Java NIO.
Java NIO.
The AIO journal is only available when running Linux kernel 2.6 or The AIO journal is only available when running Linux kernel 2.6 or
later and after having installed libaio (if it's not already later and after having installed libaio (if it's not already
@ -73,7 +70,7 @@ implementations. Apache ActiveMQ Artemis ships with two implementations:
libaio is part of the kernel project. libaio is part of the kernel project.
- [Memory mapped](https://en.wikipedia.org/wiki/Memory-mapped_file). ### [Memory mapped](https://en.wikipedia.org/wiki/Memory-mapped_file)
The third implementation uses a file-backed [READ_WRITE](https://docs.oracle.com/javase/8/docs/api/java/nio/channels/FileChannel.MapMode.html#READ_WRITE) The third implementation uses a file-backed [READ_WRITE](https://docs.oracle.com/javase/8/docs/api/java/nio/channels/FileChannel.MapMode.html#READ_WRITE)
memory mapping against the OS page cache to interface with the file system. memory mapping against the OS page cache to interface with the file system.
@ -89,6 +86,8 @@ implementations. Apache ActiveMQ Artemis ships with two implementations:
It benefits by the configuration of OS [huge pages](https://en.wikipedia.org/wiki/Page_%28computer_memory%29), It benefits by the configuration of OS [huge pages](https://en.wikipedia.org/wiki/Page_%28computer_memory%29),
in particular when is used a big number of journal files and sizing them as multiple of the OS page size in bytes. in particular when is used a big number of journal files and sizing them as multiple of the OS page size in bytes.
### Standard Files
The standard Apache ActiveMQ Artemis core server uses two instances of the journal: The standard Apache ActiveMQ Artemis core server uses two instances of the journal:
- Bindings journal. - Bindings journal.
@ -128,7 +127,7 @@ If no persistence is required at all, Apache ActiveMQ Artemis can also be config
not to persist any data at all to storage as discussed in the Configuring not to persist any data at all to storage as discussed in the Configuring
the broker for Zero Persistence section. the broker for Zero Persistence section.
### Configuring the bindings journal #### Configuring the bindings journal
The bindings journal is configured using the following attributes in The bindings journal is configured using the following attributes in
`broker.xml` `broker.xml`
@ -145,11 +144,11 @@ The bindings journal is configured using the following attributes in
`bindings-directory` if it does not already exist. The default value `bindings-directory` if it does not already exist. The default value
is `true` is `true`
### Configuring the jms journal #### Configuring the jms journal
The jms config shares its configuration with the bindings journal. The jms config shares its configuration with the bindings journal.
### Configuring the message journal #### Configuring the message journal
The message journal is configured using the following attributes in The message journal is configured using the following attributes in
`broker.xml` `broker.xml`
@ -308,7 +307,7 @@ The message journal is configured using the following attributes in
This is particular effective for `NIO` and `MAPPED` journals, which rely on This is particular effective for `NIO` and `MAPPED` journals, which rely on
*fsync*/*msync* to force write changes to disk. *fsync*/*msync* to force write changes to disk.
### An important note on disabling `journal-datasync`. #### Note on disabling `journal-datasync`
> Any modern OS guarantees that on process failures (i.e. crash) all the uncommitted changes > Any modern OS guarantees that on process failures (i.e. crash) all the uncommitted changes
> to the page cache will be flushed to the file system, maintaining coherence between > to the page cache will be flushed to the file system, maintaining coherence between
@ -320,7 +319,7 @@ The message journal is configured using the following attributes in
> effectiveness of the journal operations, capable of exploiting > effectiveness of the journal operations, capable of exploiting
> the read caching and write combining features provided by the OS's kernel page cache subsystem. > the read caching and write combining features provided by the OS's kernel page cache subsystem.
### An important note on disabling disk write cache. ### Note on disabling disk write cache
> **Warning** > **Warning**
> >
@ -379,7 +378,7 @@ Using aptitude, (e.g. on Ubuntu or Debian system):
apt-get install libaio apt-get install libaio
## Apache ActiveMQ Artemis JDBC Persistence ## JDBC Persistence
WARNING: The Apache ActiveMQ Artemis JDBC persistence store is under development and is included for evaluation purposes. WARNING: The Apache ActiveMQ Artemis JDBC persistence store is under development and is included for evaluation purposes.
@ -469,7 +468,7 @@ To configure Apache ActiveMQ Artemis to use a database for persisting messages a
Note that some DBMS (e.g. Oracle, 30 chars) have restrictions on the size of table names, this should be taken into consideration when configuring table names for the Artemis database store, pay particular attention to the page store table name, which can be appended with a unique ID of up to 20 characters. (for Oracle this would mean configuring a page-store-table-name of max size of 10 chars). Note that some DBMS (e.g. Oracle, 30 chars) have restrictions on the size of table names, this should be taken into consideration when configuring table names for the Artemis database store, pay particular attention to the page store table name, which can be appended with a unique ID of up to 20 characters. (for Oracle this would mean configuring a page-store-table-name of max size of 10 chars).
## Configuring Apache ActiveMQ Artemis for Zero Persistence ## Zero Persistence
In some situations, zero persistence is sometimes required for a In some situations, zero persistence is sometimes required for a
messaging system. Configuring Apache ActiveMQ Artemis to perform zero persistence is messaging system. Configuring Apache ActiveMQ Artemis to perform zero persistence is

2
docs/user-manual/en/pre-acknowledge.md
View File

@ -48,8 +48,10 @@ to `true`.
Alternatively, when using the JMS API, create a JMS Session with the Alternatively, when using the JMS API, create a JMS Session with the
`ActiveMQSession.PRE_ACKNOWLEDGE` constant. `ActiveMQSession.PRE_ACKNOWLEDGE` constant.
```java
// messages will be acknowledge on the server *before* being delivered to the client // messages will be acknowledge on the server *before* being delivered to the client
Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE); Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);
```
## Individual Acknowledge ## Individual Acknowledge

21
docs/user-manual/en/protocols-interoperability.md
View File

@ -26,6 +26,7 @@ protocol on a particular acceptor simply add a url parameter "protocol=AMQP,STOM
of the parameter is a comma separated list of protocol names. If the protocol parameter is omitted from the url all of the parameter is a comma separated list of protocol names. If the protocol parameter is omitted from the url all
protocols are enabled. protocols are enabled.
```xml
<!-- The following example enables only MQTT on port 1883 --> <!-- The following example enables only MQTT on port 1883 -->
<acceptors> <acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT</acceptor> <acceptor>tcp://localhost:1883?protocols=MQTT</acceptor>
@ -40,6 +41,7 @@ protocols are enabled.
<acceptors> <acceptors>
<acceptor>tcp://localhost:61616</acceptor> <acceptor>tcp://localhost:61616</acceptor>
</acceptors> </acceptors>
```
## AMQP ## AMQP
@ -48,7 +50,9 @@ Apache ActiveMQ Artemis supports the [AMQP
specification. To enable AMQP you must configure a Netty Acceptor to specification. To enable AMQP you must configure a Netty Acceptor to
receive AMQP clients, like so: receive AMQP clients, like so:
```xml
<acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor> <acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor>
```
Apache ActiveMQ Artemis will then accept AMQP 1.0 clients on port 5672 which is the Apache ActiveMQ Artemis will then accept AMQP 1.0 clients on port 5672 which is the
@ -135,8 +139,9 @@ Apache ActiveMQ Artemis now supports the
Apache ActiveMQ 5.x JMS client can talk directly to an Apache ActiveMQ Artemis server. To enable Apache ActiveMQ 5.x JMS client can talk directly to an Apache ActiveMQ Artemis server. To enable
OpenWire support you must configure a Netty Acceptor, like so: OpenWire support you must configure a Netty Acceptor, like so:
```xml
<acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor> <acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor>
```
The Apache ActiveMQ Artemis server will then listens on port 61616 for incoming The Apache ActiveMQ Artemis server will then listens on port 61616 for incoming
openwire commands. Please note the "protocols" is not mandatory here. openwire commands. Please note the "protocols" is not mandatory here.
@ -219,7 +224,9 @@ For example, the default 5.x virtual topic with consumer prefix of ```Consumer.*
the url significant characters ```>;``` are escaped with their hex code points. the url significant characters ```>;``` are escaped with their hex code points.
In an acceptor url it would be: In an acceptor url it would be:
```xml
<acceptor name="artemis">tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2</acceptor> <acceptor name="artemis">tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2</acceptor>
```
This will translate ```Consumer.A.VirtualTopic.Orders``` into a FQQN of ```VirtualTopic.Orders::Consumer.A``` using the This will translate ```Consumer.A.VirtualTopic.Orders``` into a FQQN of ```VirtualTopic.Orders::Consumer.A``` using the
int component ```2``` of the configuration to identify the consumer queue as the first two paths of the destination. int component ```2``` of the configuration to identify the consumer queue as the first two paths of the destination.
@ -339,7 +346,9 @@ Apache ActiveMQ Artemis provides native support for Stomp. To be able to send an
receive Stomp messages, you must configure a `NettyAcceptor` with a receive Stomp messages, you must configure a `NettyAcceptor` with a
`protocols` parameter set to have `stomp`: `protocols` parameter set to have `stomp`:
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor>
```
With this configuration, Apache ActiveMQ Artemis will accept Stomp connections on the With this configuration, Apache ActiveMQ Artemis will accept Stomp connections on the
port `61613` (which is the default port of the Stomp brokers). port `61613` (which is the default port of the Stomp brokers).
@ -425,7 +434,9 @@ configure your stomp acceptor with the "connectionTtl" property, which
is used to set the ttl for connections that are created from that acceptor. is used to set the ttl for connections that are created from that acceptor.
For example: For example:
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor>
```
The above configuration will make sure that any Stomp connection that is The above configuration will make sure that any Stomp connection that is
created from that acceptor and does not include a `heart-beat` header created from that acceptor and does not include a `heart-beat` header
@ -550,7 +561,7 @@ the queue used for the durable subscription in a deterministic way (i.e. using t
subscription on the address `myAddress` with a client-id of `myclientid` and a subscription subscription on the address `myAddress` with a client-id of `myclientid` and a subscription
name of `mysubscription` then configure the durable subscription: name of `mysubscription` then configure the durable subscription:
~~~ ```xml
<core xmlns="urn:activemq:core"> <core xmlns="urn:activemq:core">
... ...
<addresses> <addresses>
@ -562,7 +573,7 @@ name of `mysubscription` then configure the durable subscription:
</addresses> </addresses>
... ...
</core> </core>
~~~ ```
### Handling of Large Messages with Stomp ### Handling of Large Messages with Stomp
@ -572,7 +583,9 @@ prevent this situation from happening, Apache ActiveMQ Artemis provides a stomp
configuration attribute `stompMinLargeMessageSize`. This attribute configuration attribute `stompMinLargeMessageSize`. This attribute
can be configured inside a stomp acceptor, as a parameter. For example: can be configured inside a stomp acceptor, as a parameter. For example:
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor>
```
The type of this attribute is integer. When this attributed is The type of this attribute is integer. When this attributed is
configured, Apache ActiveMQ Artemis server will check the size of the body of each configured, Apache ActiveMQ Artemis server will check the size of the body of each
@ -596,7 +609,9 @@ support Web Sockets can send and receive Stomp messages from Apache ActiveMQ Art
Stomp over Web Sockets is supported via the normal Stomp acceptor: Stomp over Web Sockets is supported via the normal Stomp acceptor:
```xml
<acceptor name="stomp-ws-acceptor">tcp://localhost:61614?protocols=STOMP</acceptor> <acceptor name="stomp-ws-acceptor">tcp://localhost:61614?protocols=STOMP</acceptor>
```
With this configuration, Apache ActiveMQ Artemis will accept Stomp connections over Web With this configuration, Apache ActiveMQ Artemis will accept Stomp connections over Web
Sockets on the port `61614`. Web browser can Sockets on the port `61614`. Web browser can

2
docs/user-manual/en/resource-limits.md
View File

@ -10,12 +10,14 @@ configure such limits.
Here is an example of the XML used to set resource limits: Here is an example of the XML used to set resource limits:
```xml
<resource-limit-settings> <resource-limit-settings>
<resource-limit-setting match="myUser"> <resource-limit-setting match="myUser">
<max-connections>5</max-connections> <max-connections>5</max-connections>
<max-queues>3</max-queues> <max-queues>3</max-queues>
</resource-limit-setting> </resource-limit-setting>
</resource-limit-settings> </resource-limit-settings>
```
Unlike the `match` from `address-setting`, this `match` does not use Unlike the `match` from `address-setting`, this `match` does not use
any wild-card syntax. It's a simple 1:1 mapping of the limits to a user. any wild-card syntax. It's a simple 1:1 mapping of the limits to a user.

8
docs/user-manual/en/security.md
View File

@ -811,7 +811,7 @@ For example, if a class full name is "org.apache.pkg1.Class1", some matching ent
A `*` means 'match-all' in a black or white list. A `*` means 'match-all' in a black or white list.
### Specifying black list and white list via Connection Factories ### Config via Connection Factories
To specify the white and black lists one can use the URL parameters To specify the white and black lists one can use the URL parameters
`deserializationBlackList` and `deserializationWhiteList`. For example, `deserializationBlackList` and `deserializationWhiteList`. For example,
@ -823,7 +823,7 @@ The above statement creates a factory that has a black list contains two
forbidden packages, "org.apache.pkg1" and "org.some.pkg2", separated by a forbidden packages, "org.apache.pkg1" and "org.some.pkg2", separated by a
comma. comma.
### Specifying black list and white list via system properties ### Config via system properties
There are two system properties available for specifying black list and white list: There are two system properties available for specifying black list and white list:
@ -833,7 +833,7 @@ There are two system properties available for specifying black list and white li
Once defined, all JMS object message deserialization in the VM is subject to checks against the two lists. However if you create a ConnectionFactory Once defined, all JMS object message deserialization in the VM is subject to checks against the two lists. However if you create a ConnectionFactory
and set a new set of black/white lists on it, the new values will override the system properties. and set a new set of black/white lists on it, the new values will override the system properties.
### Specifying black list and white list for resource adapters ### Config for resource adapters
Message beans using a JMS resource adapter to receive messages can also control their object deserialization via properly configuring relevant Message beans using a JMS resource adapter to receive messages can also control their object deserialization via properly configuring relevant
properties for their resource adapters. There are two properties that you can configure with connection factories in a resource adapter: properties for their resource adapters. There are two properties that you can configure with connection factories in a resource adapter:
@ -843,7 +843,7 @@ properties for their resource adapters. There are two properties that you can co
These properties, once specified, are eventually set on the corresponding internal factories. These properties, once specified, are eventually set on the corresponding internal factories.
### Specifying black list and white list for REST interface ### Config for REST interface
Apache Artemis REST interface ([Rest](rest.md)) allows interactions between jms client and rest clients. Apache Artemis REST interface ([Rest](rest.md)) allows interactions between jms client and rest clients.
It uses JMS ObjectMessage to wrap the actual user data between the 2 types of clients and deserialization It uses JMS ObjectMessage to wrap the actual user data between the 2 types of clients and deserialization

10
docs/user-manual/en/send-guarantees.md
View File

@ -1,6 +1,6 @@
# Guarantees of sends and commits # Guarantees of Sends and Commits
## Guarantees of Transaction Completion ## Transaction Completion
When committing or rolling back a transaction with Apache ActiveMQ Artemis, the request When committing or rolling back a transaction with Apache ActiveMQ Artemis, the request
to commit or rollback is sent to the server, and the call will block on to commit or rollback is sent to the server, and the call will block on
@ -24,7 +24,7 @@ of some loss of transaction durability.
This parameter is set in `broker.xml` This parameter is set in `broker.xml`
## Guarantees of Non Transactional Message Sends ## Non Transactional Message Sends
If you are sending messages to a server using a non transacted session, If you are sending messages to a server using a non transacted session,
Apache ActiveMQ Artemis can be configured to block the call to send until the message Apache ActiveMQ Artemis can be configured to block the call to send until the message
@ -61,7 +61,7 @@ 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. and the server has a guarantee that the data has been persisted to disk.
The default value for this parameter is `true`. The default value for this parameter is `true`.
## Guarantees of Non Transactional Acknowledgements ## Non Transactional Acknowledgements
If you are acknowledging the delivery of a message at the client side If you are acknowledging the delivery of a message at the client side
using a non transacted session, Apache ActiveMQ Artemis can be configured to block the using a non transacted session, Apache ActiveMQ Artemis can be configured to block the
@ -114,8 +114,6 @@ The window size for send acknowledgements is determined by the
confirmation-window-size parameter on the connection factory or client confirmation-window-size parameter on the connection factory or client
session factory. Please see [Client Reconnection and Session Reattachment](client-reconnection.md) for more info on this. session factory. Please see [Client Reconnection and Session Reattachment](client-reconnection.md) for more info on this.
# Asynchronous Send Acknowledgements
To use the feature using the core API, you implement the interface To use the feature using the core API, you implement the interface
`org.apache.activemq.artemis.api.core.client.SendAcknowledgementHandler` and set `org.apache.activemq.artemis.api.core.client.SendAcknowledgementHandler` and set
a handler instance on your `ClientSession`. a handler instance on your `ClientSession`.

2
docs/user-manual/en/slow-consumers.md
View File

@ -12,7 +12,7 @@ non-durable JMS subscriber would allow the broker to remove the
subscription and all of its messages freeing up valuable server subscription and all of its messages freeing up valuable server
resources. resources.
## Configuration required for detecting slow consumers ## Required Configuration
By default the server will not detect slow consumers. If slow consumer By default the server will not detect slow consumers. If slow consumer
detection is desired then see [address model chapter](address-model.md) detection is desired then see [address model chapter](address-model.md)

2
docs/user-manual/en/spring-integration.md
View File

@ -13,6 +13,7 @@ automatically populate the Spring context with references to those beans
so that you can use them. Below is an example Spring JMS bean file so that you can use them. Below is an example Spring JMS bean file
taking advantage of this feature: taking advantage of this feature:
```xml
<beans xmlns="http://www.springframework.org/schema/beans" <beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans xsi:schemaLocation="http://www.springframework.org/schema/beans
@ -28,6 +29,7 @@ taking advantage of this feature:
<property name="messageListener" ref="listener"/> <property name="messageListener" ref="listener"/>
</bean> </bean>
</beans> </beans>
```
As you can see, the `listenerContainer` bean references the components As you can see, the `listenerContainer` bean references the components
defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class

2
docs/user-manual/en/syntax.md
View File

@ -3,7 +3,9 @@
### Header 3 ### Header 3
#### Header 4 #### Header 4
```xml
<xml>somexml</xml> <xml>somexml</xml>
```
```java ```java
Somejava s = new SomeJava(); Somejava s = new SomeJava();

16
docs/user-manual/en/tomcat.md
View File

@ -1,15 +1,15 @@
# Apache ActiveMQ Artemis - Apache Tomcat Support # Apache Tomcat Support
##Apache Tomcat resource context client configuration ## Resource Context Client Configuration
Apache ActiveMQ Artemis provides support for configuring the client, in the tomcat resource context.xml of Tomcat container. Apache ActiveMQ Artemis provides support for configuring the client, in the tomcat resource context.xml of Tomcat container.
This is very similar to the way this is done in ActiveMQ 5.x so anyone migrating should find this familiar. This is very similar to the way this is done in ActiveMQ 5.x so anyone migrating should find this familiar.
Please note though the connection url and properties that can be set for ActiveMQ Artemis are different please see [Migration Documentation](https://activemq.apache.org/artemis/migration/) Please note though the connection url and properties that can be set for ActiveMQ Artemis are different please see [Migration Documentation](https://activemq.apache.org/artemis/migration/)
#### Example of Connection Factory ### Example of Connection Factory
```` ```xml
<Context> <Context>
... ...
<Resource name="jms/ConnectionFactory" auth="Container" type="org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory" description="JMS Connection Factory" <Resource name="jms/ConnectionFactory" auth="Container" type="org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory" description="JMS Connection Factory"
@ -18,9 +18,9 @@ Please note though the connection url and properties that can be set for ActiveM
</Context> </Context>
```` ````
#### Example of Destination (Queue and Topic) ### Example of Destination (Queue and Topic)
```` ```xml
<Context> <Context>
... ...
<Resource name="jms/ExampleQueue" auth="Container" type="org.apache.activemq.artemis.jms.client.ActiveMQQueue" description="JMS Queue" <Resource name="jms/ExampleQueue" auth="Container" type="org.apache.activemq.artemis.jms.client.ActiveMQQueue" description="JMS Queue"
@ -32,8 +32,8 @@ Please note though the connection url and properties that can be set for ActiveM
</Context> </Context>
```` ````
#### Example Tomcat App ## Example Tomcat App
A sample tomcat app with the container context configured as an example can be seen here: A sample Tomcat app with the container context configured as an example can be seen here:
/examples/features/sub-modules/tomcat /examples/features/sub-modules/tomcat

8
docs/user-manual/en/tools.md
View File

@ -1,12 +1,9 @@
# Tools # Tools
You can use the artemis cli interface to execute data maintenance tools: You can use the artemis cli interface to execute data maintenance tools:
This is a list of sub-commands available This is a list of sub-commands available
Name | Description Name | Description
:--- | :--- :--- | :---
exp | Export the message data using a special and independent XML format exp | Export the message data using a special and independent XML format
@ -15,9 +12,6 @@ data | Prints a report about journal records and summary of existent records
encode | shows an internal format of the journal encoded to String encode | shows an internal format of the journal encoded to String
decode | imports the internal journal format from encode decode | imports the internal journal format from encode
You can use the help at the tool for more information on how to execute each of the tools. For example: You can use the help at the tool for more information on how to execute each of the tools. For example:
``` ```
@ -219,6 +213,4 @@ COMMANDS
With --bindings option, The folder used for bindings (default from With --bindings option, The folder used for bindings (default from
broker.xml) broker.xml)
``` ```

7
docs/user-manual/en/undelivered-messages.md
View File

@ -35,6 +35,7 @@ consuming valuable CPU and network resources.
Delayed redelivery is defined in the address-setting configuration: Delayed redelivery is defined in the address-setting configuration:
```xml
<!-- delay redelivery of messages for 5s --> <!-- delay redelivery of messages for 5s -->
<address-setting match="exampleQueue"> <address-setting match="exampleQueue">
<!-- default is 1.0 --> <!-- default is 1.0 -->
@ -43,8 +44,8 @@ Delayed redelivery is defined in the address-setting configuration:
<redelivery-delay>5000</redelivery-delay> <redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 --> <!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay> <max-redelivery-delay>50000</max-redelivery-delay>
</address-setting> </address-setting>
```
If a `redelivery-delay` is specified, Apache ActiveMQ Artemis will wait this delay If a `redelivery-delay` is specified, Apache ActiveMQ Artemis will wait this delay
before redelivering the messages. before redelivering the messages.
@ -102,12 +103,14 @@ from the dead letter address for further inspection.
Dead letter address is defined in the address-setting configuration: Dead letter address is defined in the address-setting configuration:
```xml
<!-- undelivered messages in exampleQueue will be sent to the dead letter address <!-- undelivered messages in exampleQueue will be sent to the dead letter address
deadLetterQueue after 3 unsuccessful delivery attempts --> deadLetterQueue after 3 unsuccessful delivery attempts -->
<address-setting match="exampleQueue"> <address-setting match="exampleQueue">
<dead-letter-address>deadLetterQueue</dead-letter-address> <dead-letter-address>deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts> <max-delivery-attempts>3</max-delivery-attempts>
</address-setting> </address-setting>
```
If a `dead-letter-address` is not specified, messages will removed after If a `dead-letter-address` is not specified, messages will removed after
`max-delivery-attempts` unsuccessful attempts. `max-delivery-attempts` unsuccessful attempts.
@ -167,4 +170,6 @@ due to performance implications.
To enable it, set `persist-delivery-count-before-delivery` to `true` in To enable it, set `persist-delivery-count-before-delivery` to `true` in
`broker.xml`: `broker.xml`:
```xml
<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery> <persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
```

9
docs/user-manual/en/upgrading.md
View File

@ -17,9 +17,12 @@ To create an Artemis broker instance navigate into the Artemis home folder and r
> downloaded. This separation allows you run multiple broker instances with the same > downloaded. This separation allows you run multiple broker instances with the same
> Artemis "home" for example. It also simplifies updating to newer versions of Artemis. > Artemis "home" for example. It also simplifies updating to newer versions of Artemis.
Because of this separation it's very easy to upgrade Artemis in most cases. Upgrading Because of this separation it's very easy to upgrade Artemis in most cases.
may require some specific steps noted in the [versions](versions.md), but the general
process is as follows: ## General Upgrade Procedure
Upgrading may require some specific steps noted in the [versions](versions.md), but the
general process is as follows:
1. Navigate to the `etc` folder of the broker instance that's being upgraded 1. Navigate to the `etc` folder of the broker instance that's being upgraded
1. Open `artemis.profile` (`artemis.profile.cmd` on Windows). It contains a property 1. Open `artemis.profile` (`artemis.profile.cmd` on Windows). It contains a property

21
docs/user-manual/en/using-jms.md
View File

@ -19,8 +19,7 @@ server for JMS and creating a simple JMS program. We'll also show how to
configure and use JNDI, and also how to use JMS with Apache ActiveMQ Artemis without configure and use JNDI, and also how to use JMS with Apache ActiveMQ Artemis without
using any JNDI. using any JNDI.
A simple ordering system ## A simple ordering system
========================
For this chapter we're going to use a very simple ordering system as our For this chapter we're going to use a very simple ordering system as our
example. It is a somewhat contrived example because of its extreme example. It is a somewhat contrived example because of its extreme
@ -36,8 +35,7 @@ restart or crash. We also want to pre-deploy the queue, i.e. specify the
queue in the server configuration so it is created automatically queue in the server configuration so it is created automatically
without us having to explicitly create it from the client. without us having to explicitly create it from the client.
JNDI Configuration ## JNDI Configuration
==================
The JMS specification establishes the convention that *administered The JMS specification establishes the convention that *administered
objects* (i.e. JMS queue, topic and connection factory instances) are objects* (i.e. JMS queue, topic and connection factory instances) are
@ -57,8 +55,7 @@ kinds of administered objects and how to configure them.
> to an application server (e.g. Wildfly) the application server itself > to an application server (e.g. Wildfly) the application server itself
> will almost certainly provide a JNDI client with its own properties. > will almost certainly provide a JNDI client with its own properties.
ConnectionFactory JNDI ### ConnectionFactory JNDI
----------------------
A JMS connection factory is used by the client to make connections to A JMS connection factory is used by the client to make connections to
the server. It knows the location of the server it is connecting to, as the server. It knows the location of the server it is connecting to, as
@ -206,7 +203,9 @@ The property *value* should be the name of the queue hosted by the
Apache ActiveMQ Artemis server. For example, if the server had a JMS queue configured Apache ActiveMQ Artemis server. For example, if the server had a JMS queue configured
like so: like so:
```xml
<queue name="OrderQueue"/> <queue name="OrderQueue"/>
```
And if the client wanted to bind this queue to "queues/OrderQueue" then And if the client wanted to bind this queue to "queues/OrderQueue" then
the JNDI properties would be configured like so: the JNDI properties would be configured like so:
@ -289,7 +288,7 @@ see the examples directory in the distribution.
> your application will perform very poorly. This is discussed further > your application will perform very poorly. This is discussed further
> in the section on performance tuning [Performance Tuning](perf-tuning.md). > in the section on performance tuning [Performance Tuning](perf-tuning.md).
### Directly instantiating JMS Resources without using JNDI ## Directly instantiating JMS Resources without using JNDI
Although it is a very common JMS usage pattern to lookup JMS Although it is a very common JMS usage pattern to lookup JMS
*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory *Administered Objects* (that's JMS Queue, Topic and ConnectionFactory
@ -354,7 +353,7 @@ TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText()); System.out.println("Got order: " + receivedMessage.getText());
``` ```
### Setting The Client ID ## Setting The Client ID
This represents the client id for a JMS client and is needed for This represents the client id for a JMS client and is needed for
creating durable subscriptions. It is possible to configure this on the creating durable subscriptions. It is possible to configure this on the
@ -362,7 +361,7 @@ connection factory and can be set via the `clientId` element. Any
connection created by this connection factory will have this set as its connection created by this connection factory will have this set as its
client id. client id.
### Setting The Batch Size for DUPS_OK ## Setting The Batch Size for DUPS_OK
When the JMS acknowledge mode is set to `DUPS_OK` it is possible to When the JMS acknowledge mode is set to `DUPS_OK` it is possible to
configure the consumer so that it sends acknowledgements in batches configure the consumer so that it sends acknowledgements in batches
@ -370,7 +369,7 @@ rather that one at a time, saving valuable bandwidth. This can be
configured via the connection factory via the `dupsOkBatchSize` configured via the connection factory via the `dupsOkBatchSize`
element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB. element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB.
### Setting The Transaction Batch Size ## Setting The Transaction Batch Size
When receiving messages in a transaction it is possible to configure the When receiving messages in a transaction it is possible to configure the
consumer to send acknowledgements in batches rather than individually consumer to send acknowledgements in batches rather than individually
@ -378,7 +377,7 @@ saving valuable bandwidth. This can be configured on the connection
factory via the `transactionBatchSize` element and is set in bytes. factory via the `transactionBatchSize` element and is set in bytes.
The default is 1024 \* 1024. The default is 1024 \* 1024.
### Setting The Destination Cache ## Setting The Destination Cache
Many frameworks such as Spring resolve the destination by name on every operation, Many frameworks such as Spring resolve the destination by name on every operation,
this can cause a performance issue and extra calls to the broker, this can cause a performance issue and extra calls to the broker,

88
docs/user-manual/en/using-server.md
View File

@ -12,44 +12,44 @@ with a JMS Service enabled.
This document will refer to the full path of the directory where the ActiveMQ This document will refer to the full path of the directory where the ActiveMQ
distribution has been extracted to as `${ARTEMIS_HOME}` directory. distribution has been extracted to as `${ARTEMIS_HOME}` directory.
Installation ## Installation
============
After downloading the distribution, the following highlights some important folders on the distribution: After downloading the distribution, the following highlights some important folders on the distribution:
|___ bin |___ bin
| |
|___ web
| |___ user-manual
| |___ api
|
|___ examples |___ examples
| |___ core | |___ common
| |___ javaee | |___ features
| |___ jms | |___ perf
| |___ protocols
| |
|___ lib |___ lib
| |___ client
| |
|___ schema |___ schema
|
|___ web
|___ api
|___ hacking-guide
|___ migration-guide
|___ user-manual
- `bin` -- binaries and scripts needed to run ActiveMQ Artemis. - `bin` - binaries and scripts needed to run ActiveMQ Artemis.
- `web` -- The folder where the web context is loaded when ActiveMQ Artemis runs. - `examples` - All manner of examples. Please refer to the [examples](examples.md)
chapter for details on how to run them.
- `user-manual` -- The user manual is placed under the web folder. - `lib` - jars and libraries needed to run ActiveMQ Artemis
- `api` -- The api documentation is placed under the web folder - `schema` - XML Schemas used to validate ActiveMQ Artemis configuration files
- `examples` -- JMS and Java EE examples. Please refer to the 'running - `web` - The folder where the web context is loaded when the broker runs.
examples' chapter for details on how to run them.
- `lib` -- jars and libraries needed to run ActiveMQ Artemis - `api` - The api documentation is placed under the web folder.
- `licenses` -- licenses for ActiveMQ Artemis - `user-manual` - The user manual is placed under the web folder.
- `schemas` -- XML Schemas used to validate ActiveMQ Artemis configuration
files
## Creating a Broker Instance ## Creating a Broker Instance
@ -320,7 +320,7 @@ Some of these properties may be mandatory in certain configurations and the syst
``` ```
### Starting and Stopping a Broker Instance ## Starting and Stopping a Broker Instance
Assuming you created the broker instance under `/var/lib/mybroker` all you need Assuming you created the broker instance under `/var/lib/mybroker` all you need
to do start running the broker instance is execute: to do start running the broker instance is execute:
@ -359,22 +359,6 @@ would for any Java program.
If you wish to add any more JVM arguments or tune the existing ones, the If you wish to add any more JVM arguments or tune the existing ones, the
run scripts are the place to do it. run scripts are the place to do it.
## Pre-configured Options
The distribution contains several standard configuration sets for
running:
- Non clustered stand-alone.
- Clustered stand-alone
- Replicated stand-alone
- Shared-store stand-alone
You can of course create your own configuration and specify any
configuration when running the run script.
## Library Path ## Library Path
If you're using the [Asynchronous IO Journal](libaio.md) on Linux, If you're using the [Asynchronous IO Journal](libaio.md) on Linux,
@ -419,27 +403,40 @@ respectively. It is also possible to not supply a default. i.e.
`${activemq.remoting.netty.host}`, however the system property *must* be `${activemq.remoting.netty.host}`, however the system property *must* be
supplied in that case. supplied in that case.
## Bootstrap File ### Bootstrap configuration file
The stand-alone server is basically a set of POJOs which are The stand-alone server is basically a set of POJOs which are
instantiated by Airline commands. instantiated by Airline commands.
The bootstrap file is very simple. Let's take a look at an example: The bootstrap file is very simple. Let's take a look at an example:
```xml
<broker xmlns="http://activemq.org/schema"> <broker xmlns="http://activemq.org/schema">
<file:core configuration="${activemq.home}/config/stand-alone/non-clustered/broker.xml"></core> <jaas-security domain="activemq"/>
<basic-security/> <server configuration="file:/path/to/broker.xml"/>
<web bind="http://localhost:8161" path="web">
<app url="activemq-branding" war="activemq-branding.war"/>
<app url="artemis-plugin" war="artemis-plugin.war"/>
<app url="console" war="console.war"/>
</web>
</broker> </broker>
```
- core - Instantiates a core server using the configuration file from the
- `server` - Instantiates a core server using the configuration file from the
`configuration` attribute. This is the main broker POJO necessary to `configuration` attribute. This is the main broker POJO necessary to
do all the real messaging work. In addition all JMS objects such as: do all the real messaging work.
Queues, Topics and ConnectionFactory instances are configured here.
## The main configuration file. - `jaas-security` - Configures security for the server. The `domain` attribute
refers to the relevant login module entry in `login.config`.
- `web` - Configures an embedded Jetty instance to serve web applications like
the admin console.
### Broker configuration file
The configuration for the Apache ActiveMQ Artemis core server is contained in The configuration for the Apache ActiveMQ Artemis core server is contained in
`broker.xml`. This is what the FileConfiguration bean `broker.xml`. This is what the FileConfiguration bean
@ -452,8 +449,7 @@ is a valid configuration file. The different configuration will be
explained throughout the manual or you can refer to the configuration explained throughout the manual or you can refer to the configuration
reference [here](configuration-index.md). reference [here](configuration-index.md).
Windows Server ## Windows Server
==============
On windows you will have the option to run ActiveMQ Artemis as a service. On windows you will have the option to run ActiveMQ Artemis as a service.
Just use the following command to install it: Just use the following command to install it:

20
docs/user-manual/en/versions.md
View File

@ -13,13 +13,13 @@ This chapter provides the information for each release:
[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342127). [Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342127).
Highlights: Highlights:
- [Exclusive consumers](address-model.md). - [Exclusive consumers](exclusive-queues.md).
- Equivalent ActiveMQ 5.x Virtual Topic naming abilities. - Equivalent ActiveMQ 5.x Virtual Topic naming abilities.
- SSL Certificate revocation list. - SSL Certificate revocation list.
- [Last-value queue](last-value-queues.md) support for OpenWire. - [Last-value queue](last-value-queues.md) support for OpenWire.
- Support [masked passwords](masking-passwords.md) in bootstrap.xm and login.config - Support [masked passwords](masking-passwords.md) in bootstrap.xm and login.config
- Configurable [broker plugin](broker-plugins.md) implementation for logging various broker events (i.e. `LoggingActiveMQServerPlugin`). - Configurable [broker plugin](broker-plugins.md#using-the-loggingactivemqserverplugin) implementation for logging various broker events (i.e. `LoggingActiveMQServerPlugin`).
- Option to use OpenSSL provider for Netty. - Option to use OpenSSL provider for Netty via the [`sslProvider`](configuring-transports.md#configuring-netty-ssl) URL parameter.
- Enable [splitting of broker.xml into multiple files](configuration-index.md). - Enable [splitting of broker.xml into multiple files](configuration-index.md).
- Enhanced message count and size metrics for queues. - Enhanced message count and size metrics for queues.
@ -28,8 +28,8 @@ Highlights:
[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341540). [Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341540).
Highlights: Highlights:
- [JMX configuration via XML](management.md) rather than having to use system properties via command line or start script. - [JMX configuration via XML](management.md#role-based-authorisation-for-jmx) rather than having to use system properties via command line or start script.
- Configuration of [max frame payload length for STOMP web-socket](protocols-interoperability.md). - Configuration of [max frame payload length for STOMP web-socket](protocols-interoperability.md#stomp-over-web-sockets).
- Ability to configure HA using JDBC persistence. - Ability to configure HA using JDBC persistence.
- Implement [role-based access control for management objects](management.md). - Implement [role-based access control for management objects](management.md).
@ -60,7 +60,7 @@ Highlights:
Highlights: Highlights:
- [Web admin console](management-console.md)! - [Web admin console](management-console.md)!
- [Critical Analysis](critical-analysis.md) and deadlock detection on broker - [Critical Analysis](critical-analysis.md) and deadlock detection on broker
- Support [Netty native kqueue](configuring-transports.md) on Mac. - Support [Netty native kqueue](configuring-transports.md#macos-native-transport) on Mac.
- [Last-value queue](last-value-queues.md) for AMQP - [Last-value queue](last-value-queues.md) for AMQP
#### Upgrading from 2.2.0 #### Upgrading from 2.2.0
@ -78,8 +78,8 @@ Highlights:
Highlights: Highlights:
- Scheduled messages with the STOMP protocol. - Scheduled messages with the STOMP protocol.
- Support for JNDIReferenceFactory and JNDIStorable. - Support for JNDIReferenceFactory and JNDIStorable.
- Ability to delete queues and addresses when broker.xml changes. - Ability to delete queues and addresses when [broker.xml changes](config-reload.md).
- Client authentication via Kerberos TLS Cipher Suites (RFC 2712). - [Client authentication via Kerberos TLS Cipher Suites (RFC 2712)](security.md#kerberos-authentication).
## 2.1.0 ## 2.1.0
@ -88,7 +88,7 @@ Highlights:
Highlights: Highlights:
- [Broker plugin support](broker-plugins.md). - [Broker plugin support](broker-plugins.md).
- Support [Netty native epoll](configuring-transports.md) on Linux. - Support [Netty native epoll](configuring-transports.md#linux-native-transport) on Linux.
- Ability to configure arbitrary security role mappings. - Ability to configure arbitrary security role mappings.
- AMQP performance improvements. - AMQP performance improvements.
@ -103,7 +103,7 @@ Highlights:
- Support for additional messaging use-cases. - Support for additional messaging use-cases.
- Eliminates confusing JMS-specific queue naming conventions (i.e. "jms.queue." & "jms.topic." prefixes). - Eliminates confusing JMS-specific queue naming conventions (i.e. "jms.queue." & "jms.topic." prefixes).
- Pure encoding of messages so protocols like AMQP don't need to convert messages to "core" format unless absolutely necessary. - Pure encoding of messages so protocols like AMQP don't need to convert messages to "core" format unless absolutely necessary.
- ["MAPPED" journal type](persistence.md) for increased performance in certain use-cases. - ["MAPPED" journal type](persistence.md#memory-mapped) for increased performance in certain use-cases.
## 1.5.6 ## 1.5.6

2
docs/user-manual/en/wildcard-routing.md
View File

@ -14,9 +14,11 @@ messages which are sent to a *hierarchy* of addresses.
This functionality is enabled by default. To turn it off add the following to the `broker.xml` configuration. This functionality is enabled by default. To turn it off add the following to the `broker.xml` configuration.
```xml
<wildcard-addresses> <wildcard-addresses>
<routing-enabled>false</routing-enabled> <routing-enabled>false</routing-enabled>
</wildcard-addresses> </wildcard-addresses>
```
For more information on the wild card syntax and how to configure it, take a look at [wildcard syntax](wildcard-syntax.md) chapter, For more information on the wild card syntax and how to configure it, take a look at [wildcard syntax](wildcard-syntax.md) chapter,
also see the topic hierarchy example in the [examples](examples.md). also see the topic hierarchy example in the [examples](examples.md).

6
docs/user-manual/en/wildcard-syntax.md
View File

@ -1,4 +1,4 @@
# Understanding the Apache ActiveMQ Artemis Wildcard Syntax # Wildcard Syntax
Apache ActiveMQ Artemis uses a specific syntax for representing wildcards in security Apache ActiveMQ Artemis uses a specific syntax for representing wildcards in security
settings, address settings and when creating consumers. settings, address settings and when creating consumers.
@ -26,16 +26,18 @@ The wildcard 'news.\*' would match 'news.europe', but not
The wildcard 'news.\*.sport' would match 'news.europe.sport' and also The wildcard 'news.\*.sport' would match 'news.europe.sport' and also
'news.usa.sport', but not 'news.europe.politics'. 'news.usa.sport', but not 'news.europe.politics'.
## Configuring Wildcard syntax ## Customizing the Syntax
It's possible to further configure the syntax of the wildcard addresses using the broker configuration. It's possible to further configure the syntax of the wildcard addresses using the broker configuration.
For that, the `<wildcard-addresses>` configuration tag is used. For that, the `<wildcard-addresses>` configuration tag is used.
```xml
<wildcard-addresses> <wildcard-addresses>
<routing-enabled>true</routing-enabled> <routing-enabled>true</routing-enabled>
<delimiter>.</delimiter> <delimiter>.</delimiter>
<any-words>#</any-words> <any-words>#</any-words>
<single-word>*</single-word> <single-word>*</single-word>
</wildcard-addresses> </wildcard-addresses>
```
The example above shows the default configuration. The example above shows the default configuration.