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

NO-JIRA Fix up user manual

This commit is contained in:
Martyn Taylor 2017-03-09 16:59:09 +00:00
parent c971476a88
commit 24a045e266
11 changed files with 186 additions and 315 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/user-manual/en/architecture.md
View File

@ -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:
![ActiveMQ Artemis architecture3](images/architecture3.jpg)
For more information on server configuration files see [Server Configuration](configuration-index.md)
## Apache ActiveMQ Artemis embedded in your own application
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.
![ActiveMQ Artemis architecture2](images/architecture2.jpg)
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:
![ActiveMQ Artemis architecture3](images/architecture3.jpg)
For more information on server configuration files see [Server Configuration](configuration-index.md)

2
docs/user-manual/en/client-reconnection.md
View File

@ -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

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

@ -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

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

@ -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

37
docs/user-manual/en/jms-core-mapping.md
View File

@ -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.

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

@ -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

58
docs/user-manual/en/management.md
View File

@ -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

32
docs/user-manual/en/messaging-concepts.md
View File

@ -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

5
docs/user-manual/en/perf-tuning.md
View File

@ -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

197
docs/user-manual/en/rest.md
View File

@ -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

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

@ -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.