blob: 405f4aac0adf836a530e145dba3b1209ee47edd8 [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="" >
<head>
<title>Embedding Apache ActiveMQ Artemis ยท ActiveMQ Artemis Documentation</title>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="generator" content="GitBook 3.1.1">
<link rel="stylesheet" href="gitbook/style.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="karaf.html" />
<link rel="prev" href="rest.html" />
</head>
<body>
<div class="book">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" data-path="./">
<a href="./">
Introduction
</a>
</li>
<li class="chapter " data-level="1.2" data-path="notice.html">
<a href="notice.html">
Legal Notice
</a>
</li>
<li class="chapter " data-level="1.3" data-path="preface.html">
<a href="preface.html">
Preface
</a>
</li>
<li class="chapter " data-level="1.4" data-path="project-info.html">
<a href="project-info.html">
Project Info
</a>
</li>
<li class="chapter " data-level="1.5" data-path="messaging-concepts.html">
<a href="messaging-concepts.html">
Messaging Concepts
</a>
</li>
<li class="chapter " data-level="1.6" data-path="architecture.html">
<a href="architecture.html">
Architecture
</a>
</li>
<li class="chapter " data-level="1.7" data-path="using-server.html">
<a href="using-server.html">
Using the Server
</a>
</li>
<li class="chapter " data-level="1.8" data-path="using-jms.html">
<a href="using-jms.html">
Using JMS
</a>
</li>
<li class="chapter " data-level="1.9" data-path="using-core.html">
<a href="using-core.html">
Using Core
</a>
</li>
<li class="chapter " data-level="1.10" data-path="jms-core-mapping.html">
<a href="jms-core-mapping.html">
Mapping JMS Concepts to the Core API
</a>
</li>
<li class="chapter " data-level="1.11" data-path="client-classpath.html">
<a href="client-classpath.html">
The Client Classpath
</a>
</li>
<li class="chapter " data-level="1.12" data-path="examples.html">
<a href="examples.html">
Examples
</a>
</li>
<li class="chapter " data-level="1.13" data-path="wildcard-routing.html">
<a href="wildcard-routing.html">
Routing Messages With Wild Cards
</a>
</li>
<li class="chapter " data-level="1.14" data-path="wildcard-syntax.html">
<a href="wildcard-syntax.html">
Understanding the Apache ActiveMQ Artemis Wildcard Syntax
</a>
</li>
<li class="chapter " data-level="1.15" data-path="filter-expressions.html">
<a href="filter-expressions.html">
Filter Expressions
</a>
</li>
<li class="chapter " data-level="1.16" data-path="persistence.html">
<a href="persistence.html">
Persistence
</a>
</li>
<li class="chapter " data-level="1.17" data-path="configuring-transports.html">
<a href="configuring-transports.html">
Configuring Transports
</a>
</li>
<li class="chapter " data-level="1.18" data-path="config-reload.html">
<a href="config-reload.html">
Configuration Reload
</a>
</li>
<li class="chapter " data-level="1.19" data-path="connection-ttl.html">
<a href="connection-ttl.html">
Detecting Dead Connections
</a>
</li>
<li class="chapter " data-level="1.20" data-path="slow-consumers.html">
<a href="slow-consumers.html">
Detecting Slow Consumers
</a>
</li>
<li class="chapter " data-level="1.21" data-path="network-isolation.html">
<a href="network-isolation.html">
Avoiding Network Isolation
</a>
</li>
<li class="chapter " data-level="1.22" data-path="transaction-config.html">
<a href="transaction-config.html">
Resource Manager Configuration
</a>
</li>
<li class="chapter " data-level="1.23" data-path="flow-control.html">
<a href="flow-control.html">
Flow Control
</a>
</li>
<li class="chapter " data-level="1.24" data-path="send-guarantees.html">
<a href="send-guarantees.html">
Guarantees of sends and commits
</a>
</li>
<li class="chapter " data-level="1.25" data-path="undelivered-messages.html">
<a href="undelivered-messages.html">
Message Redelivery and Undelivered Messages
</a>
</li>
<li class="chapter " data-level="1.26" data-path="message-expiry.html">
<a href="message-expiry.html">
Message Expiry
</a>
</li>
<li class="chapter " data-level="1.27" data-path="large-messages.html">
<a href="large-messages.html">
Large Messages
</a>
</li>
<li class="chapter " data-level="1.28" data-path="paging.html">
<a href="paging.html">
Paging
</a>
</li>
<li class="chapter " data-level="1.29" data-path="queue-attributes.html">
<a href="queue-attributes.html">
Queue Attributes
</a>
</li>
<li class="chapter " data-level="1.30" data-path="scheduled-messages.html">
<a href="scheduled-messages.html">
Scheduled Messages
</a>
</li>
<li class="chapter " data-level="1.31" data-path="last-value-queues.html">
<a href="last-value-queues.html">
Last-Value Queues
</a>
</li>
<li class="chapter " data-level="1.32" data-path="message-grouping.html">
<a href="message-grouping.html">
Message Grouping
</a>
</li>
<li class="chapter " data-level="1.33" data-path="pre-acknowledge.html">
<a href="pre-acknowledge.html">
Extra Acknowledge Modes
</a>
</li>
<li class="chapter " data-level="1.34" data-path="management.html">
<a href="management.html">
Management
</a>
</li>
<li class="chapter " data-level="1.35" data-path="security.html">
<a href="security.html">
Security
</a>
</li>
<li class="chapter " data-level="1.36" data-path="resource-limits.html">
<a href="resource-limits.html">
Resource Limits
</a>
</li>
<li class="chapter " data-level="1.37" data-path="jms-bridge.html">
<a href="jms-bridge.html">
The JMS Bridge
</a>
</li>
<li class="chapter " data-level="1.38" data-path="client-reconnection.html">
<a href="client-reconnection.html">
Client Reconnection and Session Reattachment
</a>
</li>
<li class="chapter " data-level="1.39" data-path="diverts.html">
<a href="diverts.html">
Diverting and Splitting Message Flows
</a>
</li>
<li class="chapter " data-level="1.40" data-path="core-bridges.html">
<a href="core-bridges.html">
Core Bridges
</a>
</li>
<li class="chapter " data-level="1.41" data-path="duplicate-detection.html">
<a href="duplicate-detection.html">
Duplicate Message Detection
</a>
</li>
<li class="chapter " data-level="1.42" data-path="clusters.html">
<a href="clusters.html">
Clusters
</a>
</li>
<li class="chapter " data-level="1.43" data-path="ha.html">
<a href="ha.html">
High Availability and Failover
</a>
</li>
<li class="chapter " data-level="1.44" data-path="graceful-shutdown.html">
<a href="graceful-shutdown.html">
Graceful Server Shutdown
</a>
</li>
<li class="chapter " data-level="1.45" data-path="libaio.html">
<a href="libaio.html">
Libaio Native Libraries
</a>
</li>
<li class="chapter " data-level="1.46" data-path="thread-pooling.html">
<a href="thread-pooling.html">
Thread management
</a>
</li>
<li class="chapter " data-level="1.47" data-path="logging.html">
<a href="logging.html">
Logging
</a>
</li>
<li class="chapter " data-level="1.48" data-path="rest.html">
<a href="rest.html">
REST Interface
</a>
</li>
<li class="chapter active" data-level="1.49" data-path="embedding-activemq.html">
<a href="embedding-activemq.html">
Embedding Apache ActiveMQ Artemis
</a>
</li>
<li class="chapter " data-level="1.50" data-path="karaf.html">
<a href="karaf.html">
Apache Karaf
</a>
</li>
<li class="chapter " data-level="1.51" data-path="spring-integration.html">
<a href="spring-integration.html">
Spring Integration
</a>
</li>
<li class="chapter " data-level="1.52" data-path="aerogear-integration.html">
<a href="aerogear-integration.html">
AeroGear Integration
</a>
</li>
<li class="chapter " data-level="1.53" data-path="vertx-integration.html">
<a href="vertx-integration.html">
VertX Integration
</a>
</li>
<li class="chapter " data-level="1.54" data-path="cdi-integration.html">
<a href="cdi-integration.html">
CDI Integration
</a>
</li>
<li class="chapter " data-level="1.55" data-path="intercepting-operations.html">
<a href="intercepting-operations.html">
Intercepting Operations
</a>
</li>
<li class="chapter " data-level="1.56" data-path="protocols-interoperability.html">
<a href="protocols-interoperability.html">
Protocols and Interoperability
</a>
</li>
<li class="chapter " data-level="1.57" data-path="tools.html">
<a href="tools.html">
Tools
</a>
</li>
<li class="chapter " data-level="1.58" data-path="maven-plugin.html">
<a href="maven-plugin.html">
Maven Plugin
</a>
</li>
<li class="chapter " data-level="1.59" data-path="unit-testing.html">
<a href="unit-testing.html">
Unit Testing
</a>
</li>
<li class="chapter " data-level="1.60" data-path="perf-tuning.html">
<a href="perf-tuning.html">
Troubleshooting and Performance Tuning
</a>
</li>
<li class="chapter " data-level="1.61" data-path="configuration-index.html">
<a href="configuration-index.html">
Configuration Reference
</a>
</li>
<li class="divider"></li>
<li>
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
Published with GitBook
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href="." >Embedding Apache ActiveMQ Artemis</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="embedding-apache-activemq-artemis">Embedding Apache ActiveMQ Artemis</h1>
<p>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 <em>directly instantiate</em>
Apache ActiveMQ Artemis clients and servers in its own application code to perform that
functionality. We call this <em>embedding</em> Apache ActiveMQ Artemis.</p>
<p>Examples of applications that might want to do this include any
application that needs very high performance, transactional, persistent
messaging but doesn&apos;t want the hassle of writing it all from scratch.</p>
<p>Embedding Apache ActiveMQ Artemis can be done in very few easy steps. Instantiate the
configuration object, instantiate the server, start it, and you have a
Apache ActiveMQ Artemis running in your virtual machine. It&apos;s as simple and easy as
that.</p>
<h2 id="simple-config-file-embedding">Simple Config File Embedding</h2>
<p>The simplest way to embed Apache ActiveMQ Artemis is to use the embedded wrapper
classes and configure Apache ActiveMQ Artemis through its configuration files. There
are two different helper classes for this depending on whether your
using the Apache ActiveMQ Artemis Core API or JMS.</p>
<h2 id="core-api-only">Core API Only</h2>
<p>For instantiating a core Apache ActiveMQ Artemis Server only, the steps are pretty
simple. The example requires that you have defined a configuration file
<code>broker.xml</code> in your classpath:</p>
<pre><code class="lang-java"><span class="hljs-keyword">import</span> org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
...
EmbeddedActiveMQ embedded = <span class="hljs-keyword">new</span> EmbeddedActiveMQ();
embedded.start();
ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
<span class="hljs-keyword">new</span> TransportConfiguration(
InVMConnectorFactory.class.getName()));
ClientSession session = factory.createSession();
session.createQueue(<span class="hljs-string">&quot;example&quot;</span>, <span class="hljs-string">&quot;example&quot;</span>, <span class="hljs-keyword">true</span>);
ClientProducer producer = session.createProducer(<span class="hljs-string">&quot;example&quot;</span>);
ClientMessage message = session.createMessage(<span class="hljs-keyword">true</span>);
message.getBody().writeString(<span class="hljs-string">&quot;Hello&quot;</span>);
producer.send(message);
session.start();
ClientConsumer consumer = session.createConsumer(<span class="hljs-string">&quot;example&quot;</span>);
ClientMessage msgReceived = consumer.receive();
System.out.println(<span class="hljs-string">&quot;message = &quot;</span> + msgReceived.getBody().readString());
session.close();
</code></pre>
<p>The <code>EmbeddedActiveMQ</code> 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.</p>
<h2 id="jms-api">JMS API</h2>
<p>JMS embedding is simple as well. This example requires that you have
defined the config file <code>broker.xml</code>. Let&apos;s also assume that a queue
and connection factory has been defined in the <code>broker.xml</code>
config file as well.</p>
<pre><code class="lang-java"><span class="hljs-keyword">import</span> org.apache.activemq.artemis.jms.server.embedded.EmbeddedJMS;
...
EmbeddedJMS jms = <span class="hljs-keyword">new</span> EmbeddedJMS();
jms.start();
<span class="hljs-comment">// This assumes we have configured broker.xml with the appropriate config information</span>
ConnectionFactory connectionFactory = jms.lookup(<span class="hljs-string">&quot;ConnectionFactory&quot;</span>);
Destination destination = jms.lookup(<span class="hljs-string">&quot;/example/queue&quot;</span>);
... regular JMS code ...
</code></pre>
<p>By default, the <code>EmbeddedJMS</code> class will store the &quot;entries&quot; defined for
your JMS components within <code>broker.xml</code> in an internal concurrent hash
map. The <code>EmbeddedJMS.lookup()</code> method returns components stored in
this map. If you want to use JNDI, call the <code>EmbeddedJMS.setContext()</code>
method with the root JNDI context you want your components bound into.
See the JavaDocs for this class for more details on other config options.</p>
<h2 id="pojo-instantiation---embedding-programmatically">POJO instantiation - Embedding Programmatically</h2>
<p>You can follow this step-by-step guide to programmatically embed the
core, non-JMS Apache ActiveMQ Artemis Server instance:</p>
<p>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 describe in
the <a href="configuration-index.html">Server Configuration</a> section.</p>
<p>The acceptors are configured through <code>ConfigurationImpl</code>. Just add the
<code>NettyAcceptorFactory</code> on the transports the same way you would through
the main configuration file.</p>
<pre><code class="lang-java"><span class="hljs-keyword">import</span> org.apache.activemq.artemis.core.config.Configuration;
<span class="hljs-keyword">import</span> org.apache.activemq.artemis.core.config.impl.ConfigurationImpl;
...
Configuration config = <span class="hljs-keyword">new</span> ConfigurationImpl();
HashSet&lt;TransportConfiguration&gt; transports = <span class="hljs-keyword">new</span> HashSet&lt;TransportConfiguration&gt;();
transports.add(<span class="hljs-keyword">new</span> TransportConfiguration(NettyAcceptorFactory.class.getName()));
transports.add(<span class="hljs-keyword">new</span> TransportConfiguration(InVMAcceptorFactory.class.getName()));
config.setAcceptorConfigurations(transports);
</code></pre>
<p>You need to instantiate an instance of
<code>org.apache.activemq.artemis.api.core.server.embedded.EmbeddedActiveMQ</code> and add
the configuration object to it.</p>
<pre><code class="lang-java"><span class="hljs-keyword">import</span> org.apache.activemq.artemis.api.core.server.ActiveMQ;
<span class="hljs-keyword">import</span> org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;
...
EmbeddedActiveMQ server = <span class="hljs-keyword">new</span> EmbeddedActiveMQ();
server.setConfiguration(config);
server.start();
</code></pre>
<p>You also have the option of instantiating <code>ActiveMQServerImpl</code> directly:</p>
<pre><code class="lang-java">ActiveMQServer server = <span class="hljs-keyword">new</span> ActiveMQServerImpl(config);
server.start();
</code></pre>
<p>For JMS POJO instantiation, you work with the EmbeddedJMS class instead
as described earlier. First you define the configuration
programmatically for your ConnectionFactory and Destination objects,
then set the JmsConfiguration property of the EmbeddedJMS class. Here is
an example of this:</p>
<pre><code class="lang-java"><span class="hljs-comment">// Step 1. Create Apache ActiveMQ Artemis core configuration, and set the properties accordingly</span>
Configuration configuration = <span class="hljs-keyword">new</span> ConfigurationImpl()
.setPersistenceEnabled(<span class="hljs-keyword">false</span>)
.setSecurityEnabled(<span class="hljs-keyword">false</span>)
.addAcceptorConfiguration(<span class="hljs-keyword">new</span> TransportConfiguration(NettyAcceptorFactory.class.getName()))
.addConnectorConfiguration(<span class="hljs-string">&quot;myConnector&quot;</span>, <span class="hljs-keyword">new</span> TransportConfiguration(NettyConnectorFactory.class.getName()));
<span class="hljs-comment">// Step 2. Create the JMS configuration</span>
JMSConfiguration jmsConfig = <span class="hljs-keyword">new</span> JMSConfigurationImpl();
<span class="hljs-comment">// Step 3. Configure the JMS ConnectionFactory</span>
ConnectionFactoryConfiguration cfConfig = <span class="hljs-keyword">new</span> ConnectionFactoryConfigurationImpl()
.setName(<span class="hljs-string">&quot;cf&quot;</span>)
.setConnectorNames(Arrays.asList(<span class="hljs-string">&quot;myConnector&quot;</span>))
.setBindings(<span class="hljs-string">&quot;/cf&quot;</span>);
jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
<span class="hljs-comment">// Step 4. Configure the JMS Queue</span>
JMSQueueConfiguration queueConfig = <span class="hljs-keyword">new</span> JMSQueueConfigurationImpl()
.setName(<span class="hljs-string">&quot;queue1&quot;</span>)
.setDurable(<span class="hljs-keyword">false</span>)
.setBindings(<span class="hljs-string">&quot;/queue/queue1&quot;</span>);
jmsConfig.getQueueConfigurations().add(queueConfig);
<span class="hljs-comment">// Step 5. Start the JMS Server using the Apache ActiveMQ Artemis core server and the JMS configuration</span>
jmsServer = <span class="hljs-keyword">new</span> EmbeddedJMS()
.setConfiguration(configuration)
.setJmsConfiguration(jmsConfig)
.start();
</code></pre>
<p>Please see the examples for an example which shows how to setup and run Apache ActiveMQ Artemis
embedded with JMS.</p>
<h2 id="dependency-frameworks">Dependency Frameworks</h2>
<p>You may also choose to use a dependency injection framework such as
The Spring Framework. See <a href="spring-integration.html">Spring Integration</a> for more details on
Spring and Apache ActiveMQ Artemis.</p>
<p>Apache ActiveMQ Artemis standalone uses <a href="https://github.com/airlift/airline" target="_blank">Airline</a> to bootstrap.</p>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="rest.html" class="navigation navigation-prev " aria-label="Previous page: REST Interface">
<i class="fa fa-angle-left"></i>
</a>
<a href="karaf.html" class="navigation navigation-next " aria-label="Next page: Apache Karaf">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Embedding Apache ActiveMQ Artemis","level":"1.49","depth":1,"next":{"title":"Apache Karaf","level":"1.50","depth":1,"path":"karaf.md","ref":"karaf.md","articles":[]},"previous":{"title":"REST Interface","level":"1.48","depth":1,"path":"rest.md","ref":"rest.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"apache/activemq-artemis","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"ActiveMQ Artemis Documentation","links":{"home":"http://activemq.apache.org/","issues":"http://activemq.apache.org/","contribute":"http://activemq.apache.org/contributing.html"},"gitbook":"3.x.x","description":"ActiveMQ Artemis User Guide and Reference Documentation"},"file":{"path":"embedding-activemq.md","mtime":"2017-03-08T02:33:12.000Z","type":"markdown"},"gitbook":{"version":"3.1.1","time":"2017-03-08T02:38:15.470Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
<script src="gitbook/gitbook.js"></script>
<script src="gitbook/theme.js"></script>
<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="gitbook/gitbook-plugin-search/search.js"></script>
<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>
<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
</body>
</html>