http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/send-guarantees.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/send-guarantees.md b/docs/user-manual/en/send-guarantees.md index 79b9097..da631e4 100644 --- a/docs/user-manual/en/send-guarantees.md +++ b/docs/user-manual/en/send-guarantees.md @@ -32,15 +32,15 @@ has definitely reached the server, and a response has been sent back to the client. This can be configured individually for durable and non-durable messages, and is determined by the following two URL parameters: -- `blockOnDurableSend`. If this is set to `true` then all calls to - send for durable messages on non transacted sessions will block - until the message has reached the server, and a response has been - sent back. The default value is `true`. - -- `blockOnNonDurableSend`. If this is set to `true` then all calls to - send for non-durable messages on non transacted sessions will block - until the message has reached the server, and a response has been - sent back. The default value is `false`. +- `blockOnDurableSend`. If this is set to `true` then all calls to + send for durable messages on non transacted sessions will block + until the message has reached the server, and a response has been + sent back. The default value is `true`. + +- `blockOnNonDurableSend`. If this is set to `true` then all calls to + send for non-durable messages on non transacted sessions will block + until the message has reached the server, and a response has been + sent back. The default value is `false`. Setting block on sends to `true` can reduce performance since each send requires a network round trip before the next send can be performed.
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/slow-consumers.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/slow-consumers.md b/docs/user-manual/en/slow-consumers.md index 49d5141..fc85d38 100644 --- a/docs/user-manual/en/slow-consumers.md +++ b/docs/user-manual/en/slow-consumers.md @@ -36,5 +36,5 @@ the detection algorithm. See [thread pooling](thread-pooling.md) for more detail ## Example -See the [examples](examples.md) chapter for an example which shows how to detect a slow consumer +See the [slow consumer example](examples.md#slow-consumer) which shows how to detect a slow consumer with Apache ActiveMQ Artemis. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/spring-integration.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/spring-integration.md b/docs/user-manual/en/spring-integration.md index 9c7c939..f63df5c 100644 --- a/docs/user-manual/en/spring-integration.md +++ b/docs/user-manual/en/spring-integration.md @@ -1,39 +1,16 @@ # Spring Integration Apache ActiveMQ Artemis provides a simple bootstrap class, -`org.apache.activemq.integration.spring.SpringJmsBootstrap`, for -integration with Spring. To use it, you configure Apache ActiveMQ Artemis as you always -would, through its various configuration files like -`broker.xml`. +`org.apache.activemq.artemis.integration.spring.SpringJmsBootstrap`, for +integration with Spring. To use it, you configure Apache ActiveMQ Artemis as +you always would, through its various configuration files like `broker.xml`. -Here we've specified a `javax.jms.ConnectionFactory` we want bound to a -`ConnectionFactory` entry as well as a queue destination bound to a -`/queue/exampleQueue` entry. Using the `SpringJmsBootStrap` bean will -automatically populate the Spring context with references to those beans -so that you can use them. Below is an example Spring JMS bean file -taking advantage of this feature: +The `SpringJmsBootstrap` class extends the EmbeddedJMS class talked about in +[embedding ActiveMQ](embedding-activemq.md) and the same defaults and +configuration options apply. See the javadocs for more details on other +properties of the bean class. -```xml -<beans xmlns="http://www.springframework.org/schema/beans"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://www.springframework.org/schema/beans - http://www.springframework.org/schema/beans/spring-beans-3.0.xsd";> +## Example - <bean id="EmbeddedJms" class="org.apache.activemq.integration.spring.SpringJmsBootstrap" init-method="start"/> - - <bean id="listener" class="org.apache.activemq.tests.integration.spring.ExampleListener"/> - - <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> - <property name="connectionFactory" ref="ConnectionFactory"/> - <property name="destination" ref="/queue/exampleQueue"/> - <property name="messageListener" ref="listener"/> - </bean> -</beans> -``` - -As you can see, the `listenerContainer` bean references the components -defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class -extends the EmbeddedJMS class talked about in [JMS API](embedding-activemq.md) and the same defaults -and configuration options apply. Also notice that an `init-method` must -be declared with a start value so that the bean's lifecycle is executed. -See the javadocs for more details on other properties of the bean class. +See the [Spring Integration Example](examples.md#spring-integration) for a +demonstration of how this can work. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/stomp.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/stomp.md b/docs/user-manual/en/stomp.md new file mode 100644 index 0000000..8ba11f2 --- /dev/null +++ b/docs/user-manual/en/stomp.md @@ -0,0 +1,293 @@ +# STOMP + +[STOMP](https://stomp.github.io/) is a text-orientated wire protocol that +allows STOMP clients to communicate with STOMP Brokers. Apache ActiveMQ Artemis +supports STOMP 1.0, 1.1 and 1.2. + +STOMP clients are available for several languages and platforms making it a +good choice for interoperability. + +By default there are `acceptor` elements configured to accept STOMP connections +on ports `61616` and `61613`. + +See the general [Protocols and Interoperability](protocols-interoperability.md) +chapter for details on configuring an `acceptor` for STOMP. + +Refer to the STOMP examples for a look at some of this functionality in action. + +## Limitations + +The STOMP specification identifies **transactional acknowledgements** as an +optional feature. Support for transactional acknowledgements is not implemented +in Apache ActiveMQ Artemis. The `ACK` frame can not be part of a transaction. +It will be ignored if its `transaction` header is set. + +## Virtual Hosting + +Apache ActiveMQ Artemis currently doesn't support virtual hosting, which means +the `host` header in `CONNECT` frame will be ignored. + +## Mapping STOMP destinations to addresses and queues + +STOMP clients deals with *destinations* when sending messages and subscribing. +Destination names are simply strings which are mapped to some form of +destination on the server - how the server translates these is left to the +server implementation. + +In Apache ActiveMQ Artemis, these destinations are mapped to *addresses* and +*queues* depending on the operation being done and the desired semantics (e.g. +anycast or multicast). + +## Sending + +When a STOMP client sends a message (using a `SEND` frame), the protocol +manager looks at the message to determine where to route it and potentially how +to create the address and/or queue to which it is being sent. The protocol +manager uses either of the following bits of information from the frame to +determine the routing type: + +1. The value of the `destination-type` header. Valid values are `ANYCAST` and + `MULTICAST` (case sensitive). + +2. The "prefix" on the `destination` header. See [additional + info](address-model.md#using-prefixes-to-determine-routing-type) on + prefixes. + +If no indication of routing type is supplied then anycast semantics are used. + +The `destination` header maps to an address of the same name. If the +`destination` header used a prefix then the prefix is stripped. + +## Subscribing + +When a STOMP client subscribes to a destination (using a `SUBSCRIBE` frame), +the protocol manager looks at the frame to determine what subscription +semantics to use and potentially how to create the address and/or queue for the +subscription. The protocol manager uses either of the following bits of +information from the frame to determine the routing type: + +1. The value of the `subscription-type` header. Valid values are `ANYCAST` and + `MULTICAST` (case sensitive). + +2. The "prefix" on the `destination` header. See [additional + info](address-model.md#using-prefixes-to-determine-routing-type) on + prefixes. + +If no indication of routing type is supplied then anycast semantics are used. + +The `destination` header maps to an address of the same name if multicast is +used or to a queue of the same name if anycast is used. If the `destination` +header used a prefix then the prefix is stripped. + +## STOMP heart-beating and connection-ttl + +Well behaved STOMP clients will always send a `DISCONNECT` frame before closing +their connections. In this case the server will clear up any server side +resources such as sessions and consumers synchronously. However if STOMP +clients exit without sending a `DISCONNECT` frame or if they crash the server +will have no way of knowing immediately whether the client is still alive or +not. STOMP connections therefore default to a `connection-ttl` value of 1 +minute (see chapter on [connection-ttl](connection-ttl.md) for more +information. This value can be overridden using the `connection-ttl-override` +property or if you need a specific connectionTtl for your stomp connections +without affecting the broker-wide `connection-ttl-override` setting, you can +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: + +```xml +<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor> +``` + +The above configuration will make sure that any STOMP connection that is +created from that acceptor and does not include a `heart-beat` header or +disables client-to-server heart-beats by specifying a `0` value will have its +`connection-ttl` set to 20 seconds. The `connectionTtl` set on an acceptor will +take precedence over `connection-ttl-override`. The default `connectionTtl` is +60,000 milliseconds. + +Since STOMP 1.0 does not support heart-beating then all connections from STOMP +1.0 clients will have a connection TTL imposed upon them by the broker based on +the aforementioned configuration options. Likewise, any STOMP 1.1 or 1.2 +clients that don't specify a `heart-beat` header or disable client-to-server +heart-beating (e.g. by sending `0,X` in the `heart-beat` header) will have a +connection TTL imposed upon them by the broker. + +For STOMP 1.1 and 1.2 clients which send a non-zero client-to-server +`heart-beat` header value then their connection TTL will be set accordingly. +However, the broker will not strictly set the connection TTL to the same value +as the specified in the `heart-beat` since even small network delays could then +cause spurious disconnects. Instead, the client-to-server value in the +`heart-beat` will be multiplied by the `heartBeatConnectionTtlModifer` +specified on the acceptor. The `heartBeatConnectionTtlModifer` is a decimal +value that defaults to `2.0` so for example, if a client sends a `heart-beat` +header of `1000,0` the the connection TTL will be set to `2000` so that the +data or ping frames sent every 1000 milliseconds will have a sufficient cushion +so as not to be considered late and trigger a disconnect. This is also in +accordance with the STOMP 1.1 and 1.2 specifications which both state, "because +of timing inaccuracies, the receiver SHOULD be tolerant and take into account +an error margin." + +The minimum and maximum connection TTL allowed can also be specified on the +acceptor via the `connectionTtlMin` and `connectionTtlMax` properties +respectively. The default `connectionTtlMin` is 1000 and the default +`connectionTtlMax` is Java's `Long.MAX_VALUE` meaning there essentially is no +max connection TTL by default. Keep in mind that the +`heartBeatConnectionTtlModifer` is relevant here. For example, if a client +sends a `heart-beat` header of `20000,0` and the acceptor is using a +`connectionTtlMax` of `30000` and a default `heartBeatConnectionTtlModifer` of +`2.0` then the connection TTL would be `40000` (i.e. `20000` * `2.0`) which +would exceed the `connectionTtlMax`. In this case the server would respond to +the client with a `heart-beat` header of `0,15000` (i.e. `30000` / `2.0`). As +described previously, this is to make sure there is a sufficient cushion for +the client heart-beats in accordance with the STOMP 1.1 and 1.2 specifications. +The same kind of calculation is done for `connectionTtlMin`. + +The minimum server-to-client heart-beat value is 500ms. + +> **Note:** +> +> Please note that the STOMP protocol version 1.0 does not contain any +> heart-beat frame. It is therefore the user's responsibility to make sure data +> is sent within connection-ttl or the server will assume the client is dead +> and clean up server side resources. With STOMP 1.1 users can use heart-beats +> to maintain the life cycle of stomp connections. + +## Selector/Filter expressions + +STOMP subscribers can specify an expression used to select or filter what the +subscriber receives using the `selector` header. The filter expression syntax +follows the *core filter syntax* described in the [Filter +Expressions](filter-expressions.md) documentation. + +## STOMP and JMS interoperability + +### Sending and consuming STOMP message from JMS or Core API + +STOMP is mainly a text-orientated protocol. To make it simpler to interoperate +with JMS and Core API, our STOMP implementation checks for presence of the +`content-length` header to decide how to map a STOMP 1.0 message to a JMS +Message or a Core message. + +If the STOMP 1.0 message does *not* have a `content-length` header, it will be +mapped to a JMS *TextMessage* or a Core message with a *single nullable +SimpleString in the body buffer*. + +Alternatively, if the STOMP 1.0 message *has* a `content-length` header, it +will be mapped to a JMS *BytesMessage* or a Core message with a *byte[] in the +body buffer*. + +The same logic applies when mapping a JMS message or a Core message to STOMP. A +STOMP 1.0 client can check the presence of the `content-length` header to +determine the type of the message body (String or bytes). + +### Message IDs for STOMP messages + +When receiving STOMP messages via a JMS consumer or a QueueBrowser, the +messages have no properties like JMSMessageID by default. However this may +bring some inconvenience to clients who wants an ID for their purpose. The +broker STOMP provides a parameter to enable message ID on each incoming STOMP +message. If you want each STOMP message to have a unique ID, just set the +`stompEnableMessageId` to true. For example: + +```xml +<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor> +``` + +When the server starts with the above setting, each stomp message sent through +this acceptor will have an extra property added. The property key is +`amq-message-id` and the value is a String representation of a long type +internal message id prefixed with `STOMP`, like: + +``` +amq-message-id : STOMP12345 +``` + +The default `stomp-enable-message-id` value is `false`. + +## Durable Subscriptions + +The `SUBSCRIBE` and `UNSUBSCRIBE` frames can be augmented with special headers +to create and destroy durable subscriptions respectively. + +To create a durable subscription the `client-id` header must be set on the +`CONNECT` frame and the `durable-subscription-name` must be set on the +`SUBSCRIBE` frame. The combination of these two headers will form the identity +of the durable subscription. + +To delete a durable subscription the `client-id` header must be set on the +`CONNECT` frame and the `durable-subscription-name` must be set on the +`UNSUBSCRIBE` frame. The values for these headers should match what was set on +the `SUBSCRIBE` frame to delete the corresponding durable subscription. + +It is possible to pre-configure durable subscriptions since the STOMP +implementation creates the queue used for the durable subscription in a +deterministic way (i.e. using the format of `client-id`.`subscription-name`). +For example, if you wanted to configure a durable subscription on the address +`myAddress` with a client-id of `myclientid` and a subscription name of +`mysubscription` then configure the durable subscription: + +```xml +<addresses> + <address name="myAddress"> + <multicast> + <queue name="myclientid.mysubscription"/> + </multicast> + </address> +</addresses> +``` + +## Handling of Large Messages with STOMP + +STOMP clients may send very large frame bodies which can exceed the size of the +broker's internal buffer, causing unexpected errors. To prevent this situation +from happening, the broker provides a STOMP configuration attribute +`stompMinLargeMessageSize`. This attribute can be configured inside a stomp +acceptor, as a parameter. For example: + +```xml +<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor> +``` + +The type of this attribute is integer. When this attributed is configured, the +broker will check the size of the body of each STOMP frame arrived from +connections established with this acceptor. If the size of the body is equal or +greater than the value of `stompMinLargeMessageSize`, the message will be +persisted as a large message. When a large message is delievered to a STOMP +consumer, the broker will automatically handle the conversion from a large +message to a normal message, before sending it to the client. + +If a large message is compressed, the server will uncompressed it before +sending it to stomp clients. The default value of `stompMinLargeMessageSize` is +the same as the default value of +[min-large-message-size](large-messages.md#configuring-parameters). + +## Web Sockets + +Apache ActiveMQ Artemis also support STOMP over [Web +Sockets](https://html.spec.whatwg.org/multipage/web-sockets.html). Modern web +browsers which support Web Sockets can send and receive STOMP messages. + +STOMP over Web Sockets is supported via the normal STOMP acceptor: + +```xml +<acceptor name="stomp-ws-acceptor">tcp://localhost:61614?protocols=STOMP</acceptor> +``` + +With this configuration, Apache ActiveMQ Artemis will accept STOMP connections +over Web Sockets on the port `61614`. Web browsers can then connect to +`ws://<server>:61614` using a Web Socket to send and receive STOMP messages. + +A companion JavaScript library to ease client-side development is available +from [GitHub](https://github.com/jmesnil/stomp-websocket) (please see its +[documentation](http://jmesnil.net/stomp-websocket/doc/) for a complete +description). + +The payload length of Web Socket frames can vary between client +implementations. By default the broker will accept frames with a payload length +of 65,536. If the client needs to send payloads longer than this in a single +frame this length can be adjusted by using the `stompMaxFramePayloadLength` URL +parameter on the acceptor. + +The `stomp-websockets` example shows how to configure an Apache ActiveMQ +Artemis broker to have web browsers and Java applications exchanges messages. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/syntax.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/syntax.md b/docs/user-manual/en/syntax.md index 71db615..c37820d 100644 --- a/docs/user-manual/en/syntax.md +++ b/docs/user-manual/en/syntax.md @@ -11,7 +11,7 @@ Somejava s = new SomeJava(); ``` -> **Note** +> **Note:** > > This is a Note http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/tools.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/tools.md b/docs/user-manual/en/tools.md deleted file mode 100644 index 4a6aa0d..0000000 --- a/docs/user-manual/en/tools.md +++ /dev/null @@ -1,216 +0,0 @@ -# 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 -imp | Imports the journal to a running broker using the output from expt -data | Prints a report about journal records and summary of existent records, as well a report on paging -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: - -``` -$ ./artemis help data print -NAME - artemis data print - Print data records information (WARNING: don't use - while a production server is running) - -SYNOPSIS - artemis data print [--bindings <binding>] [--journal <journal>] - [--paging <paging>] - -OPTIONS - --bindings <binding> - The folder used for bindings (default ../data/bindings) - - --journal <journal> - The folder used for messages journal (default ../data/journal) - - --paging <paging> - The folder used for paging (default ../data/paging) - - -``` - - -For a full list of data tools commands available use: - -``` -NAME - artemis data - data tools group - (print|imp|exp|encode|decode|compact) (example ./artemis data print) - -SYNOPSIS - artemis data - artemis data compact [--broker <brokerConfig>] [--verbose] - [--paging <paging>] [--journal <journal>] - [--large-messages <largeMessges>] [--bindings <binding>] - artemis data decode [--broker <brokerConfig>] [--suffix <suffix>] - [--verbose] [--paging <paging>] [--prefix <prefix>] [--file-size <size>] - [--directory <directory>] --input <input> [--journal <journal>] - [--large-messages <largeMessges>] [--bindings <binding>] - artemis data encode [--directory <directory>] [--broker <brokerConfig>] - [--suffix <suffix>] [--verbose] [--paging <paging>] [--prefix <prefix>] - [--file-size <size>] [--journal <journal>] - [--large-messages <largeMessges>] [--bindings <binding>] - artemis data exp [--broker <brokerConfig>] [--verbose] - [--paging <paging>] [--journal <journal>] - [--large-messages <largeMessges>] [--bindings <binding>] - artemis data imp [--host <host>] [--verbose] [--port <port>] - [--password <password>] [--transaction] --input <input> [--user <user>] - artemis data print [--broker <brokerConfig>] [--verbose] - [--paging <paging>] [--journal <journal>] - [--large-messages <largeMessges>] [--bindings <binding>] - -COMMANDS - With no arguments, Display help information - - print - Print data records information (WARNING: don't use while a - production server is running) - - With --broker option, This would override the broker configuration - from the bootstrap - - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --bindings option, The folder used for bindings (default from - broker.xml) - - exp - Export all message-data using an XML that could be interpreted by - any system. - - With --broker option, This would override the broker configuration - from the bootstrap - - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --bindings option, The folder used for bindings (default from - broker.xml) - - imp - Import all message-data using an XML that could be interpreted by - any system. - - With --host option, The host used to import the data (default - localhost) - - With --verbose option, Adds more information on the execution - - With --port option, The port used to import the data (default 61616) - - With --password option, User name used to import the data. (default - null) - - With --transaction option, If this is set to true you will need a - whole transaction to commit at the end. (default false) - - With --input option, The input file name (default=exp.dmp) - - With --user option, User name used to import the data. (default - null) - - decode - Decode a journal's internal format into a new journal set of files - - With --broker option, This would override the broker configuration - from the bootstrap - - With --suffix option, The journal suffix (default amq) - - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - - With --prefix option, The journal prefix (default activemq-data) - - With --file-size option, The journal size (default 10485760) - - With --directory option, The journal folder (default journal folder - from broker.xml) - - With --input option, The input file name (default=exp.dmp) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --bindings option, The folder used for bindings (default from - broker.xml) - - encode - Encode a set of journal files into an internal encoded data format - - With --directory option, The journal folder (default the journal - folder from broker.xml) - - With --broker option, This would override the broker configuration - from the bootstrap - - With --suffix option, The journal suffix (default amq) - - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - - With --prefix option, The journal prefix (default activemq-data) - - With --file-size option, The journal size (default 10485760) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --bindings option, The folder used for bindings (default from - broker.xml) - - compact - Compacts the journal of a non running server - - With --broker option, This would override the broker configuration - from the bootstrap - - With --verbose option, Adds more information on the execution - - With --paging option, The folder used for paging (default from - broker.xml) - - With --journal option, The folder used for messages journal (default - from broker.xml) - - With --large-messages option, The folder used for large-messages - (default from broker.xml) - - With --bindings option, The folder used for bindings (default from - broker.xml) -``` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/undelivered-messages.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/undelivered-messages.md b/docs/user-manual/en/undelivered-messages.md index 6156c8f..5ef5565 100644 --- a/docs/user-manual/en/undelivered-messages.md +++ b/docs/user-manual/en/undelivered-messages.md @@ -8,18 +8,18 @@ in the queue indefinitely, clogging the system. There are 2 ways to deal with these undelivered messages: -- Delayed redelivery. +- Delayed redelivery. - It is possible to delay messages redelivery. This gives the client some - time to recover from any transient failures and to prevent overloading - its network or CPU resources. + It is possible to delay messages redelivery. This gives the client some + time to recover from any transient failures and to prevent overloading + its network or CPU resources. -- Dead Letter Address. +- Dead Letter Address. - It is also possible to configure a dead letter address so that after - a specified number of unsuccessful deliveries, messages are removed - from their queue and sent to the dead letter address. These messages - will not be delivered again from this queue. + It is also possible to configure a dead letter address so that after + a specified number of unsuccessful deliveries, messages are removed + from their queue and sent to the dead letter address. These messages + will not be delivered again from this queue. Both options can be combined for maximum flexibility. @@ -130,15 +130,15 @@ set of addresses (see [Understanding the Wildcard Syntax](wildcard-syntax.md)). Dead letter messages which are consumed from a dead letter address have the following properties: -- `_AMQ_ORIG_ADDRESS` +- `_AMQ_ORIG_ADDRESS` - a String property containing the *original address* of the dead - letter message + a String property containing the *original address* of the dead + letter message -- `_AMQ_ORIG_QUEUE` +- `_AMQ_ORIG_QUEUE` - a String property containing the *original queue* of the dead letter - message + a String property containing the *original queue* of the dead letter + message ### Example http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/unit-testing.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/unit-testing.md b/docs/user-manual/en/unit-testing.md index 7beb311..859ec00 100644 --- a/docs/user-manual/en/unit-testing.md +++ b/docs/user-manual/en/unit-testing.md @@ -1,29 +1,26 @@ # Unit Testing -The package ```artemis-junit``` provides tools to facilitate how to run Artemis resources inside Junit Tests. +The package `artemis-junit` provides tools to facilitate how to run Artemis resources inside JUnit Tests. -These are provided as junit rules and can make it easier to embed Messaging functionality on your tests. +These are provided as JUnit "rules" and can make it easier to embed messaging functionality on your tests. ## Example - ### Import this on your pom.xml ```xml <dependency> - <groupId>org.apache.activemq</groupId> - <artifactId>artemis-junit</artifactId> - <!-- replace this for the version you are using --> - <version>1.5.0</version> - <scope>test</scope> + <groupId>org.apache.activemq</groupId> + <artifactId>artemis-junit</artifactId> + <!-- replace this for the version you are using --> + <version>2.5.0</version> + <scope>test</scope> </dependency> ``` - ### Declare a rule on your JUnit Test - ```java import org.apache.activemq.artemis.junit.EmbeddedJMSResource; import org.junit.Rule; @@ -44,34 +41,31 @@ public class MyTest { This will start a server that will be available for your test: ``` -ain] 17:00:16,644 INFO [org.apache.activemq.artemis.core.server] AMQ221000: live Message Broker is starting with configuration Broker Configuration (clustered=false,journalDirectory=data/journal,bindingsDirectory=data/bindings,largeMessagesDirectory=data/largemessages,pagingDirectory=data/paging) +[main] 17:00:16,644 INFO [org.apache.activemq.artemis.core.server] AMQ221000: live Message Broker is starting with configuration Broker Configuration (clustered=false,journalDirectory=data/journal,bindingsDirectory=data/bindings,largeMessagesDirectory=data/largemessages,pagingDirectory=data/paging) [main] 17:00:16,666 INFO [org.apache.activemq.artemis.core.server] AMQ221045: libaio is not available, switching the configuration into NIO [main] 17:00:16,688 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-server]. Adding protocol support for: CORE [main] 17:00:16,801 INFO [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live [main] 17:00:16,801 INFO [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 1.5.0-SNAPSHOT [embedded-jms-server, nodeID=39e78380-842c-11e6-9e43-f45c8992f3c7] [main] 17:00:16,891 INFO [org.apache.activemq.artemis.core.server] AMQ221002: Apache ActiveMQ Artemis Message Broker version 1.5.0-SNAPSHOT [39e78380-842c-11e6-9e43-f45c8992f3c7] stopped, uptime 0.272 seconds - ``` - ### Ordering rules -This is actually a Junit feature, but this could be helpful on pre-determining the order on which rules are executed. +This is actually a JUnit feature, but this could be helpful on pre-determining the order on which rules are executed. ```java - ActiveMQDynamicProducerResource producer = new ActiveMQDynamicProducerResource(server.getVmURL()); - - @Rule - public RuleChain ruleChain = RuleChain.outerRule(new ThreadLeakCheckRule()).around(server).around(producer); +ActiveMQDynamicProducerResource producer = new ActiveMQDynamicProducerResource(server.getVmURL()); +@Rule +public RuleChain ruleChain = RuleChain.outerRule(new ThreadLeakCheckRule()).around(server).around(producer); ``` ### Available Rules Name | Description -:--- | :--- -EmbeddedActiveMQResource | It will run a Server, without the JMS manager -EmbeddedJMSResource | It will run a Server, including the JMS Manager -ActiveMQConsumerResource | It will automate the creation of a consumer -ActiveMQProducerResource | It will automate the creation of a producer -ThreadLeakCheckRule | It will check that all threads have been finished after the test is finished +--- | --- +EmbeddedActiveMQResource | Run a Server, without the JMS manager +EmbeddedJMSResource | Run a Server, including the JMS Manager +ActiveMQConsumerResource | Automate the creation of a consumer +ActiveMQProducerResource | Automate the creation of a producer +ThreadLeakCheckRule | Check that all threads have been finished after the test is finished http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/upgrading.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/upgrading.md b/docs/user-manual/en/upgrading.md index e564f49..61609b8 100644 --- a/docs/user-manual/en/upgrading.md +++ b/docs/user-manual/en/upgrading.md @@ -1,38 +1,41 @@ # Upgrading the Broker -Apache ActiveMQ 5.x (and previous versions) is runnable out of the box by executing -the command: `./bin/activemq run`. The ActiveMQ Artemis broker follows a different -paradigm where the project distribution serves as the broker "home" and one or more -broker "instances" are created which reference the "home" for resources (e.g. jar files) -which can be safely shared between broker instances. Therefore, an instance of the broker -must be created before it can be run. This may seems like an overhead at first -glance, but it becomes very practical when updating to a new Artemis version for example. - -To create an Artemis broker instance navigate into the Artemis home folder and run: -`./bin/artemis create /path/to/myBrokerInstance` on the command line. - -> **Note** -> -> It's recommended to choose a folder different than the on where Apache Artemis was -> 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. +Apache ActiveMQ 5.x (and previous versions) is runnable out of the box by +executing the command: `./bin/activemq run`. The ActiveMQ Artemis broker +follows a different paradigm where the project distribution serves as the +broker "home" and one or more broker "instances" are created which reference +the "home" for resources (e.g. jar files) which can be safely shared between +broker instances. Therefore, an instance of the broker must be created before +it can be run. This may seems like an overhead at first glance, but it becomes +very practical when updating to a new Artemis version for example. + +To create an Artemis broker instance navigate into the Artemis home folder and +run: `./bin/artemis create /path/to/myBrokerInstance` on the command line. -Because of this separation it's very easy to upgrade Artemis in most cases. +Because of this separation it's very easy to upgrade Artemis in most cases. + +> **Note:** +> +> It's recommended to choose a folder different than the on where Apache +> Artemis was 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. ## General Upgrade Procedure -Upgrading may require some specific steps noted in the [versions](versions.md), but the -general process is as follows: +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 - which is relevant for the upgrade: +1. Open `artemis.profile` (`artemis.profile.cmd` on Windows). It contains a + property which is relevant for the upgrade: ``` ARTEMIS_HOME='/path/to/apache-artemis-version' ``` -The `ARTEMIS_HOME` property is used to link the instance with the home. -_In most cases_ the instance can be upgraded to a newer version simply by changing the -value of this property to the location of the new broker home. Please refer to the -aforementioned [versions](versions.md) document for additional upgrade steps (if required). \ No newline at end of file +The `ARTEMIS_HOME` property is used to link the instance with the home. _In +most cases_ the instance can be upgraded to a newer version simply by changing +the value of this property to the location of the new broker home. Please refer +to the aforementioned [versions](versions.md) document for additional upgrade +steps (if required). http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/using-AMQP.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/using-AMQP.md b/docs/user-manual/en/using-AMQP.md deleted file mode 100644 index 49d0478..0000000 --- a/docs/user-manual/en/using-AMQP.md +++ /dev/null @@ -1,74 +0,0 @@ -# Using AMQP - -Apache ActiveMQ Artemis is also a pure AMQP 1.0 broker, with a high performant and feature complete protocol manager for AMQP. - -You can use *any* AMQP 1.0 compatible clients. - -A short list includes: - -- qpid clients at the [qpid project](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. - - -# 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 on a AMQP JMS Client, you must follow the JMS Mapping convention: - -- [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. - -So, 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. - - -# Example - -We have a few examples as part of the Artemis distribution: - - -- .NET: - * ./examples/protocols/amqp/dotnet - -- ProtonCPP - * ./examples/protocols/amqp/proton-cpp - -- Ruby - * ./examples/protocols/amqp/proton-ruby - -- Java (Using the qpid JMS Client) - * ./examples/protocols/amqp/queue - -- Interceptors - * ./examples/features/standard/broker-plugin - - - # Intercepting and changing messages - - We don't recommend changing messages at the server's side for a few reasons: - - - AMQPMessages 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 example under ./examples/features/standard/broker-plugin. - -This example will send AMQP Message and modify properties before they reach the journals and are sent to the consumers. - - - http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/using-core.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/using-core.md b/docs/user-manual/en/using-core.md deleted file mode 100644 index 78c08a5..0000000 --- a/docs/user-manual/en/using-core.md +++ /dev/null @@ -1,212 +0,0 @@ -# Using Core - -Apache ActiveMQ Artemis core is a completely JMS-agnostic messaging system with its own -API. We call this the *core API*. - -If you don't want to use JMS or other protocols you can use the core API directly. The core -API provides all the functionality of JMS but without much of the -complexity. It also provides features that are not available using JMS. - -## Core Messaging Concepts - -Some of the core messaging concepts are similar to JMS concepts, but -core messaging concepts differ in some ways. In general the core -messaging API is simpler than the JMS API, since we remove distinctions -between queues, topics and subscriptions. We'll discuss each of the -major core messaging concepts in turn, but to see the API in detail, -please consult the Javadoc. - -### Message - -- A message is the unit of data which is sent between clients and - servers. - -- A message has a body which is a buffer containing convenient methods - for reading and writing data into it. - -- A message has a set of properties which are key-value pairs. Each - property key is a string and property values can be of type integer, - long, short, byte, byte[], String, double, float or boolean. - -- A message has an *address* it is being sent to. When the message - arrives on the server it is routed to any queues that are bound to - the address - if the queues are bound with any filter, the message - will only be routed to that queue if the filter matches. An address - may have many queues bound to it or even none. There may also be - entities other than queues, like *diverts* bound to addresses. - -- Messages can be either durable or non durable. Durable messages in a - durable queue will survive a server crash or restart. Non durable - messages will never survive a server crash or restart. - -- Messages can be specified with a priority value between 0 and 9. 0 - represents the lowest priority and 9 represents the highest. - Apache ActiveMQ Artemis will attempt to deliver higher priority messages before - lower priority ones. - -- Messages can be specified with an optional expiry time. Apache ActiveMQ Artemis - will not deliver messages after its expiry time has been exceeded. - -- Messages also have an optional timestamp which represents the time - the message was sent. - -- Apache ActiveMQ Artemis also supports the sending/consuming of very large messages - much larger than can fit in available RAM at any one time. - -### Address - -A server maintains a mapping between an address and a set of queues. -Zero or more queues can be bound to a single address. Each queue can be -bound with an optional message filter. When a message is routed, it is -routed to the set of queues bound to the message's address. If any of -the queues are bound with a filter expression, then the message will -only be routed to the subset of bound queues which match that filter -expression. - -Other entities, such as *diverts* can also be bound to an address and -messages will also be routed there. - -> **Note** -> -> In core, there is no concept of a Topic, Topic is a JMS only term. -> Instead, in core, we just deal with *addresses* and *queues*. -> -> For example, a JMS topic would be implemented by a single address to -> which many queues are bound. Each queue represents a subscription of -> the topic. A JMS Queue would be implemented as a single address to -> which one queue is bound - that queue represents the JMS queue. - -### Queue - -Queues can be durable, meaning the messages they contain survive a -server crash or restart, as long as the messages in them are durable. -Non durable queues do not survive a server restart or crash even if the -messages they contain are durable. - -Queues can also be temporary, meaning they are automatically deleted -when the client connection is closed, if they are not explicitly deleted -before that. - -Queues can be bound with an optional filter expression. If a filter -expression is supplied then the server will only route messages that -match that filter expression to any queues bound to the address. - -Many queues can be bound to a single address. A particular queue is only -bound to a maximum of one address. - -### ServerLocator - -Clients use `ServerLocator` instances to create `ClientSessionFactory` -instances. `ServerLocator` instances are used to locate servers and -create connections to them. - -In JMS terms think of a `ServerLocator` in the same way you would a JMS -Connection Factory. - -`ServerLocator` instances are created using the `ActiveMQClient` factory -class. - -### ClientSessionFactory - -Clients use `ClientSessionFactory` instances to create `ClientSession` -instances. `ClientSessionFactory` instances are basically the connection -to a server - -In JMS terms think of them as JMS Connections. - -`ClientSessionFactory` instances are created using the `ServerLocator` -class. - -### ClientSession - -A client uses a ClientSession for consuming and producing messages and -for grouping them in transactions. ClientSession instances can support -both transactional and non transactional semantics and also provide an -`XAResource` interface so messaging operations can be performed as part -of a -[JTA](http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html) -transaction. - -ClientSession instances group ClientConsumers and ClientProducers. - -ClientSession instances can be registered with an optional -`SendAcknowledgementHandler`. This allows your client code to be -notified asynchronously when sent messages have successfully reached the -server. This unique Apache ActiveMQ Artemis feature, allows you to have full guarantees -that sent messages have reached the server without having to block on -each message sent until a response is received. Blocking on each -messages sent is costly since it requires a network round trip for each -message sent. By not blocking and receiving send acknowledgements -asynchronously you can create true end to end asynchronous systems which -is not possible using the standard JMS API. For more information on this -advanced feature please see the section [Guarantees of sends and commits](send-guarantees.md). - -### ClientConsumer - -Clients use `ClientConsumer` instances to consume messages from a queue. -Core Messaging supports both synchronous and asynchronous message -consumption semantics. `ClientConsumer` instances can be configured with -an optional filter expression and will only consume messages which match -that expression. - -### ClientProducer - -Clients create `ClientProducer` instances on `ClientSession` instances -so they can send messages. ClientProducer instances can specify an -address to which all sent messages are routed, or they can have no -specified address, and the address is specified at send time for the -message. - -> **Warning** -> -> Please note that ClientSession, ClientProducer and ClientConsumer -> instances are *designed to be re-used*. -> -> It's an anti-pattern to create new ClientSession, ClientProducer and -> ClientConsumer instances for each message you produce or consume. If -> you do this, your application will perform very poorly. This is -> discussed further in the section on performance tuning [Performance Tuning](perf-tuning.md). - -## A simple example of using Core - -Here's a very simple program using the core messaging API to send and -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 -ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration( - InVMConnectorFactory.class.getName())); - -// In this simple example, we just use one session for both producing and receiving - -ClientSessionFactory factory = locator.createClientSessionFactory(); -ClientSession session = factory.createSession(); - -// A producer is associated with an address ... - -ClientProducer producer = session.createProducer("example"); -ClientMessage message = session.createMessage(true); -message.getBodyBuffer().writeString("Hello"); - -// We need a queue attached to the address ... - -session.createQueue("example", "example", true); - -// And a consumer attached to the queue ... - -ClientConsumer consumer = session.createConsumer("example"); - -// Once we have a queue, we can send the message ... - -producer.send(message); - -// We need to start the session before we can -receive- messages ... - -session.start(); -ClientMessage msgReceived = consumer.receive(); - -System.out.println("message = " + msgReceived.getBodyBuffer().readString()); - -session.close(); -``` http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/using-jms.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/using-jms.md b/docs/user-manual/en/using-jms.md index bf654b9..bc9f3f2 100644 --- a/docs/user-manual/en/using-jms.md +++ b/docs/user-manual/en/using-jms.md @@ -1,186 +1,193 @@ # Using JMS -Although Apache ActiveMQ Artemis provides a JMS agnostic messaging API, many users will -be more comfortable using JMS. +Although Apache ActiveMQ Artemis provides a JMS agnostic messaging API, many +users will be more comfortable using JMS. -JMS is a very popular API standard for messaging, and most messaging -systems provide a JMS API. If you are completely new to JMS we suggest -you follow the [Oracle JMS tutorial](https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm) - -a full JMS tutorial is out of scope for this guide. +JMS is a very popular API standard for messaging, and most messaging systems +provide a JMS API. If you are completely new to JMS we suggest you follow the +[Oracle JMS +tutorial](https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm) - a full +JMS tutorial is out of scope for this guide. Apache ActiveMQ Artemis also ships with a wide range of examples, many of which -demonstrate JMS API usage. A good place to start would be to play around -with the simple JMS Queue and Topic example, but we also provide -examples for many other parts of the JMS API. A full description of the -examples is available in [Examples](examples.md). +demonstrate JMS API usage. A good place to start would be to play around with +the simple JMS Queue and Topic example, but we also provide examples for many +other parts of the JMS API. A full description of the examples is available in +[Examples](examples.md). -In this section we'll go through the main steps in configuring the -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. +In this section we'll go through the main steps in configuring the 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 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 -simplicity, but it serves to demonstrate the very basics of setting up -and using JMS. - -We will have a single JMS Queue called `OrderQueue`, and we will have a -single `MessageProducer` sending an order message to the queue and a -single `MessageConsumer` consuming the order message from the queue. - -The queue will be a `durable` queue, i.e. it will survive a server -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 - -The JMS specification establishes the convention that *administered -objects* (i.e. JMS queue, topic and connection factory instances) are -made available via the JNDI API. Brokers are free to implement JNDI as -they see fit assuming the implementation fits the API. Apache ActiveMQ Artemis does not -have a JNDI server. Rather, it uses a client-side JNDI implementation -that relies on special properties set in the environment to construct -the appropriate JMS objects. In other words, no objects are stored in -JNDI on the Apache ActiveMQ Artemis server, instead they are simply instantiated on the -client based on the provided configuration. Let's look at the different -kinds of administered objects and how to configure them. - -> **Note** +example. It is a somewhat contrived example because of its extreme simplicity, +but it serves to demonstrate the very basics of setting up and using JMS. + +We will have a single JMS Queue called `OrderQueue`, and we will have a single +`MessageProducer` sending an order message to the queue and a single +`MessageConsumer` consuming the order message from the queue. + +The queue will be a `durable` queue, i.e. it will survive a server 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 + +The JMS specification establishes the convention that *administered objects* +(i.e. JMS queue, topic and connection factory instances) are made available via +the JNDI API. Brokers are free to implement JNDI as they see fit assuming the +implementation fits the API. Apache ActiveMQ Artemis does not have a JNDI +server. Rather, it uses a client-side JNDI implementation that relies on +special properties set in the environment to construct the appropriate JMS +objects. In other words, no objects are stored in JNDI on the Apache ActiveMQ +Artemis server, instead they are simply instantiated on the client based on the +provided configuration. Let's look at the different kinds of administered +objects and how to configure them. + +> **Note:** > -> The following configuration properties *are strictly required when -> Apache ActiveMQ Artemis is running in stand-alone mode*. When Apache ActiveMQ Artemis is integrated -> to an application server (e.g. Wildfly) the application server itself -> will almost certainly provide a JNDI client with its own properties. +> The following configuration properties *are strictly required when Apache +> ActiveMQ Artemis is running in stand-alone mode*. When Apache ActiveMQ +> Artemis is integrated to an application server (e.g. Wildfly) the application +> server itself will almost certainly provide a JNDI client with its own +> properties. ### 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 -well as many other configuration parameters. +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 well as +many other configuration parameters. -Here's a simple example of the JNDI context environment for a client -looking up a connection factory to access an *embedded* instance of -Apache ActiveMQ Artemis: +Here's a simple example of the JNDI context environment for a client looking up +a connection factory to access an *embedded* instance of Apache ActiveMQ +Artemis: - java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory - connectionFactory.invmConnectionFactory=vm://0 -In this instance we have created a connection factory that is bound to -`invmConnectionFactory`, any entry with prefix `connectionFactory.` will - create a connection factory. +```properties +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +connectionFactory.invmConnectionFactory=vm://0 +``` -In certain situations there could be multiple server instances running -within a particular JVM. In that situation each server would typically -have an InVM acceptor with a unique server-ID. A client using JMS and -JNDI can account for this by specifying a connction factory for each -server, like so: +In this instance we have created a connection factory that is bound to +`invmConnectionFactory`, any entry with prefix `connectionFactory.` will create +a connection factory. - java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory - connectionFactory.invmConnectionFactory0=vm://0 - connectionFactory.invmConnectionFactory1=vm://1 - connectionFactory.invmConnectionFactory2=vm://2 +In certain situations there could be multiple server instances running within a +particular JVM. In that situation each server would typically have an InVM +acceptor with a unique server-ID. A client using JMS and JNDI can account for +this by specifying a connction factory for each server, like so: -Here is a list of all the supported URL schemes: -- `vm` +```properties +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +connectionFactory.invmConnectionFactory0=vm://0 +connectionFactory.invmConnectionFactory1=vm://1 +connectionFactory.invmConnectionFactory2=vm://2 +``` -- `tcp` +Here is a list of all the supported URL schemes: -- `udp` +- `vm` +- `tcp` +- `udp` +- `jgroups` -- `jgroups` +Most clients won't be connecting to an embedded broker. Clients will most +commonly connect across a network a remote broker. Here's a simple example of a +client configuring a connection factory to connect to a remote broker running +on myhost:5445: -Most clients won't be connecting to an embedded broker. Clients will -most commonly connect across a network a remote broker. Here's a simple -example of a client configuring a connection factory to connect to a -remote broker running on myhost:5445: - java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory - connectionFactory.ConnectionFactory=tcp://myhost:5445 +```properties +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +connectionFactory.ConnectionFactory=tcp://myhost:5445 +``` -In the example above the client is using the `tcp` scheme for the -provider URL. A client may also specify multiple comma-delimited -host:port combinations in the URL (e.g. -`(tcp://remote-host1:5445,remote-host2:5445)`). Whether there is one or -many host:port combinations in the URL they are treated as the *initial +In the example above the client is using the `tcp` scheme for the provider URL. +A client may also specify multiple comma-delimited host:port combinations in +the URL (e.g. `(tcp://remote-host1:5445,remote-host2:5445)`). Whether there is +one or many host:port combinations in the URL they are treated as the *initial connector(s)* for the underlying connection. -The `udp` scheme is also supported which should use a host:port -combination that matches the `group-address` and `group-port` from the -corresponding `broadcast-group` configured on the ActiveMQ Artemis server(s). +The `udp` scheme is also supported which should use a host:port combination +that matches the `group-address` and `group-port` from the corresponding +`broadcast-group` configured on the ActiveMQ Artemis server(s). Each scheme has a specific set of properties which can be set using the traditional URL query string format (e.g. -`scheme://host:port?key1=value1&key2=value2`) to customize the -underlying transport mechanism. For example, if a client wanted to -connect to a remote server using TCP and SSL it would create a connection -factory like so, `tcp://remote-host:5445?ssl-enabled=true`. +`scheme://host:port?key1=value1&key2=value2`) to customize the underlying +transport mechanism. For example, if a client wanted to connect to a remote +server using TCP and SSL it would create a connection factory like so, +`tcp://remote-host:5445?ssl-enabled=true`. All the properties available for the `tcp` scheme are described in [the documentation regarding the Netty transport](configuring-transports.md#configuring-the-netty-transport). -Note if you are using the `tcp` scheme and multiple addresses then a query -can be applied to all the url's or just to an individual connector, so where -you have +Note if you are using the `tcp` scheme and multiple addresses then a query can +be applied to all the url's or just to an individual connector, so where you +have -- `(tcp://remote-host1:5445?httpEnabled=true,remote-host2:5445?httpEnabled=true)?clientID=1234` +- `(tcp://remote-host1:5445?httpEnabled=true,remote-host2:5445?httpEnabled=true)?clientID=1234` -then the `httpEnabled` property is only set on the individual connectors where as the `clientId` -is set on the actual connection factory. Any connector specific properties set on the whole -URI will be applied to all the connectors. +then the `httpEnabled` property is only set on the individual connectors where +as the `clientId` is set on the actual connection factory. Any connector +specific properties set on the whole URI will be applied to all the connectors. The `udp` scheme supports 4 properties: -- `localAddress` - 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. - -- `localPort` - 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 `localAddress`. - -- `refreshTimeout` - 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). - -- `discoveryInitialWaitTimeout` - If the connection factory is used - immediately after creation then it may not have had enough time to - received broadcasts from all the nodes in the cluster. On first - usage, the connection factory will make sure it waits this long - since creation before creating the first connection. The default - value for this parameter is 10000 milliseconds. - -Lastly, the `jgroups` scheme is supported which provides an alternative -to the `udp` scheme for server discovery. The URL pattern is either +- `localAddress` - 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. + +- `localPort` - 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 `localAddress`. + +- `refreshTimeout` - 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). + +- `discoveryInitialWaitTimeout` - If the connection factory is used immediately + after creation then it may not have had enough time to received broadcasts + from all the nodes in the cluster. On first usage, the connection factory will + make sure it waits this long since creation before creating the first + connection. The default value for this parameter is 10000 milliseconds. + +Lastly, the `jgroups` scheme is supported which provides an alternative to the +`udp` scheme for server discovery. The URL pattern is either `jgroups://channelName?file=jgroups-xml-conf-filename` -where`jgroups-xml-conf-filename` refers to an XML file on the classpath -that contains the JGroups configuration or it can be -`jgroups://channelName?properties=some-jgroups-properties`. In both instance the -`channelName` is the name given to the jgroups channel created. +where`jgroups-xml-conf-filename` refers to an XML file on the classpath that +contains the JGroups configuration or it can be +`jgroups://channelName?properties=some-jgroups-properties`. In both instance +the `channelName` is the name given to the jgroups channel created. + +The `refreshTimeout` and `discoveryInitialWaitTimeout` properties are supported +just like with `udp`. -The `refreshTimeout` and `discoveryInitialWaitTimeout` properties -are supported just like with `udp`. +The default type for the default connection factory is of type +`javax.jms.ConnectionFactory`. This can be changed by setting the type like so -The default type for the default connection factory is of type `javax.jms.ConnectionFactory`. -This can be changed by setting the type like so - java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory - java.naming.provider.url=tcp://localhost:5445?type=CF +```properties +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +java.naming.provider.url=tcp://localhost:5445?type=CF +``` -In this example it is still set to the default, below shows a list of types that can be set. +In this example it is still set to the default, below shows a list of types +that can be set. #### Configuration for Connection Factory Types @@ -195,42 +202,46 @@ TOPIC_XA_CF | javax.jms.XATopicConnectionFactory ### Destination JNDI -JMS destinations are also typically looked up via JNDI. As with -connection factories, destinations can be configured using special -properties in the JNDI context environment. The property *name* should -follow the pattern: `queue.<jndi-binding>` or `topic.<jndi-binding>`. -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: +JMS destinations are also typically looked up via JNDI. As with connection +factories, destinations can be configured using special properties in the JNDI +context environment. The property *name* should follow the pattern: +`queue.<jndi-binding>` or `topic.<jndi-binding>`. 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 -<queue name="OrderQueue"/> +<address name="OrderQueue"> + <queue name="OrderQueue"/> +</address> ``` -And if the client wanted to bind this queue to "queues/OrderQueue" then -the JNDI properties would be configured like so: +And if the client wanted to bind this queue to "queues/OrderQueue" then the +JNDI properties would be configured like so: - java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory - java.naming.provider.url=tcp://myhost:5445 - queue.queues/OrderQueue=OrderQueue +```properties +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +java.naming.provider.url=tcp://myhost:5445 +queue.queues/OrderQueue=OrderQueue +``` -It is also possible to look-up JMS destinations which haven't been -configured explicitly in the JNDI context environment. This is possible -using `dynamicQueues/` or `dynamicTopics/` in the look-up string. For -example, if the client wanted to look-up the aforementioned "OrderQueue" -it could do so simply by using the string "dynamicQueues/OrderQueue". -Note, the text that follows `dynamicQueues/` or `dynamicTopics/` must -correspond *exactly* to the name of the destination on the server. +It is also possible to look-up JMS destinations which haven't been configured +explicitly in the JNDI context environment. This is possible using +`dynamicQueues/` or `dynamicTopics/` in the look-up string. For example, if the +client wanted to look-up the aforementioned "OrderQueue" it could do so simply +by using the string "dynamicQueues/OrderQueue". Note, the text that follows +`dynamicQueues/` or `dynamicTopics/` must correspond *exactly* to the name of +the destination on the server. ### The code Here's the code for the example: -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 +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 InitialContext ic = new InitialContext(); //Now we'll look up the connection factory from which we can create @@ -280,35 +291,36 @@ see the examples directory in the distribution. > **Warning** > -> Please note that JMS connections, sessions, producers and consumers -> are *designed to be re-used*. +> Please note that JMS connections, sessions, producers and consumers are +> *designed to be re-used*. > -> It is an anti-pattern to create new connections, sessions, producers -> and consumers for each message you produce or consume. If you do this, -> your application will perform very poorly. This is discussed further -> in the section on performance tuning [Performance Tuning](perf-tuning.md). +> It is an anti-pattern to create new connections, sessions, producers and +> consumers for each message you produce or consume. If you do this, 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 -Although it is a very common JMS usage pattern to lookup JMS -*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory -instances) from JNDI, in some cases you just think "Why do I need JNDI? -Why can't I just instantiate these objects directly?" +Although it is a very common JMS usage pattern to lookup JMS *Administered +Objects* (that's JMS Queue, Topic and ConnectionFactory instances) from JNDI, +in some cases you just think "Why do I need JNDI? Why can't I just instantiate +these objects directly?" -With Apache ActiveMQ Artemis you can do exactly that. Apache ActiveMQ Artemis supports the direct -instantiation of JMS Queue, Topic and ConnectionFactory instances, so -you don't have to use JNDI at all. +With Apache ActiveMQ Artemis you can do exactly that. Apache ActiveMQ Artemis +supports the direct instantiation of JMS Queue, Topic and ConnectionFactory +instances, so you don't have to use JNDI at all. ->For a full working example of direct instantiation please look at the ->"Instantiate JMS Objects Directly" example under the JMS section of the ->examples. See the [Examples](examples.md) section for more info. +> For a full working example of direct instantiation please look at the +> [Instantiate JMS Objects +> Directly](examples.md#instantiate-jms-objects-directly) example under the JMS +> section of the examples. Here's our simple example, rewritten to not use JNDI at all: -We create the JMS ConnectionFactory object via the ActiveMQJMSClient -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). +We create the JMS ConnectionFactory object via the ActiveMQJMSClient 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 TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName()); @@ -355,35 +367,33 @@ System.out.println("Got order: " + receivedMessage.getText()); ## 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 -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. +This represents the client id for a JMS client and is needed for creating +durable subscriptions. It is possible to configure this on the 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 -When the JMS acknowledge mode is set to `DUPS_OK` it is possible to -configure the consumer so that it sends acknowledgements in batches -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. +When the JMS acknowledge mode is set to `DUPS_OK` it is possible to configure +the consumer so that it sends acknowledgements in batches 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 When receiving messages in a transaction it is possible to configure the -consumer to send acknowledgements in batches rather than individually -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. +consumer to send acknowledgements in batches rather than individually 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 -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, -in a scenario where destinations (addresses) are permanent broker side, -such as they are managed by a platform or operations team. -using `destinationCache` element, you can toggle on the destination cache -to improve the performance and reduce the calls to the broker. -This should not be used if destinations (addresses) are not permanent broker side, -as in dynamic creation/deletion. +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, in +a scenario where destinations (addresses) are permanent broker side, such as +they are managed by a platform or operations team. using `destinationCache` +element, you can toggle on the destination cache to improve the performance and +reduce the calls to the broker. This should not be used if destinations +(addresses) are not permanent broker side, as in dynamic creation/deletion.
