activemq-artemis/docs/user-manual/en/embedding-activemq.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd"> -->
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES;
]>
<chapter id="embedding-activemq">
  <title>Embedding ActiveMQ</title>

  <para>ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
  This means ActiveMQ can be instantiated and run in any dependency injection
  framework such as JBoss Microcontainer, Spring or Google Guice. It also
  means that if you have an application that could use messaging functionality
  internally, then it can <emphasis>directly instantiate</emphasis> ActiveMQ
  clients and servers in its own application code to perform that
  functionality. We call this <emphasis>embedding</emphasis> ActiveMQ.</para>

  <para>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.</para>

  <para>Embedding ActiveMQ can be done in very few easy steps. Instantiate the
  configuration object, instantiate the server, start it, and you have a
  ActiveMQ running in your virtual machine. It's as simple and easy as
  that.</para>

  <section>
    <title>Simple Config File Embedding</title>

    <para>The simplest way to embed ActiveMQ is to use the embedded wrapper
    classes and configure ActiveMQ through its configuration files. There are
    two different helper classes for this depending on whether your using the
    ActiveMQ Core API or JMS.</para>

    <section>
      <title>Core API Only</title>
      <para>For instantiating a core ActiveMQ Server only, the steps are pretty
      simple. The example requires that you have defined a configuration file
      <literal>activemq-configuration.xml</literal> in your
      classpath:</para>
        <programlisting>
import org.apache.activemq.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();</programlisting>

<para>The <literal>EmbeddedActiveMQ</literal> 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.</para>
    </section>

    <section id="simple.embedded.jms">
      <title>JMS API</title>

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

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

  <section>
    <title>POJO instantiation - Embedding Programmatically</title>

    <para>You can follow this step-by-step guide to programmatically embed the
    core, non-JMS ActiveMQ Server instance:</para>

    <para>Create the configuration object - this contains configuration
    information for a ActiveMQ instance. The setter methods of this class allow
    you to programmatically set configuration options as describe in the <xref
    linkend="server.configuration" /> section.</para>

    <para>The acceptors are configured through
    <literal>ConfigurationImpl</literal>. Just add the
    <literal>NettyAcceptorFactory</literal> on the transports the same way you
    would through the main configuration file.</para>

    <programlisting>
import org.apache.activemq.core.config.Configuration;
import org.apache.activemq.core.config.impl.ConfigurationImpl;

...

Configuration config = new ConfigurationImpl();
HashSet&lt;TransportConfiguration> transports = new HashSet&lt;TransportConfiguration>();
      
transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));

config.setAcceptorConfigurations(transports);</programlisting>

    <para>You need to instantiate an instance of
    <literal>org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ</literal>
    and add the configuration object to it.</para>

    <programlisting>
import org.apache.activemq.api.core.server.ActiveMQ;
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;

...

EmbeddedActiveMQ server = new EmbeddedActiveMQ();
server.setConfiguration(config);

server.start();</programlisting>

    <para>You also have the option of instantiating
    <literal>ActiveMQServerImpl</literal> directly:</para>

    <programlisting>
ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();</programlisting>

    <para>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:</para>

    <programlisting>
// Step 1. Create ActiveMQ 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 ActiveMQ core server and the JMS configuration
EmbeddedJMS jmsServer = new EmbeddedJMS();
jmsServer.setConfiguration(configuration);
jmsServer.setJmsConfiguration(jmsConfig);
jmsServer.start();</programlisting>

    <para>Please see <xref linkend="examples.embedded.jms" /> for an example which
    shows how to setup and run ActiveMQ embedded with JMS.</para>
  </section>

  <section>
    <title>Dependency Frameworks</title>

    <para>You may also choose to use a dependency injection framework such as
    <trademark>JBoss Micro Container</trademark> or <trademark>Spring
    Framework</trademark>. See <xref linkend="spring.integration" /> for more
    details on Spring and ActiveMQ, but here's how you would do things with the
    JBoss Micro Container.</para>

    <para>ActiveMQ standalone uses JBoss Micro Container as the injection
    framework. <literal>ActiveMQBootstrapServer</literal> and
    <literal>activemq-beans.xml</literal> which are part of the ActiveMQ
    distribution provide a very complete implementation of what's needed to
    bootstrap the server using JBoss Micro Container.</para>

    <para>When using JBoss Micro Container, you need to provide an XML file
    declaring the <literal>ActiveMQServer</literal> and
    <literal>Configuration</literal> object, you can also inject a security
    manager and a MBean server if you want, but those are optional.</para>

    <para>A very basic XML Bean declaration for the JBoss Micro Container
    would be:</para>

    <programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;deployment xmlns="urn:jboss:bean-deployer:2.0">
   &lt;!-- The core configuration -->
   &lt;bean name="Configuration" 
         class="org.apache.activemq.core.config.impl.FileConfiguration">
   &lt;/bean>

     &lt;!-- The core server -->
   &lt;bean name="ActiveMQServer"
         class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
      &lt;constructor>
         &lt;parameter>
            &lt;inject bean="Configuration"/>
         &lt;/parameter>
      &lt;/constructor>
   &lt;/bean>
&lt;/deployment></programlisting>

    <para><literal>ActiveMQBootstrapServer</literal> provides an easy
    encapsulation of JBoss Micro Container.</para>

    <programlisting>
ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
bootStrap.run();</programlisting>
  </section>
</chapter>