This is an automated email from the ASF dual-hosted git repository.
jbertram pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
The following commit(s) were added to refs/heads/main by this push:
new b2486db000 NO-JIRA clarify docs around queue auto-creation
b2486db000 is described below
commit b2486db000897287c7081d1dd7562bc017deb4c5
Author: Justin Bertram <[email protected]>
AuthorDate: Fri May 3 11:47:32 2024 -0500
NO-JIRA clarify docs around queue auto-creation
---
docs/user-manual/_auto-queue-creation-note.adoc | 3 +++
docs/user-manual/address-model.adoc | 2 ++
docs/user-manual/address-settings.adoc | 4 +++-
docs/user-manual/jms-core-mapping.adoc | 26 ++++++++++++++++++-------
4 files changed, 27 insertions(+), 8 deletions(-)
diff --git a/docs/user-manual/_auto-queue-creation-note.adoc
b/docs/user-manual/_auto-queue-creation-note.adoc
new file mode 100644
index 0000000000..9d05d33c9a
--- /dev/null
+++ b/docs/user-manual/_auto-queue-creation-note.adoc
@@ -0,0 +1,3 @@
+NOTE: Automatic queue creation is for queues that _would not otherwise be
created during normal operation_.
+For example, when a remote application creates a consumer on a JMS topic then
a queue will be created representing that subscription as described in the
xref:jms-core-mapping.adoc[JMS-to-core mapping chapter].
+This queue will be created regardless of how `auto-create-queues` is
configured because it is required for _normal operation_.
\ No newline at end of file
diff --git a/docs/user-manual/address-model.adoc
b/docs/user-manual/address-model.adoc
index 6a50770311..92f6a3b02b 100644
--- a/docs/user-manual/address-model.adoc
+++ b/docs/user-manual/address-model.adoc
@@ -62,6 +62,8 @@ Automatic creation and deletion is configured on a per
address basis and is cont
* `auto-delete-queues`
* `default-queue-routing-type`
+include::_auto-queue-creation-note.adoc[]
+
See xref:address-settings.adoc#address-settings[the documentation on address
settings] for more details on these elements.
Of course, automatic configuration can be disabled and everything can be
configured manually.
diff --git a/docs/user-manual/address-settings.adoc
b/docs/user-manual/address-settings.adoc
index b810e519f6..3455d7bead 100644
--- a/docs/user-manual/address-settings.adoc
+++ b/docs/user-manual/address-settings.adoc
@@ -247,9 +247,11 @@ Whether or not the broker should automatically create a
queue when a message is
Queues which are auto-created are durable, non-temporary, and non-transient.
Default is `true`.
+
-NOTE: automatic queue creation does _not_ work for the core client.
+NOTE: Automatic queue creation does _not_ work for the core client.
The core API is a low-level API and is not meant to have such automation.
+include::_auto-queue-creation-note.adoc[]
+
auto-delete-queues::
Whether or not the broker should automatically delete auto-created queues when
they have both 0 consumers and the message count is less than or equal to
`auto-delete-queues-message-count`.
Default is `true`.
diff --git a/docs/user-manual/jms-core-mapping.adoc
b/docs/user-manual/jms-core-mapping.adoc
index 93442632aa..3d29681c17 100644
--- a/docs/user-manual/jms-core-mapping.adoc
+++ b/docs/user-manual/jms-core-mapping.adoc
@@ -2,13 +2,25 @@
:idprefix:
:idseparator: -
-This chapter describes how JMS destinations are mapped to Apache ActiveMQ
Artemis addresses.
+This chapter describes how JMS destinations are mapped to the Apache ActiveMQ
Artemis address model.
+If you haven't already done so, please read about the
xref:address-model.adoc[address model] as it introduces concepts which are
referenced here.
-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 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.
+== JMS Topic
-Likewise, a JMS queue is implemented as an address with name=(the JMS queue
name) with an ANYCAST routing type associated with it.
+A JMS topic is implemented as a xref:address-model.adoc#address[*address*]
where the name of the address is the same as the name of the JMS topic.
-NOTE: While 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.
+A subscription on that JMS topic is represented as a
xref:address-model.adoc#multicast[*multicast*]
xref:address-model.adoc#queue[*queue*] on the corresponding address. The queue
is named according to the whether the subscription is durable and according to
the client ID and subscription named provided via the JMS API.
+
+Typically there is just one consumer per queue, but there can be multiple
consumers on a queue when using JMS shared topic subscriptions.
+Any messages sent to the JMS topic is therefore routed to every multicast
queue bound to the corresponding address and then dispatched to any consumers
on those queues (i.e. JMS topic subscriber).
+If there are no queues on the address then the message is simply dropped.
+
+This effectively achieves JMS pub/sub semantics.
+
+== JMS Queue
+
+Likewise, a JMS queue is implemented as an
xref:address-model.adoc#address[*address*] where the name of the address is the
same as the name of the JMS queue.
+
+However, there will be just one xref:address-model.adoc#anycast[*anycast*]
xref:address-model.adoc#queue[*queue*] on the corresponding address. All JMS
consumers on this queue will _share_ the messages in the queue. The queue is
named the same as the address.
+
+This effectively achieves JMS point-to-point semantics.
