You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2017/03/09 21:53:25 UTC
[1/3] activemq-artemis git commit: NO-JIRA Fix up user manual
Repository: activemq-artemis
Updated Branches:
refs/heads/master d408c4634 -> 4fabbc804
NO-JIRA Fix up user manual
Project: http://git-wip-us.apache.org/repos/asf/activemq-artemis/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-artemis/commit/24a045e2
Tree: http://git-wip-us.apache.org/repos/asf/activemq-artemis/tree/24a045e2
Diff: http://git-wip-us.apache.org/repos/asf/activemq-artemis/diff/24a045e2
Branch: refs/heads/master
Commit: 24a045e2663ab6a79cebf0ad5fb3d9bdf05b4838
Parents: c971476
Author: Martyn Taylor <mt...@redhat.com>
Authored: Thu Mar 9 16:59:09 2017 +0000
Committer: Martyn Taylor <mt...@redhat.com>
Committed: Thu Mar 9 21:24:02 2017 +0000
----------------------------------------------------------------------
docs/user-manual/en/architecture.md | 79 ++++----
docs/user-manual/en/client-reconnection.md | 2 +-
docs/user-manual/en/embedding-activemq.md | 74 +-------
docs/user-manual/en/intercepting-operations.md | 2 +-
docs/user-manual/en/jms-core-mapping.md | 37 +---
docs/user-manual/en/large-messages.md | 11 +-
docs/user-manual/en/management.md | 58 +-----
docs/user-manual/en/messaging-concepts.md | 32 +++-
docs/user-manual/en/perf-tuning.md | 5 +
docs/user-manual/en/rest.md | 197 ++++++++++----------
docs/user-manual/en/using-core.md | 4 +-
11 files changed, 186 insertions(+), 315 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/architecture.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md
index 402acac..2a43e5c 100644
--- a/docs/user-manual/en/architecture.md
+++ b/docs/user-manual/en/architecture.md
@@ -8,15 +8,6 @@ architecture.
Apache ActiveMQ Artemis core is designed simply as set of Plain Old Java Objects
(POJOs) - we hope you like its clean-cut design.
-We've also designed it to have as few dependencies on external jars as
-possible. In fact, Apache ActiveMQ Artemis core has only one jar dependency, netty.jar,
-other than the standard JDK classes! This is because we use some of the
-netty buffer classes internally.
-
-This allows Apache ActiveMQ Artemis to be easily embedded in your own project, or
-instantiated in any dependency injection framework such as Spring or
-Google Guice.
-
Each Apache ActiveMQ Artemis server has its own ultra high performance persistent
journal, which it uses for message and other persistence.
@@ -28,18 +19,20 @@ Apache ActiveMQ Artemis clients, potentially on different physical machines inte
with the Apache ActiveMQ Artemis server. Apache ActiveMQ Artemis currently provides two APIs for
messaging at the client side:
-1. Core client API. This is a simple intuitive Java API that allows the
- 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, 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.
-2. JMS client API. The standard JMS API is available at the client
- side.
+2. JMS 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. Stomp
+1. AMQP
2. OpenWire
-3. AMQP
+3. MQTT
+4. STOMP
+5. HornetQ (for use with HornetQ clients).
+6. CORE (Artemis CORE protocol)
JMS semantics are implemented by a JMS facade layer on the client
@@ -66,6 +59,32 @@ server. User Application 1 is using the JMS API, while User Application
You can see from the diagram that the JMS API is implemented by a thin
facade layer on the client side.
+## Apache ActiveMQ Artemis stand-alone server
+
+The standard stand-alone messaging server configuration comprises a core
+messaging server and a number of protocol managers that provide support for
+the various protocol mentioned earlier. Protocol managers are plugable
+if you
+
+The role of the JMS Service is to deploy any JMS Queue, Topic and
+ConnectionFactory instances from any server side JMS
+configuration. It also provides a simple management API for
+creating and destroying Queues and Topics
+which can be accessed via JMX or the connection. It is a separate
+service to the ActiveMQ Artemis core server, since the core server is JMS
+agnostic. If you don't want to deploy any JMS Queue or Topic via
+server side XML configuration and don't require a JMS management
+API on the server side then you can disable this service.
+
+The stand-alone server configuration uses [Airline](https://github.com/airlift/airline)
+for bootstrapping the Broker.
+
+The stand-alone server architecture is shown in figure 3.3 below:
+
+
+
+For more information on server configuration files see [Server Configuration](configuration-index.md)
+
## Apache ActiveMQ Artemis embedded in your own application
Apache ActiveMQ Artemis core is designed as a set of simple POJOs so if you have an
@@ -122,31 +141,3 @@ time you want to interact from the EJB, which is an anti-pattern.
For more information on using the JCA adaptor, please see [Application Server Integration and Java EE](appserver-integration.md).
-
-## Apache ActiveMQ Artemis stand-alone server
-
-Apache ActiveMQ Artemis can also be deployed as a stand-alone server. This means a
-fully independent messaging server not dependent on a Java EE application
-server.
-
-The standard stand-alone messaging server configuration comprises a core
-messaging server and a JMS service.
-
-The role of the JMS Service is to deploy any JMS Queue, Topic and
-ConnectionFactory instances from any server side JMS
-configuration. It also provides a simple management API for
-creating and destroying Queues and Topics
-which can be accessed via JMX or the connection. It is a separate
-service to the ActiveMQ Artemis core server, since the core server is JMS
-agnostic. If you don't want to deploy any JMS Queue or Topic via
-server side XML configuration and don't require a JMS management
-API on the server side then you can disable this service.
-
-The stand-alone server configuration uses [Airline](https://github.com/airlift/airline)
-for bootstrapping the Broker.
-
-The stand-alone server architecture is shown in figure 3.3 below:
-
-
-
-For more information on server configuration files see [Server Configuration](configuration-index.md)
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/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 5cd7fb0..83ca625 100644
--- a/docs/user-manual/en/client-reconnection.md
+++ b/docs/user-manual/en/client-reconnection.md
@@ -27,7 +27,7 @@ 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.
+server can reconcile their states.Ac
The size of this buffer is configured by the `ConfirmationWindowSize`
parameter, when the server has received `ConfirmationWindowSize` bytes
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/embedding-activemq.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/embedding-activemq.md b/docs/user-manual/en/embedding-activemq.md
index 64e698c..b7a4e72 100644
--- a/docs/user-manual/en/embedding-activemq.md
+++ b/docs/user-manual/en/embedding-activemq.md
@@ -23,9 +23,9 @@ classes and configure Apache ActiveMQ Artemis through its configuration files. T
are two different helper classes for this depending on whether your
using the Apache ActiveMQ Artemis Core API or JMS.
-## Core API Only
+## Embeddeing Apache ActiveMQ Artemis Server
-For instantiating a core Apache ActiveMQ Artemis Server only, the steps are pretty
+For instantiating a core Apache ActiveMQ Artemis Server, the steps are pretty
simple. The example requires that you have defined a configuration file
`broker.xml` in your classpath:
@@ -69,35 +69,6 @@ The `EmbeddedActiveMQ` class has a few additional setter methods that
allow you to specify a different config file name as well as other
properties. See the javadocs for this class for more details.
-## JMS API
-
-JMS embedding is simple as well. This example requires that you have
-defined the config file `broker.xml`. Let's also assume that a queue
-and connection factory has been defined in the `broker.xml`
-config file as well.
-
-``` java
-import org.apache.activemq.artemis.jms.server.embedded.EmbeddedJMS;
-
-...
-
-EmbeddedJMS jms = new EmbeddedJMS();
-jms.start();
-
-// This assumes we have configured broker.xml with the appropriate config information
-ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
-Destination destination = jms.lookup("/example/queue");
-
-... regular JMS code ...
-```
-
-By default, the `EmbeddedJMS` class will store the "entries" defined for
-your JMS components within `broker.xml` in an internal concurrent hash
-map. The `EmbeddedJMS.lookup()` method returns components stored in
-this map. If you want to use JNDI, call the `EmbeddedJMS.setContext()`
-method with the root JNDI context you want your components bound into.
-See the JavaDocs for this class for more details on other config options.
-
## POJO instantiation - Embedding Programmatically
You can follow this step-by-step guide to programmatically embed the
@@ -150,47 +121,6 @@ ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();
```
-For JMS POJO instantiation, you work with the EmbeddedJMS class instead
-as described earlier. First you define the configuration
-programmatically for your ConnectionFactory and Destination objects,
-then set the JmsConfiguration property of the EmbeddedJMS class. Here is
-an example of this:
-
-``` java
-// Step 1. Create Apache ActiveMQ Artemis core configuration, and set the properties accordingly
-Configuration configuration = new ConfigurationImpl()
- .setPersistenceEnabled(false)
- .setSecurityEnabled(false)
- .addAcceptorConfiguration(new TransportConfiguration(NettyAcceptorFactory.class.getName()))
- .addConnectorConfiguration("myConnector", new TransportConfiguration(NettyConnectorFactory.class.getName()));
-
-// Step 2. Create the JMS configuration
-JMSConfiguration jmsConfig = new JMSConfigurationImpl();
-
-// Step 3. Configure the JMS ConnectionFactory
-ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl()
- .setName("cf")
- .setConnectorNames(Arrays.asList("myConnector"))
- .setBindings("/cf");
-jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
-
-// Step 4. Configure the JMS Queue
-JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl()
- .setName("queue1")
- .setDurable(false)
- .setBindings("/queue/queue1");
-jmsConfig.getQueueConfigurations().add(queueConfig);
-
-// Step 5. Start the JMS Server using the Apache ActiveMQ Artemis core server and the JMS configuration
-jmsServer = new EmbeddedJMS()
- .setConfiguration(configuration)
- .setJmsConfiguration(jmsConfig)
- .start();
-```
-
-Please see the examples for an example which shows how to setup and run Apache ActiveMQ Artemis
-embedded with JMS.
-
## Dependency Frameworks
You may also choose to use a dependency injection framework such as
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/intercepting-operations.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/intercepting-operations.md b/docs/user-manual/en/intercepting-operations.md
index 2b1d0d4..591ee42 100644
--- a/docs/user-manual/en/intercepting-operations.md
+++ b/docs/user-manual/en/intercepting-operations.md
@@ -72,7 +72,7 @@ server classpath to be properly instantiated and called.
## Interceptors on the Client Side
-The interceptors can also be run on the client side to intercept packets
+The interceptors can also be run on the Apache ActiveMQ Artemit client side to intercept packets
either sent by the client to the server or by the server to the client.
This is done by adding the interceptor to the `ServerLocator` with the
`addIncomingInterceptor(Interceptor)` or
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/jms-core-mapping.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/jms-core-mapping.md b/docs/user-manual/en/jms-core-mapping.md
index 51e87b9..d7fe3fc 100644
--- a/docs/user-manual/en/jms-core-mapping.md
+++ b/docs/user-manual/en/jms-core-mapping.md
@@ -4,35 +4,12 @@ This chapter describes how JMS destinations are mapped to Apache ActiveMQ Artemi
addresses.
Apache ActiveMQ Artemis core is JMS-agnostic. It does not have any concept of a JMS
-topic. A JMS topic is implemented in core as an address (the topic name)
-with zero or more queues bound to it. Each queue bound to that address
-represents a topic subscription. Likewise, a JMS queue is implemented as
-an address (the JMS queue name) with one single queue bound to it which
-represents the JMS queue.
+topic. A JMS topic is implemented in core as an address with name=(the topic name)
+and with a MULTICAST routing type with zero or more queues bound to it. Each queue bound to that address
+represents a topic subscription.
-By convention, all JMS queues map to core queues where the core queue
-name has the string `jms.queue.` prepended to it. E.g. the JMS queue
-with the name "orders.europe" would map to the core queue with the name
-"jms.queue.orders.europe". The address at which the core queue is bound
-is also given by the core queue name.
+Likewise, a JMS queue is implemented as an address with name=(the JMS queue name) with an ANYCAST routing type assocatied
+with it.
-For JMS topics the address at which the queues that represent the
-subscriptions are bound is given by prepending the string "jms.topic."
-to the name of the JMS topic. E.g. the JMS topic with name "news.europe"
-would map to the core address "jms.topic.news.europe"
-
-In other words if you send a JMS message to a JMS queue with name
-"orders.europe" it will get routed on the server to any core queues
-bound to the address "jms.queue.orders.europe". If you send a JMS
-message to a JMS topic with name "news.europe" it will get routed on the
-server to any core queues bound to the address "jms.topic.news.europe".
-
-If you want to configure settings for a JMS Queue with the name
-"orders.europe", you need to configure the corresponding core queue
-"jms.queue.orders.europe":
-
- <!-- expired messages in JMS Queue "orders.europe" will be sent to the JMS Queue "expiry.europe" -->
- <address-setting match="jms.queue.orders.europe">
- <expiry-address>jms.queue.expiry.europe</expiry-address>
- ...
- </address-setting>
+Note. That whilst it is possible to configure a JMS topic and queue with the same name, it is not a recommended
+configuration for use with cross protocol.
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/large-messages.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/large-messages.md b/docs/user-manual/en/large-messages.md
index 0ae1573..e87dd01 100644
--- a/docs/user-manual/en/large-messages.md
+++ b/docs/user-manual/en/large-messages.md
@@ -28,7 +28,8 @@ Large messages are stored on a disk directory on the server side, as
configured on the main configuration file.
The configuration property `large-messages-directory` specifies where
-large messages are stored.
+large messages are stored. For JDBC persistence the `large-message-table`
+should be configured.
<configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -38,11 +39,11 @@ large messages are stored.
...
</configuration
-By default the large message directory is `data/largemessages`
+By default the large message directory is `data/largemessages` and `large-message-table` is
+configured as "LARGE_MESSAGE_TABLE".
-For the best performance we recommend large messages directory is stored
-on a different physical volume to the message journal or paging
-directory.
+For the best performance we recommend using file store with large messages directory stored
+on a different physical volume to the message journal or paging directory.
## Configuring Parameters
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/management.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md
index 544ffbe..dce2401 100644
--- a/docs/user-manual/en/management.md
+++ b/docs/user-manual/en/management.md
@@ -25,13 +25,9 @@ This choice depends on your requirements, your application settings and
your environment to decide which way suits you best.
-
-## Object name changes in version 2
-
In version 2 of Apache ActiveMQ Artemis the syntax used for MBean Object names has changed significantly due to changes
in the addressing scheme. See the documentation for each individual resource for details on the new sytanx.
-
## The Management API
Regardless of the way you *invoke* management operations, the management
@@ -52,12 +48,12 @@ messages, or JMS messages are used.
> empty string means that the management operation will be performed on
> *all messages*.
-### Core Management API
+### Apache ActiveMQ Artemis Management API
Apache ActiveMQ Artemis defines a core management API to manage core resources. For
full details of the API please consult the javadoc. In summary:
-#### Core Server Management
+#### Apache ActiveMQ Artemis Server Management
- Listing, creating, deploying and destroying queues
@@ -360,12 +356,12 @@ This would give you back something like the following:
{"request":{"mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\"","attribute":"Version","type":"read"},"value":"2.0.0-SNAPSHOT","timestamp":1487017918,"status":200}
-## Using Management Via Core API
+## Using Management Via Apache ActiveMQ Artemis API
-The core management API in ActiveMQ Artemis is called by sending Core messages
+The management API in ActiveMQ Artemis is called by sending Core Client messages
to a special address, the *management address*.
-*Management messages* are regular Core messages with well-known
+*Management messages* are regular Core Client messages with well-known
properties that the server needs to understand to interact with the
management API:
@@ -428,7 +424,7 @@ Names of the resources are built using the helper class
straightforward (e.g. `queue.exampleQueue` for the Core Queue
`exampleQueue`.
-### Configuring Core Management
+### Configuring Management
The management address to send management messages is configured in
`broker.xml`:
@@ -447,48 +443,6 @@ configured in broker.xml:
<permission type="manage" roles="admin" />
</security-setting>
-## Using Management Via JMS
-
-Using JMS messages to manage ActiveMQ Artemis is very similar to using core API.
-
-The *management queue* is a special queue and needs to be instantiated
-directly by the client:
-
- Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
-
-All the other steps are the same than for the Core API but they use JMS
-API instead:
-
-1. create a `QueueRequestor` to send messages to the management address
- and receive replies
-
-2. create a `Message`
-
-3. use the helper class
- `org.apache.activemq.artemis.api.jms.management.JMSManagementHelper` to fill
- the message with the management properties
-
-4. send the message using the `QueueRequestor`
-
-5. use the helper class
- `org.apache.activemq.artemis.api.jms.management.JMSManagementHelper` to
- retrieve the operation result from the management reply
-
-For example, to know the number of messages in the JMS queue
-`exampleQueue`:
-``` java
-Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
-
-QueueSession session = ...
-QueueRequestor requestor = new QueueRequestor(session, managementQueue);
-connection.start();
-Message message = session.createMessage();
-JMSManagementHelper.putAttribute(message, "exampleQueue", "messageCount");
-Message reply = requestor.request(message);
-int count = (Integer)JMSManagementHelper.getResult(reply);
-System.out.println("There are " + count + " messages in exampleQueue");
-```
-
### Example
See the [examples](examples.md) chapter for an example which shows
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/messaging-concepts.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/messaging-concepts.md b/docs/user-manual/en/messaging-concepts.md
index 49f9440..1a90d7f 100644
--- a/docs/user-manual/en/messaging-concepts.md
+++ b/docs/user-manual/en/messaging-concepts.md
@@ -218,16 +218,6 @@ fact the internet is already tuned to deal with HTTP optimally.
Please see [Rest Interface](rest.md) for using Apache ActiveMQ Artemis's RESTful interface.
-### STOMP
-
-[Stomp](http://stomp.github.io/) is a very simple text protocol for
-interoperating with messaging systems. It defines a wire format, so
-theoretically any Stomp client can work with any messaging system that
-supports Stomp. Stomp clients are available in many different
-programming languages.
-
-Please see [Stomp](interoperability.md) for using STOMP with Apache ActiveMQ Artemis.
-
### AMQP
[AMQP](http://en.wikipedia.org/wiki/AMQP) is a specification for
@@ -240,6 +230,28 @@ Apache ActiveMQ Artemis implements the [AMQP
specification. Any client that supports the 1.0 specification will be
able to interact with Apache ActiveMQ Artemis.
+### MQTT
+[MQTT](http://mqtt.org/) is a lightweight connectivity protocol. It is designed
+to run in environments where device and networks are constrained. Out of the box
+Apache ActiveMQ Artemis supports version MQTT 3.1.1. Any client supporting this
+version of the protocol will work against Apache ActiveMQ Artemis.
+
+### STOMP
+
+[Stomp](http://stomp.github.io/) is a very simple text protocol for
+interoperating with messaging systems. It defines a wire format, so
+theoretically any Stomp client can work with any messaging system that
+supports Stomp. Stomp clients are available in many different
+programming languages.
+
+Please see [Stomp](interoperability.md) for using STOMP with Apache ActiveMQ Artemis.
+
+### OPENWIRE
+
+ActiveMQ 5.x defines it's own wire Protocol "OPENWIRE". In order to support
+ActiveMQ 5.x clients, Apache ActiveMQ Artemis supports OPENWIRE. Any ActiveMQ 5.12.x
+or higher can be used with Apache ActiveMQ Artemis.
+
## High Availability
High Availability (HA) means that the system should remain operational
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/perf-tuning.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/perf-tuning.md b/docs/user-manual/en/perf-tuning.md
index 39f9993..e5266f6 100644
--- a/docs/user-manual/en/perf-tuning.md
+++ b/docs/user-manual/en/perf-tuning.md
@@ -5,6 +5,11 @@ performance.
## Tuning persistence
+- To get the best performance from Apache ActiveMQ Artemis whilst
+ using perisistent messages it is recommended that the file store
+ is used. Apache ActiveMQ Artemis also supports JDBC persistence,
+ but there is a performance cost when persisting to a database vs
+ local disk.
- Put the message journal on its own physical volume. If the disk is
shared with other processes e.g. transaction co-ordinator, database
or other journals which are also reading and writing from it, then
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/docs/user-manual/en/rest.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/rest.md b/docs/user-manual/en/rest.md
index 78d68ca..9034c39 100644
--- a/docs/user-manual/en/rest.md
+++ b/docs/user-manual/en/rest.md
@@ -2,8 +2,11 @@
The Apache ActiveMQ Artemis REST interface allows you to leverage the reliability and
scalability features of Apache ActiveMQ Artemis over a simple REST/HTTP interface.
-Messages are produced and consumed by sending and receiving simple HTTP
-messages that contain the content you want to push around. For instance,
+The REST Interface implementation sits on top of an Apache ActiveMQ Artemis JMS API and
+as such exposes JMS like concepts via REST.
+
+Using the REST internface Messages can produced and consumed by sending
+and receiving simple HTTP messages that contain the content you want to push around. For instance,
here's a simple example of posting an order to an order processing queue
express as an HTTP message:
@@ -285,30 +288,28 @@ REST server within as defined in the [Installation and
Configuration](#install) section of this document. Replace the `{name}`
string within the above URI pattern with the name of the queue or topic
you are interested in interacting with. For example if you have
-configured a JMS topic named "foo" within your `activemq-jms.xml` file,
-the URI name should be "jms.topic.foo". If you have configured a JMS
+configured a named "foo" within your `activemq-jms.xml` file,
+the URI name should be "foo". If you have configured a JMS
queue name "bar" within your `activemq-jms.xml` file, the URI name
-should be "jms.queue.bar". Internally, Apache ActiveMQ Artemis prepends the "jms.topic"
-or "jms.queue" strings to the name of the deployed destination. Next,
-perform your HEAD or GET request on this URI. Here's what a
-request/response would look like.
+should be "bar". Next, perform your HEAD or GET request on this URI.
+Here's what a request/response would look like.
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
- msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
- msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+ msg-create: http://example.com/queues/bar/create
+ msg-create-with-id: http://example.com/queues/bar/create/{id}
+ msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/bar/push-consumers
> **Note**
>
> You can use the "curl" utility to test this easily. Simply execute a
> command like this:
>
-> curl --head http://example.com/queues/jms.queue.bar
+> curl --head http://example.com/queues/.bar
The HEAD or GET response contains a number of custom response headers
that are URLs to additional REST resources that allow you to interact
@@ -379,17 +380,17 @@ Apache ActiveMQ Artemis destination. Here's an example scenario:
1. Obtain the starting `msg-create` header from the queue or topic
resource.
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+ msg-create: http://example.com/queues/bar/create
+ msg-create-with-id: http://example.com/queues/bar/create/{id}
2. Do a POST to the URL contained in the `msg-create` header.
- POST /queues/jms.queue.bar/create
+ POST /queues/bar/create
Host: example.com
Content-Type: application/xml
@@ -401,14 +402,14 @@ Apache ActiveMQ Artemis destination. Here's an example scenario:
--- Response ---
HTTP/1.1 201 Created
- msg-create-next: http://example.com/queues/jms.queue.bar/create
+ msg-create-next: http://example.com/queues/bar/create
> **Note**
>
> You can use the "curl" utility to test this easily. Simply execute
> a command like this:
>
- > curl --verbose --data "123" http://example.com/queues/jms.queue.bar/create
+ > curl --verbose --data "123" http://example.com/queues/bar/create
A successful response will return a 201 response code. Also notice
that a `msg-create-next` response header is sent as well. You must
@@ -417,7 +418,7 @@ Apache ActiveMQ Artemis destination. Here's an example scenario:
3. POST your next message to the queue using the URL returned in the
`msg-create-next` header.
- POST /queues/jms.queue.bar/create
+ POST /queues/bar/create
Host: example.com
Content-Type: application/xml
@@ -429,7 +430,7 @@ Apache ActiveMQ Artemis destination. Here's an example scenario:
--- Response --
HTTP/1.1 201 Created
- msg-create-next: http://example.com/queues/jms.queue.bar/create
+ msg-create-next: http://example.com/queues/bar/create
Continue using the new `msg-create-next` header returned with each
response.
@@ -462,17 +463,17 @@ discussed earlier. Here's an example:
1. Obtain the starting `msg-create` header from the queue or topic
resource.
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+ msg-create: http://example.com/queues/bar/create
+ msg-create-with-id: http://example.com/queues/bar/create/{id}
2. Do a POST to the URL contained in the `msg-create` header.
- POST /queues/jms.queue.bar/create
+ POST /queues/bar/create
Host: example.com
Content-Type: application/xml
@@ -484,7 +485,7 @@ discussed earlier. Here's an example:
--- Response ---
HTTP/1.1 307 Redirect
- Location: http://example.com/queues/jms.queue.bar/create/13582001787372
+ Location: http://example.com/queues/bar/create/13582001787372
A successful response will return a 307 response code. This is
standard HTTP protocol. It is telling you that you must re-POST to
@@ -493,7 +494,7 @@ discussed earlier. Here's an example:
3. re-POST your message to the URL provided within the `Location`
header.
- POST /queues/jms.queue.bar/create/13582001787372
+ POST /queues/bar/create/13582001787372
Host: example.com
Content-Type: application/xml
@@ -505,7 +506,7 @@ discussed earlier. Here's an example:
--- Response --
HTTP/1.1 201 Created
- msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787373
+ msg-create-next: http://example.com/queues/bar/create/13582001787373
You should receive a 201 Created response. If there is a network
failure, just re-POST to the Location header. For new messages, use
@@ -513,7 +514,7 @@ discussed earlier. Here's an example:
4. POST any new message to the returned `msg-create-next` header.
- POST /queues/jms.queue.bar/create/13582001787373
+ POST /queues/bar/create/13582001787373
Host: example.com
Content-Type: application/xml
@@ -525,7 +526,7 @@ discussed earlier. Here's an example:
--- Response --
HTTP/1.1 201 Created
- msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374
+ msg-create-next: http://example.com/queues/bar/create/13582001787374
If there ever is a network problem, just repost to the URL provided
in the `msg-create-next` header.
@@ -542,7 +543,7 @@ If you happen to use the same ID more than once you'll see a message
like this on the server:
WARN [org.apache.activemq.artemis.core.server] (Thread-3 (Apache ActiveMQ Artemis-remoting-threads-ActiveMQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) AMQ112098: Duplicate message detected - message will not be routed. Message information:
- ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _AMQ_DUPL_ID=42}]]@12835058
+ ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _AMQ_DUPL_ID=42}]]@12835058
An alternative to this approach is to use the `msg-create-with-id`
header. This is not an invokable URL, but a URL template. The idea is
@@ -550,7 +551,7 @@ that the client provides the `DUPLICATE_DETECTION_ID` and creates its
own `create-next` URL. The `msg-create-with-id` header looks like this
(you've see it in previous examples, but we haven't used it):
- msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}
+ msg-create-with-id: http://example.com/queues/bar/create/{id}
You see that it is a regular URL appended with a `{id}`. This `{id}` is
a pattern matching substring. A client would generate its
@@ -575,7 +576,7 @@ called `durable` to true when you post your messages to the URLs
returned in the `msg-create`, `msg-create-with-id`, or `msg-create-next`
headers. here's an example of that.
- POST /queues/jms.queue.bar/create?durable=true
+ POST /queues/bar/create?durable=true
Host: example.com
Content-Type: application/xml
@@ -595,7 +596,7 @@ time in milliseconds you want the message active. The `priority` is
another query parameter with an integer value between 0 and 9 expressing
the priority of the message. i.e.:
- POST /queues/jms.queue.bar/create?expiration=30000&priority=3
+ POST /queues/bar/create?expiration=30000&priority=3
Host: example.com
Content-Type: application/xml
@@ -688,25 +689,25 @@ Here is an example of creating an auto-acknowledged queue pull consumer.
1. Find the pull-consumers URL by doing a HEAD or GET request to the
base queue resource.
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
- msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+ msg-create: http://example.com/queues/bar/create
+ msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/bar/push-consumers
2. Next do an empty POST to the URL returned in the
`msg-pull-consumers` header.
- POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
+ POST /queues/bar/pull-consumers HTTP/1.1
Host: example.com
--- response ---
HTTP/1.1 201 Created
- Location: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333
- msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/auto-ack/333/consume-next-1
+ Location: http://example.com/queues/bar/pull-consumers/auto-ack/333
+ msg-consume-next: http://example.com/queues/bar/pull-consumers/auto-ack/333/consume-next-1
The `Location` header points to the JMS consumer resource that was
created on the server. It is good to remember this URL, although, as
@@ -720,19 +721,19 @@ pull subscription.
1. Find the `pull-subscriptions` URL by doing a HEAD or GET request to
the base topic resource
- HEAD /topics/jms.topic.bar HTTP/1.1
+ HEAD /topics/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/topics/jms.topic.foo/create
- msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
- msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions
+ msg-create: http://example.com/topics/foo/create
+ msg-pull-subscriptions: http://example.com/topics/foo/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/foo/push-subscriptions
2. Next do a POST to the URL returned in the `msg-pull-subscriptions`
header passing in a `true` value for the `durable` form parameter.
- POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
+ POST /topics/foo/pull-subscriptions HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
@@ -740,9 +741,9 @@ pull subscription.
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222
+ Location: http://example.com/topics/foo/pull-subscriptions/auto-ack/222
msg-consume-next:
- http://example.com/topics/jms.topic.foo/pull-subscriptions/auto-ack/222/consume-next-1
+ http://example.com/topics/foo/pull-subscriptions/auto-ack/222/consume-next-1
The `Location` header points to the JMS subscription resource that
was created on the server. It is good to remember this URL,
@@ -774,14 +775,14 @@ resource.
1. Do a POST on the msg-consume-next URL that was returned with the
consumer or subscription resource discussed earlier.
- POST /queues/jms.queue.bar/pull-consumers/consume-next-1
+ POST /queues/bar/pull-consumers/consume-next-1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
Content-Type: application/xml
- msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2
- msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
+ msg-consume-next: http://example.com/queues/bar/pull-consumers/333/consume-next-2
+ msg-consumer: http://example.com/queues/bar/pull-consumers/333
<order>...</order>
@@ -796,13 +797,13 @@ resource.
returns a new msg-consume-next link. Use this new link to get the
next message.
- POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ POST /queues/bar/pull-consumers/consume-next-2
Host: example.com
--- Response ---
Http/1.1 503 Service Unavailable
Retry-After: 5
- msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-2
+ msg-consume-next: http://example.com/queues/bar/pull-consumers/333/consume-next-2
In this case, there are no messages in the queue, so we get a 503
response back. As per the HTTP 1.1 spec, a 503 response may return a
@@ -816,13 +817,13 @@ resource.
3. POST to the URL within the last `msg-consume-next` to get the next
message.
- POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ POST /queues/bar/pull-consumers/consume-next-2
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
Content-Type: application/xml
- msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
+ msg-consume-next: http://example.com/queues/bar/pull-consumers/333/consume-next-3
<order>...</order>
@@ -892,19 +893,19 @@ Here is an example of creating an auto-acknowledged queue pull consumer.
1. Find the pull-consumers URL by doing a HEAD or GET request to the
base queue resource.
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
- msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+ msg-create: http://example.com/queues/bar/create
+ msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/bar/push-consumers
2. Next do a POST to the URL returned in the `msg-pull-consumers`
header passing in a `false` value to the `autoAck` form parameter .
- POST /queues/jms.queue.bar/pull-consumers HTTP/1.1
+ POST /queues/bar/pull-consumers HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
@@ -912,8 +913,8 @@ Here is an example of creating an auto-acknowledged queue pull consumer.
--- response ---
HTTP/1.1 201 Created
- Location: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333
- msg-acknowledge-next: http://example.com/queues/jms.queue.bar/pull-consumers/acknowledged/333/acknowledge-next-1
+ Location: http://example.com/queues/bar/pull-consumers/acknowledged/333
+ msg-acknowledge-next: http://example.com/queues/bar/pull-consumers/acknowledged/333/acknowledge-next-1
The `Location` header points to the JMS consumer resource that was
created on the server. It is good to remember this URL, although, as
@@ -927,20 +928,20 @@ topic pull subscription.
1. Find the `pull-subscriptions` URL by doing a HEAD or GET request to
the base topic resource
- HEAD /topics/jms.topic.bar HTTP/1.1
+ HEAD /topics/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/topics/jms.topic.foo/create
- msg-pull-subscriptions: http://example.com/topics/jms.topic.foo/pull-subscriptions
- msg-push-subscriptions: http://example.com/topics/jms.topic.foo/push-subscriptions
+ msg-create: http://example.com/topics/foo/create
+ msg-pull-subscriptions: http://example.com/topics/foo/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/foo/push-subscriptions
2. Next do a POST to the URL returned in the `msg-pull-subscriptions`
header passing in a `true` value for the `durable` form parameter
and a `false` value to the `autoAck` form parameter.
- POST /topics/jms.topic.foo/pull-subscriptions HTTP/1.1
+ POST /topics/foo/pull-subscriptions HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
@@ -948,9 +949,9 @@ topic pull subscription.
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222
+ Location: http://example.com/topics/foo/pull-subscriptions/acknowledged/222
msg-acknowledge-next:
- http://example.com/topics/jms.topic.foo/pull-subscriptions/acknowledged/222/consume-next-1
+ http://example.com/topics/foo/pull-subscriptions/acknowledged/222/consume-next-1
The `Location` header points to the JMS subscription resource that
was created on the server. It is good to remember this URL,
@@ -977,15 +978,15 @@ resource.
1. Do a POST on the msg-acknowledge-next URL that was returned with the
consumer or subscription resource discussed earlier.
- POST /queues/jms.queue.bar/pull-consumers/consume-next-1
+ POST /queues/bar/pull-consumers/consume-next-1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
Content-Type: application/xml
msg-acknowledgement:
- http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledgement/2
- msg-consumer: http://example.com/queues/jms.queue.bar/pull-consumers/333
+ http://example.com/queues/bar/pull-consumers/333/acknowledgement/2
+ msg-consumer: http://example.com/queues/bar/pull-consumers/333
<order>...</order>
@@ -1002,7 +1003,7 @@ resource.
whether you want to acknowledge or unacknowledge the message on the
server.
- POST /queues/jms.queue.bar/pull-consumers/acknowledgement/2
+ POST /queues/bar/pull-consumers/acknowledgement/2
Host: example.com
Content-Type: application/x-www-form-urlencoded
@@ -1011,7 +1012,7 @@ resource.
--- Response ---
Http/1.1 200 Ok
msg-acknowledge-next:
- http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledge-next-2
+ http://example.com/queues/bar/pull-consumers/333/acknowledge-next-2
Whether you acknowledge or unacknowledge the message, the response
will contain a new msg-acknowledge-next header that you must use to
@@ -1070,14 +1071,14 @@ response from the server. The value of this header is the time in
seconds the client is willing to block for. You would send this request
header with your pull requests. Here's an example:
- POST /queues/jms.queue.bar/pull-consumers/consume-next-2
+ POST /queues/bar/pull-consumers/consume-next-2
Host: example.com
Accept-Wait: 30
--- Response ---
HTTP/1.1 200 Ok
Content-Type: application/xml
- msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/consume-next-3
+ msg-consume-next: http://example.com/queues/bar/pull-consumers/333/consume-next-3
<order>...</order>
@@ -1164,7 +1165,7 @@ values a rel attribute can have:
messages to the Apache ActiveMQ Artemis REST endpoint reliably. Here's an example:
<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
+ <link rel="destination" href="http://somewhere.com/queues/foo"/>
</push-registration>
- `template`. In this case, the server is expecting the link element's
@@ -1213,29 +1214,29 @@ Here's an example of creating a push registration for a queue:
1. First do a HEAD request to the queue resource:
- HEAD /queues/jms.queue.bar HTTP/1.1
+ HEAD /queues/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/queues/jms.queue.bar/create
- msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
- msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers
+ msg-create: http://example.com/queues/bar/create
+ msg-pull-consumers: http://example.com/queues/bar/pull-consumers
+ msg-push-consumers: http://example.com/queues/bar/push-consumers
2. Next POST your subscription XML to the URL returned from
msg-push-consumers header
- POST /queues/jms.queue.bar/push-consumers
+ POST /queues/bar/push-consumers
Host: example.com
Content-Type: application/xml
<push-registration>
- <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
+ <link rel="destination" href="http://somewhere.com/queues/foo"/>
</push-registration>
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/queues/jms.queue.bar/push-consumers/1-333-1212
+ Location: http://example.com/queues/bar/push-consumers/1-333-1212
The Location header contains the URL for the created resource. If
you want to unregister this, then do a HTTP DELETE on this URL.
@@ -1244,19 +1245,19 @@ Here's an example of creating a push registration for a topic:
1. First do a HEAD request to the topic resource:
- HEAD /topics/jms.topic.bar HTTP/1.1
+ HEAD /topics/bar HTTP/1.1
Host: example.com
--- Response ---
HTTP/1.1 200 Ok
- msg-create: http://example.com/topics/jms.topic.bar/create
- msg-pull-subscriptions: http://example.com/topics/jms.topic.bar/pull-subscriptions
- msg-push-subscriptions: http://example.com/topics/jms.topic.bar/push-subscriptions
+ msg-create: http://example.com/topics/bar/create
+ msg-pull-subscriptions: http://example.com/topics/bar/pull-subscriptions
+ msg-push-subscriptions: http://example.com/topics/bar/push-subscriptions
2. Next POST your subscription XML to the URL returned from
msg-push-subscriptions header
- POST /topics/jms.topic.bar/push-subscriptions
+ POST /topics/bar/push-subscriptions
Host: example.com
Content-Type: application/xml
@@ -1266,7 +1267,7 @@ Here's an example of creating a push registration for a topic:
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212
+ Location: http://example.com/topics/bar/push-subscriptions/1-333-1212
The Location header contains the URL for the created resource. If
you want to unregister this, then do a HTTP DELETE on this URL.
@@ -1287,7 +1288,7 @@ go in the directory specified by the queue-push-store-dir config
variable defined in Chapter 2:
<push-registration id="111">
- <destination>jms.queue.bar</destination>
+ <destination>bar</destination>
<durable>true</durable>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
</push-registration>
@@ -1300,7 +1301,7 @@ variable defined in Chapter 2:
<destination>my-subscription-1</destination
<durable>true</durable>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
- <topic>jms.topic.foo</topic>
+ <topic>foo</topic>
</push-topic-registration>
### Pushing to Authenticated Servers
@@ -1343,7 +1344,7 @@ there. For example:
POST /queues
Host: example.com
- Content-Type: application/activemq.jms.queue+xml
+ Content-Type: application/activemq.xml
<queue name="testQueue">
<durable>true</durable>
@@ -1351,22 +1352,22 @@ there. For example:
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/queues/jms.queue.testQueue
+ Location: http://example.com/queues/testQueue
-Notice that the Content-Type is application/activemq.jms.queue+xml.
+Notice that the Content-Type is application/activemq.xml.
Here's what creating a topic would look like:
POST /topics
Host: example.com
- Content-Type: application/activemq.jms.topic+xml
+ Content-Type: application/activemq.xml
<topic name="testTopic">
</topic>
--- Response ---
HTTP/1.1 201 Created
- Location: http://example.com/topics/jms.topic.testTopic
+ Location: http://example.com/topics/testTopic
## Securing the Apache ActiveMQ Artemis REST Interface
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/24a045e2/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
index c7e194f..e256e5e 100644
--- a/docs/user-manual/en/using-core.md
+++ b/docs/user-manual/en/using-core.md
@@ -1,9 +1,9 @@
# Using Core
Apache ActiveMQ Artemis core is a completely JMS-agnostic messaging system with its own
-non-JMS API. We call this the *core API*.
+API. We call this the *core API*.
-If you don't want to use JMS you can use the core API directly. The core
+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.
[3/3] activemq-artemis git commit: This closes #1077
Posted by cl...@apache.org.
This closes #1077
Project: http://git-wip-us.apache.org/repos/asf/activemq-artemis/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-artemis/commit/4fabbc80
Tree: http://git-wip-us.apache.org/repos/asf/activemq-artemis/tree/4fabbc80
Diff: http://git-wip-us.apache.org/repos/asf/activemq-artemis/diff/4fabbc80
Branch: refs/heads/master
Commit: 4fabbc8041d8f048039879264e1926910b16f217
Parents: d408c46 24a045e
Author: Clebert Suconic <cl...@apache.org>
Authored: Thu Mar 9 16:53:15 2017 -0500
Committer: Clebert Suconic <cl...@apache.org>
Committed: Thu Mar 9 16:53:15 2017 -0500
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 1 +
docs/user-manual/en/address-model.md | 585 +++++++++++++++++++
docs/user-manual/en/architecture.md | 79 ++-
docs/user-manual/en/client-reconnection.md | 2 +-
docs/user-manual/en/configuration-index.md | 26 +-
docs/user-manual/en/embedding-activemq.md | 74 +--
.../en/images/addressing-model-p2p-pubsub.png | Bin 0 -> 73261 bytes
.../en/images/addressing-model-p2p.png | Bin 0 -> 45091 bytes
.../en/images/addressing-model-p2p2.png | Bin 0 -> 55731 bytes
.../en/images/addressing-model-pubsub.png | Bin 0 -> 53982 bytes
docs/user-manual/en/intercepting-operations.md | 2 +-
docs/user-manual/en/jms-core-mapping.md | 37 +-
docs/user-manual/en/large-messages.md | 11 +-
docs/user-manual/en/management.md | 58 +-
docs/user-manual/en/messaging-concepts.md | 32 +-
docs/user-manual/en/perf-tuning.md | 5 +
docs/user-manual/en/queue-attributes.md | 220 +------
docs/user-manual/en/rest.md | 197 +++----
docs/user-manual/en/using-core.md | 4 +-
19 files changed, 786 insertions(+), 547 deletions(-)
----------------------------------------------------------------------
[2/3] activemq-artemis git commit: ARTEMIS-780 Added section on
latest address model
Posted by cl...@apache.org.
ARTEMIS-780 Added section on latest address model
Project: http://git-wip-us.apache.org/repos/asf/activemq-artemis/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-artemis/commit/c971476a
Tree: http://git-wip-us.apache.org/repos/asf/activemq-artemis/tree/c971476a
Diff: http://git-wip-us.apache.org/repos/asf/activemq-artemis/diff/c971476a
Branch: refs/heads/master
Commit: c971476a8879e6105b56f36ba3dfa77239d68a93
Parents: d408c46
Author: Martyn Taylor <mt...@redhat.com>
Authored: Wed Mar 8 16:00:45 2017 +0000
Committer: Martyn Taylor <mt...@redhat.com>
Committed: Thu Mar 9 21:24:02 2017 +0000
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 1 +
docs/user-manual/en/address-model.md | 585 +++++++++++++++++++
docs/user-manual/en/configuration-index.md | 26 +-
.../en/images/addressing-model-p2p-pubsub.png | Bin 0 -> 73261 bytes
.../en/images/addressing-model-p2p.png | Bin 0 -> 45091 bytes
.../en/images/addressing-model-p2p2.png | Bin 0 -> 55731 bytes
.../en/images/addressing-model-pubsub.png | Bin 0 -> 53982 bytes
docs/user-manual/en/queue-attributes.md | 220 +------
8 files changed, 600 insertions(+), 232 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index f514ff7..0e2f0a0 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -7,6 +7,7 @@
* [Messaging Concepts](messaging-concepts.md)
* [Architecture](architecture.md)
* [Using the Server](using-server.md)
+* [Address Model](address-model.md)
* [Using JMS](using-jms.md)
* [Using Core](using-core.md)
* [Using AMQP](using-amqp.md)
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/address-model.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/address-model.md b/docs/user-manual/en/address-model.md
new file mode 100644
index 0000000..8de3b67
--- /dev/null
+++ b/docs/user-manual/en/address-model.md
@@ -0,0 +1,585 @@
+# Apache ActiveMQ Artemis Addressing and Queues
+
+Apache ActiveMQ Artemis has a unique addressing model that is both powerful and flexible and that offers great performance. The addressing model comprises three main concepts: addresses, queues and routing types.
+
+An address represents a messaging endpoint. Within the configuration, a typical address is given a unique name, 0 or more queues, and a routing type.
+
+A queue is associated with an address. There can be multiple queues per address. Once an incoming message is matched to an address, the message will be sent on to one or more of its queues, depending on the routing type configured. Queues can be configured to be automatically created and deleted.
+
+A routing type determines how messages are sent to the queues associated with an address. A Apache ActiveMQ Artemis address can be configured with two different routing types.
+
+Table 1. Routing Types
+
+| If you want your messages routed to\u2026\u200b | Use this routing type \u2026\u200b |
+| :----------------------------------------------------------------------: | :---------------------: |
+| A single queue within the matching address, in a point-to-point manner. | Anycast |
+| Every queue within the matching address, in a publish-subscribe manner. | Multicast |
+
+--------------------------------------------------------------------------------------------
+**Note:** It is possible to define more than one routing type per address, but this typically results in an anti-pattern and is therefore not recommended. If an address does use both routing types, however, and the client does not show a preference for either one, the broker typically defaults to the anycast routing type.
+The one exception is when the client uses the MQTT protocol. In that case, the default routing type is multicast. |
+
+## Basic Address Configuration
+
+The following examples show how to configure basic point to point and publish subscribe addresses.
+
+### Point-to-Point Messaging
+
+Point-to-point messaging is a common scenario in which a message sent by a producer has only one consumer. AMQP and JMS message producers and consumers can make use of point-to-point messaging queues, for example. Define an anycast routing type for an address so that its queues receive messages in a point-to-point manner.
+
+When a message is received on an address using anycast, Apache ActiveMQ Artemis locates the queue associated with the address and routes the message to it. When consumers request to consume from the address, the broker locates the relevant queue and associates this queue with the appropriate consumers. If multiple consumers are connected to the same queue, messages are distributed amongst each consumer equally, providing the consumers are equally able to handle them.
+
+
+Figure 1. Point to Point Messaging
+
+#### Configuring an Address to Use the Anycast Routing Type
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+Add an address configuration element and its associated queue if they do not exist already.
+
+**Note** For normal Point to Point semantics, the queue name **MUST** match the address name.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="orders">
+ <anycast>
+ <queue name="orders"/>
+ </anycast>
+ </address>
+ </core>
+</configuration>
+```
+
+### Publish-Subscribe Messaging
+
+In a publish-subscribe scenario, messages are sent to every consumer subscribed to an address. JMS topics and MQTT subscriptions are two examples of publish-subscribe messaging.
+
+To configure an address with publish-subscribe semantics, create an address with the multicast routing tyoe.
+
+
+Figure 2. Publish-Subscribe
+
+#### Configuring an Address to Use the Multicast Routing Type
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+Add an address configuration element with multicast routing type.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="pubsub.foo">
+ <multicast/>
+ </address>
+ </core>
+</configuration>
+```
+
+When clients connect to an address with the multicast element, a subscription queue for the client will be automatically created for the client. It is also possible to pre-configure subscription queues and connect to them directly using the queue's [Fully Qualified Queue names](#fully-qualified-queue-names).
+
+Add one more queue elements to the address and wrap the multicast element around them. This step is typically not needed since the broker will automatically create a queue for each subscription requested by a client.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="pubsub.foo">
+ <multicast>
+ <queue name="client123.pubsub.foo"/>
+ <queue name="client456.pubsub.foo"/>
+ </multicast>
+ </address>
+ </core>
+</configration>
+```
+
+Figure 3. Point-to-Point with Two Queues
+
+### Point-to-Point Address multiple Queues
+
+It is actually possible to define more than one queue on an address with an anycast routing type. When messages are received on such an address, they are firstly distributed evenly across all the defined queues. Using [Fully Qualified Queue names](#fully-qualified-queue-names)., clients are able to select the queue that they\u2019d like to subscribe to. Should more than one consumer connect direct to a single queue, Apache ActiveMQ Artemis will take care of distributing messages between them, as in the example above.
+
+
+Figure 3. Point-to-Point with Two Queues
+
+--------------------------------------------------------------------------------------------
+**Note:** This is how Apache ActiveMQ Artemis handles load balancing of queues across multiple nodes in a cluster.
+Configuring a Point-to-Point Address with Two Queues
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+Add an address configuration with Anycast routing type element and its associated queues.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="address.foo">
+ <anycast>
+ <queue name="q1"/>
+ <queue name="q2"/>
+ </anycast>
+ </address>
+ </core>
+</configuration>
+```
+
+### Point-to-Point and Publish-Subscribe Addresses
+
+It is possible to define an address with both point-to-point and publish-subscribe semantics enabled. While not typically recommend, this can be useful when you want, for example, a JMS Queue say orders and a JMS Topic named orders. The different routing types make the addresses appear to be distinct.
+
+Using an example of JMS Clients, the messages sent by a JMS queue producer will be routed using the anycast routing type. Messages sent by a JMS topic producer will use the multicast routing type. In addition when a JMS topic consumer attaches it will be attached to it\u2019s own subscription queue. JMS queue consumer will be attached to the anycast queue.
+
+
+Figure 4. [Point-to-Point and Publish-Subscribe
+
+--------------------------------------------------------------------------------------------
+**Note:** The behavior in this scenario is dependent on the protocol being used. For JMS there is a clear distinction between topic and queue producers and consumers, which make the logic straight forward. Other protocols like AMQP do not make this distinction. A message being sent via AMQP will be routed by both anycast and multicast and consumers will default to anycast. For more information, please check the behavior of each protocol in the sections on protocols.
+
+The XML snippet below is an example of what the configuration for an address using both anycast and multicast would look like in <broker-instance>/etc/broker.xml. routing types. Note that subscription queues are typically created on demand, so there is no need to list specific queue elements inside the multicast routing type.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="foo.orders">
+ <anycast>
+ <queue name="orders"/>
+ </anycast>
+ <multicast/>
+ </address>
+ </core>
+</configuration>
+```
+
+## How to filter messages
+
+Apache ActiveMQ Artemis supports the ability to filter messages using Apache Artemis [Filter Expressions](#filter-expressions).
+
+Filters can be applied in two places, on a queue and on a consumer.
+
+### Queue Filter
+
+When a filter is applied to a queue, messages are filter before they sent to the queue. To add a queue filter use the
+filter element when configuring a queue. Open up the broker.xml and add an address with a queue, using the filter element
+to configure a filter on this queue.
+
+```xml
+ <address name="filter">
+ <queue name="filter">
+ <filter string="color='red'"/>
+ </queue>
+ </address>
+```
+
+The filter defined above ensures that only messages with an attribute "color='red'" is sent to this queue.
+
+### Consumer Filters
+
+Consumer filters are applied after messages have reached a queue and are defined using the appropriate client APIs. The
+follow JMS example shows how to consumer filters work.
+
+1. Define an address with a single queue, with no filter applied.
+
+```xml
+ <address name="filter">
+ <queue name="filter">
+ </queue>
+ </address>
+```
+
+```java
+ ...
+ // Send some messages
+ for (int i = 0; i < 3; i ++) {
+ TextMessage redMessage = senderSession.createTextMessage("Red");
+ redMessage.setStringProperty("color", "red");
+ producer.send(redMessage)
+
+ TextMessage greenMessage = senderSession.createTextMessage("Green");
+ greenMessage.setStringProperty("color", "green");
+ producer.send(greenMessage)
+ }
+```
+
+At this point the queue would have 6 messages: red,green,red,green,red,green
+
+```java
+ MessageConsumer redConsumer = redSession.createConsumer(queue, "color='red'");
+```
+
+The redConsumer has a filter that only matches "red" messages. The redConsumer will receive 3 messages.
+
+```
+red, red, red
+```
+
+The resulting queue would now be
+
+```
+green, green, green
+```
+
+## Creating and Deleting Addresses and Queues Automatically
+
+You can configure Apache ActiveMQ Artemis to automatically create addresses and queues, and then delete them when they are no longer in use. This saves you from having to preconfigure each address and queue before a client can connect to it. Automatic creation and deletion is configured on a per address basis and is controlled by following:
+
+| Parameter | Description |
+|-----------|-------------|
+| auto-create-addresses | When set to true, the broker will create the address requested by the client if it does not exist already. The default is true.|
+| auto-delete-addresses | When set to true, the broker will be delete any **auto-created** adddress once all of it\u2019s queues have been deleted. The default is true |
+|default-address-routing-type | The routing type to use if the client does not specify one. Possible values are MULTICAST and ANYCAST. See earlier in this chapter for more information about routing types. The default value is MULTICAST. |
+
+### Configuring an Address to be Automatically Created
+
+Edit the file <broker-instance>/etc/broker.xml and add the auto-create-addresses element to the address-setting you want the broker to automatically create.
+
+(Optional) Add the address-setting if it does not exits. Use the match parameter and the The Apache ActiveMQ Artemis Wildcard Syntax to match more than one specific address.
+
+Set auto-create-addresses to true
+
+(Optional) Assign MULTICAST or ANYCAST as the default routing type for the address.
+
+The example below configures an address-setting to be automatically created by the broker. The default routing type to be used if not specified by the client is MULTICAST. Note that wildcard syntax is used. Any address starting with /news/politics/ will be automatically created by the broker.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address-settings>
+ <address-setting match="/news/politics/#">
+ <auto-create-addresses>true</auto-create-addresses>
+ <default-address-routing-type>MULTICAST</default-address-routing-type>
+ </address-setting>
+ </address-settings>
+ ...
+ </core>
+</configuration>
+```
+
+### Configuring an Address to be Automatically Deleted
+
+Edit the file <broker-instance>/etc/broker.xml and add the auto-delete-addresses element to the address-setting you want the broker to automatically create.
+
+(Optional) Add the address-setting if it does not exits. Use the match parameter and the The Apache ActiveMQ Artemis Wildcard Syntax to match more than one specific address.
+
+Set auto-delete-addresses to true
+
+The example below configures an address-setting to be automatically deleted by the broker. Note that wildcard syntax is used. Any address request by the client that starts with /news/politics/ is configured to be automatically deleted by the broker.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address-settings>
+ <address-setting match="/news/politics/#">
+ <auto-create-addresses>true</auto-create-addresses>
+ <default-address-routing-type>MULTICAST</default-address-routing-type>
+ </address-setting>
+ </address-settings>
+ ...
+ </core>
+</configuration>
+```
+
+## Fully Qualified Queue Names
+
+Internally the broker maps a client\u2019s request for an address to specific queues. The broker decides on behalf of the client which queues to send messages to or from which queue to receive messages. However, more advanced use cases might require that the client specify a queue directly. In these situations the client and use a fully qualified queue name, by specifying both the address name and the queue name, separated by a ::.
+
+### Specifying a Fully Qualified Queue Name
+In this example, the address foo is configured with two queues q1, q2 as shown in the configuration below.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <addresses>
+ <address name="foo">
+ <anycast>
+ <queue name="q1" />
+ <queue name="q2" />
+ </anycast>
+ </address>
+ </addresses>
+ </core>
+</configuration>
+```
+
+In the client code, use both the address name and the queue name when requesting a connection from the broker. Remember to use two colons, ::, to separate the names, as in the example Java code below.
+
+```java
+String FQQN = "foo::q1";
+Queue q1 session.createQueue(FQQN);
+MessageConsumer consumer = session.createConsumer(q1);
+```
+
+## Configuring a Prefix to Connect to a Specific Routing Type
+
+Normally, if a Apache ActiveMQ Artemis receivs a message sent to a particular address, that has both anycast and multicast routing types enable, Apache ActiveMQ Artemis will route a copy of the message to **one** of the anycast queues and to **all** of the multicast queues.
+
+However, clients can specify a special prefix when connecting to an address to specify whether to connect using anycast or multicast. The prefixes are custom values that are designated using the anycastPrefix and multicastPrefix parameters within the URL of an acceptor.
+
+### Configuring an Anycast Prefix
+
+In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the desired acceptor. In the example below, the acceptor is configured to use anycast:// for the anycastPrefix. Client code can specify anycast://foo/ if the client needs to send a message to only one of the anycast queues.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <acceptors>
+ <acceptor name="artemis">tcp://0.0.0.0:61616?protocols=AMQP;anycastPrefix=anycast://</acceptor>
+ </acceptors>
+ ...
+ </core>
+</configuration>
+```
+
+### Configuring a Multicast Prefix
+
+In <broker-instance>/etc/broker.xml, add the anycastPrefix to the URL of the desired acceptor. In the example below, the acceptor is configured to use multicast:// for the multicastPrefix. Client code can specify multicast://foo/ if the client needs the message sent to only the multicast queues of the address.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <acceptors>
+ <acceptor name="artemis">tcp://0.0.0.0:61616?protocols=AMQP;multicastPrefix=multicast://</acceptor>
+ </acceptors>
+ ...
+ </core>
+</configuration>
+```
+
+## Advanced Address Configuration
+
+### Pre-configuring subscription queue semantics
+
+In most cases it\u2019s not necessary to pre-create subscription queues. The relevant protocol managers take care of creating subscription queues when clients request to subscribe to an address. The type of subscription queue created, depends on what properties the client request. E.g. durable, non-shared, shared etc... Protocol managers uses special queue names to identify which queues below to which consumers and users need not worry about the details.
+
+However, there are scenarios where a user may want to use broker side configuration to pre-configure a subscription. And later connect to that queue directly using a [Fully Qualified Queue name](#fully-qualified-queue-names).. The examples below show how to use broker side configuration to pre-configure a queue with publish subscribe behavior for shared, non-shared, durable and non-durable subscription behavior.
+
+#### Configuring a shared durable subscription queue with up to 10 concurrent consumers
+
+The default behavior for queues is to not limit the number connected queue consumers. The **max-consumers** paramter of the queue element can be used to limit the number of connected consumers allowed at any one time.
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="durable.foo">
+ <multicast>
+ <!-- pre-configured shared durable subscription queue -->
+ <queue name="q1" max-consumers="10">
+ <durable>true</durable>
+ </queue>
+ </multicast>
+ </address>
+ </core>
+</configuration>
+```
+
+#### Configuring a non-shared durable subscription
+
+The broker can be configured to prevent more than one consumer from connecting to a queue at any one time. The subscriptions to queues configured this way are therefore "non-shared". To do this simply set the **max-consumers** parameter to "1"
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="durable.foo">
+ <multicast>
+ <!-- pre-configured non shared durable subscription queue -->
+ <queue name="q1" max-consumers="1">
+ <durable>true</durable>
+ </queue>
+ </multicast>
+ </address>
+ </core>
+</configuration>
+```
+
+#### Pre-configuring a queue as a non-durable subscription queue
+
+Non-durable subscriptions are again usually managed by the relevant protocol manager, by creating and deleting temporary queues.
+
+If a user requires to pre-create a queue that behaves like a non-durable subscription queue the **purge-on-no-consumers** flag can be enabled on the queue. When **purge-on-no-consumers** is set to **true**. The queue will not start receiving messages until a consumer is attached. When the last consumer is detached from the queue. The queue is purged (it's messages are removed) and will not receive any more messages until a new consumer is attached.
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="non.shared.durable.foo">
+ <multicast>
+ <queue name="orders1" purge-on-no-consumers="true"/>
+ </multicast>
+ </address>
+ </core>
+</configuration>
+```
+
+## Additional Information: Protocol Managers, Address
+
+A protocol manager maps protocol specific concepts down to the Apache ActiveMQ Artemis core model of addresses, queues and routing types. For example, when a client sends a MQTT subscription packet with the addresses
+
+```
+/house/room1/lights
+/house/room2/lights
+```
+
+The MQTT protocol manager understands that the two addresses require multicast semantics. The protocol manager will therefore first look to ensure that multicast is enabled for both addresses. If not, it will attempt to dynamically create them. If successful, the protocol manager will then create special subscription queues with special names, for each subscription requested by the client.
+
+The special name allows the protocol manager to quickly identify the required client subscription queues should the client disconnect and reconnect at a later date. If the subscription is temporary the protocol manager will delete the queue once the client disconnects.
+
+When a client requests to subscribe to a point to point address. The protocol manager will look up the queue associated with the point to point address. This queue should have the same name as the addresss.
+
+**Note:** If the queue is auto created, it will be auto deleted once there are no consumers and no messages in it. For more information on auto create see the next section [Configuring Addresses and Queues via Address Settings](#Configuring-Addresses-and-Queues-via-Address-Settings)
+
+## Configuring Addresses and Queues via Address Settings
+
+There are some attributes that are defined against an address wildcard
+rather than a specific address/queue. Here an example of an `address-setting`
+entry that would be found in the `broker.xml` file.
+
+ <address-settings>
+ <address-setting match="order.foo">
+ <dead-letter-address>DLA</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ <redelivery-delay>5000</redelivery-delay>
+ <expiry-address>ExpiryQueue</expiry-address>
+ <last-value-queue>true</last-value-queue>
+ <max-size-bytes>100000</max-size-bytes>
+ <page-size-bytes>20000</page-size-bytes>
+ <redistribution-delay>0</redistribution-delay>
+ <send-to-dla-on-no-route>true</send-to-dla-on-no-route>
+ <address-full-policy>PAGE</address-full-policy>
+ <slow-consumer-threshold>-1</slow-consumer-threshold>
+ <slow-consumer-policy>NOTIFY</slow-consumer-policy>
+ <slow-consumer-check-period>5</slow-consumer-check-period>
+ </address-setting>
+ </address-settings>
+
+The idea with address settings, is you can provide a block of settings
+which will be applied against any addresses that match the string in the
+`match` attribute. In the above example the settings would only be
+applied to the address "order.foo" address but you can also use wildcards
+to apply settings. See: [The chapter on the wild card syntax](#wildcard-syntax).
+
+For example, if you used the `match` string `jms.queue.#` the settings
+would be applied to all addresses which start with `jms.queue.` which
+would be all JMS queues.
+
+The meaning of the specific settings are explained fully throughout the
+user manual, however here is a brief description with a link to the
+appropriate chapter if available.
+
+`max-delivery-attempts` defines how many time a cancelled message can be
+redelivered before sending to the `dead-letter-address`. A full
+explanation can be found [here](#undelivered-messages.configuring).
+
+`redelivery-delay` defines how long to wait before attempting redelivery
+of a cancelled message. see [here](#undelivered-messages.delay).
+
+`expiry-address` defines where to send a message that has expired. see
+[here](#message-expiry.configuring).
+
+`expiry-delay` defines the expiration time that will be used for
+messages which are using the default expiration time (i.e. 0). For
+example, if `expiry-delay` is set to "10" and a message which is using
+the default expiration time (i.e. 0) arrives then its expiration time of
+"0" will be changed to "10." However, if a message which is using an
+expiration time of "20" arrives then its expiration time will remain
+unchanged. Setting `expiry-delay` to "-1" will disable this feature. The
+default is "-1".
+
+`last-value-queue` defines whether a queue only uses last values or not.
+see [here](#last-value-queues).
+
+`max-size-bytes` and `page-size-bytes` are used to set paging on an
+address. This is explained [here](#paging).
+
+`redistribution-delay` defines how long to wait when the last consumer
+is closed on a queue before redistributing any messages. see
+[here](#clusters).
+
+`send-to-dla-on-no-route`. If a message is sent to an address, but the
+server does not route it to any queues, for example, there might be no
+queues bound to that address, or none of the queues have filters that
+match, then normally that message would be discarded. However if this
+parameter is set to true for that address, if the message is not routed
+to any queues it will instead be sent to the dead letter address (DLA)
+for that address, if it exists.
+
+`address-full-policy`. This attribute can have one of the following
+values: PAGE, DROP, FAIL or BLOCK and determines what happens when an
+address where `max-size-bytes` is specified becomes full. The default
+value is PAGE. If the value is PAGE then further messages will be paged
+to disk. If the value is DROP then further messages will be silently
+dropped. If the value is FAIL then further messages will be dropped and
+an exception will be thrown on the client-side. If the value is BLOCK
+then client message producers will block when they try and send further
+messages. See the following chapters for more info [Flow Control](flow-control.md), [Paging](paging.md).
+
+`slow-consumer-threshold`. The minimum rate of message consumption
+allowed before a consumer is considered "slow." Measured in
+messages-per-second. Default is -1 (i.e. disabled); any other valid
+value must be greater than 0.
+
+`slow-consumer-policy`. What should happen when a slow consumer is
+detected. `KILL` will kill the consumer's connection (which will
+obviously impact any other client threads using that same connection).
+`NOTIFY` will send a CONSUMER\_SLOW management notification which an
+application could receive and take action with. See [slow consumers](slow-consumers.md) for more details
+on this notification.
+
+`slow-consumer-check-period`. How often to check for slow consumers on a
+particular queue. Measured in seconds. Default is 5. See [slow consumers](slow-consumers.md)
+for more information about slow consumer detection.
+
+`auto-create-jms-queues`. Whether or not the broker should automatically
+create a JMS queue when a JMS message is sent to a queue whose name fits
+the address `match` (remember, a JMS queue is just a core queue which has
+the same address and queue name) or a JMS consumer tries to connect to a
+queue whose name fits the address `match`. Queues which are auto-created
+are durable, non-temporary, and non-transient. Default is `true`. This is
+_DEPRECATED_. See `auto-create-queues`.
+
+`auto-delete-jms-queues`. Whether or not the broker should automatically
+delete auto-created JMS queues when they have both 0 consumers and 0 messages.
+Default is `true`. This is _DEPRECATED_. See `auto-delete-queues`.
+
+`auto-create-jms-topics`. Whether or not the broker should automatically
+create a JMS topic when a JMS message is sent to a topic whose name fits
+the address `match` (remember, a JMS topic is just a core address which has
+one or more core queues mapped to it) or a JMS consumer tries to subscribe
+to a topic whose name fits the address `match`. Default is `true`. This is
+_DEPRECATED_. See `auto-create-addresses`.
+
+`auto-delete-jms-topics`. Whether or not the broker should automatically
+delete auto-created JMS topics once the last subscription on the topic has
+been closed. Default is `true`. This is _DEPRECATED_. See `auto-delete-addresses`.
+
+`auto-create-queues`. Whether or not the broker should automatically
+create a queue when a message is sent or a consumer tries to connect to a
+queue whose name fits the address `match`. Queues which are auto-created
+are durable, non-temporary, and non-transient. Default is `true`.
+
+`auto-delete-queues`. Whether or not the broker should automatically
+delete auto-created queues when they have both 0 consumers and 0 messages.
+Default is `true`.
+
+`auto-create-addresses`. Whether or not the broker should automatically
+create an address when a message is sent to or a consumer tries to consume
+from a queue which is mapped to an address whose name fits the address `match`.
+Default is `true`.
+
+`auto-delete-addresses`. Whether or not the broker should automatically
+delete auto-created addresses once the address no longer has any queues.
+Default is `true`.
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/configuration-index.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuration-index.md b/docs/user-manual/en/configuration-index.md
index cffee06..955c87b 100644
--- a/docs/user-manual/en/configuration-index.md
+++ b/docs/user-manual/en/configuration-index.md
@@ -42,7 +42,7 @@ Name | Description
:--- | :---
[acceptors](configuring-transports.md "Understanding Acceptors") | a list of remoting acceptors
[acceptors.acceptor](configuring-transports.md "Understanding Acceptors") | Each acceptor is composed for just an URL
-[address-settings](queue-attributes.md "Configuring Queues Via Address Settings") | [a list of address-setting](#address-setting-type)
+[address-settings](address-model.md "Configuring Addresses and Queues Via Address Settings") | [a list of address-setting](#address-setting-type)
[allow-failback](ha.md "Failing Back to live Server") | Should stop backup on live restart. default true
[async-connection-execution-enabled](connection-ttl.md "Configuring Asynchronous Connection Execution") | If False delivery would be always asynchronous. default true
[bindings-directory](persistence.md "Configuring the bindings journal") | The folder in use for the bindings folder
@@ -99,7 +99,7 @@ Name | Description
[persist-delivery-count-before-delivery](undelivered-messages.md "Delivery Count Persistence") | True means that the delivery count is persisted before delivery. False means that this only happens after a message has been cancelled. Default=false
[persistence-enabled](persistence.md "Configuring ActiveMQ Artemis for Zero Persistence") | true means that the server will use the file based journal for persistence. Default=true
[persist-id-cache](duplicate-detection.md "Configuring the Duplicate ID Cache") | true means that ID's are persisted to the journal. Default=true
-[queues](queue-attributes.md "Predefined Queues") | [a list of queue to be created](#queue-type)
+[queues](address-model.md "Predefined Queues") | [a list of queue to be created](#queue-type)
[remoting-incoming-interceptors](intercepting-operations.md "Intercepting Operations") | A list of interceptor
[resolveProtocols]() | Use [ServiceLoader](http://docs.oracle.com/javase/tutorial/ext/basics/spi.html) to load protocol modules. Default=true
[scheduled-thread-pool-max-size](thread-pooling.md#server.scheduled.thread.pool "Server Scheduled Thread Pool")| Maximum number of threads to use for the scheduled thread pool. Default=5
@@ -122,22 +122,22 @@ system-property-prefix | Prefix for replacing configuration settings using Bean
Name | Description
:--- | :---
-[match ](queue-attributes.md "Configuring Queues Via Address Settings") | The filter to apply to the setting
+[match ](address-model.md "Configuring Queues Via Address Settings") | The filter to apply to the setting
[dead-letter-address](undelivered-messages.md "Configuring Dead Letter Addresses") | dead letter address
[expiry-address](message-expiry.md "Configuring Expiry Addresses") | expired messages address
-[expiry-delay](queue-attributes.md "Configuring Queues Via Address Settings") | expiration time override, -1 don't override with default=-1
+[expiry-delay](address-model.md "Configuring Queues Via Address Settings") | expiration time override, -1 don't override with default=-1
[redelivery-delay](undelivered-messages.md "Configuring Delayed Redelivery") | time to redeliver a message (in ms) with default=0
-[redelivery-delay-multiplier](queue-attributes.md "Configuring Queues Via Address Settings") | multiplier to apply to the "redelivery-delay"
-[max-redelivery-delay](queue-attributes.md "Configuring Queues Via Address Settings") | Max value for the redelivery-delay
+[redelivery-delay-multiplier](address-model.md "Configuring Queues Via Address Settings") | multiplier to apply to the "redelivery-delay"
+[max-redelivery-delay](address-model.md "Configuring Queues Via Address Settings") | Max value for the redelivery-delay
[max-delivery-attempts](undelivered-messages.md "Configuring Dead Letter Addresses") | Number of retries before dead letter address, default=10
[max-size-bytes](paging.md "Paging") | Limit before paging. -1 = infinite
[page-size-bytes](paging.md "Paging") | Size of each file on page, default=10485760
[page-max-cache-size](paging.md "Paging") | Maximum number of files cached from paging default=5
-[address-full-policy](queue-attributes.md "Configuring Queues Via Address Settings") | Model to chose after queue full
-[message-counter-history-day-limit](queue-attributes.md "Configuring Queues Via Address Settings") | Days to keep in history
+[address-full-policy](address-model.md "Configuring Queues Via Address Settings") | Model to chose after queue full
+[message-counter-history-day-limit](address-model.md "Configuring Queues Via Address Settings") | Days to keep in history
[last-value-queue](last-value-queues.md "Last-Value Queues") | Queue is a last value queue, default=false
[redistribution-delay](clusters.md "Clusters") | Timeout before redistributing values after no consumers. default=-1
-[send-to-dla-on-no-route](queue-attributes.md "Configuring Queues Via Address Settings") | Forward messages to DLA when no queues subscribing. default=false
+[send-to-dla-on-no-route](address-model.md "Configuring Queues Via Address Settings") | Forward messages to DLA when no queues subscribing. default=false
#bridge type
@@ -235,10 +235,10 @@ Name | Description
Name | Description
:--- | :---
-[name ](queue-attributes.md "Predefined Queues") | unique name
-[address](queue-attributes.md "Predefined Queues") | address for the queue
-[filter](queue-attributes.md "Predefined Queues") | optional core filter expression
-[durable](queue-attributes.md "Predefined Queues") | whether the queue is durable (persistent). Default=true
+[name ](address-model.md "Predefined Queues") | unique name
+[address](address-model.md "Predefined Queues") | address for the queue
+[filter](address-model.md "Predefined Queues") | optional core filter expression
+[durable](address-model.md "Predefined Queues") | whether the queue is durable (persistent). Default=true
#security-setting type
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/images/addressing-model-p2p-pubsub.png
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/images/addressing-model-p2p-pubsub.png b/docs/user-manual/en/images/addressing-model-p2p-pubsub.png
new file mode 100644
index 0000000..81e43e7
Binary files /dev/null and b/docs/user-manual/en/images/addressing-model-p2p-pubsub.png differ
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/images/addressing-model-p2p.png
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/images/addressing-model-p2p.png b/docs/user-manual/en/images/addressing-model-p2p.png
new file mode 100644
index 0000000..9547ed7
Binary files /dev/null and b/docs/user-manual/en/images/addressing-model-p2p.png differ
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/images/addressing-model-p2p2.png
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/images/addressing-model-p2p2.png b/docs/user-manual/en/images/addressing-model-p2p2.png
new file mode 100644
index 0000000..ae13978
Binary files /dev/null and b/docs/user-manual/en/images/addressing-model-p2p2.png differ
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/images/addressing-model-pubsub.png
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/images/addressing-model-pubsub.png b/docs/user-manual/en/images/addressing-model-pubsub.png
new file mode 100644
index 0000000..da87371
Binary files /dev/null and b/docs/user-manual/en/images/addressing-model-pubsub.png differ
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/c971476a/docs/user-manual/en/queue-attributes.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/queue-attributes.md b/docs/user-manual/en/queue-attributes.md
index 7a8fe78..156b9ba 100644
--- a/docs/user-manual/en/queue-attributes.md
+++ b/docs/user-manual/en/queue-attributes.md
@@ -1,220 +1,2 @@
-# Queue Attributes
+# Address and Queue Attributes and Settings
-Queue attributes can be set in one of two ways. Either by configuring
-them using the configuration file or by using the core API. This chapter
-will explain how to configure each attribute and what effect the
-attribute has.
-
-## Predefined Queues
-
-Queues can be predefined via configuration at a core level or at a JMS
-level. Firstly let's look at a JMS level.
-
-The following shows a queue predefined in the jms element of the `broker.xml`
-configuration file.
-
- <queue name="selectorQueue">
- <selector string="color='red'"/>
- <durable>true</durable>
- </queue>
-
-This name attribute of queue defines the name of the queue. When we do
-this at a jms level we follow a naming convention so the actual name of
-the core queue will be `jms.queue.selectorQueue`.
-
-The selector element defines what JMS message selector the predefined
-queue will have. Only messages that match the selector will be added to
-the queue. This is an optional element with a default of null when
-omitted.
-
-The durable element specifies whether the queue will be persisted. This
-again is optional and defaults to true if omitted.
-
-Secondly a queue can be predefined at a core level in the
-`broker.xml` file. The following is an example.
-
- <queues>
- <queue name="jms.queue.selectorQueue">
- <address>jms.queue.selectorQueue</address>
- <filter string="color='red'"/>
- <durable>true</durable>
- </queue>
- </queues>
-
-This is very similar to the JMS configuration, with 3 real differences
-which are.
-
-1. The name attribute of queue is the actual name used for the queue
- with no naming convention as in JMS.
-
-2. The address element defines what address is used for routing
- messages.
-
-3. The filter uses the *Core filter syntax* (described in [filter Expressions](filter-expressions.md)), *not* the
- JMS selector syntax.
-
-## Using the API
-
-Queues can also be created using the core API or the management API.
-
-For the core API, queues can be created via the
-`org.apache.activemq.artemis.api.core.client.ClientSession` interface. There are
-multiple `createQueue` methods that support setting all of the
-previously mentioned attributes. There is one extra attribute that can
-be set via this API which is `temporary`. setting this to true means
-that the queue will be deleted once the session is disconnected.
-
-Take a look at [Management](management.md) for a description of the management API for creating
-queues.
-
-## Configuring Queues Via Address Settings
-
-There are some attributes that are defined against an address wildcard
-rather than a specific queue. Here an example of an `address-setting`
-entry that would be found in the `broker.xml` file.
-
- <address-settings>
- <address-setting match="jms.queue.exampleQueue">
- <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
- <max-delivery-attempts>3</max-delivery-attempts>
- <redelivery-delay>5000</redelivery-delay>
- <expiry-address>jms.queue.expiryQueue</expiry-address>
- <last-value-queue>true</last-value-queue>
- <max-size-bytes>100000</max-size-bytes>
- <page-size-bytes>20000</page-size-bytes>
- <redistribution-delay>0</redistribution-delay>
- <send-to-dla-on-no-route>true</send-to-dla-on-no-route>
- <address-full-policy>PAGE</address-full-policy>
- <slow-consumer-threshold>-1</slow-consumer-threshold>
- <slow-consumer-policy>NOTIFY</slow-consumer-policy>
- <slow-consumer-check-period>5</slow-consumer-check-period>
- <auto-create-jms-queues>true</auto-create-jms-queues> <!-- DEPRECATED see auto-create-queues>
- <auto-delete-jms-queues>true</auto-delete-jms-queues> <!-- DEPRECATED see auto-delete-queues>
- <auto-create-jms-topics>true</auto-create-jms-topics> <!-- DEPRECATED see auto-create-addresses>
- <auto-delete-jms-topics>true</auto-delete-jms-topics> <!-- DEPRECATED see auto-delete-addresses>
- <auto-create-jms-queues>true</auto-create-jms-queues>
- <auto-delete-jms-queues>true</auto-delete-jms-queues>
- <auto-create-jms-topics>true</auto-create-jms-topics>
- <auto-delete-jms-topics>true</auto-delete-jms-topics>
- </address-setting>
- </address-settings>
-
-The idea with address settings, is you can provide a block of settings
-which will be applied against any addresses that match the string in the
-`match` attribute. In the above example the settings would only be
-applied to any addresses which exactly match the address
-`jms.queue.exampleQueue`, but you can also use wildcards to apply sets
-of configuration against many addresses. The wildcard syntax used is
-described [here](#wildcard-syntax).
-
-For example, if you used the `match` string `jms.queue.#` the settings
-would be applied to all addresses which start with `jms.queue.` which
-would be all JMS queues.
-
-The meaning of the specific settings are explained fully throughout the
-user manual, however here is a brief description with a link to the
-appropriate chapter if available.
-
-`max-delivery-attempts` defines how many time a cancelled message can be
-redelivered before sending to the `dead-letter-address`. A full
-explanation can be found [here](#undelivered-messages.configuring).
-
-`redelivery-delay` defines how long to wait before attempting redelivery
-of a cancelled message. see [here](#undelivered-messages.delay).
-
-`expiry-address` defines where to send a message that has expired. see
-[here](#message-expiry.configuring).
-
-`expiry-delay` defines the expiration time that will be used for
-messages which are using the default expiration time (i.e. 0). For
-example, if `expiry-delay` is set to "10" and a message which is using
-the default expiration time (i.e. 0) arrives then its expiration time of
-"0" will be changed to "10." However, if a message which is using an
-expiration time of "20" arrives then its expiration time will remain
-unchanged. Setting `expiry-delay` to "-1" will disable this feature. The
-default is "-1".
-
-`last-value-queue` defines whether a queue only uses last values or not.
-see [here](#last-value-queues).
-
-`max-size-bytes` and `page-size-bytes` are used to set paging on an
-address. This is explained [here](#paging).
-
-`redistribution-delay` defines how long to wait when the last consumer
-is closed on a queue before redistributing any messages. see
-[here](#clusters).
-
-`send-to-dla-on-no-route`. If a message is sent to an address, but the
-server does not route it to any queues, for example, there might be no
-queues bound to that address, or none of the queues have filters that
-match, then normally that message would be discarded. However if this
-parameter is set to true for that address, if the message is not routed
-to any queues it will instead be sent to the dead letter address (DLA)
-for that address, if it exists.
-
-`address-full-policy`. This attribute can have one of the following
-values: PAGE, DROP, FAIL or BLOCK and determines what happens when an
-address where `max-size-bytes` is specified becomes full. The default
-value is PAGE. If the value is PAGE then further messages will be paged
-to disk. If the value is DROP then further messages will be silently
-dropped. If the value is FAIL then further messages will be dropped and
-an exception will be thrown on the client-side. If the value is BLOCK
-then client message producers will block when they try and send further
-messages. See the following chapters for more info [Flow Control](flow-control.md), [Paging](paging.md).
-
-`slow-consumer-threshold`. The minimum rate of message consumption
-allowed before a consumer is considered "slow." Measured in
-messages-per-second. Default is -1 (i.e. disabled); any other valid
-value must be greater than 0.
-
-`slow-consumer-policy`. What should happen when a slow consumer is
-detected. `KILL` will kill the consumer's connection (which will
-obviously impact any other client threads using that same connection).
-`NOTIFY` will send a CONSUMER\_SLOW management notification which an
-application could receive and take action with. See [slow consumers](slow-consumers.md) for more details
-on this notification.
-
-`slow-consumer-check-period`. How often to check for slow consumers on a
-particular queue. Measured in seconds. Default is 5. See [slow consumers](slow-consumers.md)
-for more information about slow consumer detection.
-
-`auto-create-jms-queues`. Whether or not the broker should automatically
-create a JMS queue when a JMS message is sent to a queue whose name fits
-the address `match` (remember, a JMS queue is just a core queue which has
-the same address and queue name) or a JMS consumer tries to connect to a
-queue whose name fits the address `match`. Queues which are auto-created
-are durable, non-temporary, and non-transient. Default is `true`. This is
-_DEPRECATED_. See `auto-create-queues`.
-
-`auto-delete-jms-queues`. Whether or not the broker should automatically
-delete auto-created JMS queues when they have both 0 consumers and 0 messages.
-Default is `true`. This is _DEPRECATED_. See `auto-delete-queues`.
-
-`auto-create-jms-topics`. Whether or not the broker should automatically
-create a JMS topic when a JMS message is sent to a topic whose name fits
-the address `match` (remember, a JMS topic is just a core address which has
-one or more core queues mapped to it) or a JMS consumer tries to subscribe
-to a topic whose name fits the address `match`. Default is `true`. This is
-_DEPRECATED_. See `auto-create-addresses`.
-
-`auto-delete-jms-topics`. Whether or not the broker should automatically
-delete auto-created JMS topics once the last subscription on the topic has
-been closed. Default is `true`. This is _DEPRECATED_. See `auto-delete-addresses`.
-
-`auto-create-queues`. Whether or not the broker should automatically
-create a queue when a message is sent or a consumer tries to connect to a
-queue whose name fits the address `match`. Queues which are auto-created
-are durable, non-temporary, and non-transient. Default is `true`.
-
-`auto-delete-queues`. Whether or not the broker should automatically
-delete auto-created queues when they have both 0 consumers and 0 messages.
-Default is `true`.
-
-`auto-create-addresses`. Whether or not the broker should automatically
-create an address when a message is sent to or a consumer tries to consume
-from a queue which is mapped to an address whose name fits the address `match`.
-Default is `true`.
-
-`auto-delete-addresses`. Whether or not the broker should automatically
-delete auto-created addresses once the address no longer has any queues.
-Default is `true`.