docs/user-manual/wildcard-syntax.adoc

= Wildcard Syntax
:idprefix:
:idseparator: -
:docinfo: shared

{project-name-full} uses a specific syntax for representing wildcards in security settings, address settings, and when creating consumers.

The syntax is similar to that used by https://www.amqp.org[AMQP].

An wildcard expression contains *words separated by a delimiter*.
The default delimiter is `.` (full stop).

The special characters `#` and `*` also have special meaning and can take the place of a **word**.

To be clear, the wildcard characters cannot be used like wildcards in a https://en.wikipedia.org/wiki/Regular_expression[regular expression].
They operate exclusively on *words separated by a delimiter*.

== Matching Any Word

The character `#` means "match any sequence of zero or more words".

So the wildcard `news.europe.#` would match:

* `news.europe`
* `news.europe.sport`
* `news.europe.politics`
* `news.europe.politics.regional`

But `news.europe.#` would _not_ match:

* `news.usa`
* `news.usa.sport`
* `entertainment`

== Matching a Single Word

The character `*` means "match a single word".

The wildcard `news.*` would match:

* `news.europe`
* `news.usa`

But `news.*` would _not_ match:

* `news.europe.sport`
* `news.usa.sport`
* `news.europe.politics.regional`

The wildcard `news.*.sport` would match:

* `news.europe.sport`
* `news.usa.sport`

But `news.*.sport` would _not_ match:

* `news.europe.politics`

== Customizing the Syntax

It's possible to further configure the syntax of the wildcard addresses using the broker configuration.
For that, the `<wildcard-addresses>` configuration tag is used.

[,xml]
----
<wildcard-addresses>
   <routing-enabled>true</routing-enabled>
   <delimiter>.</delimiter>
   <any-words>#</any-words>
   <single-word>*</single-word>
</wildcard-addresses>
----

The example above shows the default configuration.

[NOTE]
====
It is technically _possible_ to use `$` as a custom wildcard character, but it is **not recommended** for three main reasons:

. The default value of `internal-naming-prefix` is `$.activemq.internal.` which includes a `$` character.
While this value can be changed, doing so may cause problems if, for example, you have already created a cluster while the default value was in use.
In this case the broker will have already created store-and-forward resources that will have to be renamed manually.
Similar problems exist with retroactive addresses.
. AMQP federation and mirroring use `$` in the names of their internal resources.
. The MQTT protocol uses `$` for certain bits of functionality (e.g. shared subscriptions) and this cannot be changed so MQTT functionality would need to be completely avoided.
====