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

NO-JIRA review docs for content, style, & format

This commit is contained in:
Justin Bertram 2018-03-08 14:46:38 -06:00 committed by Clebert Suconic
parent 524ca73a3f
commit 86c9e7267b
46 changed files with 801 additions and 712 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
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.
@ -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)
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.
@ -62,7 +62,7 @@ To configure an address with publish-subscribe semantics, create an address with
![Publish Subscribe](images/addressing-model-pubsub.png)
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.
@ -167,11 +167,11 @@ filter element when configuring a queue. Open up the broker.xml and add an addr
to configure a filter on this queue.
```xml
<address name="filter">
<queue name="filter">
<filter string="color='red'"/>
</queue>
</address>
<address name="filter">
<queue name="filter">
<filter string="color='red'"/>
</queue>
</address>
```
The filter defined above ensures that only messages with an attribute "color='red'" is sent to this queue.
@ -184,10 +184,9 @@ follow JMS example shows how to consumer filters work.
1. Define an address with a single queue, with no filter applied.
```xml
<address name="filter">
<queue name="filter">
</queue>
</address>
<address name="filter">
<queue name="filter"/>
</address>
```
```java
@ -222,7 +221,7 @@ The resulting queue would now be
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:
@ -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 |
|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
<configuration ...>
@ -259,15 +258,15 @@ The example below configures an address-setting to be automatically created by t
</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
<configuration ...>
@ -284,12 +283,11 @@ The example below configures an address-setting to be automatically deleted by t
</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 ::.
Currently Artemis supports fully qualified queue names on Core, AMQP, JMS, OpenWire, MQTT and Stomp protocols for
receiving messages only.
Currently Artemis supports fully qualified queue names on Core, AMQP, JMS, OpenWire, MQTT and Stomp protocols for receiving messages only.
### 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.
@ -318,15 +316,15 @@ Queue q1 session.createQueue(FQQN);
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
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
<configuration ...>
@ -342,7 +340,7 @@ In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the des
### 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
<configuration ...>
@ -358,17 +356,17 @@ In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the des
## 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.
Open the file <broker-instance>/etc/broker.xml for editing.
Open the file `<broker-instance>/etc/broker.xml` for editing.
```xml
<configuration ...>
@ -386,7 +384,7 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</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"
@ -406,13 +404,13 @@ The broker can be configured to prevent more than one consumer from connecting t
</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.
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
<configuration ...>
@ -427,14 +425,15 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</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.
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.
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.
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
<configuration ...>
@ -449,16 +448,16 @@ Open the file <broker-instance>/etc/broker.xml for editing.
</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/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.
@ -472,23 +471,25 @@ There are some attributes that are defined against an address wildcard
rather than a specific address/queue. Here an example of an `address-setting`
entry that would be found in the `broker.xml` file.
<address-settings>
<address-setting match="order.foo">
<dead-letter-address>DLA</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
<redelivery-delay>5000</redelivery-delay>
<expiry-address>ExpiryQueue</expiry-address>
<last-value-queue>true</last-value-queue>
<max-size-bytes>100000</max-size-bytes>
<page-size-bytes>20000</page-size-bytes>
<redistribution-delay>0</redistribution-delay>
<send-to-dla-on-no-route>true</send-to-dla-on-no-route>
<address-full-policy>PAGE</address-full-policy>
<slow-consumer-threshold>-1</slow-consumer-threshold>
<slow-consumer-policy>NOTIFY</slow-consumer-policy>
<slow-consumer-check-period>5</slow-consumer-check-period>
</address-setting>
</address-settings>
```xml
<address-settings>
<address-setting match="order.foo">
<dead-letter-address>DLA</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
<redelivery-delay>5000</redelivery-delay>
<expiry-address>ExpiryQueue</expiry-address>
<last-value-queue>true</last-value-queue>
<max-size-bytes>100000</max-size-bytes>
<page-size-bytes>20000</page-size-bytes>
<redistribution-delay>0</redistribution-delay>
<send-to-dla-on-no-route>true</send-to-dla-on-no-route>
<address-full-policy>PAGE</address-full-policy>
<slow-consumer-threshold>-1</slow-consumer-threshold>
<slow-consumer-policy>NOTIFY</slow-consumer-policy>
<slow-consumer-check-period>5</slow-consumer-check-period>
</address-setting>
</address-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
@ -615,5 +616,4 @@ Default is `true`.
`config-delete-addresses`. How the broker should handle addresses deleted
on config reload, by delete policy: `OFF` or `FORCE`.
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
In this section we will give an overview of the Apache ActiveMQ Artemis high level
architecture.
## Core Architecture
# Core Architecture
Apache ActiveMQ Artemis core is designed simply as set of Plain Old Java Objects
(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)
JMS semantics are implemented by a JMS facade layer on the client
side.
JMS semantics are implemented by a JMS facade layer on the client side.
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
@ -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
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
messaging server and a number of protocol managers that provide support for
the various protocol mentioned earlier. Protocol managers are plugable
The normal stand-alone messaging broker configuration comprises a core
messaging broker and a number of protocol managers that provide support for
the various protocol mentioned earlier. Protocol managers are pluggable
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.
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)
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
application that requires messaging functionality internally but you
don't want to expose that as an Apache ActiveMQ Artemis server you can directly
instantiate and embed Apache ActiveMQ Artemis servers in your own application.
don't want to expose that as an Apache ActiveMQ Artemis broker you can directly
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).
## 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
(JCA) adaptor which enables it to be integrated easily into any Java EE

4
docs/user-manual/en/broker-plugins.md
View File

@ -24,14 +24,14 @@ has been instantiated.
```xml
<configuration ...>
...
...
<broker-plugins>
<broker-plugin class-name="some.plugin.UserPlugin">
<property key="property1" value="val_1" />
<property key="property2" value="val_2" />
</broker-plugin>
</broker-plugins>
...
...
</configuration>
```

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

@ -1,6 +1,6 @@
# Clusters
## Clusters Overview
## Overview
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
@ -91,16 +91,18 @@ Apache ActiveMQ Artemis server. All broadcast groups must be defined in a
Let's take a look at an example broadcast group from
`broker.xml` that defines a UDP broadcast group:
<broadcast-groups>
<broadcast-group name="my-broadcast-group">
<local-bind-address>172.16.9.3</local-bind-address>
<local-bind-port>5432</local-bind-port>
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
<broadcast-period>2000</broadcast-period>
<connector-ref>netty-connector</connector-ref>
</broadcast-group>
</broadcast-groups>
```xml
<broadcast-groups>
<broadcast-group name="my-broadcast-group">
<local-bind-address>172.16.9.3</local-bind-address>
<local-bind-port>5432</local-bind-port>
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
<broadcast-period>2000</broadcast-period>
<connector-ref>netty-connector</connector-ref>
</broadcast-group>
</broadcast-groups>
```
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

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.
## 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,
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.
> 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
@ -77,7 +77,7 @@ attribute `roles` | N/A* | X* | Changing the ‘roles’ value means updating th
> * `N/A` means this operation is not applicable.
> * `X` means this operation is not allowed.
#### Parameters under `<address-settings>`
#### `<address-settings>`
* `<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.
#### Parameters under `<diverts>`
#### `<diverts>`
All `<divert>` elements will be reloaded. Each `<divert>` element
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)
`<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
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
`<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.
@ -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 `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.
@ -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
`<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.

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

@ -3,15 +3,17 @@
In this chapter we'll describe the concepts required for understanding
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
*acceptor*. Let's dive straight in and take a look at an acceptor
defined in xml in the configuration file `broker.xml`.
<acceptors>
<acceptor name="netty">tcp://localhost:61617</acceptor>
</acceptors>
```xml
<acceptors>
<acceptor name="netty">tcp://localhost:61617</acceptor>
</acceptors>
```
Acceptors are always defined inside an `acceptors` element. There can be
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
`URL` as part of the query, like so:
<acceptor name="netty">tcp://localhost:61617?sslEnabled=true&keyStorePath=/path</acceptor>
```xml
<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
connections, connectors are used to define how to connect to a server.
Let's look at a connector defined in our `broker.xml` file:
<connectors>
<connector name="netty">tcp://localhost:61617</connector>
</connectors>
```xml
<connectors>
<connector name="netty">tcp://localhost:61617</connector>
</connectors>
```
Connectors can be defined inside a `connectors` element. There can be
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.
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
that it needs to connect with a server?
@ -77,7 +83,7 @@ connect directly to the acceptor we defined earlier in this chapter, it
uses the standard Netty TCP transport and will try and connect on port
61617 to localhost (default):
``` java
```java
ServerLocator locator = ActiveMQClient.createServerLocator("tcp://localhost:61617");
ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
@ -88,7 +94,7 @@ ClientSession session = sessionFactory.createSession(...);
Similarly, if you're using JMS, you can configure the JMS connection
factory directly on the client side:
``` java
```java
ConnectionFactory connectionFactory = new ActiveMQConnectionFactory("tcp://localhost:61617");
Connection jmsConnection = connectionFactory.createConnection();
@ -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.
## Single Port Support
### Single Port Support
Apache ActiveMQ Artemis supports using a single port for all
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
`protocols` parameter on the Acceptor like so:
<acceptor name="netty">tcp://localhost:61617?protocols=CORE,AMQP</acceptor>
```xml
<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
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
to restart server to take effect.
## Configuring Netty Native Transport
### Configuring Netty Native Transport
Netty Native Transport support exists for selected OS platforms.
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`
## Configuring Netty SSL
### Configuring Netty SSL
Netty SSL is similar to the Netty TCP transport but it provides
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
scenarios where firewalls only allow HTTP traffic to pass.

12
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
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
practice that it should close its resources in a controlled manner,
@ -13,7 +13,7 @@ using a `finally` block.
Here's an example of a well behaved core client application closing its
session and session factory in a finally block:
``` java
```java
ServerLocator locator = null;
ClientSessionFactory sf = null;
ClientSession session = null;
@ -49,7 +49,7 @@ finally
And here's an example of a well behaved JMS client application:
``` java
```java
Connection jmsConnection = null;
try
@ -72,7 +72,7 @@ finally
Or with using auto-closeable feature from Java, which can save a few lines of code:
``` java
```java
try (
@ -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
`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
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
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
server and how "dead" connection resources are cleaned up by the server.

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

@ -41,30 +41,32 @@ server. They do this by using duplicate detection (described in [Duplicate Detec
Bridges are configured in `broker.xml`. Let's kick off
with an example (this is actually from the bridge example):
<bridge name="my-bridge">
<queue-name>sausage-factory</queue-name>
<forwarding-address>mincing-machine</forwarding-address>
<filter string="name='aardvark'"/>
<transformer-class-name>
org.apache.activemq.artemis.jms.example.HatColourChangeTransformer
</transformer-class-name>
<retry-interval>1000</retry-interval>
<ha>true</ha>
<retry-interval-multiplier>1.0</retry-interval-multiplier>
<initial-connect-attempts>-1</initial-connect-attempts>
<reconnect-attempts>-1</reconnect-attempts>
<failover-on-server-shutdown>false</failover-on-server-shutdown>
<use-duplicate-detection>true</use-duplicate-detection>
<confirmation-window-size>10000000</confirmation-window-size>
<user>foouser</user>
<password>foopassword</password>
<static-connectors>
<connector-ref>remote-connector</connector-ref>
</static-connectors>
<!-- alternative to static-connectors
<discovery-group-ref discovery-group-name="bridge-discovery-group"/>
-->
</bridge>
```xml
<bridge name="my-bridge">
<queue-name>sausage-factory</queue-name>
<forwarding-address>mincing-machine</forwarding-address>
<filter string="name='aardvark'"/>
<transformer-class-name>
org.apache.activemq.artemis.jms.example.HatColourChangeTransformer
</transformer-class-name>
<retry-interval>1000</retry-interval>
<ha>true</ha>
<retry-interval-multiplier>1.0</retry-interval-multiplier>
<initial-connect-attempts>-1</initial-connect-attempts>
<reconnect-attempts>-1</reconnect-attempts>
<failover-on-server-shutdown>false</failover-on-server-shutdown>
<use-duplicate-detection>true</use-duplicate-detection>
<confirmation-window-size>10000000</confirmation-window-size>
<user>foouser</user>
<password>foopassword</password>
<static-connectors>
<connector-ref>remote-connector</connector-ref>
</static-connectors>
<!-- alternative to static-connectors
<discovery-group-ref discovery-group-name="bridge-discovery-group"/>
-->
</bridge>
```
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

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`.
## What would you expect
## What to Expect
- You will see some logs

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

@ -68,15 +68,17 @@ address. Matching messages do not get routed to the old address.
Here's some example xml configuration for an exclusive divert, it's
taken from the divert example:
<divert name="prices-divert">
<address>priceUpdates</address>
<forwarding-address>priceForwarding</forwarding-address>
<filter string="office='New York'"/>
<transformer-class-name>
org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer
</transformer-class-name>
<exclusive>true</exclusive>
</divert>
```xml
<divert name="prices-divert">
<address>priceUpdates</address>
<forwarding-address>priceForwarding</forwarding-address>
<filter string="office='New York'"/>
<transformer-class-name>
org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer
</transformer-class-name>
<exclusive>true</exclusive>
</divert>
```
We define a divert called `prices-divert` that will divert any
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
non-exclusive divert, again from the divert example:
<divert name="order-divert">
<address>orders</address>
<forwarding-address>spyTopic</forwarding-address>
<exclusive>false</exclusive>
</divert>
```xml
<divert name="order-divert">
<address>orders</address>
<forwarding-address>spyTopic</forwarding-address>
<exclusive>false</exclusive>
</divert>
```
The above divert example takes a copy of every message sent to the
address '`orders`' and sends it to a local address called

4
docs/user-manual/en/duplicate-detection.md
View File

@ -73,7 +73,7 @@ by generating a UUID.
Here's an example of setting the property using the core API:
``` java
```java
...
ClientMessage message = session.createMessage(true);
@ -86,7 +86,7 @@ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
And here's an example using the JMS API:
``` java
```java
...
Message jmsMessage = session.createMessage();

8
docs/user-manual/en/embedding-activemq.md
View File

@ -29,7 +29,7 @@ For instantiating a core Apache ActiveMQ Artemis Server, the steps are pretty
simple. The example requires that you have defined a configuration file
`broker.xml` in your classpath:
``` java
```java
import org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
...
@ -83,7 +83,7 @@ The acceptors are configured through `ConfigurationImpl`. Just add the
`NettyAcceptorFactory` on the transports the same way you would through
the main configuration file.
``` java
```java
import org.apache.activemq.artemis.core.config.Configuration;
import org.apache.activemq.artemis.core.config.impl.ConfigurationImpl;
@ -102,7 +102,7 @@ You need to instantiate an instance of
`org.apache.activemq.artemis.api.core.server.embedded.EmbeddedActiveMQ` and add
the configuration object to it.
``` java
```java
import org.apache.activemq.artemis.api.core.server.ActiveMQ;
import org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
@ -116,7 +116,7 @@ server.start();
You also have the option of instantiating `ActiveMQServerImpl` directly:
``` java
```java
ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();
```

15
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:
- features - Examples containing broker specific features.
- ha - examples showing failover and reconnection 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
- standard - examples demonstrating various broker features.
- sub-modules - examples of integrated external modules.
- protocols - Protocol specific examples
- openwire
- mqtt
- stomp
- amqp
A set of Java EE examples are also provided which need WildFly installed to be able to run.
- mqtt
- openwire
- stomp
Running the Examples
=====================
@ -32,7 +31,7 @@ For each server, you will have a created server under `./target/server0` (some e
You have the option to prevent the example from starting the server (e.g. if you want to start the server manually) by
simply specifying the `-PnoServer` profile, e.g.:
``` sh
```sh
# running an example without running the server
mvn verify -PnoServer
```
@ -47,7 +46,7 @@ generated by the `Queue` example. This is useful to see exactly what command(s)
Several examples use UDP clustering which may not work in your environment by default. On linux the command would be:
``` sh
```sh
route add -net 224.0.0.0 netmask 240.0.0.0 dev lo
```

20
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
Exclusive queues can be pre configured at the address queue level
Exclusive queues can be statically configured using the `exclusive` boolean property:
```xml
<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.
Queue queue = session.createQueue("my.destination.name?exclusive=true");
Topic topic = session.createTopic("my.destination.name?exclusive=true");
```java
Queue queue = session.createQueue("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:
<address-setting match="lastValueQueue">
<default-exclusive-queue>true</default-exclusive-queue>
</address-setting>
```xml
<address-setting match="lastValueQueue">
<default-exclusive-queue>true</default-exclusive-queue>
</address-setting>
```
By default, `exclusive-queue` is false. Address wildcards can be used
to configure Exclusive queues for a set of addresses (see [here](wildcard-syntax.md)).
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)).
## Example

22
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
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)
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.
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
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:
<address-settings>
<address-setting match="exampleQueue">
<max-size-bytes>100000</max-size-bytes>
<address-full-policy>BLOCK</address-full-policy>
</address-setting>
</address-settings>
```xml
<address-settings>
<address-setting match="exampleQueue">
<max-size-bytes>100000</max-size-bytes>
<address-full-policy>BLOCK</address-full-policy>
</address-setting>
</address-settings>
```
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
@ -212,7 +216,7 @@ control.
> a misbehaving client to ignore the flow control credits issued by the broker
> 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
AMQP. Both protocols implement flow control slightly differently and therefore address full BLOCK policy behaves slightly

353
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
`ha-policy` configuration element.
<ha-policy>
<replication/>
</ha-policy>
```xml
<ha-policy>
<replication/>
</ha-policy>
```
or
<ha-policy>
<shared-store/>
</ha-policy>
```xml
<ha-policy>
<shared-store/>
</ha-policy>
```
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
@ -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
backup). This would look something like:
<ha-policy>
<replication>
<master/>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<master/>
</replication>
</ha-policy>
```
or
<ha-policy>
<shared-store/>
<slave/>
</shared-store/>
</ha-policy>
```xml
<ha-policy>
<shared-store>
<slave/>
</shared-store>
</ha-policy>
```
or
<ha-policy>
<replication>
<colocated/>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<colocated/>
</replication>
</ha-policy>
```
### 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,
configure the live server in ' `broker.xml` to have:
<ha-policy>
<replication>
<master/>
</replication>
</ha-policy>
.
<cluster-connections>
<cluster-connection name="my-cluster">
...
</cluster-connection>
</cluster-connections>
```xml
<ha-policy>
<replication>
<master/>
</replication>
</ha-policy>
...
<cluster-connections>
<cluster-connection name="my-cluster">
...
</cluster-connection>
</cluster-connections>
```
The backup server must be similarly configured but as a `slave`
<ha-policy>
<replication>
<slave/>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<slave/>
</replication>
</ha-policy>
```
#### All Replication Configuration
@ -365,27 +374,29 @@ on amount of data).
To configure the live and backup servers to share their store, configure
id via the `ha-policy` configuration in `broker.xml`:
<ha-policy>
<shared-store>
<master/>
</shared-store>
</ha-policy>
.
<cluster-connections>
<cluster-connection name="my-cluster">
...
</cluster-connection>
</cluster-connections>
```xml
<ha-policy>
<shared-store>
<master/>
</shared-store>
</ha-policy>
...
<cluster-connections>
<cluster-connection name="my-cluster">
...
</cluster-connection>
</cluster-connections>
```
The backup server must also be configured as a backup.
<ha-policy>
<shared-store>
<slave/>
</shared-store>
</ha-policy>
```xml
<ha-policy>
<shared-store>
<slave/>
</shared-store>
</ha-policy>
```
In order for live - backup groups to operate properly with a shared
store, both servers must have configured the location of journal
@ -413,13 +424,15 @@ Alternatively you can set `allow-fail-back` to `true` on the slave
config which will force the backup that has become live to automatically
stop. This configuration would look like:
<ha-policy>
<shared-store>
<slave>
<allow-failback>true</allow-failback>
</slave>
</shared-store>
</ha-policy>
```xml
<ha-policy>
<shared-store>
<slave>
<allow-failback>true</allow-failback>
</slave>
</shared-store>
</ha-policy>
```
In replication HA mode you need to set an extra property
`check-for-live-server` to `true` in the `master` configuration. If set
@ -435,13 +448,15 @@ and if there was if the server that took its duties is still running or
not. To configure this option at your `broker.xml`
configuration file as follows:
<ha-policy>
<replication>
<master>
<check-for-live-server>true</check-for-live-server>
</master>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<master>
<check-for-live-server>true</check-for-live-server>
</master>
</replication>
</ha-policy>
```
> **Warning**
>
@ -455,13 +470,15 @@ occur on normal server shutdown, to enable this set the following
property to true in the `ha-policy` configuration on either the `master`
or `slave` like so:
<ha-policy>
<shared-store>
<master>
<failover-on-shutdown>true</failover-on-shutdown>
</master>
</shared-store>
</ha-policy>
```xml
<ha-policy>
<shared-store>
<master>
<failover-on-shutdown>true</failover-on-shutdown>
</master>
</shared-store>
</ha-policy>
```
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
@ -472,13 +489,15 @@ server comes back up allowing the original live server to take over
automatically by setting the following property in the
`broker.xml` configuration file as follows:
<ha-policy>
<shared-store>
<slave>
<allow-failback>true</allow-failback>
</slave>
</shared-store>
</ha-policy>
```xml
<ha-policy>
<shared-store>
<slave>
<allow-failback>true</allow-failback>
</slave>
</shared-store>
</ha-policy>
```
#### All Shared Store Configuration
@ -563,18 +582,20 @@ can evenly distribute backups around the cluster. This is configured via
the `ha-policy` element in the `broker.xml` file like
so:
<ha-policy>
<replication>
<colocated>
<request-backup>true</request-backup>
<max-backups>1</max-backups>
<backup-request-retries>-1</backup-request-retries>
<backup-request-retry-interval>5000</backup-request-retry-interval>
<master/>
<slave/>
</colocated>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<colocated>
<request-backup>true</request-backup>
<max-backups>1</max-backups>
<backup-request-retries>-1</backup-request-retries>
<backup-request-retry-interval>5000</backup-request-retry-interval>
<master/>
<slave/>
</colocated>
</replication>
</ha-policy>
```
the above example is configured to use replication, in this case the
@ -605,14 +626,16 @@ Connector used by the cluster connection to do quorum voting for a
replicated backup server, these can be omitted from being offset by
adding them to the `ha-policy` configuration like so:
<ha-policy>
<replication>
<colocated>
<excludes>
<connector-ref>remote-connector</connector-ref>
</excludes>
.........
</ha-policy>
```xml
<ha-policy>
<replication>
<colocated>
<excludes>
<connector-ref>remote-connector</connector-ref>
</excludes>
.........
</ha-policy>
```
#### Configuring Directories
@ -684,15 +707,17 @@ 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
like:
<ha-policy>
<live-only>
<scale-down>
<connectors>
<connector-ref>server1-connector</connector-ref>
</connectors>
</scale-down>
</live-only>
</ha-policy>
```xml
<ha-policy>
<live-only>
<scale-down>
<connectors>
<connector-ref>server1-connector</connector-ref>
</connectors>
</scale-down>
</live-only>
</ha-policy>
```
In this instance the server is configured to use a specific connector to
@ -701,14 +726,15 @@ 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,
this would look like:
<ha-policy>
<live-only>
<scale-down>
<discovery-group-ref discovery-group-name="my-discovery-group"/>
</scale-down>
</live-only>
</ha-policy>
```xml
<ha-policy>
<live-only>
<scale-down>
<discovery-group-ref discovery-group-name="my-discovery-group"/>
</scale-down>
</live-only>
</ha-policy>
```
#### Scale Down with groups
@ -716,15 +742,16 @@ 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
like so:
<ha-policy>
<live-only>
<scale-down>
...
<group-name>my-group</group-name>
</scale-down>
</live-only>
</ha-policy>
```xml
<ha-policy>
<live-only>
<scale-down>
...
<group-name>my-group</group-name>
</scale-down>
</live-only>
</ha-policy>
```
In this scenario only servers that belong to the group `my-group` will
be scaled down to
@ -740,34 +767,36 @@ they will automatically be backed up by server and as live servers are
shutdown, there messages are made available on another live server. A
typical configuration would look like:
<ha-policy>
<replication>
<colocated>
<backup-request-retries>44</backup-request-retries>
<backup-request-retry-interval>33</backup-request-retry-interval>
<max-backups>3</max-backups>
<request-backup>false</request-backup>
<backup-port-offset>33</backup-port-offset>
<master>
<group-name>purple</group-name>
<check-for-live-server>true</check-for-live-server>
<cluster-name>abcdefg</cluster-name>
</master>
<slave>
<group-name>tiddles</group-name>
<max-saved-replicated-journals-size>22</max-saved-replicated-journals-size>
<cluster-name>33rrrrr</cluster-name>
<restart-backup>false</restart-backup>
<scale-down>
<!--a grouping of servers that can be scaled down to-->
<group-name>boo!</group-name>
<!--either a discovery group-->
<discovery-group-ref discovery-group-name="wahey"/>
</scale-down>
</slave>
</colocated>
</replication>
</ha-policy>
```xml
<ha-policy>
<replication>
<colocated>
<backup-request-retries>44</backup-request-retries>
<backup-request-retry-interval>33</backup-request-retry-interval>
<max-backups>3</max-backups>
<request-backup>false</request-backup>
<backup-port-offset>33</backup-port-offset>
<master>
<group-name>purple</group-name>
<check-for-live-server>true</check-for-live-server>
<cluster-name>abcdefg</cluster-name>
</master>
<slave>
<group-name>tiddles</group-name>
<max-saved-replicated-journals-size>22</max-saved-replicated-journals-size>
<cluster-name>33rrrrr</cluster-name>
<restart-backup>false</restart-backup>
<scale-down>
<!--a grouping of servers that can be scaled down to-->
<group-name>boo!</group-name>
<!--either a discovery group-->
<discovery-group-ref discovery-group-name="wahey"/>
</scale-down>
</slave>
</colocated>
</replication>
</ha-policy>
```
#### Scale Down and Clients

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

@ -13,7 +13,7 @@ All interceptors are protocol specific.
An interceptor for the core protocol must implement the interface `Interceptor`:
``` java
```java
package org.apache.activemq.artemis.api.core.interceptor;
public interface Interceptor
@ -24,7 +24,7 @@ public interface Interceptor
For stomp protocol an interceptor must implement the interface `StompFrameInterceptor`:
``` java
```java
package org.apache.activemq.artemis.core.protocol.stomp;
public interface StompFrameInterceptor extends BaseInterceptor<StompFrame>
@ -35,7 +35,7 @@ public interface StompFrameInterceptor extends BaseInterceptor<StompFrame>
Likewise for MQTT protocol, an interceptor must implement the interface `MQTTInterceptor`:
``` java
```java
package org.apache.activemq.artemis.core.protocol.mqtt;
public interface MQTTInterceptor extends BaseInterceptor<MqttMessage>
@ -57,15 +57,17 @@ The returned boolean value is important:
Both incoming and outgoing interceptors are configured in
`broker.xml`:
<remoting-incoming-interceptors>
<class-name>org.apache.activemq.artemis.jms.example.LoginInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-incoming-interceptors>
```xml
<remoting-incoming-interceptors>
<class-name>org.apache.activemq.artemis.jms.example.LoginInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-incoming-interceptors>
<remoting-outgoing-interceptors>
<class-name>org.apache.activemq.artemis.jms.example.LogoutInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-outgoing-interceptors>
<remoting-outgoing-interceptors>
<class-name>org.apache.activemq.artemis.jms.example.LogoutInterceptor</class-name>
<class-name>org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor</class-name>
</remoting-outgoing-interceptors>
```
See the documentation on [adding runtime dependencies](using-server.md) to
understand how to make your interceptor available to the broker.

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

@ -31,13 +31,15 @@ The configuration property `large-messages-directory` specifies where
large messages are stored. For JDBC persistence the `large-message-table`
should be configured.
<configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:activemq /schema/artemis-server.xsd">
...
<large-messages-directory>/data/large-messages</large-messages-directory>
...
</configuration
```xml
<configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:activemq /schema/artemis-server.xsd">
...
<large-messages-directory>/data/large-messages</large-messages-directory>
...
</configuration
```
By default the large message directory is `data/largemessages` and `large-message-table` is
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
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.
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
or JMS connection factory.
### Compressed Large Messages
## Compressed Large Messages
You can choose to send large messages in compressed form using
`compressLargeMessages` URL parameter.
#### `compressLargeMessages`
If you specify the boolean URL parameter `compressLargeMessages` as true,
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
@ -220,7 +220,7 @@ messageReceived.setObjectProperty("JMS_AMQ_OutputStream", bufferedOutput);
> When using JMS, Streaming large messages are only supported on
> `StreamMessage` and `BytesMessage`.
## Streaming Alternative
### Streaming Alternative
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

17
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
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
<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:
<address-setting match="lastValueQueue">
<default-last-value-queue>true</default-last-value-queue>
</address-setting>
```xml
<address-setting match="lastValueQueue">
<default-last-value-queue>true</default-last-value-queue>
</address-setting>
```
By default, `default-last-value-queue` is false.
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.
## Using Last-Value Property
## Last-Value Property
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).
@ -53,7 +56,7 @@ For example, if two messages with the same value for the Last-Value
property are sent to a Last-Value queue, only the latest message will be
kept in the queue:
``` java
```java
// send 1st message with Last-Value property set to STOCK_NAME
TextMessage message = session.createTextMessage("1st message with Last-Value property set");
message.setStringProperty("_AMQ_LVQ_NAME", "STOCK_NAME");

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

50
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
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:
#### Apache ActiveMQ Artemis Server Management
#### Server 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
`jmx-domain` in `broker.xml`:
<!-- use a specific JMX domain for ActiveMQ Artemis MBeans -->
<jmx-domain>my.org.apache.activemq</jmx-domain>
```xml
<!-- use a specific JMX domain for ActiveMQ Artemis MBeans -->
<jmx-domain>my.org.apache.activemq</jmx-domain>
```
### 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
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*.
*Management messages* are regular Core Client messages with well-known
@ -537,7 +539,7 @@ operations using Core messages:
For example, to find out the number of messages in the queue
`exampleQueue`:
``` java
```java
ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "activemq.management");
ClientMessage message = session.createMessage(false);
@ -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
configured in broker.xml:
<!-- users with the admin role will be allowed to manage -->
<!-- Apache ActiveMQ Artemis using management messages -->
<security-setting match="activemq.management">
<permission type="manage" roles="admin" />
</security-setting>
```xml
<!-- users with the admin role will be allowed to manage -->
<!-- Apache ActiveMQ Artemis using management messages -->
<security-setting match="activemq.management">
<permission type="manage" roles="admin" />
</security-setting>
```
### Example
@ -626,7 +630,9 @@ of all the notifications emitted by the server.
The management notification address to receive management notifications
is configured in `broker.xml`:
<management-notification-address>activemq.notifications</management-notification-address>
```xml
<management-notification-address>activemq.notifications</management-notification-address>
```
By default, the address is `activemq.notifications`.
@ -634,7 +640,7 @@ By default, the address is `activemq.notifications`.
Apache ActiveMQ Artemis's Core JMS Client can be used to receive notifications:
``` java
```java
Topic notificationsTopic = ActiveMQJMSClient.createTopic("activemq.notifications");
Session session = ...
@ -819,7 +825,9 @@ negative effect on memory.
To enable message counters, you can set it to `true` in
`broker.xml`:
<message-counter-enabled>true</message-counter-enabled>
```xml
<message-counter-enabled>true</message-counter-enabled>
```
Message counters keep a history of the queue metrics (10 days by
default) and sample all the queues at regular interval (10 seconds by
@ -827,15 +835,17 @@ default). If message counters are enabled, these values should be
configured to suit your messaging use case in
`broker.xml`:
<!-- keep history for a week -->
<message-counter-max-day-history>7</message-counter-max-day-history>
<!-- sample the queues every minute (60000ms) -->
<message-counter-sample-period>60000</message-counter-sample-period>
```xml
<!-- keep history for a week -->
<message-counter-max-day-history>7</message-counter-max-day-history>
<!-- sample the queues every minute (60000ms) -->
<message-counter-sample-period>60000</message-counter-sample-period>
```
Message counters can be retrieved using the Management API. For example,
to retrieve message counters on a queue using JMX:
``` java
```java
// retrieve a connection to Apache ActiveMQ Artemis's MBeanServer
MBeanServerConnection mbsc = ...
QueueControlMBean queueControl = (QueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,

41
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
in a configuration file should be treated as 'masked'. For example:
```
```xml
<mask-password>true</mask-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.
##### Passwords in connectors and acceptors
##### Connectors & Acceptors
In broker.xml `connector` and `acceptor` configurations sometimes needs to
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.
##### Passwords in bridge configurations
##### Core Bridges
Core Bridges are configured in the server configuration file and so the
masking of its `password` properties follows the same rules as that of
`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
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
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
@ -145,14 +145,14 @@ You can also set the `passwordCodec` attribute if you want to use a password cod
other than the default one. For example
```xml
<web bind="https://localhost:8443" path="web"
keyStorePassword="ENC(-5a2376c61c668aaf)"
trustStorePassword="ENC(3d617352d12839eb71208edf41d66b34)">
<app url="activemq-branding" war="activemq-branding.war"/>
</web>
<web bind="https://localhost:8443" path="web"
keyStorePassword="ENC(-5a2376c61c668aaf)"
trustStorePassword="ENC(3d617352d12839eb71208edf41d66b34)">
<app url="activemq-branding" war="activemq-branding.war"/>
</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
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
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
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
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
file (default name is `login.config`). When connecting to a LDAP server usually
@ -310,7 +310,7 @@ can also be service loaded rather than class loaded, if the decoder's service pr
Then configure the server to use it as follows:
```xml
<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>
<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>
```
If your decoder needs params passed to it you can do this via key/value
@ -318,27 +318,27 @@ pairs when configuring. For instance if your decoder needs say a
"key-location" parameter, you can define like so:
```xml
<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>
<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>
```
Then configure your cluster-password like this:
```xml
<cluster-password>ENC(masked_password)</cluster-password>
<cluster-password>ENC(masked_password)</cluster-password>
```
When Apache ActiveMQ Artemis reads the cluster-password it will initialize the
NewDecoder and use it to decode "mask\_password". It also process all
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
from existing libraries or you implement it yourself. All decoders must
implement the `org.apache.activemq.artemis.utils.SensitiveDataCodec<T>`
interface:
``` java
```java
public interface SensitiveDataCodec<T>
{
T decode(Object mask) throws Exception;
@ -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
classpath by packaging it in a JAR file and putting the JAR file in the `lib`
directory. Otherwise Apache ActiveMQ Artemis will fail to load it!
Last but not least, once you get your own decoder please [add it to the
classpath](using-server.md#adding-runtime-dependencies) otherwise the broker will fail to load it!

24
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.
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
message:
// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
```java
// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
```
JMS MessageProducer allows to set a TimeToLive for the messages it sent:
// messages sent by this producer will be retained for 5s (5000ms) before expiration
producer.setTimeToLive(5000);
```java
// messages sent by this producer will be retained for 5s (5000ms) before expiration
producer.setTimeToLive(5000);
```
Expired messages which are consumed from an expiry address have the
following properties:
@ -46,10 +50,12 @@ following properties:
Expiry address are defined in the address-setting configuration:
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
<address-setting match="exampleQueue">
<expiry-address>expiryQueue</expiry-address>
</address-setting>
```xml
<!-- expired messages in exampleQueue will be sent to the expiry address expiryQueue -->
<address-setting match="exampleQueue">
<expiry-address>expiryQueue</expiry-address>
</address-setting>
```
If messages are expired and no expiry address is specified, messages are
simply removed from the queue and dropped. Address wildcards can be used

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

@ -102,17 +102,19 @@ message should take.
Here is a sample config for each type of handler. This should be
configured in `broker.xml`.
<grouping-handler name="my-grouping-handler">
<type>LOCAL</type>
<address>jms</address>
<timeout>5000</timeout>
</grouping-handler>
```xml
<grouping-handler name="my-grouping-handler">
<type>LOCAL</type>
<address>jms</address>
<timeout>5000</timeout>
</grouping-handler>
<grouping-handler name="my-grouping-handler">
<type>REMOTE</type>
<address>jms</address>
<timeout>5000</timeout>
</grouping-handler>
<grouping-handler name="my-grouping-handler">
<type>REMOTE</type>
<address>jms</address>
<timeout>5000</timeout>
</grouping-handler>
```
- `type` two types of handlers are supported - `LOCAL` and `REMOTE`.
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
capable of, then you can skip this chapter.
## Messaging Concepts
## General Concepts
Messaging systems allow you to loosely couple heterogeneous systems
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.
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
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
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
entity on the server, often called a *topic* (e.g. in the JMS world).

20
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
@ -68,18 +68,20 @@ that address alone goes into page mode.
> total overall size of all matching addresses is limited to
> max-size-bytes.
## Configuration
### Configuration
Configuration is done at the address settings, done at the main
configuration file (`broker.xml`).
<address-settings>
<address-setting match="jms.someaddress">
<max-size-bytes>104857600</max-size-bytes>
<page-size-bytes>10485760</page-size-bytes>
<address-full-policy>PAGE</address-full-policy>
</address-setting>
</address-settings>
```xml
<address-settings>
<address-setting match="jms.someaddress">
<max-size-bytes>104857600</max-size-bytes>
<page-size-bytes>10485760</page-size-bytes>
<address-full-policy>PAGE</address-full-policy>
</address-setting>
</address-settings>
```
This is the list of available parameters on the address settings.

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

@ -1,16 +1,14 @@
# Persistence
In this chapter we will describe how persistence works with Apache ActiveMQ Artemis and
how to configure it.
Apache ActiveMQ Artemis ships with two persistence options. The file journal which is
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
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).
## File Journal (Default)
## Apache ActiveMQ Artemis File Journal (Default)
An Apache ActiveMQ Artemis file journal is an *append only* journal. It consists of a set of
The 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
filled with padding. As operations are performed on the server, e.g. add
message, update message, delete message, records are appended to the
@ -45,49 +43,50 @@ The majority of the journal is written in Java, however we abstract out
the interaction with the actual file system to allow different pluggable
implementations. 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 file system. This provides extremely good performance and runs
on any platform where there's a Java 6+ runtime.
The first implementation uses standard Java NIO to interface with
the file system. This provides extremely good performance and runs
on any platform where there's a Java 6+ runtime.
- Linux Asynchronous IO
### Linux Asynchronous IO
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
called back when the data has made it to disk, allowing us to avoid
explicit syncs altogether and simply send back confirmation of
completion when AIO informs us that the data has been persisted.
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
called back when the data has made it to disk, allowing us to avoid
explicit syncs altogether and simply send back confirmation of
completion when AIO informs us that the data has been persisted.
Using AIO will typically provide even better performance than using
Java NIO.
Using AIO will typically provide even better performance than using Java NIO.
The AIO journal is only available when running Linux kernel 2.6 or
later and after having installed libaio (if it's not already
installed). For instructions on how to install libaio please see Installing AIO section.
The AIO journal is only available when running Linux kernel 2.6 or
later and after having installed libaio (if it's not already
installed). For instructions on how to install libaio please see Installing AIO section.
Also, please note that AIO will only work with the following file
systems: ext2, ext3, ext4, jfs, xfs and NFSV4.
Also, please note that AIO will only work with the following file
systems: ext2, ext3, ext4, jfs, xfs and NFSV4.
For more information on libaio please see [lib AIO](libaio.md).
For more information on libaio please see [lib AIO](libaio.md).
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)
memory mapping against the OS page cache to interface with the file system.
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.
This provides extremely good performance (especially under strictly process failure durability requirements),
almost zero copy (actually *is* the kernel page cache) and zero garbage (from the Java HEAP perspective) operations and runs
on any platform where there's a Java 4+ runtime.
This provides extremely good performance (especially under strictly process failure durability requirements),
almost zero copy (actually *is* the kernel page cache) and zero garbage (from the Java HEAP perspective) operations and runs
on any platform where there's a Java 4+ runtime.
Under power failure durability requirements it will perform at least on par with the NIO journal with the only
exception of Linux OS with kernel less or equals 2.6, in which the [*msync*](https://docs.oracle.com/javase/8/docs/api/java/nio/MappedByteBuffer.html#force%28%29)) implementation necessary to ensure
durable writes was different (and slower) from the [*fsync*](https://docs.oracle.com/javase/8/docs/api/java/nio/channels/FileChannel.html#force%28boolean%29) used is case of NIO journal.
Under power failure durability requirements it will perform at least on par with the NIO journal with the only
exception of Linux OS with kernel less or equals 2.6, in which the [*msync*](https://docs.oracle.com/javase/8/docs/api/java/nio/MappedByteBuffer.html#force%28%29)) implementation necessary to ensure
durable writes was different (and slower) from the [*fsync*](https://docs.oracle.com/javase/8/docs/api/java/nio/channels/FileChannel.html#force%28boolean%29) used is case of NIO journal.
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.
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.
### Standard Files
The standard Apache ActiveMQ Artemis core server uses two instances of the 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
the broker for Zero Persistence section.
### Configuring the bindings journal
#### Configuring the bindings journal
The bindings journal is configured using the following attributes in
`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
is `true`
### Configuring the jms journal
#### Configuring the jms 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
`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
*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
> 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
> 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**
>
@ -379,7 +378,7 @@ Using aptitude, (e.g. on Ubuntu or Debian system):
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.
@ -411,16 +410,16 @@ To configure Apache ActiveMQ Artemis to use a database for persisting messages a
2. Create a store element in your broker.xml config file under the ```<core>``` element. For example:
```xml
<store>
<database-store>
<jdbc-connection-url>jdbc:derby:data/derby/database-store;create=true</jdbc-connection-url>
<bindings-table-name>BINDINGS_TABLE</bindings-table-name>
<message-table-name>MESSAGE_TABLE</message-table-name>
<page-store-table-name>MESSAGE_TABLE</page-store-table-name>
<large-message-table-name>LARGE_MESSAGES_TABLE</large-message-table-name>
<jdbc-driver-class-name>org.apache.derby.jdbc.EmbeddedDriver</jdbc-driver-class-name>
</database-store>
</store>
<store>
<database-store>
<jdbc-connection-url>jdbc:derby:data/derby/database-store;create=true</jdbc-connection-url>
<bindings-table-name>BINDINGS_TABLE</bindings-table-name>
<message-table-name>MESSAGE_TABLE</message-table-name>
<page-store-table-name>MESSAGE_TABLE</page-store-table-name>
<large-message-table-name>LARGE_MESSAGES_TABLE</large-message-table-name>
<jdbc-driver-class-name>org.apache.derby.jdbc.EmbeddedDriver</jdbc-driver-class-name>
</database-store>
</store>
```
- `jdbc-connection-url`
@ -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).
## Configuring Apache ActiveMQ Artemis for Zero Persistence
## Zero Persistence
In some situations, zero persistence is sometimes required for a
messaging system. Configuring Apache ActiveMQ Artemis to perform zero persistence is

6
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
`ActiveMQSession.PRE_ACKNOWLEDGE` constant.
// messages will be acknowledge on the server *before* being delivered to the client
Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);
```java
// messages will be acknowledge on the server *before* being delivered to the client
Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);
```
## Individual Acknowledge

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

@ -26,20 +26,22 @@ 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
protocols are enabled.
<!-- The following example enables only MQTT on port 1883 -->
<acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT</acceptor>
</acceptors>
```xml
<!-- The following example enables only MQTT on port 1883 -->
<acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT</acceptor>
</acceptors>
<!-- The following example enables MQTT and AMQP on port 61617 -->
<acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT,AMQP</acceptor>
</acceptors>
<!-- The following example enables MQTT and AMQP on port 61617 -->
<acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT,AMQP</acceptor>
</acceptors>
<!-- The following example enables all protocols on 61616 -->
<acceptors>
<acceptor>tcp://localhost:61616</acceptor>
</acceptors>
<!-- The following example enables all protocols on 61616 -->
<acceptors>
<acceptor>tcp://localhost:61616</acceptor>
</acceptors>
```
## AMQP
@ -48,7 +50,9 @@ Apache ActiveMQ Artemis supports the [AMQP
specification. To enable AMQP you must configure a Netty Acceptor to
receive AMQP clients, like so:
<acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor>
```xml
<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
@ -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
OpenWire support you must configure a Netty Acceptor, like so:
<acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor>
```xml
<acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor>
```
The Apache ActiveMQ Artemis server will then listens on port 61616 for incoming
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.
In an acceptor url it would be:
<acceptor name="artemis">tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2</acceptor>
```xml
<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
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
`protocols` parameter set to have `stomp`:
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor>
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor>
```
With this configuration, Apache ActiveMQ Artemis will accept Stomp connections on the
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.
For example:
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor>
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor>
```
The above configuration will make sure that any Stomp connection that is
created from that acceptor and does not include a `heart-beat` header
@ -550,19 +561,19 @@ 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
name of `mysubscription` then configure the durable subscription:
~~~
<core xmlns="urn:activemq:core">
...
<addresses>
<address name="myAddress">
<multicast>
<queue name="myclientid.mysubscription"/>
</multicast>
</address>
</addresses>
...
</core>
~~~
```xml
<core xmlns="urn:activemq:core">
...
<addresses>
<address name="myAddress">
<multicast>
<queue name="myclientid.mysubscription"/>
</multicast>
</address>
</addresses>
...
</core>
```
### 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
can be configured inside a stomp acceptor, as a parameter. For example:
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor>
```xml
<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor>
```
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
@ -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:
<acceptor name="stomp-ws-acceptor">tcp://localhost:61614?protocols=STOMP</acceptor>
```xml
<acceptor name="stomp-ws-acceptor">tcp://localhost:61614?protocols=STOMP</acceptor>
```
With this configuration, Apache ActiveMQ Artemis will accept Stomp connections over Web
Sockets on the port `61614`. Web browser can

14
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:
<resource-limit-settings>
<resource-limit-setting match="myUser">
<max-connections>5</max-connections>
<max-queues>3</max-queues>
</resource-limit-setting>
</resource-limit-settings>
```xml
<resource-limit-settings>
<resource-limit-setting match="myUser">
<max-connections>5</max-connections>
<max-queues>3</max-queues>
</resource-limit-setting>
</resource-limit-settings>
```
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.

2
docs/user-manual/en/scheduled-messages.md
View File

@ -15,7 +15,7 @@ The specified value must be a positive `long` corresponding to the time
the message must be delivered (in milliseconds). An example of sending a
scheduled message using the JMS API is as follows.
``` java
```java
TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
message.setLongProperty("_AMQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
producer.send(message);

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.
### 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
`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
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:
@ -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
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
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.
### 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.
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
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`
## Guarantees of Non Transactional Message Sends
## Non Transactional Message Sends
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
@ -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.
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
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
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
`org.apache.activemq.artemis.api.core.client.SendAcknowledgementHandler` and set
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
resources.
## Configuration required for detecting slow consumers
## Required Configuration
By default the server will not detect slow consumers. If slow consumer
detection is desired then see [address model chapter](address-model.md)

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

@ -13,21 +13,23 @@ automatically populate the Spring context with references to those beans
so that you can use them. Below is an example Spring JMS bean file
taking advantage of this feature:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
```xml
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
<bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
<bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/>
<bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
<bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/>
<bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
<property name="connectionFactory" ref="ConnectionFactory"/>
<property name="destination" ref="/queue/exampleQueue"/>
<property name="messageListener" ref="listener"/>
</bean>
</beans>
<bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
<property name="connectionFactory" ref="ConnectionFactory"/>
<property name="destination" ref="/queue/exampleQueue"/>
<property name="messageListener" ref="listener"/>
</bean>
</beans>
```
As you can see, the `listenerContainer` bean references the components
defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class

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

@ -3,10 +3,12 @@
### Header 3
#### Header 4
<xml>somexml</xml>
```xml
<xml>somexml</xml>
```
``` java
Somejava s = new SomeJava();
```java
Somejava s = new SomeJava();
```
> **Note**

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.
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/)
#### Example of Connection Factory
````
### Example of Connection Factory
```xml
<Context>
...
<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>
````
#### Example of Destination (Queue and Topic)
### Example of Destination (Queue and Topic)
````
```xml
<Context>
...
<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>
````
#### 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

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

@ -1,12 +1,9 @@
# Tools
You can use the artemis cli interface to execute data maintenance tools:
This is a list of sub-commands available
Name | Description
:--- | :---
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
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:
```
@ -219,6 +213,4 @@ COMMANDS
With --bindings option, The folder used for bindings (default from
broker.xml)
```

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

@ -35,16 +35,17 @@ consuming valuable CPU and network resources.
Delayed redelivery is defined in the address-setting configuration:
<!-- delay redelivery of messages for 5s -->
<address-setting match="exampleQueue">
<!-- default is 1.0 -->
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
<!-- default is 0 (no delay) -->
<redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay>
</address-setting>
```xml
<!-- delay redelivery of messages for 5s -->
<address-setting match="exampleQueue">
<!-- default is 1.0 -->
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
<!-- default is 0 (no delay) -->
<redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay>
</address-setting>
```
If a `redelivery-delay` is specified, Apache ActiveMQ Artemis will wait this delay
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:
<!-- undelivered messages in exampleQueue will be sent to the dead letter address
deadLetterQueue after 3 unsuccessful delivery attempts -->
<address-setting match="exampleQueue">
<dead-letter-address>deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
</address-setting>
```xml
<!-- undelivered messages in exampleQueue will be sent to the dead letter address
deadLetterQueue after 3 unsuccessful delivery attempts -->
<address-setting match="exampleQueue">
<dead-letter-address>deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
</address-setting>
```
If a `dead-letter-address` is not specified, messages will removed after
`max-delivery-attempts` unsuccessful attempts.
@ -167,4 +170,6 @@ due to performance implications.
To enable it, set `persist-delivery-count-before-delivery` to `true` in
`broker.xml`:
<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
```xml
<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
> 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
may require some specific steps noted in the [versions](versions.md), but the general
process is as follows:
Because of this separation it's very easy to upgrade Artemis in most cases.
## 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. Open `artemis.profile` (`artemis.profile.cmd` on Windows). It contains a property

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

@ -174,7 +174,7 @@ receive a message. Logically it's comprised of two sections: firstly
setting up the producer to write a message to an *addresss*, and
secondly, creating a *queue* for the consumer, creating the consumer and
*starting* it.
``` java
```java
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
InVMConnectorFactory.class.getName()));

27
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
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
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
without us having to explicitly create it from the client.
JNDI Configuration
==================
## JNDI Configuration
The JMS specification establishes the convention that *administered
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
> 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
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
like so:
<queue name="OrderQueue"/>
```xml
<queue name="OrderQueue"/>
```
And if the client wanted to bind this queue to "queues/OrderQueue" then
the JNDI properties would be configured like so:
@ -231,7 +230,7 @@ First we'll create a JNDI initial context from which to lookup our JMS
objects. If the above properties are set in `jndi.properties` and it is
on the classpath then any new, empty `InitialContext` will be
initialized using those properties:
``` java
```java
InitialContext ic = new InitialContext();
//Now we'll look up the connection factory from which we can create
@ -289,7 +288,7 @@ see the examples directory in the distribution.
> your application will perform very poorly. This is discussed further
> 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
*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory
@ -311,7 +310,7 @@ Utility class, note we need to provide connection parameters and specify
which transport we are using, for more information on connectors please
see [Configuring the Transport](configuring-transports.md).
``` java
```java
TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
@ -354,7 +353,7 @@ TextMessage receivedMessage = (TextMessage)consumer.receive();
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
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
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
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`
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
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.
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,
this can cause a performance issue and extra calls to the broker,

94
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
distribution has been extracted to as `${ARTEMIS_HOME}` directory.
Installation
============
## Installation
After downloading the distribution, the following highlights some important folders on the distribution:
|___ bin
|
|___ web
| |___ user-manual
| |___ api
|
|___ examples
| |___ core
| |___ javaee
| |___ jms
| |___ common
| |___ features
| |___ perf
| |___ protocols
|
|___ lib
| |___ client
|
|___ 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
examples' chapter for details on how to run them.
- `web` - The folder where the web context is loaded when the broker runs.
- `lib` -- jars and libraries needed to run ActiveMQ Artemis
- `api` - The api documentation is placed under the web folder.
- `licenses` -- licenses for ActiveMQ Artemis
- `schemas` -- XML Schemas used to validate ActiveMQ Artemis configuration
files
- `user-manual` - The user manual is placed under the web folder.
## Creating a Broker Instance
@ -77,7 +77,7 @@ A broker instance directory will contain the following sub directories:
At this point you may want to adjust the default configuration located in
the `etc` directory.
###Options
### Options
There are several options you can use when creating an instance.
For a full list of updated properties always use:
@ -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
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
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
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
supplied in that case.
## Bootstrap File
### Bootstrap configuration file
The stand-alone server is basically a set of POJOs which are
instantiated by Airline commands.
The bootstrap file is very simple. Let's take a look at an example:
<broker xmlns="http://activemq.org/schema">
```xml
<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"/>
</broker>
<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>
```
- 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
do all the real messaging work. In addition all JMS objects such as:
Queues, Topics and ConnectionFactory instances are configured here.
do all the real messaging work.
## 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
`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
reference [here](configuration-index.md).
Windows Server
==============
## Windows Server
On windows you will have the option to run ActiveMQ Artemis as a service.
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).
Highlights:
- [Exclusive consumers](address-model.md).
- [Exclusive consumers](exclusive-queues.md).
- Equivalent ActiveMQ 5.x Virtual Topic naming abilities.
- SSL Certificate revocation list.
- [Last-value queue](last-value-queues.md) support for OpenWire.
- 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`).
- Option to use OpenSSL provider for Netty.
- 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 via the [`sslProvider`](configuring-transports.md#configuring-netty-ssl) URL parameter.
- Enable [splitting of broker.xml into multiple files](configuration-index.md).
- 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).
Highlights:
- [JMX configuration via XML](management.md) 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).
- [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#stomp-over-web-sockets).
- Ability to configure HA using JDBC persistence.
- Implement [role-based access control for management objects](management.md).
@ -60,7 +60,7 @@ Highlights:
Highlights:
- [Web admin console](management-console.md)!
- [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
#### Upgrading from 2.2.0
@ -78,8 +78,8 @@ Highlights:
Highlights:
- Scheduled messages with the STOMP protocol.
- Support for JNDIReferenceFactory and JNDIStorable.
- Ability to delete queues and addresses when broker.xml changes.
- Client authentication via Kerberos TLS Cipher Suites (RFC 2712).
- Ability to delete queues and addresses when [broker.xml changes](config-reload.md).
- [Client authentication via Kerberos TLS Cipher Suites (RFC 2712)](security.md#kerberos-authentication).
## 2.1.0
@ -88,7 +88,7 @@ Highlights:
Highlights:
- [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.
- AMQP performance improvements.
@ -103,7 +103,7 @@ Highlights:
- Support for additional messaging use-cases.
- 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.
- ["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

8
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.
<wildcard-addresses>
<routing-enabled>false</routing-enabled>
</wildcard-addresses>
```xml
<wildcard-addresses>
<routing-enabled>false</routing-enabled>
</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,
also see the topic hierarchy example in the [examples](examples.md).

18
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
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
'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.
For that, the `<wildcard-addresses>` configuration tag is used.
<wildcard-addresses>
<routing-enabled>true</routing-enabled>
<delimiter>.</delimiter>
<any-words>#</any-words>
<single-word>*</single-word>
</wildcard-addresses>
```xml
<wildcard-addresses>
<routing-enabled>true</routing-enabled>
<delimiter>.</delimiter>
<any-words>#</any-words>
<single-word>*</single-word>
</wildcard-addresses>
```
The example above shows the default configuration.