activemq-artemis/docs/user-manual/openwire.adoc

112 lines
6.1 KiB
Plaintext
Raw Normal View History

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
= OpenWire
:idprefix:
:idseparator: -
Apache ActiveMQ Artemis supports the http://activemq.apache.org/openwire.html[OpenWire] protocol so that an Apache ActiveMQ "Classic" JMS client can talk directly to an Apache ActiveMQ Artemis server.
By default there is an `acceptor` configured to accept OpenWire connections on port `61616`.
See the general xref:protocols-interoperability.adoc#protocols-and-interoperability[Protocols and Interoperability] chapter for details on configuring an `acceptor` for OpenWire.
Refer to the OpenWire examples for a look at this functionality in action.
== Connection Monitoring
OpenWire has a few parameters to control how each connection is monitored, they are:
maxInactivityDuration::
It specifies the time (milliseconds) after which the connection is closed by the broker if no data was received.
Default value is 30000.
maxInactivityDurationInitalDelay::
It specifies the maximum delay (milliseconds) before inactivity monitoring is started on the connection.
It can be useful if a broker is under load with many connections being created concurrently.
Default value is 10000.
useInactivityMonitor::
A value of false disables the InactivityMonitor completely and connections will never time out.
By default it is enabled.
On broker side you don't neet set this.
Instead you can set the connection-ttl to -1.
useKeepAlive::
Indicates whether to send a KeepAliveInfo on an idle connection to prevent it from timing out.
Enabled by default.
Disabling the keep alive will still make connections time out if no data was received on the connection for the specified amount of time.
Note at the beginning the InactivityMonitor negotiates the appropriate `maxInactivityDuration` and `maxInactivityDurationInitalDelay`.
The shortest duration is taken for the connection.
Fore more details please see http://activemq.apache.org/activemq-inactivitymonitor.html[ActiveMQ InactivityMonitor].
== Disable/Enable Advisories
By default, advisory topics (http://activemq.apache.org/advisory-message.html[ActiveMQ Advisory]) are created in order to send certain type of advisory messages to listening clients.
As a result, advisory addresses and queues will be displayed on the management console, along with user deployed addresses and queues.
This sometimes cause confusion because the advisory objects are internally managed without user being aware of them.
In addition, users may not want the advisory topics at all (they cause extra resources and performance penalty) and it is convenient to disable them at all from the broker side.
The protocol provides two parameters to control advisory behaviors on the broker side.
supportAdvisory::
Indicates whether the broker supports advisory messages.
If the value is true, advisory addresses/queues will be created.
If the value is false, no advisory addresses/queues are created.
Default value is `true`.
suppressInternalManagementObjects::
Indicates whether advisory addresses/queues, if any, will be registered to management service (e.g. JMX registry).
If set to true, no advisory addresses/queues will be registered.
If set to false, those are registered and will be displayed on the management console.
Default value is `true`.
The two parameters are configured on an OpenWire `acceptor`, e.g.:
[,xml]
----
<acceptor name="artemis">tcp://localhost:61616?protocols=OPENWIRE;supportAdvisory=true;suppressInternalManagementObjects=false</acceptor>
----
== OpenWire Destination Cache
For improved performance of the broker we keep a cache of recently used destinations, so that when new messages are dispatched to them, we do not have to do a lookup every time.
By default, this cache holds up to `16` destinations.
If additional destinations are added they will overwrite older records.
If you are dealing with a large amount of queues you might want to increase this value, which is done via configuration option: `openWireDestinationCacheSize` set on the OpenWire `acceptor` like this:
[,xml]
----
<acceptor name="artemis">tcp://localhost:61616?protocols=OPENWIRE;openWireDestinationCacheSize=64</acceptor>
----
This cache has to be set to a power of 2, i.e.: `2`, `16`, `128` and so on.
== Virtual Topic Consumer Destination Translation
For existing OpenWire consumers of virtual topic destinations it is possible to configure a mapping function that will translate the virtual topic consumer destination into a FQQN address.
This address will then represents the consumer as a multicast binding to an address representing the virtual topic.
The configuration string list property `virtualTopicConsumerWildcards` has parts separated by a `;`.
The first is the classic style destination filter that identifies the destination as belonging to a virtual topic.
The second identifies the number of `paths` that identify the consumer queue such that it can be parsed from the destination.
Any subsequent parts are additional configuration parameters for that mapping.
For example, the default virtual topic with consumer prefix of `Consumer.*.`, would require a `virtualTopicConsumerWildcards` filter of `Consumer.*.>;2`.
As a url parameter this transforms to `Consumer.*.%3E%3B2` when the url significant characters `>;` are escaped with their hex code points.
In an `acceptor` url it would be:
[,xml]
----
<acceptor name="artemis">tcp://localhost:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2</acceptor>
----
This will translate `Consumer.A.VirtualTopic.Orders` into a FQQN of `VirtualTopic.Orders::Consumer.A.VirtualTopic.Orders` using the int component `2` of the configuration to identify the consumer queue as the first two paths of the destination.
`virtualTopicConsumerWildcards` is multi valued using a `,` separator.
=== selectorAware
The mappings support an optional parameter, `selectorAware` which when true, transfers any selector information from the OpenWire consumer into a queue filter of any auto-created subscription queue.
NOTE: the selector/filter is persisted with the queue binding in the normal way, such that it works independent of connected consumers.
Please see Virtual Topic Mapping example contained in the OpenWire xref:examples.adoc#examples[examples].