This is an automated email from the ASF dual-hosted git repository.
gtully pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
The following commit(s) were added to refs/heads/master by this push:
new 90273e6 no jira - give some love to the migration guide
90273e6 is described below
commit 90273e6818d1a1f75c34ddbd1e90b3c1572987df
Author: gtully <[email protected]>
AuthorDate: Thu Jul 23 14:17:33 2020 +0100
no jira - give some love to the migration guide
---
docs/migration-guide/en/README.md | 34 ++--------------------
docs/migration-guide/en/SUMMARY.md | 4 +++
.../en/{README.md => key-differences.md} | 14 ++-------
docs/migration-guide/en/message-store.md | 11 +++++++
docs/migration-guide/en/preface.md | 12 ++++++++
5 files changed, 31 insertions(+), 44 deletions(-)
diff --git a/docs/migration-guide/en/README.md
b/docs/migration-guide/en/README.md
index 8a04fd7..730f8ac 100644
--- a/docs/migration-guide/en/README.md
+++ b/docs/migration-guide/en/README.md
@@ -1,37 +1,7 @@
Apache ActiveMQ Artemis Migration Guide
-=====================================
-
-As more and more people start using Artemis, it's valuable to have a migration
guide that will help experienced ActiveMQ users adapt to the new broker. From
outside, two brokers might seem very similar, but there are subtle differences
in their inner-workings that can lead to confusions. The goal of this guide is
to explain these differences and help make a transition.
-
-Migration is a fairly broad term in systems like these, so what are we talking
about here? This guide will be focused only on broker server migration. We'll
assume that the current system is a working ActiveMQ 5.x broker with OpenWire
JMS clients. We'll see how we can replace the broker with Artemis and leave the
clients intact. This guide will not cover a message store migration. That topic
and aspects of migrating clients that use some other protocol will be the
subject of future guides.
-
-This guide is aimed at experienced ActiveMQ users that want to learn more
about what's different in Artemis. We will assume that you know the concepts
that are covered in these articles. They will not be explained from the first
principles, for that you're advised to see appropriate manuals of the ActiveMQ
and Artemis brokers.
-
-Before we dig into more details on the migration, let's talk about basic
conceptual differences between two brokers.
-
-## Architectural differences
-
-Although they are designed to do the same job, things are done differently
internally. Here are some of the most notable architectural differences you
need to be aware of when you're planning the migration.
-
-In ActiveMQ, we have a few different implementations of the IO connectivity
layer, like tcp (synchronous one) and nio (non-blocking one). In Artemis, the
IO layer is implemented using Netty, which is a nio framework. This means that
there's no more need to choose between different implementations as the
non-blocking one is used by default.
-
-The other important part of every broker is a message store. Most of the
ActiveMQ users are familiar with KahaDB. It consists of a message journal for
fast sequential storing of messages (and other command packets) and an index
for retrieving messages when needed.
-
-Artemis has its own message store. It consists only of the append-only message
journal. Because of the differences in how paging is done, there's no need for
the message index. We'll talk more about that in a minute. It's important to
say at this point that these two stores are not interchangeable, and data
migration if needed must be carefully planed.
-
-What do we mean by paging differences? Paging is the process that happens when
broker can't hold all incoming messages in its memory. The strategy of how to
deal with this situation differs between two brokers. ActiveMQ have *cursors*,
which are basically a cache of messages ready to be dispatched to the consumer.
It will try to keep all incoming messages in there. When we run out of the the
available memory, messages are added to the store, but the caching stops. When
the space become a [...]
-
-In Artemis, things work differently in this regard. The whole message journal
is kept in memory and messages are dispatched directly from it. When we run out
of memory, messages are paged *on the producer side* (before they hit the
broker). Theay are stored in sequential page files in the same order as they
arrived. Once the memory is freed, messages are moved from these page files
into the journal. With paging working like this, messages are read from the
file journal only when the brok [...]
-
-This is one of the main differences between ActiveMQ 5.x and Artemis. It's
important to understand it early on as it affects a lot of destination policy
settings and how we configure brokers in order to support these scenarios
properly.
-
-## Addressing differences
-
-Another big difference that's good to cover early on is the difference is how
message addressing and routing is done. ActiveMQ started as an open source JMS
implementation, so at its core all JMS concepts like queues, topics and durable
subscriptions are implemented as the first-class citizens. It's all based on
OpenWire protocol developed within the project and even KahaDB message store is
OpenWire centric. This means that all other supported protocols, like MQTT and
AMQP are translated [...]
-
-Artemis took a different approach. It implements only queues internally and
all other messaging concepts are achieved by routing messages to appropriate
queue(s) using addresses. Messaging concepts like publish-subscribe (topics)
and point-to-point (queues) are implemented using different type of routing
mechanisms on addresses. *Multicast* routing is used to implement
*publish-subscribe* semantics, where all subscribers to a certain address will
get their own internal queue and messages [...]
-
+=======================================
+The migration guide outlines how users can migrate an existing ActiveMQ 5
broker installation to ActiveMQ Artemis.
diff --git a/docs/migration-guide/en/SUMMARY.md
b/docs/migration-guide/en/SUMMARY.md
index 3c30dd3..e197246 100644
--- a/docs/migration-guide/en/SUMMARY.md
+++ b/docs/migration-guide/en/SUMMARY.md
@@ -1,5 +1,8 @@
# Summary
+* [Introduction](README.md)
+* [Preface](preface.md)
+* [Key Differences](key-differences.md)
* [Configuration](configuration.md)
* [Connectors](connectors.md)
* [Destinations](destinations.md)
@@ -7,4 +10,5 @@
* [Authentication](authentication.md)
* [Authorization](authorization.md)
* [SSL](ssl.md)
+* [Message Store](message-store.md)
* [Legal Notice](notice.md)
diff --git a/docs/migration-guide/en/README.md
b/docs/migration-guide/en/key-differences.md
similarity index 75%
copy from docs/migration-guide/en/README.md
copy to docs/migration-guide/en/key-differences.md
index 8a04fd7..e3a6bb5 100644
--- a/docs/migration-guide/en/README.md
+++ b/docs/migration-guide/en/key-differences.md
@@ -1,15 +1,5 @@
-
-
-Apache ActiveMQ Artemis Migration Guide
-=====================================
-
-As more and more people start using Artemis, it's valuable to have a migration
guide that will help experienced ActiveMQ users adapt to the new broker. From
outside, two brokers might seem very similar, but there are subtle differences
in their inner-workings that can lead to confusions. The goal of this guide is
to explain these differences and help make a transition.
-
-Migration is a fairly broad term in systems like these, so what are we talking
about here? This guide will be focused only on broker server migration. We'll
assume that the current system is a working ActiveMQ 5.x broker with OpenWire
JMS clients. We'll see how we can replace the broker with Artemis and leave the
clients intact. This guide will not cover a message store migration. That topic
and aspects of migrating clients that use some other protocol will be the
subject of future guides.
-
-This guide is aimed at experienced ActiveMQ users that want to learn more
about what's different in Artemis. We will assume that you know the concepts
that are covered in these articles. They will not be explained from the first
principles, for that you're advised to see appropriate manuals of the ActiveMQ
and Artemis brokers.
-
-Before we dig into more details on the migration, let's talk about basic
conceptual differences between two brokers.
+Differences From ActiveMQ 5
+===========================
## Architectural differences
diff --git a/docs/migration-guide/en/message-store.md
b/docs/migration-guide/en/message-store.md
new file mode 100644
index 0000000..3b314c8
--- /dev/null
+++ b/docs/migration-guide/en/message-store.md
@@ -0,0 +1,11 @@
+#Message Store Migration
+
+## ActiveMQ 5 KahaDB or mKahaDB
+
+ActiveMQ Artemis supports an XML format for message store exchange. An
existing store may be exported from a broker using the command line tools and
subsequently imported to another broker.
+
+The [Apache ActiveMQ Command Line
Tools](https://github.com/apache/activemq-cli-tools) project provides an
command line export tool for ActiveMQ 5.x that will export a KahaDB (or
mKahaDB) message store into the ActiveMQ Artemis XML format, for subsequent
import by ActiveMQ Artemis.
+
+The export tool supports selective export using filters, useful if only some
of your data needs to be migrated. From version 0.2.0, the export tool has
support for virtual topic consumer queue mapping, which will allow existing
Openwire virtual topic consumers to resume on an ActiveMQ Artemis broker with
no message loss. Note the OpenWire acceptor `virtualTopicConsumerWildcards`
option from [virtual topics migration](VirtualTopics.md).
+
+Full details of tool can be found on the project website:
https://github.com/apache/activemq-cli-tools
diff --git a/docs/migration-guide/en/preface.md
b/docs/migration-guide/en/preface.md
new file mode 100644
index 0000000..6c5e48c
--- /dev/null
+++ b/docs/migration-guide/en/preface.md
@@ -0,0 +1,12 @@
+Preface
+=======
+
+As more and more people start using Artemis, it's valuable to have a migration
guide that will help experienced ActiveMQ users adapt to the new broker. From
outside, two brokers might seem very similar, but there are subtle differences
in their inner-workings that can lead to confusions. The goal of this guide is
to explain these differences and help make a transition.
+
+Migration is a fairly broad term in systems like these, so what are we talking
about here? This guide will be focused only on broker server migration. We'll
assume that the current system is a working ActiveMQ 5.x broker with OpenWire
JMS clients. We'll see how we can replace the broker with Artemis and leave the
clients intact.
+
+This guide is aimed at experienced ActiveMQ users that want to learn more
about what's different in Artemis. We will assume that you know the concepts
that are covered in these articles. They will not be explained from the first
principles, for that you're advised to see appropriate manuals of the ActiveMQ
and Artemis brokers.
+
+Before we dig into more details on the migration, let's talk about basic
conceptual differences between two brokers.
+
+
