mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-07 02:29:08 +00:00
3a4b421d2e
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
114 lines
4.1 KiB
Plaintext
114 lines
4.1 KiB
Plaintext
= Embedding Apache ActiveMQ Artemis
|
|
:idprefix:
|
|
:idseparator: -
|
|
|
|
Apache ActiveMQ Artemis is designed as set of simple Plain Old Java Objects (POJOs).
|
|
This means Apache ActiveMQ Artemis can be instantiated and run in any dependency injection framework such as Spring or Google Guice.
|
|
It also means that if you have an application that could use messaging functionality internally then it can _directly instantiate_ Apache ActiveMQ Artemis clients and servers in its own application code to perform that functionality.
|
|
We call this _embedding_ Apache ActiveMQ Artemis.
|
|
|
|
Examples of applications that might want to do this include any application that needs very high performance, transactional, persistent messaging but doesn't want the hassle of writing it all from scratch.
|
|
|
|
Embedding Apache ActiveMQ Artemis can be done in very few easy steps - supply a `broker.xml` on the classpath or instantiate the configuration object, instantiate the server, start it, and you have a Apache ActiveMQ Artemis running in your JVM.
|
|
It's as simple and easy as that.
|
|
|
|
== Embedding with XML configuration
|
|
|
|
The simplest way to embed Apache ActiveMQ Artemis is to use the embedded wrapper class and configure Apache ActiveMQ Artemis through `broker.xml`.
|
|
|
|
Here's a simple example `broker.xml`:
|
|
|
|
[,xml]
|
|
----
|
|
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:activemq" xsi:schemaLocation="urn:activemq /schema/artemis-server.xsd">
|
|
<core xmlns="urn:activemq:core">
|
|
|
|
<persistence-enabled>false</persistence-enabled>
|
|
|
|
<security-enabled>false</security-enabled>
|
|
|
|
<acceptors>
|
|
<acceptor name="in-vm">vm://0</acceptor>
|
|
</acceptors>
|
|
</core>
|
|
</configuration>
|
|
----
|
|
|
|
[,java]
|
|
----
|
|
import org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
|
|
|
|
...
|
|
|
|
EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
|
|
embedded.start();
|
|
|
|
ServerLocator serverLocator = ActiveMQClient.createServerLocator("vm://0");
|
|
ClientSessionFactory factory = serverLocator.createSessionFactory();
|
|
ClientSession session = factory.createSession();
|
|
|
|
session.createQueue(new QueueConfiguration("example"));
|
|
|
|
ClientProducer producer = session.createProducer("example");
|
|
ClientMessage message = session.createMessage(true);
|
|
message.getBody().writeString("Hello");
|
|
producer.send(message);
|
|
|
|
session.start();
|
|
ClientConsumer consumer = session.createConsumer("example");
|
|
ClientMessage msgReceived = consumer.receive();
|
|
System.out.println("message = " + msgReceived.getBody().readString());
|
|
session.close();
|
|
----
|
|
|
|
The `EmbeddedActiveMQ` class has a few additional setter methods that allow you to specify a different config file name as well as other properties.
|
|
See the javadocs for this class for more details.
|
|
|
|
== Embedding with programmatic configuration
|
|
|
|
You can follow this step-by-step guide to programmatically embed a broker instance.
|
|
|
|
Create the `Configuration` object.
|
|
This contains configuration information for an Apache ActiveMQ Artemis instance.
|
|
The setter methods of this class allow you to programmatically set configuration options as described in the xref:configuration-index.adoc#configuration-reference[Server Configuration] section.
|
|
|
|
The acceptors are configured through `Configuration`.
|
|
Just add the acceptor URL the same way you would through the main configuration file.
|
|
|
|
[,java]
|
|
----
|
|
import org.apache.activemq.artemis.core.config.Configuration;
|
|
import org.apache.activemq.artemis.core.config.impl.ConfigurationImpl;
|
|
|
|
...
|
|
|
|
Configuration config = new ConfigurationImpl();
|
|
|
|
config.addAcceptorConfiguration("in-vm", "vm://0");
|
|
config.addAcceptorConfiguration("tcp", "tcp://127.0.0.1:61616");
|
|
----
|
|
|
|
You need to instantiate an instance of `org.apache.activemq.artemis.api.core.server.embedded.EmbeddedActiveMQ` and add the configuration object to it.
|
|
|
|
[,java]
|
|
----
|
|
import org.apache.activemq.artemis.api.core.server.ActiveMQ;
|
|
import org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
|
|
|
|
...
|
|
|
|
EmbeddedActiveMQ server = new EmbeddedActiveMQ();
|
|
server.setConfiguration(config);
|
|
|
|
server.start();
|
|
----
|
|
|
|
You also have the option of instantiating `ActiveMQServerImpl` directly:
|
|
|
|
[,java]
|
|
----
|
|
ActiveMQServer server = new ActiveMQServerImpl(config);
|
|
server.start();
|
|
----
|
|
|