Topology it expects, and what it refuses¶
Source: naming.go, session.go (Publish, sender, durableReceiver, verify, volatileReceiver).
Messages quoted are what the code returns, run against Artemis 2.57.0.
Pattern to address¶
A subscription's Pattern is translated to the broker's wildcard address grammar. A subject you
publish to is its own address.
| Pattern | Address |
|---|---|
> |
# |
a.b.> (a trailing .>) |
a.b.# |
anything else, * included |
unchanged |
Artemis's wildcards: . delimits words, * matches one word, # matches zero or more. The core's
> matches one or more tokens (see Subjects and patterns), so
a.b.# on the broker also matches the address a.b itself. See Limits and
gaps.
Publish¶
Before the first publish to an address in a session, the adapter asks the Management whether
anything receives from it: a queue on the address itself, or a queue on a wildcard address that
matches it. If nothing does, Publish returns ErrUnrouted, because a publish nothing receives is
accepted by the broker and kept by nobody.
The check is once per address per session. A subscriber that appears afterwards is the next session's news; one that disappears is not noticed.
The sender link is opened on first publish and kept. Its target carries the capability topic.
Subscribe, AtLeastOnce¶
The subscription attaches by fully qualified name, address::queue, to a queue the operator made. The
queue name comes from the Topology, which by default returns the subscription's DurableName. The
adapter reads the queue and its address's settings through the Management and refuses unless all of
these hold, checked in this order.
| Requirement | Refusal |
|---|---|
| The queue exists. | ErrNoQueue, wrapped as queue "<queue>" on "<address>". |
| It is durable. | messaging-amqp: queue "<queue>" on "<address>" is not durable; an at-least-once identity must be (auto-create on the address makes a volatile queue of a name that did not exist — turn it off for at-least-once addresses) |
Its routing type is MULTICAST. |
messaging-amqp: queue "<queue>" is <type>; an at-least-once identity is a multicast queue |
| It is on the pattern's address. | messaging-amqp: Pattern "<pattern>": queue "<queue>" is on address "<actual>", not "<expected>"; a subscription's Pattern is its queue's address, and a different one is a different identity (0008 D10) |
The address's max-delivery-attempts is not below MaxDeliver. A negative value is not checked. |
messaging-amqp: MaxDeliver <n> but address "<address>"'s max-delivery-attempts is <m>; the broker would dead-letter before the last attempt |
The address has a dead-letter-address. |
messaging-amqp: address "<address>" has no dead-letter-address; an exhausted message would be dropped silently |
| That dead-letter address has at least one queue. | messaging-amqp: dead-letter address "<dla>" of "<address>" has no queue; a message sent to it is dropped |
The receiver is then attached with the queue name as the link name, unsettled-state durability and a never-expiring expiry policy.
Nothing here creates a durable queue, an address, or a dead-letter address. A changed Pattern on a
reopened DurableName is refused by the address check above. A changed MaxDeliver is accepted while
it stays within the address's budget; the budget is shared by every queue on the address.
On a broker whose address has no dead-letter-address of its own, Artemis may apply a catch-all's.
The adapter reports what the broker reports for that address, so the dead-letter case an operator can
get wrong is a dead-letter address with no queue. The module's test fixture holds an address,
c.#, dead-lettering to a name with no queue to prove that refusal.
Subscribe, AtMostOnce¶
The protocol gives this mode its own topology, so there is nothing to verify.
| Shape | Attaches to | The queue |
|---|---|---|
Fanout |
the address, with a source terminus that has no durability | the broker backs the link with a queue of its own |
Competing |
address::group |
the group's shared queue |
The group's queue is made by the broker, so auto-create must be on for these addresses. The module's test fixture records that such a queue outlives its last member until the broker's auto-delete scan, about sixty seconds.
What the operator needs on the broker¶
For Artemis, the user the adapter connects as needs permission on activemq.management, which it
uses for every check above. The test fixture's broker.xml grants its role manage along with
send, consume, browse and queue and address creation. See Prepare Artemis for
at-least-once.