- Introduction
- 1. Legal Notice
- 2. Preface
- 3. Project Info
- 4. Messaging Concepts
- 5. Architecture
- 6. Using the Server
- 7. Using JMS
- 8. Using Core
- 9. Mapping JMS Concepts to the Core API
- 10. The Client Classpath
- 11. Examples
- 12. Routing Messages With Wild Cards
- 13. Understanding the Apache ActiveMQ Artemis Wildcard Syntax
- 14. Filter Expressions
- 15. Persistence
- 16. Configuring Transports
- 17. Detecting Dead Connections
- 18. Detecting Slow Consumers
- 19. Resource Manager Configuration
- 20. Flow Control
- 21. Guarantees of sends and commits
- 22. Message Redelivery and Undelivered Messages
- 23. Message Expiry
- 24. Large Messages
- 25. Paging
- 26. Queue Attributes
- 27. Scheduled Messages
- 28. Last-Value Queues
- 29. Message Grouping
- 30. Extra Acknowledge Modes
- 31. Management
- 32. Security
- 33. Resource Limits
- 34. The JMS Bridge
- 35. Client Reconnection and Session Reattachment
- 36. Diverting and Splitting Message Flows
- 37. Core Bridges
- 38. Duplicate Message Detection
- 39. Clusters
- 40. High Availability and Failover
- 41. Graceful Server Shutdown
- 42. Libaio Native Libraries
- 43. Thread management
- 44. Logging
- 45. REST Interface
- 46. Embedding Apache ActiveMQ Artemis
- 47. Spring Integration
- 48. AeroGear Integration
- 49. VertX Integration
- 50. Intercepting Operations
- 51. Protocols and Interoperability
- 52. Tools
- 53. Maven Plugin
- 54. Troubleshooting and Performance Tuning
- 55. Configuration Reference
- Published with GitBook

# ActiveMQ Artemis Documentation

# Embedding Apache ActiveMQ Artemis

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. Instantiate the configuration object, instantiate the server, start it, and you have a Apache ActiveMQ Artemis running in your virtual machine. It's as simple and easy as that.

## Simple Config File Embedding

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.

## Core API Only

For instantiating a core Apache ActiveMQ Artemis Server only, the steps are pretty simple. The example requires that you have defined a configuration file `broker.xml` in your classpath:

    import org.apache.activemq.artemis.core.server.embedded.EmbeddedActiveMQ;

    ...

    EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();

    embedded.start();

    ClientSessionFactory nettyFactory =  ActiveMQClient.createClientSessionFactory(
                                            new TransportConfiguration(
                                               InVMConnectorFactory.class.getName()));

    ClientSession session = factory.createSession();

    session.createQueue("example", "example", true);

    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.

## JMS API

JMS embedding is simple as well. This example requires that you have defined the config files `broker.xml`, `activemq-jms.xml`, and a `activemq-users.xml` if you have security enabled. Let's also assume that a queue and connection factory has been defined in the `activemq-jms.xml` config file.

    import org.apache.activemq.artemis.jms.server.embedded.EmbeddedJMS;

    ...

    EmbeddedJMS jms = new EmbeddedJMS();
    jms.start();

    // This assumes we have configured activemq-jms.xml with the appropriate config information
    ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
    Destination destination = jms.lookup("/example/queue");

    ... regular JMS code ...

By default, the `EmbeddedJMS` class will store component entries defined within your `activemq-jms.xml` file in an internal concurrent hash map. The `EmbeddedJMS.lookup()` method returns components stored in this map. If you want to use JNDI, call the `EmbeddedJMS.setContext()` 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.

## POJO instantiation - Embedding Programmatically

You can follow this step-by-step guide to programmatically embed the core, non-JMS Apache ActiveMQ Artemis Server 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 describe in the Server Configuration section.

The acceptors are configured through `ConfigurationImpl`. Just add the `NettyAcceptorFactory` on the transports the same way you would through the main configuration file.

    import org.apache.activemq.artemis.core.config.Configuration;
    import org.apache.activemq.artemis.core.config.impl.ConfigurationImpl;

    ...

    Configuration config = new ConfigurationImpl();
    HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();

    transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
    transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));

    config.setAcceptorConfigurations(transports);

You need to instantiate an instance of `org.apache.activemq.artemis.api.core.server.embedded.EmbeddedActiveMQ` and add the configuration object to it.

    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:

    ActiveMQServer server = new ActiveMQServerImpl(config);
    server.start();

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:

    // Step 1. Create Apache ActiveMQ Artemis core configuration, and set the properties accordingly
    Configuration configuration = new ConfigurationImpl();
    configuration.setPersistenceEnabled(false);
    configuration.setSecurityEnabled(false);
    configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));

    // Step 2. Create the JMS configuration
    JMSConfiguration jmsConfig = new JMSConfigurationImpl();

    // Step 3. Configure the JMS ConnectionFactory
    TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
    ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
    jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);

    // Step 4. Configure the JMS Queue
    JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
    jmsConfig.getQueueConfigurations().add(queueConfig);

    // Step 5. Start the JMS Server using the Apache ActiveMQ Artemis core server and the JMS configuration
    EmbeddedJMS jmsServer = new EmbeddedJMS();
    jmsServer.setConfiguration(configuration);
    jmsServer.setJmsConfiguration(jmsConfig);
    jmsServer.start();

Please see the examples for an example which shows how to setup and run Apache ActiveMQ Artemis embedded with JMS.

## Dependency Frameworks

You may also choose to use a dependency injection framework such as The Spring Framework. See Spring Integration for more details on Spring and Apache ActiveMQ Artemis.

Apache ActiveMQ Artemis standalone uses Airline to bootstrap.