ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
= Protocols and Interoperability
:idprefix:
:idseparator: -
Apache ActiveMQ Artemis has a powerful & flexible core which provides a foundation upon which other protocols can be implemented.
Each protocol implementation translates the ideas of its specific protocol onto this core.
The broker ships with a client implementation which interacts directly with this core.
It uses what's called the xref:core.adoc#using-core["core" API], and it communicates over the network using the "core" protocol.
== Supported Protocols
The broker has a pluggable protocol architecture.
Protocol plugins come in the form of protocol modules.
Each protocol module is included on the broker's class path and loaded by the broker at boot time.
The broker ships with 5 protocol modules out of the box.
=== AMQP
https://en.wikipedia.org/wiki/AMQP[AMQP] is a specification for interoperable messaging.
It also defines a wire format, so any AMQP client can work with any messaging system that supports AMQP.
AMQP clients are available in many different programming languages.
Apache ActiveMQ Artemis implements the https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp[AMQP 1.0] specification.
Any client that supports the 1.0 specification will be able to interact with Apache ActiveMQ Artemis.
Please see xref:amqp.adoc#amqp[AMQP] for more details.
=== MQTT
https://mqtt.org/[MQTT] is a lightweight connectivity protocol.
It is designed to run in environments where device and networks are constrained.
Any client that supports the 3.1, 3.1.1, or 5 specification will be able to interact with Apache ActiveMQ Artemis.
Please see xref:mqtt.adoc#mqtt[MQTT] for more details.
=== STOMP
https://stomp.github.io/[Stomp] 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.
Any client that supports the 1.0, 1.1, or 1.2 specification will be able to interact with Apache ActiveMQ Artemis.
Please see xref:stomp.adoc#stomp[Stomp] for more details.
=== OpenWire
ActiveMQ Classic defines its own wire protocol: OpenWire.
2024-10-24 11:49:05 -04:00
In order to support ActiveMQ Classic clients, Apache ActiveMQ Artemis supports OpenWire.
2024-10-24 12:09:59 -04:00
Any application using the OpenWire JMS client library shipped with ActiveMQ 5.12.x or higher can be used with Apache ActiveMQ Artemis.
ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
Please see xref:openwire.adoc#openwire[OpenWire] for more details.
=== Core
2024-10-24 12:09:59 -04:00
ActiveMQ Artemis defines its own wire protocol: Core.
ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
Please see xref:core.adoc#using-core[Core] for more details.
==== APIs and Other Interfaces
Although JMS and Jakarta Messaging are standardized APIs, they do not define a network protocol.
The ActiveMQ Artemis xref:using-jms.adoc#using-jms-or-jakarta-messaging[JMS & Jakarta Messaging clients] are implemented on top of the core protocol.
We also provide a xref:using-jms.adoc#jndi[client-side JNDI implementation].
== Configuring Acceptors
In order to make use of a particular protocol, a transport must be configured with the desired protocol enabled.
There is a whole section on configuring transports that can be found xref:configuring-transports.adoc#configuring-the-transport[here].
The default configuration shipped with the ActiveMQ Artemis distribution comes with a number of acceptors already defined, one for each of the above protocols plus a generic acceptor that supports all protocols.
To enable protocols on a particular acceptor simply add the `protocols` url parameter to the acceptor url where the value is one or more protocols (separated by commas).
If the `protocols` parameter is omitted from the url *all* protocols are enabled.
* The following example enables only MQTT on port 1883
+
[,xml]
----
<acceptors>
<acceptor>tcp://localhost:1883?protocols=MQTT</acceptor>
</acceptors>
----
* The following example enables MQTT and AMQP on port 5672
+
[,xml]
----
<acceptors>
<acceptor>tcp://localhost:5672?protocols=MQTT,AMQP</acceptor>
</acceptors>
----
* The following example enables *all* protocols on `61616`:
+
[,xml]
----
<acceptors>
<acceptor>tcp://localhost:61616</acceptor>
</acceptors>
----
Here are the supported protocols and their corresponding value used in the `protocols` url parameter.
|===
| Protocol | `protocols` value
| Core (Artemis & HornetQ native) | `CORE`
2024-10-24 11:49:05 -04:00
| OpenWire (Classic native) | `OPENWIRE`
ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
| AMQP | `AMQP`
| MQTT | `MQTT`
| STOMP | `STOMP`
|===
