272 lines
12 KiB
XML
272 lines
12 KiB
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 "HornetQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<chapter id="embedding-hornetq">
|
||
<title>Embedding HornetQ</title>
|
||
|
||
<para>HornetQ is designed as set of simple Plain Old Java Objects (POJOs).
|
||
This means HornetQ 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> HornetQ
|
||
clients and servers in its own application code to perform that
|
||
functionality. We call this <emphasis>embedding</emphasis> HornetQ.</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 HornetQ can be done in very few easy steps. Instantiate the
|
||
configuration object, instantiate the server, start it, and you have a
|
||
HornetQ 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 HornetQ is to use the embedded wrapper
|
||
classes and configure HornetQ through its configuration files. There are
|
||
two different helper classes for this depending on whether your using the
|
||
HornetQ Core API or JMS.</para>
|
||
|
||
<section>
|
||
<title>Core API Only</title>
|
||
<para>For instantiating a core HornetQ Server only, the steps are pretty
|
||
simple. The example requires that you have defined a configuration file
|
||
<literal>hornetq-configuration.xml</literal> in your
|
||
classpath:</para>
|
||
<programlisting>
|
||
import org.apache.activemq.core.server.embedded.EmbeddedHornetQ;
|
||
|
||
...
|
||
|
||
EmbeddedHornetQ embedded = new EmbeddedHornetQ();
|
||
embedded.start();
|
||
|
||
ClientSessionFactory nettyFactory = HornetQClient.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>EmbeddedHornetQ</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>hornetq-configuration.xml</literal>,
|
||
<literal>hornetq-jms.xml</literal>, and a
|
||
<literal>hornetq-users.xml</literal> if you have security enabled. Let's
|
||
also assume that a queue and connection factory has been defined in the
|
||
<literal>hornetq-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 hornetq-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>hornetq-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 HornetQ Server instance:</para>
|
||
|
||
<para>Create the configuration object - this contains configuration
|
||
information for a HornetQ 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<TransportConfiguration> transports = new HashSet<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.EmbeddedHornetQ</literal>
|
||
and add the configuration object to it.</para>
|
||
|
||
<programlisting>
|
||
import org.apache.activemq.api.core.server.HornetQ;
|
||
import org.apache.activemq.core.server.embedded.EmbeddedHornetQ;
|
||
|
||
...
|
||
|
||
EmbeddedHornetQ server = new EmbeddedHornetQ();
|
||
server.setConfiguration(config);
|
||
|
||
server.start();</programlisting>
|
||
|
||
<para>You also have the option of instantiating
|
||
<literal>HornetQServerImpl</literal> directly:</para>
|
||
|
||
<programlisting>
|
||
HornetQServer server = new HornetQServerImpl(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 HornetQ 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 HornetQ 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 HornetQ 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 HornetQ, but here's how you would do things with the
|
||
JBoss Micro Container.</para>
|
||
|
||
<para>HornetQ standalone uses JBoss Micro Container as the injection
|
||
framework. <literal>HornetQBootstrapServer</literal> and
|
||
<literal>hornetq-beans.xml</literal> which are part of the HornetQ
|
||
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>HornetQServer</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>
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<deployment xmlns="urn:jboss:bean-deployer:2.0">
|
||
<!-- The core configuration -->
|
||
<bean name="Configuration"
|
||
class="org.apache.activemq.core.config.impl.FileConfiguration">
|
||
</bean>
|
||
|
||
<!-- The core server -->
|
||
<bean name="HornetQServer"
|
||
class="org.apache.activemq.core.server.impl.HornetQServerImpl">
|
||
<constructor>
|
||
<parameter>
|
||
<inject bean="Configuration"/>
|
||
</parameter>
|
||
</constructor>
|
||
</bean>
|
||
</deployment></programlisting>
|
||
|
||
<para><literal>HornetQBootstrapServer</literal> provides an easy
|
||
encapsulation of JBoss Micro Container.</para>
|
||
|
||
<programlisting>
|
||
HornetQBootstrapServer bootStrap = new HornetQBootstrapServer(new String[] {"hornetq-beans.xml"});
|
||
bootStrap.run();</programlisting>
|
||
</section>
|
||
</chapter>
|