From 86c9e7267b8775d1a2565f167e00f92ba837d851 Mon Sep 17 00:00:00 2001 From: Justin Bertram Date: Thu, 8 Mar 2018 14:46:38 -0600 Subject: [PATCH] NO-JIRA review docs for content, style, & format --- docs/user-manual/en/address-model.md | 134 +++---- docs/user-manual/en/architecture.md | 30 +- docs/user-manual/en/broker-plugins.md | 4 +- docs/user-manual/en/clusters.md | 24 +- docs/user-manual/en/config-reload.md | 20 +- docs/user-manual/en/configuring-transports.md | 44 ++- docs/user-manual/en/connection-ttl.md | 12 +- docs/user-manual/en/core-bridges.md | 50 +-- docs/user-manual/en/critical-analysis.md | 2 +- docs/user-manual/en/diverts.md | 32 +- docs/user-manual/en/duplicate-detection.md | 4 +- docs/user-manual/en/embedding-activemq.md | 8 +- docs/user-manual/en/examples.md | 15 +- docs/user-manual/en/exclusive-queues.md | 20 +- docs/user-manual/en/flow-control.md | 22 +- docs/user-manual/en/ha.md | 353 ++++++++++-------- .../user-manual/en/intercepting-operations.md | 24 +- docs/user-manual/en/large-messages.md | 24 +- docs/user-manual/en/last-value-queues.md | 17 +- docs/user-manual/en/management-console.md | 2 +- docs/user-manual/en/management.md | 50 ++- docs/user-manual/en/masking-passwords.md | 41 +- docs/user-manual/en/message-expiry.md | 24 +- docs/user-manual/en/message-grouping.md | 22 +- docs/user-manual/en/messaging-concepts.md | 6 +- docs/user-manual/en/paging.md | 20 +- docs/user-manual/en/persistence.md | 111 +++--- docs/user-manual/en/pre-acknowledge.md | 6 +- .../en/protocols-interoperability.md | 81 ++-- docs/user-manual/en/resource-limits.md | 14 +- docs/user-manual/en/scheduled-messages.md | 2 +- docs/user-manual/en/security.md | 8 +- docs/user-manual/en/send-guarantees.md | 10 +- docs/user-manual/en/slow-consumers.md | 2 +- docs/user-manual/en/spring-integration.md | 26 +- docs/user-manual/en/syntax.md | 8 +- docs/user-manual/en/tomcat.md | 16 +- docs/user-manual/en/tools.md | 8 - docs/user-manual/en/undelivered-messages.md | 39 +- docs/user-manual/en/upgrading.md | 9 +- docs/user-manual/en/using-core.md | 2 +- docs/user-manual/en/using-jms.md | 27 +- docs/user-manual/en/using-server.md | 94 +++-- docs/user-manual/en/versions.md | 20 +- docs/user-manual/en/wildcard-routing.md | 8 +- docs/user-manual/en/wildcard-syntax.md | 18 +- 46 files changed, 801 insertions(+), 712 deletions(-) diff --git a/docs/user-manual/en/address-model.md b/docs/user-manual/en/address-model.md index e205ddefe4..1673e21e89 100644 --- a/docs/user-manual/en/address-model.md +++ b/docs/user-manual/en/address-model.md @@ -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 /etc/broker.xml for editing. +Open the file `/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 /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 -
- - - -
+
+ + + +
``` 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 -
- - -
+
+ +
``` ```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 /etc/broker.xml and add the auto-create-addresses element to the address-setting you want the broker to automatically create. +- Edit the file `/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 @@ -259,15 +258,15 @@ The example below configures an address-setting to be automatically created by t ``` -### Configuring an Address to be Automatically Deleted +### Auto Address Deletion -Edit the file /etc/broker.xml and add the auto-delete-addresses element to the address-setting you want the broker to automatically create. +Edit the file `/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 @@ -284,12 +283,11 @@ The example below configures an address-setting to be automatically deleted by t ``` -## 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 /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 `/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 @@ -342,7 +340,7 @@ In /etc/broker.xml, add the anycastPrefix to the URL of the des ### Configuring a Multicast Prefix -In /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 `/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 @@ -358,17 +356,17 @@ In /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 /etc/broker.xml for editing. +Open the file `/etc/broker.xml` for editing. ```xml @@ -386,7 +384,7 @@ Open the file /etc/broker.xml for editing. ``` -#### 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 ``` -#### 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 /etc/broker.xml for editing. +Open the file `/etc/broker.xml` for editing. ```xml @@ -427,14 +425,15 @@ Open the file /etc/broker.xml for editing. ``` -#### 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 /etc/broker.xml for editing. +Open the file `/etc/broker.xml` for editing. ```xml @@ -449,16 +448,16 @@ Open the file /etc/broker.xml for editing. ``` -## 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. - - - DLA - 3 - 5000 - ExpiryQueue - true - 100000 - 20000 - 0 - true - PAGE - -1 - NOTIFY - 5 - - +```xml + + + DLA + 3 + 5000 + ExpiryQueue + true + 100000 + 20000 + 0 + true + PAGE + -1 + NOTIFY + 5 + + +``` 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`. \ No newline at end of file diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md index ee7d0d806f..80d70b2bf5 100644 --- a/docs/user-manual/en/architecture.md +++ b/docs/user-manual/en/architecture.md @@ -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 diff --git a/docs/user-manual/en/broker-plugins.md b/docs/user-manual/en/broker-plugins.md index c3e9801994..d0a704042d 100644 --- a/docs/user-manual/en/broker-plugins.md +++ b/docs/user-manual/en/broker-plugins.md @@ -24,14 +24,14 @@ has been instantiated. ```xml -... + ... -... + ... ``` diff --git a/docs/user-manual/en/clusters.md b/docs/user-manual/en/clusters.md index 65ac15d2ed..b3f4a77048 100644 --- a/docs/user-manual/en/clusters.md +++ b/docs/user-manual/en/clusters.md @@ -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: - - - 172.16.9.3 - 5432 - 231.7.7.7 - 9876 - 2000 - netty-connector - - +```xml + + + 172.16.9.3 + 5432 + 231.7.7.7 + 9876 + 2000 + netty-connector + + +``` 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 diff --git a/docs/user-manual/en/config-reload.md b/docs/user-manual/en/config-reload.md index 41ce34fece..1ba76850b3 100644 --- a/docs/user-manual/en/config-reload.md +++ b/docs/user-manual/en/config-reload.md @@ -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, `` and ``. 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 `` 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 `` that can be reloaded at runtime +### `` -#### Parameters under `` +#### `` * `` 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 `` +#### `` * `` element @@ -130,7 +130,7 @@ attribute `match` | N/A | X | Changing this value is same as deleting the whole `` | 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 `` +#### `` All `` elements will be reloaded. Each `` 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 `` | 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) `` | 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 `` +#### `` The `` element contains a list `
` elements. Once changed, all `
` elements in `` will be reloaded. @@ -184,7 +184,7 @@ attribute `name` | N/A | X | After reloading the address of the old name will be `` | 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 ``(under ``) | A multicast queue will be deployed after reloading | The multicast queue will be undeployed | For updating queues please see next section `` -#### Parameters under `` +#### `` The `` element contains a list `` elements. Once changed, all `` elements in `` 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 `` that can be reloaded at runtime *(Deprecated)* +### `` *(Deprecated)* -#### The `` elements +#### `` Changes to any `` elements will be reloaded to the running broker. @@ -228,7 +228,7 @@ attribute `` | N/A | X | A jms queue of the new name will be deployed afte `` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker `` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker -#### The `` elements +#### `` Changes to any `` elements will be reloaded to the running broker. diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md index df985b6371..189e3dad40 100644 --- a/docs/user-manual/en/configuring-transports.md +++ b/docs/user-manual/en/configuring-transports.md @@ -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`. - - tcp://localhost:61617 - +```xml + + tcp://localhost:61617 + +``` 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: - tcp://localhost:61617?sslEnabled=true&keyStorePath=/path +```xml +tcp://localhost:61617?sslEnabled=true&keyStorePath=/path +``` -## 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: - - tcp://localhost:61617 - +```xml + + tcp://localhost:61617 + +``` 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: - tcp://localhost:61617?protocols=CORE,AMQP +```xml +tcp://localhost:61617?protocols=CORE,AMQP +``` -## 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. diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md index cb0570dc06..a1876bd096 100644 --- a/docs/user-manual/en/connection-ttl.md +++ b/docs/user-manual/en/connection-ttl.md @@ -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. diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md index 0dadf19f21..668a3b5a4a 100644 --- a/docs/user-manual/en/core-bridges.md +++ b/docs/user-manual/en/core-bridges.md @@ -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): - - sausage-factory - mincing-machine - - - org.apache.activemq.artemis.jms.example.HatColourChangeTransformer - - 1000 - true - 1.0 - -1 - -1 - false - true - 10000000 - foouser - foopassword - - remote-connector - - - +```xml + + sausage-factory + mincing-machine + + + org.apache.activemq.artemis.jms.example.HatColourChangeTransformer + + 1000 + true + 1.0 + -1 + -1 + false + true + 10000000 + foouser + foopassword + + remote-connector + + + +``` 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 diff --git a/docs/user-manual/en/critical-analysis.md b/docs/user-manual/en/critical-analysis.md index 443e156321..18c17cdf41 100644 --- a/docs/user-manual/en/critical-analysis.md +++ b/docs/user-manual/en/critical-analysis.md @@ -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 diff --git a/docs/user-manual/en/diverts.md b/docs/user-manual/en/diverts.md index b6972962d5..7408f4b73a 100644 --- a/docs/user-manual/en/diverts.md +++ b/docs/user-manual/en/diverts.md @@ -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: - -
priceUpdates
- priceForwarding - - - org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer - - true - +```xml + +
priceUpdates
+ priceForwarding + + + org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer + + true + +``` 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: - -
orders
- spyTopic - false - +```xml + +
orders
+ spyTopic + false + +``` The above divert example takes a copy of every message sent to the address '`orders`' and sends it to a local address called diff --git a/docs/user-manual/en/duplicate-detection.md b/docs/user-manual/en/duplicate-detection.md index 9ae7f6252d..c96c70224d 100644 --- a/docs/user-manual/en/duplicate-detection.md +++ b/docs/user-manual/en/duplicate-detection.md @@ -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(); diff --git a/docs/user-manual/en/embedding-activemq.md b/docs/user-manual/en/embedding-activemq.md index b7a4e72346..d309a58a4f 100644 --- a/docs/user-manual/en/embedding-activemq.md +++ b/docs/user-manual/en/embedding-activemq.md @@ -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(); ``` diff --git a/docs/user-manual/en/examples.md b/docs/user-manual/en/examples.md index 8bf8c80858..1780eaa601 100644 --- a/docs/user-manual/en/examples.md +++ b/docs/user-manual/en/examples.md @@ -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 ``` diff --git a/docs/user-manual/en/exclusive-queues.md b/docs/user-manual/en/exclusive-queues.md index a7f97cc75f..6529c9db33 100644 --- a/docs/user-manual/en/exclusive-queues.md +++ b/docs/user-manual/en/exclusive-queues.md @@ -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 @@ -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: - - true - +```xml + + true + +``` -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 diff --git a/docs/user-manual/en/flow-control.md b/docs/user-manual/en/flow-control.md index c16bd240d1..86654f2b07 100644 --- a/docs/user-manual/en/flow-control.md +++ b/docs/user-manual/en/flow-control.md @@ -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: - - - 100000 - BLOCK - - +```xml + + + 100000 + BLOCK + + +``` 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 diff --git a/docs/user-manual/en/ha.md b/docs/user-manual/en/ha.md index 01493bb97e..2fc0585e48 100644 --- a/docs/user-manual/en/ha.md +++ b/docs/user-manual/en/ha.md @@ -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. - - - +```xml + + + +``` or - - - - +```xml + + + +``` 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: - - - - - - +```xml + + + + + +``` or - - - - - - +```xml + + + + + +``` or - - - - - - +```xml + + + + + +``` ### 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: - - - - - - . - - - ... - - - +```xml + + + + + +... + + + ... + + +``` The backup server must be similarly configured but as a `slave` - - - - - +```xml + + + + + +``` #### 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`: - - - - - - . - - - ... - - - +```xml + + + + + +... + + + ... + + +``` The backup server must also be configured as a backup. - - - - - - +```xml + + + + + +``` 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: - - - - true - - - +```xml + + + + true + + + +``` 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: - - - - true - - - +```xml + + + + true + + + +``` > **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: - - - - true - - - +```xml + + + + true + + + +``` 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: - - - - true - - - +```xml + + + + true + + + +``` #### 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: - - - - true - 1 - -1 - 5000 - - - - - +```xml + + + + true + 1 + -1 + 5000 + + + + + +``` 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: - - - - - remote-connector - - ......... - +```xml + + + + + remote-connector + +......... + +``` #### 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: - - - - - server1-connector - - - - +```xml + + + + + server1-connector + + + + +``` 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: - - - - - - - - +```xml + + + + + + + +``` #### 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: - - - - ... - my-group - - - - +```xml + + + + ... + my-group + + + +``` 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: - - - - 44 - 33 - 3 - false - 33 - - purple - true - abcdefg - - - tiddles - 22 - 33rrrrr - false - - - boo! - - - - - - - +```xml + + + + 44 + 33 + 3 + false + 33 + + purple + true + abcdefg + + + tiddles + 22 + 33rrrrr + false + + + boo! + + + + + + + +``` #### Scale Down and Clients diff --git a/docs/user-manual/en/intercepting-operations.md b/docs/user-manual/en/intercepting-operations.md index 2517430def..b518ff3e1d 100644 --- a/docs/user-manual/en/intercepting-operations.md +++ b/docs/user-manual/en/intercepting-operations.md @@ -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 @@ -35,7 +35,7 @@ public interface StompFrameInterceptor extends BaseInterceptor 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 @@ -57,15 +57,17 @@ The returned boolean value is important: Both incoming and outgoing interceptors are configured in `broker.xml`: - - org.apache.activemq.artemis.jms.example.LoginInterceptor - org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor - +```xml + + org.apache.activemq.artemis.jms.example.LoginInterceptor + org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor + - - org.apache.activemq.artemis.jms.example.LogoutInterceptor - org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor - + + org.apache.activemq.artemis.jms.example.LogoutInterceptor + org.apache.activemq.artemis.jms.example.AdditionalPropertyInterceptor + +``` See the documentation on [adding runtime dependencies](using-server.md) to understand how to make your interceptor available to the broker. diff --git a/docs/user-manual/en/large-messages.md b/docs/user-manual/en/large-messages.md index 50855c1f70..0ecb8666b9 100644 --- a/docs/user-manual/en/large-messages.md +++ b/docs/user-manual/en/large-messages.md @@ -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. - - ... - /data/large-messages - ... - + ... + /data/large-messages + ... + 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 diff --git a/docs/user-manual/en/last-value-queues.md b/docs/user-manual/en/last-value-queues.md index c02eb2ff1b..f242ff5210 100644 --- a/docs/user-manual/en/last-value-queues.md +++ b/docs/user-manual/en/last-value-queues.md @@ -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 @@ -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: - - true - +```xml + + true + +``` 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"); diff --git a/docs/user-manual/en/management-console.md b/docs/user-manual/en/management-console.md index 80d22bbe4d..f542a01def 100644 --- a/docs/user-manual/en/management-console.md +++ b/docs/user-manual/en/management-console.md @@ -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 diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md index 809044dc8f..65b0b53c58 100644 --- a/docs/user-manual/en/management.md +++ b/docs/user-manual/en/management.md @@ -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`: - - my.org.apache.activemq +```xml + +my.org.apache.activemq +``` ### 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: - - - - - +```xml + + + + + +``` ### 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`: - activemq.notifications +```xml +activemq.notifications +``` 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`: - true +```xml +true +``` 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`: - - 7 - - 60000 +```xml + +7 + +60000 +``` 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, diff --git a/docs/user-manual/en/masking-passwords.md b/docs/user-manual/en/masking-passwords.md index 32329bacdc..4ec64bae9c 100644 --- a/docs/user-manual/en/masking-passwords.md +++ b/docs/user-manual/en/masking-passwords.md @@ -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 true xyz ``` @@ -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 - - - + + + ``` -### 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()`. 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 - com.foo.SomeDecoder;key1=value1;key2=value2 +com.foo.SomeDecoder;key1=value1;key2=value2 ``` 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 - com.foo.NewDecoder;key-location=/some/url/to/keyfile +com.foo.NewDecoder;key-location=/some/url/to/keyfile ``` Then configure your cluster-password like this: ```xml - ENC(masked_password) +ENC(masked_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` interface: -``` java +```java public interface SensitiveDataCodec { T decode(Object mask) throws Exception; @@ -366,6 +366,5 @@ public class MyNewDecoder implements SensitiveDataCodec } ``` -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! \ No newline at end of file +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! \ No newline at end of file diff --git a/docs/user-manual/en/message-expiry.md b/docs/user-manual/en/message-expiry.md index db04002194..99cb73f1cf 100644 --- a/docs/user-manual/en/message-expiry.md +++ b/docs/user-manual/en/message-expiry.md @@ -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: - - - expiryQueue - +```xml + + + expiryQueue + +``` If messages are expired and no expiry address is specified, messages are simply removed from the queue and dropped. Address wildcards can be used diff --git a/docs/user-manual/en/message-grouping.md b/docs/user-manual/en/message-grouping.md index 1d4bcd206d..5fb4255247 100644 --- a/docs/user-manual/en/message-grouping.md +++ b/docs/user-manual/en/message-grouping.md @@ -102,17 +102,19 @@ message should take. Here is a sample config for each type of handler. This should be configured in `broker.xml`. - - LOCAL -
jms
- 5000 - +```xml + + LOCAL +
jms
+ 5000 + - - REMOTE -
jms
- 5000 - + + REMOTE +
jms
+ 5000 + +``` - `type` two types of handlers are supported - `LOCAL` and `REMOTE`. Each cluster should choose 1 node to have a `LOCAL` grouping handler diff --git a/docs/user-manual/en/messaging-concepts.md b/docs/user-manual/en/messaging-concepts.md index 41733e91e8..582b85d754 100644 --- a/docs/user-manual/en/messaging-concepts.md +++ b/docs/user-manual/en/messaging-concepts.md @@ -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). diff --git a/docs/user-manual/en/paging.md b/docs/user-manual/en/paging.md index 833643527d..a6ce648bb2 100644 --- a/docs/user-manual/en/paging.md +++ b/docs/user-manual/en/paging.md @@ -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`). - - - 104857600 - 10485760 - PAGE - - +```xml + + + 104857600 + 10485760 + PAGE + + +``` This is the list of available parameters on the address settings. diff --git a/docs/user-manual/en/persistence.md b/docs/user-manual/en/persistence.md index 063311d5e4..e48f785588 100644 --- a/docs/user-manual/en/persistence.md +++ b/docs/user-manual/en/persistence.md @@ -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 `````` element. For example: ```xml - - - jdbc:derby:data/derby/database-store;create=true - BINDINGS_TABLE - MESSAGE_TABLE - MESSAGE_TABLE - LARGE_MESSAGES_TABLE - org.apache.derby.jdbc.EmbeddedDriver - - + + + jdbc:derby:data/derby/database-store;create=true + BINDINGS_TABLE + MESSAGE_TABLE + MESSAGE_TABLE + LARGE_MESSAGES_TABLE + org.apache.derby.jdbc.EmbeddedDriver + + ``` - `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 diff --git a/docs/user-manual/en/pre-acknowledge.md b/docs/user-manual/en/pre-acknowledge.md index a4046ea7fe..d328d8b880 100644 --- a/docs/user-manual/en/pre-acknowledge.md +++ b/docs/user-manual/en/pre-acknowledge.md @@ -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 diff --git a/docs/user-manual/en/protocols-interoperability.md b/docs/user-manual/en/protocols-interoperability.md index bbb1ca2a8c..8ce73c4d7d 100644 --- a/docs/user-manual/en/protocols-interoperability.md +++ b/docs/user-manual/en/protocols-interoperability.md @@ -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. - - - tcp://localhost:1883?protocols=MQTT - +```xml + + + tcp://localhost:1883?protocols=MQTT + - - - tcp://localhost:1883?protocols=MQTT,AMQP - + + + tcp://localhost:1883?protocols=MQTT,AMQP + - - - tcp://localhost:61616 - + + + tcp://localhost:61616 + +``` ## 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: - tcp://localhost:5672?protocols=AMQP +```xml +tcp://localhost:5672?protocols=AMQP +``` 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: - tcp://localhost:61616?protocols=OPENWIRE - +```xml +tcp://localhost:61616?protocols=OPENWIRE +``` 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: - tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2 +```xml +tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2 +``` 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`: - tcp://localhost:61613?protocols=STOMP +```xml +tcp://localhost:61613?protocols=STOMP +``` 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: - tcp://localhost:61613?protocols=STOMP;connectionTtl=20000 +```xml +tcp://localhost:61613?protocols=STOMP;connectionTtl=20000 +``` 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: -~~~ - - ... - -
- - - -
- - ... - -~~~ +```xml + + ... + +
+ + + +
+ + ... + +``` ### 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: - tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240 +```xml +tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240 +``` 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: - tcp://localhost:61614?protocols=STOMP +```xml +tcp://localhost:61614?protocols=STOMP +``` With this configuration, Apache ActiveMQ Artemis will accept Stomp connections over Web Sockets on the port `61614`. Web browser can diff --git a/docs/user-manual/en/resource-limits.md b/docs/user-manual/en/resource-limits.md index 443838f90c..7939dc7293 100644 --- a/docs/user-manual/en/resource-limits.md +++ b/docs/user-manual/en/resource-limits.md @@ -10,12 +10,14 @@ configure such limits. Here is an example of the XML used to set resource limits: - - - 5 - 3 - - +```xml + + + 5 + 3 + + +``` 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. diff --git a/docs/user-manual/en/scheduled-messages.md b/docs/user-manual/en/scheduled-messages.md index b7c2d7ead2..6dff58a025 100644 --- a/docs/user-manual/en/scheduled-messages.md +++ b/docs/user-manual/en/scheduled-messages.md @@ -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); diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md index 82b062d834..8bbcb381b2 100644 --- a/docs/user-manual/en/security.md +++ b/docs/user-manual/en/security.md @@ -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 diff --git a/docs/user-manual/en/send-guarantees.md b/docs/user-manual/en/send-guarantees.md index dc08ea1e2c..79b9097bd6 100644 --- a/docs/user-manual/en/send-guarantees.md +++ b/docs/user-manual/en/send-guarantees.md @@ -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`. diff --git a/docs/user-manual/en/slow-consumers.md b/docs/user-manual/en/slow-consumers.md index afca530f48..49d5141cc4 100644 --- a/docs/user-manual/en/slow-consumers.md +++ b/docs/user-manual/en/slow-consumers.md @@ -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) diff --git a/docs/user-manual/en/spring-integration.md b/docs/user-manual/en/spring-integration.md index 718ecf6fe1..9c7c939059 100644 --- a/docs/user-manual/en/spring-integration.md +++ b/docs/user-manual/en/spring-integration.md @@ -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: - +```xml + - + - + - - - - - - + + + + + + +``` As you can see, the `listenerContainer` bean references the components defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class diff --git a/docs/user-manual/en/syntax.md b/docs/user-manual/en/syntax.md index 6e81a3443b..71db615ea8 100644 --- a/docs/user-manual/en/syntax.md +++ b/docs/user-manual/en/syntax.md @@ -3,10 +3,12 @@ ### Header 3 #### Header 4 - somexml +```xml +somexml +``` -``` java - Somejava s = new SomeJava(); +```java +Somejava s = new SomeJava(); ``` > **Note** diff --git a/docs/user-manual/en/tomcat.md b/docs/user-manual/en/tomcat.md index ac6befa228..f41e0879f5 100644 --- a/docs/user-manual/en/tomcat.md +++ b/docs/user-manual/en/tomcat.md @@ -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 ... ```` -#### Example of Destination (Queue and Topic) +### Example of Destination (Queue and Topic) -```` +```xml ... ```` -#### 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 \ No newline at end of file diff --git a/docs/user-manual/en/tools.md b/docs/user-manual/en/tools.md index 8ea57ea392..4a6aa0de02 100644 --- a/docs/user-manual/en/tools.md +++ b/docs/user-manual/en/tools.md @@ -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) - - ``` \ No newline at end of file diff --git a/docs/user-manual/en/undelivered-messages.md b/docs/user-manual/en/undelivered-messages.md index 275ab44a16..6156c8f8e0 100644 --- a/docs/user-manual/en/undelivered-messages.md +++ b/docs/user-manual/en/undelivered-messages.md @@ -35,16 +35,17 @@ consuming valuable CPU and network resources. Delayed redelivery is defined in the address-setting configuration: - - - - 1.5 - - 5000 - - 50000 - - +```xml + + + + 1.5 + + 5000 + + 50000 + +``` 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: - - - deadLetterQueue - 3 - +```xml + + + deadLetterQueue + 3 + +``` 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`: - true +```xml +true +``` diff --git a/docs/user-manual/en/upgrading.md b/docs/user-manual/en/upgrading.md index 2121c268e7..e564f49b2d 100644 --- a/docs/user-manual/en/upgrading.md +++ b/docs/user-manual/en/upgrading.md @@ -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 diff --git a/docs/user-manual/en/using-core.md b/docs/user-manual/en/using-core.md index e256e5e437..78c08a5589 100644 --- a/docs/user-manual/en/using-core.md +++ b/docs/user-manual/en/using-core.md @@ -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())); diff --git a/docs/user-manual/en/using-jms.md b/docs/user-manual/en/using-jms.md index f2516587d1..bf654b918c 100644 --- a/docs/user-manual/en/using-jms.md +++ b/docs/user-manual/en/using-jms.md @@ -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: - +```xml + +``` 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, diff --git a/docs/user-manual/en/using-server.md b/docs/user-manual/en/using-server.md index 691d73ec1f..dea7693071 100644 --- a/docs/user-manual/en/using-server.md +++ b/docs/user-manual/en/using-server.md @@ -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: - +```xml + - + - + - + + + + + + +``` -- 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: diff --git a/docs/user-manual/en/versions.md b/docs/user-manual/en/versions.md index 6b8b02b333..84bcd50ee5 100644 --- a/docs/user-manual/en/versions.md +++ b/docs/user-manual/en/versions.md @@ -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 diff --git a/docs/user-manual/en/wildcard-routing.md b/docs/user-manual/en/wildcard-routing.md index 12facd0745..96540f3568 100644 --- a/docs/user-manual/en/wildcard-routing.md +++ b/docs/user-manual/en/wildcard-routing.md @@ -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. - - false - +```xml + + false + +``` 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). diff --git a/docs/user-manual/en/wildcard-syntax.md b/docs/user-manual/en/wildcard-syntax.md index 2d5451d528..cc566a4cfd 100644 --- a/docs/user-manual/en/wildcard-syntax.md +++ b/docs/user-manual/en/wildcard-syntax.md @@ -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 `` configuration tag is used. - - true - . - # - * - +```xml + + true + . + # + * + +``` The example above shows the default configuration. \ No newline at end of file