From commits-return-51773-archive-asf-public=cust-asf.ponee.io@activemq.apache.org Sat Jun 9 07:57:17 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 1175D1807BA for ; Sat, 9 Jun 2018 07:57:13 +0200 (CEST) Received: (qmail 65704 invoked by uid 500); 9 Jun 2018 05:57:13 -0000 Mailing-List: contact commits-help@activemq.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@activemq.apache.org Delivered-To: mailing list commits@activemq.apache.org Received: (qmail 64933 invoked by uid 99); 9 Jun 2018 05:57:12 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 09 Jun 2018 05:57:12 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 0C3F8E1181; Sat, 9 Jun 2018 05:57:12 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: clebertsuconic@apache.org To: commits@activemq.apache.org Date: Sat, 09 Jun 2018 05:57:23 -0000 Message-Id: In-Reply-To: <5cb11a70dc66485da18a9af6a10716f2@git.apache.org> References: <5cb11a70dc66485da18a9af6a10716f2@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [13/15] activemq-artemis git commit: ARTEMIS-1912 big doc refactor http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/amqp.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/amqp.md b/docs/user-manual/en/amqp.md new file mode 100644 index 0000000..a201fbd --- /dev/null +++ b/docs/user-manual/en/amqp.md @@ -0,0 +1,129 @@ +# AMQP + +Apache ActiveMQ Artemis supports the [AMQP +1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp) +specification. By default there are `acceptor` elements configured to accept +AMQP connections on ports `61616` and `5672`. + +See the general [Protocols and Interoperability](protocols-interoperability.md) +chapter for details on configuring an `acceptor` for AMQP. + +You can use *any* AMQP 1.0 compatible clients. + +A short list includes: + +- [qpid clients](https://qpid.apache.org/download.html) +- [.NET Clients](https://blogs.apache.org/activemq/entry/using-net-libraries-with-activemq) +- [Javascript NodeJS](https://github.com/noodlefrenzy/node-amqp10) +- [Java Script RHEA](https://github.com/grs/rhea) +- ... and many others. + +## Examples + +We have a few examples as part of the Artemis distribution: + +- .NET: + - ./examples/protocols/amqp/dotnet +- ProtonCPP + - ./examples/protocols/amqp/proton-cpp + - ./examples/protocols/amqp/proton-clustered-cpp +- Ruby + - ./examples/protocols/amqp/proton-ruby +- Java (Using the qpid JMS Client) + - ./examples/protocols/amqp/queue +- Interceptors + - ./examples/features/standard/interceptor-amqp + - ./examples/features/standard/broker-plugin + +## Message Conversions + +The broker will not perform any message conversion to any other protocols when +sending AMQP and receiving AMQP. + +However if you intend your message to be received by an AMQP JMS Client, you +must follow the [JMS Mapping +Conventions](https://www.oasis-open.org/committees/download.php/53086/amqp-bindmap-jms-v1.0-wd05.pdf). +If you send a body type that is not recognized by this specification the +conversion between AMQP and any other protocol will make it a Binary Message. +Make sure you follow these conventions if you intend to cross protocols or +languages. Especially on the message body. + +A compatibility setting allows aligning the naming convention of AMQP queues +(JMS Durable and Shared Subscriptions) with CORE. For backwards compatibility +reasons, you need to explicitly enable this via broker configuration: + +- `amqp-use-core-subscription-naming` + - `true` - use queue naming convention that is aligned with CORE. + - `false` (default) - use older naming convention. + +## Intercepting and changing messages + +We don't recommend changing messages at the server's side for a few reasons: + +- AMQP messages are meant to be immutable +- The message won't be the original message the user sent +- AMQP has the possibility of signing messages. The signature would be broken. +- For performance reasons. We try not to re-encode (or even decode) messages. + +If regardless these recommendations you still need and want to intercept and +change AMQP messages, look at the aforementioned interceptor examples. + +## AMQP and security + +The Apache ActiveMQ Artemis Server accepts the PLAIN, ANONYMOUS, and GSSAPI +SASL mechanism. These are implemented on the broker's [security](security.md) +infrastructure. + +## AMQP and destinations + +If an AMQP Link is dynamic then a temporary queue will be created and either +the remote source or remote target address will be set to the name of the +temporary queue. If the Link is not dynamic then the the address of the remote +target or source will used for the queue. If this does not exist then it will +be auto-created if the settings allow. + +## AMQP and Multicast Addresses (Topics) + +Although AMQP has no notion of "topics" it is still possible to treat AMQP +consumers or receivers as subscriptions rather than just consumers on a queue. +By default any receiving link that attaches to an address that has only +`multicast` enabled will be treated as a subscription and a corresponding +subscription queue will be created. If the Terminus Durability is either +`UNSETTLED_STATE` or `CONFIGURATION` then the queue will be made durable +(similar to a JMS durable subscription) and given a name made up from the +container id and the link name, something like `my-container-id:my-link-name`. +If the Terminus Durability is configured as `NONE` then a volatile `multicast` +queue will be created. + +## AMQP and Coordinations - Handling Transactions + +An AMQP links target can also be a Coordinator. A Coordinator is used to handle +transactions. If a coordinator is used then the underlying server session will +be transacted and will be either rolled back or committed via the coordinator. + +> **Note:** +> +> AMQP allows the use of multiple transactions per session, +> `amqp:multi-txns-per-ssn`, however in this version of Apache ActiveMQ Artemis +> will only support single transactions per session. + +## AMQP scheduling message delivery + +An AMQP message can provide scheduling information that controls the time in +the future when the message will be delivered at the earliest. This +information is provided by adding a message annotation to the sent message. + +There are two different message annotations that can be used to schedule a +message for later delivery: + +- `x-opt-delivery-time` + The specified value must be a positive long corresponding to the time the + message should be made available for delivery (in milliseconds). + +- `x-opt-delivery-delay` + The specified value must be a positive long corresponding to the amount of + milliseconds after the broker receives the given message before it should be + made available for delivery. + +If both annotations are present in the same message then the broker will prefer +the more specific `x-opt-delivery-time` value. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/architecture.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md index 80d70b2..6a73a64 100644 --- a/docs/user-manual/en/architecture.md +++ b/docs/user-manual/en/architecture.md @@ -1,125 +1,126 @@ # 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. +Apache ActiveMQ Artemis core is designed simply as set of Plain Old Java +Objects (POJOs) - we hope you like its clean-cut design. -Each Apache ActiveMQ Artemis server has its own ultra high performance persistent -journal, which it uses for message and other persistence. +Each Apache ActiveMQ Artemis server has its own ultra high performance +persistent journal, which it uses for message and other persistence. Using a high performance journal allows outrageous persistence message -performance, something not achievable when using a relational database -for persistence. +performance, something not achievable when using a relational database for +persistence (although JDBC is still an option if necessary). -Apache ActiveMQ Artemis clients, potentially on different physical machines interact -with the Apache ActiveMQ Artemis server. Apache ActiveMQ Artemis currently provides two APIs for -messaging at the client side: +Apache ActiveMQ Artemis clients, potentially on different physical machines, +interact with the Apache ActiveMQ Artemis broker. Apache ActiveMQ Artemis +currently ships two API implementations for messaging at the client side: -1. Core client API. This is a simple intuitive Java API that is aligned with the Artemis internal Core. Allowing more - control of broker objects, like for example, direct creation of addresses and queues. The Core API also offers a - full set of messaging functionality without some of the complexities of JMS. +1. Core client API. This is a simple intuitive Java API that is aligned with + the Artemis internal Core. Allowing more control of broker objects (e.g + direct creation of addresses and queues). The Core API also offers a full set + of messaging functionality without some of the complexities of JMS. -2. JMS client API. The standard JMS API is available at the client side. +2. JMS 2.0 client API. The standard JMS API is available at the client side. -Apache ActiveMQ Artemis also provides different protocol implementations on the server so you can use respective clients for these protocols: - -1. AMQP -2. OpenWire -3. MQTT -4. STOMP -5. HornetQ (for use with HornetQ clients). -6. CORE (Artemis CORE protocol) +Apache ActiveMQ Artemis also provides different protocol implementations on the +server so you can use respective clients for these protocols: +- AMQP +- OpenWire +- MQTT +- STOMP +- HornetQ (for use with HornetQ clients). +- Core (Artemis CORE protocol) 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 -to be used with multiple different protocols. +The Apache ActiveMQ Artemis broker does not speak JMS and in fact does not know +anything about JMS, it is a protocol agnostic messaging server designed to be +used with multiple different protocols. -When a user uses the JMS API on the client side, all JMS interactions -are translated into operations on the Apache ActiveMQ Artemis core client API before -being transferred over the wire using the Apache ActiveMQ Artemis wire format. +When a user uses the JMS API on the client side, all JMS interactions are +translated into operations on the Apache ActiveMQ Artemis core client API +before being transferred over the wire using the core protocol. -The server always just deals with core API interactions. +The broker always just deals with core API interactions. A schematic illustrating this relationship is shown in figure 3.1 below: ![ActiveMQ Artemis architecture1](images/architecture1.jpg) -Figure 3.1 shows two user applications interacting with an Apache ActiveMQ Artemis -server. User Application 1 is using the JMS API, while User Application +Figure 3.1 shows two user applications interacting with an Apache ActiveMQ +Artemis server. User Application 1 is using the JMS API, while User Application 2 is using the core client API directly. -You can see from the diagram that the JMS API is implemented by a thin -facade layer on the client side. +You can see from the diagram that the JMS API is implemented by a thin facade +layer on the client side. ## Stand-alone Broker 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 +messaging broker and a number of protocol managers that provide support for the +various protocol mentioned earlier. -The stand-alone broker configuration uses [Airline](https://github.com/airlift/airline) -for bootstrapping the Broker. +The stand-alone broker configuration uses +[Airline](https://github.com/airlift/airline) for bootstrapping the Broker. 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) +For more information on server configuration files see [Server +Configuration](configuration-index.md) ## 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 +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 broker you can directly -instantiate and embed Apache ActiveMQ Artemis brokers in your own application. +instantiate and embed brokers in your own application. -For more information on embedding Apache ActiveMQ Artemis, see [Embedding Apache ActiveMQ Artemis](embedding-activemq.md). +Read more about [embedding Apache ActiveMQ Artemis](embedding-activemq.md). ## 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 -compliant application server or servlet engine. +Apache ActiveMQ Artemis provides its own fully functional Java Connector +Architecture (JCA) adaptor which enables it to be integrated easily into any +Java EE compliant application server or servlet engine. Java EE application servers provide Message Driven Beans (MDBs), which are a -special type of Enterprise Java Beans (EJBs) that can process messages -from sources such as JMS systems or mail systems. +special type of Enterprise Java Beans (EJBs) that can process messages from +sources such as JMS systems or mail systems. Probably the most common use of an MDB is to consume messages from a JMS messaging system. According to the Java EE specification, a Java EE application server uses a JCA -adapter to integrate with a JMS messaging system so it can consume -messages for MDBs. - -However, the JCA adapter is not only used by the Java EE application server -for *consuming* messages via MDBs, it is also used when sending message -to the JMS messaging system e.g. from inside an EJB or servlet. - -When integrating with a JMS messaging system from inside a Java EE -application server it is always recommended that this is done via a JCA -adaptor. In fact, communicating with a JMS messaging system directly, -without using JCA would be illegal according to the Java EE specification. - -The application server's JCA service provides extra functionality such -as connection pooling and automatic transaction enlistment, which are -desirable when using messaging, say, from inside an EJB. It is possible -to talk to a JMS messaging system directly from an EJB, MDB or servlet -without going through a JCA adapter, but this is not recommended since -you will not be able to take advantage of the JCA features, such as -caching of JMS sessions, which can result in poor performance. - -Figure 3.2 below shows a Java EE application server integrating with a -Apache ActiveMQ Artemis server via the Apache ActiveMQ Artemis JCA adaptor. Note that all -communication between EJB sessions or entity beans and Message Driven -beans go through the adaptor and not directly to Apache ActiveMQ Artemis. - -The large arrow with the prohibited sign shows an EJB session bean -talking directly to the Apache ActiveMQ Artemis server. This is not recommended as -you'll most likely end up creating a new connection and session every -time you want to interact from the EJB, which is an anti-pattern. +adapter to integrate with a JMS messaging system so it can consume messages for +MDBs. + +However, the JCA adapter is not only used by the Java EE application server for +*consuming* messages via MDBs, it is also used when sending message to the JMS +messaging system e.g. from inside an EJB or servlet. + +When integrating with a JMS messaging system from inside a Java EE application +server it is always recommended that this is done via a JCA adaptor. In fact, +communicating with a JMS messaging system directly, without using JCA would be +illegal according to the Java EE specification. + +The application server's JCA service provides extra functionality such as +connection pooling and automatic transaction enlistment, which are desirable +when using messaging, say, from inside an EJB. It is possible to talk to a JMS +messaging system directly from an EJB, MDB or servlet without going through a +JCA adapter, but this is not recommended since you will not be able to take +advantage of the JCA features, such as caching of JMS sessions, which can +result in poor performance. + +Figure 3.2 below shows a Java EE application server integrating with a Apache +ActiveMQ Artemis server via the Apache ActiveMQ Artemis JCA adaptor. Note that +all communication between EJB sessions or entity beans and Message Driven beans +go through the adaptor and not directly to Apache ActiveMQ Artemis. + +The large arrow with the prohibited sign shows an EJB session bean talking +directly to the Apache ActiveMQ Artemis server. This is not recommended as +you'll most likely end up creating a new connection and session every time you +want to interact from the EJB, which is an anti-pattern. ![ActiveMQ Artemis architecture2](images/architecture2.jpg) http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/broker-plugins.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/broker-plugins.md b/docs/user-manual/en/broker-plugins.md index 6fd03a8..442339a 100644 --- a/docs/user-manual/en/broker-plugins.md +++ b/docs/user-manual/en/broker-plugins.md @@ -1,50 +1,46 @@ # Apache ActiveMQ Artemis Plugin Support Apache ActiveMQ Artemis is designed to allow extra functionality to be added by -creating a plugin. Multiple plugins can be registered at the same time and they will be chained -together and executed in the order they are registered. (i.e. the first plugin registered -is always executed first). +creating a plugin. Multiple plugins can be registered at the same time and they +will be chained together and executed in the order they are registered (i.e. +the first plugin registered is always executed first). -Creating a plugin is very simple. It requires implementing the [`ActiveMQServerPlugin`](https://github.com/apache/activemq-artemis/blob/master/artemis-server/src/main/java/org/apache/activemq/artemis/core/server/plugin/ActiveMQServerPlugin.java) -interface, making sure the plugin is on the classpath, and registering it with the broker. Only the methods that you want to add behavior for need to be implemented as all of the interface methods are default methods. +Creating a plugin is very simple. It requires: -## Adding the plugin to the classpath +- Implementing the [`ActiveMQServerPlugin`](https://github.com/apache/activemq-artemis/blob/master/artemis-server/src/main/java/org/apache/activemq/artemis/core/server/plugin/ActiveMQServerPlugin.java) + interface +- Making sure the plugin is [on the classpath](using-server.md#adding-runtime-dependencies) +- Registering it with the broker either via [xml](#registering-a-plugin) or [programmatically](#registering-a-plugin-programmatically). -See the documentation on [adding runtime dependencies](using-server.md) to understand how to make your plugin available to the broker. - -If you are using an embed system than you will need the jar under the regular classpath of your embedded application. +Only the methods that you want to add behavior for need to be implemented as +all of the interface methods are default methods. ## Registering a Plugin -To register a plugin with by XML you need to add the `broker-plugins` element at the `broker.xml`. It is also possible -to pass configuration to a plugin using the `property` child element(s). These properties (zero to many) -will be read and passed into the Plugin's `init(Map)` operation after the plugin -has been instantiated. +To register a plugin with by XML you need to add the `broker-plugins` element +at the `broker.xml`. It is also possible to pass configuration to a plugin +using the `property` child element(s). These properties (zero to many) will be +read and passed into the plugin's `init(Map)` operation after +the plugin has been instantiated. ```xml - - - ... - - - - - - - ... - - + + + + + + ``` ## Registering a Plugin Programmatically For registering a plugin programmatically you need to call the -registerBrokerPlugin() method and pass in a new instance of your plugin. In the example below -assuming your plugin is called `UserPlugin`, registering it looks like the following: +`registerBrokerPlugin()` method and pass in a new instance of your plugin. In +the example below assuming your plugin is called `UserPlugin`, registering it +looks like the following: ``` java - ... Configuration config = new ConfigurationImpl(); @@ -53,144 +49,80 @@ Configuration config = new ConfigurationImpl(); config.registerBrokerPlugin(new UserPlugin()); ``` -## Using the LoggingActiveMQServerPlugin - -The LoggingActiveMQServerPlugin logs specific broker events. - -You can select which events are logged by setting the following configuration properties to `true`. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyProperty Description
LOG_CONNECTION_EVENTSLog info when a Connection is created/destroy. Default `false`.
LOG_SESSION_EVENTSLog info when a Session is created/closed. Default `false`.
LOG_CONSUMER_EVENTSLogs info when a Consumer is created/closed. Default `false`.
LOG_DELIVERING_EVENTSLogs info when message is delivered to a consumer and when a message is acknowledged by a consumer. - Default `false`
LOG_SENDING_EVENTSLogs info when a message has been sent to an address and when a message has been routed within the broker. - Default `false`
LOG_INTERNAL_EVENTSLogs info when a queue created/destroyed, when a message is expired, when a bridge is deployed and when a critical - failure occurs. Default `false`
LOG_ALL_EVENTSLogs info for all the above events. Default `false`
- -By default the LoggingActiveMQServerPlugin wil not log any information. The logging is activated by setting one (or a selection) -of the above configuration properties to `true`. - -To configure the plugin, you can add the following configuration to the broker. In the example below both LOG_DELIVERING_EVENTS -and LOG_SENDING_EVENTS will be logged by the broker. +## Using the `LoggingActiveMQServerPlugin` -```xml - +The `LoggingActiveMQServerPlugin` logs specific broker events. -... - - - - - - -... +You can select which events are logged by setting the following configuration +properties to `true`. + +Property|Trigger Event|Default Value +---|---|--- +`LOG_CONNECTION_EVENTS`|Connection is created/destroy.|`false` +`LOG_SESSION_EVENTS`|Session is created/closed.|`false` +`LOG_CONSUMER_EVENTS`|Consumer is created/closed|`false` +`LOG_DELIVERING_EVENTS`|Message is delivered to a consumer and when a message is acknowledged by a consumer.|`false` +`LOG_SENDING_EVENTS`|When a message has been sent to an address and when a message has been routed within the broker.|`false` +`LOG_INTERNAL_EVENTS`|When a queue created/destroyed, when a message is expired, when a bridge is deployed and when a critical failure occurs.|`false` +`LOG_ALL_EVENTS`|Includes all the above events.|`false` + +By default the `LoggingActiveMQServerPlugin` will not log any information. The +logging is activated by setting one (or a selection) of the above configuration +properties to `true`. + +To configure the plugin, you can add the following configuration to the broker. +In the example below both `LOG_DELIVERING_EVENTS` and `LOG_SENDING_EVENTS` will +be logged by the broker. - +```xml + + + + + + ``` -Most events in the LoggingActiveMQServerPlugin follow a `beforeX` and `afterX` notification pattern e.g beforeCreateConsumer() and afterCreateConsumer(). +Most events in the `LoggingActiveMQServerPlugin` follow a `beforeX` and +`afterX` notification pattern (e.g `beforeCreateConsumer()` and +`afterCreateConsumer()`). -At Log Level `INFO`, the LoggingActiveMQServerPlugin logs an entry when an `afterX` notification occurs. By setting the Logger -"org.apache.activemq.artemis.core.server.plugin.impl" to `DEBUG` Level, log entries are generated for both `beforeX` and `afterX` notifications. -Log Level `DEBUG` will also log more information for a notification when available. +At Log Level `INFO`, the LoggingActiveMQServerPlugin logs an entry when an +`afterX` notification occurs. By setting the logger +`org.apache.activemq.artemis.core.server.plugin.impl` to `DEBUG`, log entries +are generated for both `beforeX` and `afterX` notifications. Log level `DEBUG` +will also log more information for a notification when available. ## Using the NotificationActiveMQServerPlugin -The NotificationActiveMQServerPlugin can be configured to send extra notifications for specific broker events. - -You can select which notifications are sent by setting the following configuration properties to `true`. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyProperty Description
SEND_CONNECTION_NOTIFICATIONSSends a notification when a Connection is created/destroy. Default `false`.
SEND_SESSION_NOTIFICATIONSSends a notification when a Session is created/closed. Default `false`.
SEND_ADDRESS_NOTIFICATIONSSends a notification when an Address is added/removed. Default `false`.
SEND_DELIVERED_NOTIFICATIONSSends a notification when message is delivered to a consumer. Default `false`
SEND_EXPIRED_NOTIFICATIONSSends a notification when message has been expired by the broker. Default `false`
- -By default the NotificationActiveMQServerPlugin will not send any notifications. The plugin is activated by setting one (or a selection) -of the above configuration properties to `true`. - -To configure the plugin, you can add the following configuration to the broker. In the example below both SEND_CONNECTION_NOTIFICATIONS -and SEND_SESSION_NOTIFICATIONS will be sent by the broker. +The NotificationActiveMQServerPlugin can be configured to send extra +notifications for specific broker events. -```xml - +You can select which notifications are sent by setting the following +configuration properties to `true`. -... - - - - - - -... +Property|Property Description|Default Value +---|--- +`SEND_CONNECTION_NOTIFICATIONS`|Sends a notification when a Connection is created/destroy.|`false`. +`SEND_SESSION_NOTIFICATIONS`|Sends a notification when a Session is created/closed.|`false`. +`SEND_ADDRESS_NOTIFICATIONS`|Sends a notification when an Address is added/removed.|`false`. +`SEND_DELIVERED_NOTIFICATIONS`|Sends a notification when message is delivered to a consumer.|`false` +`SEND_EXPIRED_NOTIFICATIONS`|Sends a notification when message has been expired by the broker.|`false` - +By default the NotificationActiveMQServerPlugin will not send any +notifications. The plugin is activated by setting one (or a selection) of the +above configuration properties to `true`. + +To configure the plugin, you can add the following configuration to the broker. +In the example below both `SEND_CONNECTION_NOTIFICATIONS` and +`SEND_SESSION_NOTIFICATIONS` will be sent by the broker. + +```xml + + + + + + ``` http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/client-classpath.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/client-classpath.md b/docs/user-manual/en/client-classpath.md index ea61c3a..b2820fe 100644 --- a/docs/user-manual/en/client-classpath.md +++ b/docs/user-manual/en/client-classpath.md @@ -4,12 +4,13 @@ Apache ActiveMQ Artemis requires just a single jar on the *client classpath*. > **Warning** > -> The client jar mentioned here can be found in the `lib/client` directory of the -> Apache ActiveMQ Artemis distribution. Be sure you only use the jar from the correct -> version of the release, you *must not* mix and match versions of jars -> from different Apache ActiveMQ Artemis versions. Mixing and matching different jar -> versions may cause subtle errors and failures to occur. +> The client jar mentioned here can be found in the `lib/client` directory of +> the Apache ActiveMQ Artemis distribution. Be sure you only use the jar from +> the correct version of the release, you *must not* mix and match versions of +> jars from different Apache ActiveMQ Artemis versions. Mixing and matching +> different jar versions may cause subtle errors and failures to occur. -Whether you are using JMS or just the Core API simply add the `artemis-jms-client-all.jar` -from the `lib/client` directory to your client classpath. This is a "shaded" jar that -contains all the Artemis code plus dependencies (e.g. JMS spec, Netty, etc.). \ No newline at end of file +Whether you are using JMS or just the Core API simply add the +`artemis-jms-client-all.jar` from the `lib/client` directory to your client +classpath. This is a "shaded" jar that contains all the Artemis code plus +dependencies (e.g. JMS spec, Netty, etc.). http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/client-reconnection.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/client-reconnection.md b/docs/user-manual/en/client-reconnection.md index dec0909..0c9a995 100644 --- a/docs/user-manual/en/client-reconnection.md +++ b/docs/user-manual/en/client-reconnection.md @@ -6,111 +6,102 @@ connection between the client and the server. ## 100% Transparent session re-attachment -If the failure was due to some transient failure such as a temporary -network failure, and the target server was not restarted, then the -sessions will still be existent on the server, assuming the client -hasn't been disconnected for more than connection-ttl [Detecting Dead Connections](connection-ttl.md) +If the failure was due to some transient failure such as a temporary network +failure, and the target server was not restarted, then the sessions will still +be existent on the server, assuming the client hasn't been disconnected for +more than [connection-ttl](connection-ttl.md) -In this scenario, Apache ActiveMQ Artemis will automatically re-attach the client -sessions to the server sessions when the connection reconnects. This is -done 100% transparently and the client can continue exactly as if -nothing had happened. +In this scenario, Apache ActiveMQ Artemis will automatically re-attach the +client sessions to the server sessions when the connection reconnects. This is +done 100% transparently and the client can continue exactly as if nothing had +happened. The way this works is as follows: -As Apache ActiveMQ Artemis clients send commands to their servers they store each sent -command in an in-memory buffer. In the case that connection failure -occurs and the client subsequently reattaches to the same server, as -part of the reattachment protocol the server informs the client during -reattachment with the id of the last command it successfully received -from that client. +As Apache ActiveMQ Artemis clients send commands to their servers they store +each sent command in an in-memory buffer. In the case that connection failure +occurs and the client subsequently reattaches to the same server, as part of +the reattachment protocol the server informs the client during reattachment +with the id of the last command it successfully received from that client. -If the client has sent more commands than were received before failover -it can replay any sent commands from its buffer so that the client and -server can reconcile their states.Ac +If the client has sent more commands than were received before failover it can +replay any sent commands from its buffer so that the client and server can +reconcile their states.Ac The size of this buffer is configured with the `confirmationWindowSize` parameter on the connection URL. When the server has received -`confirmationWindowSize` bytes of commands and processed them it will -send back a command confirmation to the client, and the client can then -free up space in the buffer. +`confirmationWindowSize` bytes of commands and processed them it will send back +a command confirmation to the client, and the client can then free up space in +the buffer. The window is specified in bytes. Setting this parameter to `-1` disables any buffering and prevents any -re-attachment from occurring, forcing reconnect instead. The default -value for this parameter is `-1`. (Which means by default no auto -re-attachment will occur) +re-attachment from occurring, forcing reconnect instead. The default value for +this parameter is `-1`. (Which means by default no auto re-attachment will +occur) ## Session reconnection -Alternatively, the server might have actually been restarted after -crashing or being stopped. In this case any sessions will no longer be -existent on the server and it won't be possible to 100% transparently -re-attach to them. +Alternatively, the server might have actually been restarted after crashing or +being stopped. In this case any sessions will no longer be existent on the +server and it won't be possible to 100% transparently re-attach to them. -In this case, Apache ActiveMQ Artemis will automatically reconnect the connection and -*recreate* any sessions and consumers on the server corresponding to the -sessions and consumers on the client. This process is exactly the same -as what happens during failover onto a backup server. +In this case, Apache ActiveMQ Artemis will automatically reconnect the +connection and *recreate* any sessions and consumers on the server +corresponding to the sessions and consumers on the client. This process is +exactly the same as what happens during failover onto a backup server. -Client reconnection is also used internally by components such as core -bridges to allow them to reconnect to their target servers. +Client reconnection is also used internally by components such as core bridges +to allow them to reconnect to their target servers. -Please see the section on failover [Automatic Client Failover](ha.md) to get a full understanding of how -transacted and non-transacted sessions are reconnected during -failover/reconnect and what you need to do to maintain *once and only -once*delivery guarantees. +Please see the section on failover [Automatic Client Failover](ha.md) to get a +full understanding of how transacted and non-transacted sessions are +reconnected during failover/reconnect and what you need to do to maintain *once +and only once* delivery guarantees. ## Configuring reconnection/reattachment attributes Client reconnection is configured using the following parameters: -- `retryInterval`. This optional parameter determines the period in - milliseconds between subsequent reconnection attempts, if the - connection to the target server has failed. The default value is - `2000` milliseconds. +- `retryInterval`. This optional parameter determines the period in + milliseconds between subsequent reconnection attempts, if the connection to + the target server has failed. The default value is `2000` milliseconds. -- `retryIntervalMultiplier`. This optional parameter determines - determines a multiplier to apply to the time since the last retry to - compute the time to the next retry. +- `retryIntervalMultiplier`. This optional parameter determines determines a + multiplier to apply to the time since the last retry to compute the time to + the next retry. - This allows you to implement an *exponential backoff* between retry - attempts. + This allows you to implement an *exponential backoff* between retry attempts. - Let's take an example: + Let's take an example: - If we set `retryInterval` to `1000` ms and we set - `retryIntervalMultiplier` to `2.0`, then, if the first reconnect - attempt fails, we will wait `1000` ms then `2000` ms then `4000` ms - between subsequent reconnection attempts. + If we set `retryInterval` to `1000` ms and we set `retryIntervalMultiplier` + to `2.0`, then, if the first reconnect attempt fails, we will wait `1000` ms + then `2000` ms then `4000` ms between subsequent reconnection attempts. - The default value is `1.0` meaning each reconnect attempt is spaced - at equal intervals. + The default value is `1.0` meaning each reconnect attempt is spaced at equal + intervals. -- `maxRetryInterval`. This optional parameter determines the maximum - retry interval that will be used. When setting - `retryIntervalMultiplier` it would otherwise be possible that - subsequent retries exponentially increase to ridiculously large - values. By setting this parameter you can set an upper limit on that - value. The default value is `2000` milliseconds. +- `maxRetryInterval`. This optional parameter determines the maximum retry + interval that will be used. When setting `retryIntervalMultiplier` it would + otherwise be possible that subsequent retries exponentially increase to + ridiculously large values. By setting this parameter you can set an upper limit + on that value. The default value is `2000` milliseconds. -- `reconnectAttempts`. This optional parameter determines the total - number of reconnect attempts to make before giving up and shutting - down. A value of `-1` signifies an unlimited number of attempts. The - default value is `0`. +- `reconnectAttempts`. This optional parameter determines the total number of + reconnect attempts to make before giving up and shutting down. A value of + `-1` signifies an unlimited number of attempts. The default value is `0`. All of these parameters are set on the URL used to connect to the broker. -If your client does manage to reconnect but the session is no longer -available on the server, for instance if the server has been restarted -or it has timed out, then the client won't be able to re-attach, and any -`ExceptionListener` or `FailureListener` instances registered on the -connection or session will be called. +If your client does manage to reconnect but the session is no longer available +on the server, for instance if the server has been restarted or it has timed +out, then the client won't be able to re-attach, and any `ExceptionListener` or +`FailureListener` instances registered on the connection or session will be +called. -ExceptionListeners and SessionFailureListeners -============================================== +## ExceptionListeners and SessionFailureListeners -Please note, that when a client reconnects or re-attaches, any -registered JMS `ExceptionListener` or core API `SessionFailureListener` -will be called. +Please note, that when a client reconnects or re-attaches, any registered JMS +`ExceptionListener` or core API `SessionFailureListener` will be called. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/clusters.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/clusters.md b/docs/user-manual/en/clusters.md index b3f4a77..54dc54e 100644 --- a/docs/user-manual/en/clusters.md +++ b/docs/user-manual/en/clusters.md @@ -46,13 +46,13 @@ connect to them with the minimum of configuration. Server discovery is a mechanism by which servers can propagate their connection details to: -- Messaging clients. A messaging client wants to be able to connect to - the servers of the cluster without having specific knowledge of - which servers in the cluster are up at any one time. +- Messaging clients. A messaging client wants to be able to connect to + the servers of the cluster without having specific knowledge of + which servers in the cluster are up at any one time. -- Other servers. Servers in a cluster want to be able to create - cluster connections to each other without having prior knowledge of - all the other servers in the cluster. +- Other servers. Servers in a cluster want to be able to create + cluster connections to each other without having prior knowledge of + all the other servers in the cluster. This information, let's call it the Cluster Topology, is actually sent around normal Apache ActiveMQ Artemis connections to clients and to other servers over @@ -94,12 +94,12 @@ Let's take a look at an example broadcast group from ```xml - 172.16.9.3 - 5432 - 231.7.7.7 - 9876 - 2000 - netty-connector + 172.16.9.3 + 5432 + 231.7.7.7 + 9876 + 2000 + netty-connector ``` @@ -108,64 +108,66 @@ 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 clarity. Let's discuss each one in turn: -- `name` attribute. Each broadcast group in the server must have a - unique name. +- `name` attribute. Each broadcast group in the server must have a + unique name. -- `local-bind-address`. This is the local bind address that the - datagram socket is bound to. If you have multiple network interfaces - on your server, you would specify which one you wish to use for - broadcasts by setting this property. If this property is not - specified then the socket will be bound to the wildcard address, an - IP address chosen by the kernel. This is a UDP specific attribute. +- `local-bind-address`. This is the local bind address that the + datagram socket is bound to. If you have multiple network interfaces + on your server, you would specify which one you wish to use for + broadcasts by setting this property. If this property is not + specified then the socket will be bound to the wildcard address, an + IP address chosen by the kernel. This is a UDP specific attribute. -- `local-bind-port`. If you want to specify a local port to which the - datagram socket is bound you can specify it here. Normally you would - just use the default value of `-1` which signifies that an anonymous - port should be used. This parameter is always specified in - conjunction with `local-bind-address`. This is a UDP specific - attribute. +- `local-bind-port`. If you want to specify a local port to which the + datagram socket is bound you can specify it here. Normally you would + just use the default value of `-1` which signifies that an anonymous + port should be used. This parameter is always specified in + conjunction with `local-bind-address`. This is a UDP specific + attribute. -- `group-address`. This is the multicast address to which the data - will be broadcast. It is a class D IP address in the range - `224.0.0.0` to `239.255.255.255`, inclusive. The address `224.0.0.0` - is reserved and is not available for use. This parameter is - mandatory. This is a UDP specific attribute. +- `group-address`. This is the multicast address to which the data + will be broadcast. It is a class D IP address in the range + `224.0.0.0` to `239.255.255.255`, inclusive. The address `224.0.0.0` + is reserved and is not available for use. This parameter is + mandatory. This is a UDP specific attribute. -- `group-port`. This is the UDP port number used for broadcasting. - This parameter is mandatory. This is a UDP specific attribute. +- `group-port`. This is the UDP port number used for broadcasting. + This parameter is mandatory. This is a UDP specific attribute. -- `broadcast-period`. This is the period in milliseconds between - consecutive broadcasts. This parameter is optional, the default - value is `2000` milliseconds. +- `broadcast-period`. This is the period in milliseconds between + consecutive broadcasts. This parameter is optional, the default + value is `2000` milliseconds. -- `connector-ref`. This specifies the connector and optional backup - connector that will be broadcasted (see [Configuring the Transport](configuring-transports.md) for more information on - connectors). +- `connector-ref`. This specifies the connector and optional backup + connector that will be broadcasted (see [Configuring the Transport](configuring-transports.md) for more information on + connectors). Here is another example broadcast group that defines a JGroups broadcast group: - - - test-jgroups-file_ping.xml - activemq_broadcast_channel - 2000 - netty-connector - - +```xml + + + test-jgroups-file_ping.xml + activemq_broadcast_channel + 2000 + netty-connector + + +``` To be able to use JGroups to broadcast, one must specify two attributes, i.e. `jgroups-file` and `jgroups-channel`, as discussed in details as following: -- `jgroups-file` attribute. This is the name of JGroups configuration - file. It will be used to initialize JGroups channels. Make sure the - file is in the java resource path so that Apache ActiveMQ Artemis can load it. +- `jgroups-file` attribute. This is the name of JGroups configuration + file. It will be used to initialize JGroups channels. Make sure the + file is in the java resource path so that Apache ActiveMQ Artemis can load it. -- `jgroups-channel` attribute. The name that JGroups channels connect - to for broadcasting. +- `jgroups-channel` attribute. The name that JGroups channels connect + to for broadcasting. -> **Note** +> **Note:** > > The JGroups attributes (`jgroups-file` and `jgroups-channel`) and UDP > specific attributes described above are exclusive of each other. Only @@ -174,57 +176,59 @@ following: The following is an example of a JGroups file - - - - - - - - - - - - - - - - - - +```xml + + + + + + + + + + + + + + + + + + +``` As it shows, the file content defines a jgroups protocol stacks. If you want Apache ActiveMQ Artemis to use this stacks for channel creation, you have to make @@ -233,7 +237,9 @@ configuration to be the name of this jgroups configuration file. For example if the above stacks configuration is stored in a file named "jgroups-stacks.xml" then your `jgroups-file` should be like - jgroups-stacks.xml +```xml +jgroups-stacks.xml +``` #### Discovery Groups @@ -252,18 +258,18 @@ of time it will remove that server's entry from its list. Discovery groups are used in two places in Apache ActiveMQ Artemis: -- By cluster connections so they know how to obtain an initial - connection to download the topology +- By cluster connections so they know how to obtain an initial + connection to download the topology -- By messaging clients so they know how to obtain an initial - connection to download the topology +- By messaging clients so they know how to obtain an initial + connection to download the topology Although a discovery group will always accept broadcasts, its current list of available live and backup servers is only ever used when an initial connection is made, from then server discovery is done over the normal Apache ActiveMQ Artemis connections. -> **Note** +> **Note:** > > Each discovery group must be configured with broadcast endpoint (UDP > or JGroups) that matches its broadcast group counterpart. For example, @@ -277,67 +283,71 @@ configuration file `broker.xml`. All discovery groups must be defined inside a `discovery-groups` element. There can be many discovery groups defined by Apache ActiveMQ Artemis server. Let's look at an example: - - - 172.16.9.7 - 231.7.7.7 - 9876 - 10000 - - +```xml + + + 172.16.9.7 + 231.7.7.7 + 9876 + 10000 + + +``` We'll consider each parameter of the discovery group: -- `name` attribute. Each discovery group must have a unique name per - server. - -- `local-bind-address`. If you are running with multiple network - interfaces on the same machine, you may want to specify that the - discovery group listens only only a specific interface. To do this - you can specify the interface address with this parameter. This - parameter is optional. This is a UDP specific attribute. - -- `group-address`. This is the multicast IP address of the group to - listen on. It should match the `group-address` in the broadcast - group that you wish to listen from. This parameter is mandatory. - This is a UDP specific attribute. - -- `group-port`. This is the UDP port of the multicast group. It should - match the `group-port` in the broadcast group that you wish to - listen from. This parameter is mandatory. This is a UDP specific - attribute. - -- `refresh-timeout`. This is the period the discovery group waits - after receiving the last broadcast from a particular server before - removing that servers connector pair entry from its list. You would - normally set this to a value significantly higher than the - `broadcast-period` on the broadcast group otherwise servers might - intermittently disappear from the list even though they are still - broadcasting due to slight differences in timing. This parameter is - optional, the default value is `10000` milliseconds (10 seconds). +- `name` attribute. Each discovery group must have a unique name per + server. + +- `local-bind-address`. If you are running with multiple network + interfaces on the same machine, you may want to specify that the + discovery group listens only only a specific interface. To do this + you can specify the interface address with this parameter. This + parameter is optional. This is a UDP specific attribute. + +- `group-address`. This is the multicast IP address of the group to + listen on. It should match the `group-address` in the broadcast + group that you wish to listen from. This parameter is mandatory. + This is a UDP specific attribute. + +- `group-port`. This is the UDP port of the multicast group. It should + match the `group-port` in the broadcast group that you wish to + listen from. This parameter is mandatory. This is a UDP specific + attribute. + +- `refresh-timeout`. This is the period the discovery group waits + after receiving the last broadcast from a particular server before + removing that servers connector pair entry from its list. You would + normally set this to a value significantly higher than the + `broadcast-period` on the broadcast group otherwise servers might + intermittently disappear from the list even though they are still + broadcasting due to slight differences in timing. This parameter is + optional, the default value is `10000` milliseconds (10 seconds). Here is another example that defines a JGroups discovery group: - - - test-jgroups-file_ping.xml - activemq_broadcast_channel - 10000 - - +```xml + + + test-jgroups-file_ping.xml + activemq_broadcast_channel + 10000 + + +``` To receive broadcast from JGroups channels, one must specify two attributes, `jgroups-file` and `jgroups-channel`, as discussed in details as following: -- `jgroups-file` attribute. This is the name of JGroups configuration - file. It will be used to initialize JGroups channels. Make sure the - file is in the java resource path so that Apache ActiveMQ Artemis can load it. +- `jgroups-file` attribute. This is the name of JGroups configuration + file. It will be used to initialize JGroups channels. Make sure the + file is in the java resource path so that Apache ActiveMQ Artemis can load it. -- `jgroups-channel` attribute. The name that JGroups channels connect - to for receiving broadcasts. +- `jgroups-channel` attribute. The name that JGroups channels connect + to for receiving broadcasts. -> **Note** +> **Note:** > > The JGroups attributes (`jgroups-file` and `jgroups-channel`) and UDP > specific attributes described above are exclusive of each other. Only @@ -355,7 +365,9 @@ differs depending on whether you're using JMS or the core API. Use the `udp` URL scheme and a host:port combination matches the group-address and group-port from the corresponding `broadcast-group` on the server: - udp://231.7.7.7:9876 +``` +udp://231.7.7.7:9876 +``` The element `discovery-group-ref` specifies the name of a discovery group defined in `broker.xml`. @@ -402,7 +414,9 @@ A static list of possible servers can also be used by a normal client. A list of servers to be used for the initial connection attempt can be specified in the connection URI using a syntax with `()`, e.g.: - (tcp://myhost:61616,tcp://myhost2:61616)?reconnectAttempts=5 +``` +(tcp://myhost:61616,tcp://myhost2:61616)?reconnectAttempts=5 +``` The brackets are expanded so the same query can be appended after the last bracket for ease. @@ -453,219 +467,223 @@ typical cluster connection. Cluster connections are always defined in There can be zero or more cluster connections defined per Apache ActiveMQ Artemis server. - - -
- netty-connector - 1000 - 5000 - 50000 - 5000 - 500 - 1.0 - 5000 - -1 - -1 - true - ON_DEMAND - 1 - 32000 - 30000 - 1000 - 2 - - - +```xml + + +
+ netty-connector + 1000 + 5000 + 50000 + 5000 + 500 + 1.0 + 5000 + -1 + -1 + true + ON_DEMAND + 1 + 32000 + 30000 + 1000 + 2 + + + +``` In the above cluster connection all parameters have been explicitly specified. The following shows all the available configuration options -- `address` Each cluster connection only applies to addresses that - match the specified `address` field. An address is matched on the - cluster connection when it begins with the string specified in this - field. The `address` field on a cluster connection also supports comma - separated lists and an exclude syntax `!`. To prevent an address - from being matched on this cluster connection, prepend a cluster - connection address string with `!`. - - In the case shown above the cluster connection will load balance - messages sent to all addresses (since it's empty). - - The address can be any value and you can have many cluster - connections with different values of `address`, simultaneously - balancing messages for those addresses, potentially to different - clusters of servers. By having multiple cluster connections on - different addresses a single Apache ActiveMQ Artemis Server can effectively take - part in multiple clusters simultaneously. - - Be careful not to have multiple cluster connections with overlapping - values of `address`, e.g. "europe" and "europe.news" since this - could result in the same messages being distributed between more - than one cluster connection, possibly resulting in duplicate - deliveries. - - Examples: - - - 'eu' - matches all addresses starting with 'eu' - - '!eu' - matches all address except for those starting with 'eu' - - 'eu.uk,eu.de' - matches all addresses starting with either 'eu.uk' or - 'eu.de' - - 'eu,!eu.uk' - matches all addresses starting with 'eu' but not those - starting with 'eu.uk' - - Notes: - - - Address exclusion will always takes precedence over address - inclusion. - - Address matching on cluster connections does not support - wild-card matching. - -- `connector-ref`. This is the connector which will be sent to other - nodes in the cluster so they have the correct cluster topology. - - This parameter is mandatory. - -- `check-period`. The period (in milliseconds) used to check if the - cluster connection has failed to receive pings from another server. - Default is 30000. - -- `connection-ttl`. This is how long a cluster connection should stay - alive if it stops receiving messages from a specific node in the - cluster. Default is 60000. - -- `min-large-message-size`. If the message size (in bytes) is larger - than this value then it will be split into multiple segments when - sent over the network to other cluster members. Default is 102400. - -- `call-timeout`. When a packet is sent via a cluster connection and - is a blocking call, i.e. for acknowledgements, this is how long it - will wait (in milliseconds) for the reply before throwing an - exception. Default is 30000. - -- `retry-interval`. We mentioned before that, internally, cluster - connections cause bridges to be created between the nodes of the - cluster. If the cluster connection is created and the target node - has not been started, or say, is being rebooted, then the cluster - connections from other nodes will retry connecting to the target - until it comes back up, in the same way as a bridge does. - - This parameter determines the interval in milliseconds between retry - attempts. It has the same meaning as the `retry-interval` on a - bridge (as described in [Core Bridges](core-bridges.md)). - - This parameter is optional and its default value is `500` - milliseconds. - -- `retry-interval-multiplier`. This is a multiplier used to increase - the `retry-interval` after each reconnect attempt, default is 1. - -- `max-retry-interval`. The maximum delay (in milliseconds) for - retries. Default is 2000. - -- `initial-connect-attempts`. The number of times the system will try - to connect a node in the cluster initially. If the max-retry is - achieved this node will be considered permanently down and the - system will not route messages to this node. Default is -1 (infinite - retries). - -- `reconnect-attempts`. The number of times the system will try to - reconnect to a node in the cluster. If the max-retry is achieved - this node will be considered permanently down and the system will - stop routing messages to this node. Default is -1 (infinite - retries). - -- `use-duplicate-detection`. Internally cluster connections use - bridges to link the nodes, and bridges can be configured to add a - duplicate id property in each message that is forwarded. If the - target node of the bridge crashes and then recovers, messages might - be resent from the source node. By enabling duplicate detection any - duplicate messages will be filtered out and ignored on receipt at - the target node. - - This parameter has the same meaning as `use-duplicate-detection` on - a bridge. For more information on duplicate detection, please see [Duplicate Detection](duplicate-detection.md). - Default is true. - -- `message-load-balancing`. This parameter determines if/how - messages will be distributed between other nodes of the cluster. - It can be one of three values - `OFF`, `STRICT`, or `ON_DEMAND` - (default). This parameter replaces the deprecated - `forward-when-no-consumers` parameter. - - If this is set to `OFF` then messages will never be forwarded to - another node in the cluster - - If this is set to `STRICT` then each incoming message will be round - robin'd even though the same queues on the other nodes of the - cluster may have no consumers at all, or they may have consumers - that have non matching message filters (selectors). Note that - Apache ActiveMQ Artemis will *not* forward messages to other nodes - if there are no *queues* of the same name on the other nodes, even - if this parameter is set to `STRICT`. Using `STRICT` is like setting - the legacy `forward-when-no-consumers` parameter to `true`. - - If this is set to `ON_DEMAND` then Apache ActiveMQ Artemis will only - forward messages to other nodes of the cluster if the address to which - they are being forwarded has queues which have consumers, and if those - consumers have message filters (selectors) at least one of those - selectors must match the message. Using `ON_DEMAND` is like setting - the legacy `forward-when-no-consumers` parameter to `false`. - - Default is `ON_DEMAND`. - -- `max-hops`. When a cluster connection decides the set of nodes to - which it might load balance a message, those nodes do not have to be - directly connected to it via a cluster connection. Apache ActiveMQ Artemis can be - configured to also load balance messages to nodes which might be - connected to it only indirectly with other Apache ActiveMQ Artemis servers as - intermediates in a chain. - - This allows Apache ActiveMQ Artemis to be configured in more complex topologies and - still provide message load balancing. We'll discuss this more later - in this chapter. - - The default value for this parameter is `1`, which means messages - are only load balanced to other Apache ActiveMQ Artemis serves which are directly - connected to this server. This parameter is optional. - -- `confirmation-window-size`. The size (in bytes) of the window used - for sending confirmations from the server connected to. So once the - server has received `confirmation-window-size` bytes it notifies its - client, default is 1048576. A value of -1 means no window. - -- `producer-window-size`. The size for producer flow control over cluster connection. - it's by default disabled through the cluster connection bridge but you may want - to set a value if you are using really large messages in cluster. A value of -1 means no window. - -- `call-failover-timeout`. Similar to `call-timeout` but used when a - call is made during a failover attempt. Default is -1 (no timeout). - -- `notification-interval`. How often (in milliseconds) the cluster - connection should broadcast itself when attaching to the cluster. - Default is 1000. - -- `notification-attempts`. How many times the cluster connection - should broadcast itself when connecting to the cluster. Default is - 2. - -- `discovery-group-ref`. This parameter determines which discovery - group is used to obtain the list of other servers in the cluster - that this cluster connection will make connections to. +- `address` Each cluster connection only applies to addresses that + match the specified `address` field. An address is matched on the + cluster connection when it begins with the string specified in this + field. The `address` field on a cluster connection also supports comma + separated lists and an exclude syntax `!`. To prevent an address + from being matched on this cluster connection, prepend a cluster + connection address string with `!`. + + In the case shown above the cluster connection will load balance + messages sent to all addresses (since it's empty). + + The address can be any value and you can have many cluster + connections with different values of `address`, simultaneously + balancing messages for those addresses, potentially to different + clusters of servers. By having multiple cluster connections on + different addresses a single Apache ActiveMQ Artemis Server can effectively take + part in multiple clusters simultaneously. + + Be careful not to have multiple cluster connections with overlapping + values of `address`, e.g. "europe" and "europe.news" since this + could result in the same messages being distributed between more + than one cluster connection, possibly resulting in duplicate + deliveries. + + Examples: + + - 'eu' + matches all addresses starting with 'eu' + - '!eu' + matches all address except for those starting with 'eu' + - 'eu.uk,eu.de' + matches all addresses starting with either 'eu.uk' or + 'eu.de' + - 'eu,!eu.uk' + matches all addresses starting with 'eu' but not those + starting with 'eu.uk' + + **Note:**: + + - Address exclusion will always takes precedence over address + inclusion. + - Address matching on cluster connections does not support + wild-card matching. + +- `connector-ref`. This is the connector which will be sent to other + nodes in the cluster so they have the correct cluster topology. + + This parameter is mandatory. + +- `check-period`. The period (in milliseconds) used to check if the + cluster connection has failed to receive pings from another server. + Default is 30000. + +- `connection-ttl`. This is how long a cluster connection should stay + alive if it stops receiving messages from a specific node in the + cluster. Default is 60000. + +- `min-large-message-size`. If the message size (in bytes) is larger + than this value then it will be split into multiple segments when + sent over the network to other cluster members. Default is 102400. + +- `call-timeout`. When a packet is sent via a cluster connection and + is a blocking call, i.e. for acknowledgements, this is how long it + will wait (in milliseconds) for the reply before throwing an + exception. Default is 30000. + +- `retry-interval`. We mentioned before that, internally, cluster + connections cause bridges to be created between the nodes of the + cluster. If the cluster connection is created and the target node + has not been started, or say, is being rebooted, then the cluster + connections from other nodes will retry connecting to the target + until it comes back up, in the same way as a bridge does. + + This parameter determines the interval in milliseconds between retry + attempts. It has the same meaning as the `retry-interval` on a + bridge (as described in [Core Bridges](core-bridges.md)). + + This parameter is optional and its default value is `500` + milliseconds. + +- `retry-interval-multiplier`. This is a multiplier used to increase + the `retry-interval` after each reconnect attempt, default is 1. + +- `max-retry-interval`. The maximum delay (in milliseconds) for + retries. Default is 2000. + +- `initial-connect-attempts`. The number of times the system will try + to connect a node in the cluster initially. If the max-retry is + achieved this node will be considered permanently down and the + system will not route messages to this node. Default is -1 (infinite + retries). + +- `reconnect-attempts`. The number of times the system will try to + reconnect to a node in the cluster. If the max-retry is achieved + this node will be considered permanently down and the system will + stop routing messages to this node. Default is -1 (infinite + retries). + +- `use-duplicate-detection`. Internally cluster connections use + bridges to link the nodes, and bridges can be configured to add a + duplicate id property in each message that is forwarded. If the + target node of the bridge crashes and then recovers, messages might + be resent from the source node. By enabling duplicate detection any + duplicate messages will be filtered out and ignored on receipt at + the target node. + + This parameter has the same meaning as `use-duplicate-detection` on + a bridge. For more information on duplicate detection, please see [Duplicate Detection](duplicate-detection.md). + Default is true. + +- `message-load-balancing`. This parameter determines if/how + messages will be distributed between other nodes of the cluster. + It can be one of three values - `OFF`, `STRICT`, or `ON_DEMAND` + (default). This parameter replaces the deprecated + `forward-when-no-consumers` parameter. + + If this is set to `OFF` then messages will never be forwarded to + another node in the cluster + + If this is set to `STRICT` then each incoming message will be round + robin'd even though the same queues on the other nodes of the + cluster may have no consumers at all, or they may have consumers + that have non matching message filters (selectors). Note that + Apache ActiveMQ Artemis will *not* forward messages to other nodes + if there are no *queues* of the same name on the other nodes, even + if this parameter is set to `STRICT`. Using `STRICT` is like setting + the legacy `forward-when-no-consumers` parameter to `true`. + + If this is set to `ON_DEMAND` then Apache ActiveMQ Artemis will only + forward messages to other nodes of the cluster if the address to which + they are being forwarded has queues which have consumers, and if those + consumers have message filters (selectors) at least one of those + selectors must match the message. Using `ON_DEMAND` is like setting + the legacy `forward-when-no-consumers` parameter to `false`. + + Default is `ON_DEMAND`. + +- `max-hops`. When a cluster connection decides the set of nodes to + which it might load balance a message, those nodes do not have to be + directly connected to it via a cluster connection. Apache ActiveMQ Artemis can be + configured to also load balance messages to nodes which might be + connected to it only indirectly with other Apache ActiveMQ Artemis servers as + intermediates in a chain. + + This allows Apache ActiveMQ Artemis to be configured in more complex topologies and + still provide message load balancing. We'll discuss this more later + in this chapter. + + The default value for this parameter is `1`, which means messages + are only load balanced to other Apache ActiveMQ Artemis serves which are directly + connected to this server. This parameter is optional. + +- `confirmation-window-size`. The size (in bytes) of the window used + for sending confirmations from the server connected to. So once the + server has received `confirmation-window-size` bytes it notifies its + client, default is 1048576. A value of -1 means no window. + +- `producer-window-size`. The size for producer flow control over cluster connection. + it's by default disabled through the cluster connection bridge but you may want + to set a value if you are using really large messages in cluster. A value of -1 means no window. + +- `call-failover-timeout`. Similar to `call-timeout` but used when a + call is made during a failover attempt. Default is -1 (no timeout). + +- `notification-interval`. How often (in milliseconds) the cluster + connection should broadcast itself when attaching to the cluster. + Default is 1000. + +- `notification-attempts`. How many times the cluster connection + should broadcast itself when connecting to the cluster. Default is + 2. + +- `discovery-group-ref`. This parameter determines which discovery + group is used to obtain the list of other servers in the cluster + that this cluster connection will make connections to. Alternatively if you would like your cluster connections to use a static list of servers for discovery then you can do it like this. - - ... - - server0-connector - server1-connector - - +```xml + + ... + + server0-connector + server1-connector + + +``` Here we have defined 2 servers that we know for sure will that at least one will be available. There may be many more servers in the cluster but @@ -678,8 +696,10 @@ When creating connections between nodes of a cluster to form a cluster connection, Apache ActiveMQ Artemis uses a cluster user and cluster password which is defined in `broker.xml`: - ACTIVEMQ.CLUSTER.ADMIN.USER - CHANGE ME!! +```xml +ACTIVEMQ.CLUSTER.ADMIN.USER +CHANGE ME!! +``` > **Warning** > @@ -701,35 +721,35 @@ policies, and you can also implement your own and use that. The out-of-the-box policies are -- Round Robin. With this policy the first node is chosen randomly then - each subsequent node is chosen sequentially in the same order. +- Round Robin. With this policy the first node is chosen randomly then + each subsequent node is chosen sequentially in the same order. - For example nodes might be chosen in the order B, C, D, A, B, C, D, - A, B or D, A, B, C, D, A, B, C, D or C, D, A, B, C, D, A, B, C. + For example nodes might be chosen in the order B, C, D, A, B, C, D, + A, B or D, A, B, C, D, A, B, C, D or C, D, A, B, C, D, A, B, C. - Use - `org.apache.activemq.artemis.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy` - as the ``. + Use + `org.apache.activemq.artemis.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy` + as the ``. -- Random. With this policy each node is chosen randomly. +- Random. With this policy each node is chosen randomly. - Use - `org.apache.activemq.artemis.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy` - as the ``. + Use + `org.apache.activemq.artemis.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy` + as the ``. -- Random Sticky. With this policy the first node is chosen randomly - and then re-used for subsequent connections. +- Random Sticky. With this policy the first node is chosen randomly + and then re-used for subsequent connections. - Use - `org.apache.activemq.artemis.api.core.client.loadbalance.RandomStickyConnectionLoadBalancingPolicy` - as the ``. + Use + `org.apache.activemq.artemis.api.core.client.loadbalance.RandomStickyConnectionLoadBalancingPolicy` + as the ``. -- First Element. With this policy the "first" (i.e. 0th) node is - always returned. +- First Element. With this policy the "first" (i.e. 0th) node is + always returned. - Use - `org.apache.activemq.artemis.api.core.client.loadbalance.FirstElementConnectionLoadBalancingPolicy` - as the ``. + Use + `org.apache.activemq.artemis.api.core.client.loadbalance.FirstElementConnectionLoadBalancingPolicy` + as the ``. You can also implement your own policy by implementing the interface `org.apache.activemq.artemis.api.core.client.loadbalance.ConnectionLoadBalancingPolicy` @@ -742,15 +762,17 @@ default will be used which is The parameter `connectionLoadBalancingPolicyClassName` can be set on the URI to configure what load balancing policy to use: - tcp://localhost:61616?connectionLoadBalancingPolicyClassName=org.apache.activemq.artemis.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy +``` +tcp://localhost:61616?connectionLoadBalancingPolicyClassName=org.apache.activemq.artemis.api.core.client.loadbalance.RandomConnectionLoadBalancingPolicy +``` The set of servers over which the factory load balances can be determined in one of two ways: -- Specifying servers explicitly in the URL. This also requires setting - the `useTopologyForLoadBalancing` parameter to `false` on the URL. +- Specifying servers explicitly in the URL. This also requires setting + the `useTopologyForLoadBalancing` parameter to `false` on the URL. -- Using discovery. This is the default behavior. +- Using discovery. This is the default behavior. ## Specifying Members of a Cluster Explicitly @@ -760,17 +782,19 @@ typically used to form non symmetrical clusters such as chain cluster or ring clusters. This can only be done using a static list of connectors and is configured as follows: - -
jms
- netty-connector - 500 - true - STRICT - 1 - - server1-connector - - +```xml + +
+ netty-connector + 500 + true + STRICT + 1 + + server1-connector + + +``` In this example we have set the attribute `allow-direct-connections-only` which means that the only server that @@ -808,11 +832,13 @@ information on configuring address settings, please see [Configuring Addresses a Here's an address settings snippet from `broker.xml` showing how message redistribution is enabled for a set of queues: - - - 0 - - +```xml + + + 0 + + +``` The above `address-settings` block would set a `redistribution-delay` of `0` for any queue which is bound to any address. So the above would enable