[hornetq-commits] JBoss hornetq SVN: r9630 - trunk/docs/user-manual/en.
do-not-reply at jboss.org
do-not-reply at jboss.org
Thu Sep 2 19:20:37 EDT 2010
Author: bill.burke at jboss.com
Date: 2010-09-02 19:20:36 -0400 (Thu, 02 Sep 2010)
New Revision: 9630
Added:
trunk/docs/user-manual/en/spring-integration.xml
Modified:
trunk/docs/user-manual/en/embedding-hornetq.xml
trunk/docs/user-manual/en/examples.xml
trunk/docs/user-manual/en/master.xml
Log:
Spring and embedded reworking
Modified: trunk/docs/user-manual/en/embedding-hornetq.xml
===================================================================
--- trunk/docs/user-manual/en/embedding-hornetq.xml 2010-09-02 11:58:21 UTC (rev 9629)
+++ trunk/docs/user-manual/en/embedding-hornetq.xml 2010-09-02 23:20:36 UTC (rev 9630)
@@ -1,4 +1,6 @@
<?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. -->
<!-- -->
@@ -17,51 +19,37 @@
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
<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>POJO instantiation</title>
- <para>You can follow this step-by-step guide:</para>
- <para>Create the configuration object - this contains configuration information for a
- HornetQ. If you want to configure it from a file on the classpath, use <literal
- >FileConfigurationImpl</literal></para>
- <programlisting>import org.hornetq.core.config.Configuration;
-import org.hornetq.core.config.impl.FileConfiguration;
+ <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>
-Configuration config = new FileConfiguration();
-config.setConfigurationUrl(urlToYourconfigfile);
-config.start();</programlisting>
- <para>If you don't need to support a configuration file, just use <literal
- >ConfigurationImpl</literal> and change the config parameters accordingly, such as
- adding acceptors. </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.hornetq.core.config.Configuration;
-import org.hornetq.core.config.impl.ConfigurationImpl;
+ <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>
-Configuration config = new ConfigurationImpl();
-HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
-
-transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
-transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
+ <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>
+<<<<<<< .mine
+ <section>
+ <title>Core API Only</title>
+=======
config.setAcceptorConfigurations(transports);</programlisting>
<para>You need to instantiate and start HornetQ server. The class <literal
>org.hornetq.api.core.server.HornetQ</literal> has a few static methods for creating
@@ -69,11 +57,25 @@
<programlisting>import org.hornetq.core.server.HornetQServer;
import org.hornetq.core.server.HornetQServers;
+>>>>>>> .r9629
+ <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:<programlisting>import org.hornetq.core.server.embedded.EmbeddedHornetQ;
+
...
+<<<<<<< .mine
+EmbeddedHornetQ embedded = new EmbeddedHornetQ();
+embedded.start();
+=======
HornetQServer server = HornetQServers.newHornetQServer(config);
+>>>>>>> .r9629
+<<<<<<< .mine
+// Assuming you defined an "in-vm" acceptor within your hornetq-configuration.xml file
+=======
server.start();</programlisting>
<para>You also have the option of instantiating <literal>HornetQServerImpl</literal>
directly:</para>
@@ -94,38 +96,9 @@
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"?>
+>>>>>>> .r9629
-<deployment xmlns="urn:jboss:bean-deployer:2.0">
-
- <!-- The core configuration -->
- <bean name="Configuration"
- class="org.hornetq.core.config.impl.FileConfiguration">
- </bean>
-
- <!-- The core server -->
- <bean name="HornetQServer"
- class="org.hornetq.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>
- <section>
- <title>Connecting to the Embedded HornetQ</title>
- <para>To connect clients to HornetQ you just create the factories as normal:</para>
- <section>
- <title>Core API</title>
- <para>If using the core API, just create the <literal>ClientSessionFactory</literal> and
- use the regular core API.</para>
- <programlisting>ClientSessionFactory nettyFactory = HornetQClient.createClientSessionFactory(
+ClientSessionFactory nettyFactory = HornetQClient.createClientSessionFactory(
new TransportConfiguration(
InVMConnectorFactory.class.getName()));
@@ -149,45 +122,186 @@
System.out.println("message = " + msgReceived.getBody().readString());
-session.close();</programlisting>
- </section>
- <section>
- <title>JMS API</title>
- <para>Connection on an Embedded HornetQ through JMS is also simple. Just instantiate
- <literal>ConnectionFactory</literal> directly. The following example
- illustrates that.</para>
- <programlisting>ConnectionFactory cf =
- HornetQJMSClient.createConnectionFactory(
- new TransportConfiguration(InVMConnectorFactory.class.getName()));
+session.close();
+</programlisting><parameter>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.</parameter></para>
+ </section>
-Connection conn = cf.createConnection();
+ <section id="simple.embedded.jms">
+ <title>JMS API</title>
-conn.start();
+ <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.<programlisting>import org.hornetq.jms.server.embedded.EmbeddedJMS;
-Session sess = conn.createSession(true, Session.SESSION_TRANSACTED);
+...
-MessageProducer prod = sess.createProducer(queue);
+EmbeddedJMS jms = new EmbeddedJMS();
+jms.start();
-TextMessage msg = sess.createTextMessage("Hello!");
+// This assumes we have configured hornetq-jms.xml with the appropriate config information
+ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
+Destination destination = jms.lookup("/example/queue");
-prod.send(msg);
+... regular JMS code ...
-sess.commit();
-MessageConsumer consumer = sess.createConsumer(queue);
+</programlisting><parameter>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.</parameter></para>
+ </section>
+ </section>
-TextMessage txtmsg = (TextMessage)consumer.receive();
+ <section>
+ <title>POJO instantiation - Embedding Programmatically</title>
-System.out.println("Msg = " + txtmsg.getText());
+ <para>You can follow this step-by-step guide to programmatically embed the
+ core, non-JMS HornetQ Server instance:</para>
-sess.commit();
+ <para>Create the configuration object - this contains configuration
+ information for a HornetQ instance. The setter methods of this class allow
+ you to programmitcally set configuration options as describe in the <xref
+ linkend="server.configuration" /> section.</para>
-conn.close();</programlisting>
- </section>
- </section>
- <section>
- <title>JMS Embedding Example</title>
- <para>Please see <xref linkend="examples.embedded"/> for an example which shows how to setup
- and run HornetQ embedded with JMS.</para>
- </section>
+ <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.hornetq.core.config.Configuration;
+import org.hornetq.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.hornetq.api.core.server.embedded.EmbeddedHornetQ</literal>
+ and add the configuration object to it.</para>
+
+ <programlisting>import org.hornetq.api.core.server.HornetQ;
+import org.hornetq.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 Contaier.</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.hornetq.core.config.impl.FileConfiguration">
+ </bean>
+
+ <!-- The core server -->
+ <bean name="HornetQServer"
+ class="org.hornetq.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>
+
+ <section>
+ <para />
+ </section>
</chapter>
Modified: trunk/docs/user-manual/en/examples.xml
===================================================================
--- trunk/docs/user-manual/en/examples.xml 2010-09-02 11:58:21 UTC (rev 9629)
+++ trunk/docs/user-manual/en/examples.xml 2010-09-02 23:20:36 UTC (rev 9630)
@@ -161,10 +161,14 @@
Note that for the messages to be persisted, the messages sent to them must be marked
as durable messages. </para>
</section>
- <section>
+ <section id="examples.embedded.jms.simple">
+ <title>Embedded Simple</title>
+ <para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular HornetQ XML files.</para>
+ </section>
+ <section id="examples.embedded.jms">
<title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed the HornetQ server
- within your own code.</para>
+ <para>The <literal>embedded</literal> example shows how to embed JMS
+ within your own code using POJO instantiation and no config files.</para>
</section>
<section>
<title>HTTP Transport</title>
@@ -400,6 +404,10 @@
to obtain acknowledgement from the server that sends have been received and
processed in a separate stream to the sent messages. </para>
</section>
+ <section id="examples.jms.spring.integration">
+ <title>Spring Integration</title>
+ <para>This example shows how to use embedded JMS using HornetQ's Spring integration.</para>
+ </section>
<section>
<title>SSL Transport</title>
<para>The <literal>ssl-enabled</literal> shows you how to configure SSL with HornetQ to
@@ -507,7 +515,8 @@
directory and type <literal>ant</literal></para>
<section id="examples.embedded">
<title>Embedded</title>
- <para>This example shows how to embed the HornetQ server within your own code.</para>
+ <para>The <literal>embedded</literal> example shows how to embed the HornetQ server
+ within your own code.</para>
</section>
</section>
<section>
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2010-09-02 11:58:21 UTC (rev 9629)
+++ trunk/docs/user-manual/en/master.xml 2010-09-02 23:20:36 UTC (rev 9630)
@@ -59,6 +59,7 @@
<!ENTITY scheduled-messages SYSTEM "scheduled-messages.xml">
<!ENTITY security SYSTEM "security.xml">
<!ENTITY send-guarantees SYSTEM "send-guarantees.xml">
+ <!ENTITY spring-integration SYSTEM "spring-integration.xml">
<!ENTITY thread-pooling SYSTEM "thread-pooling.xml">
<!ENTITY undelivered-messages SYSTEM "undelivered-messages.xml">
<!ENTITY using-core SYSTEM "using-core.xml">
@@ -119,6 +120,7 @@
&thread-pooling;
&logging;
&embedding-hornetq;
+ &spring-integration;
&intercepting-operations;
&interoperability;
&perf-tuning;
Added: trunk/docs/user-manual/en/spring-integration.xml
===================================================================
--- trunk/docs/user-manual/en/spring-integration.xml (rev 0)
+++ trunk/docs/user-manual/en/spring-integration.xml 2010-09-02 23:20:36 UTC (rev 9630)
@@ -0,0 +1,87 @@
+<?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. -->
+<!-- ============================================================================= -->
+<chapter id="spring.integration">
+ <title>Spring Integration<parameter></parameter></title>
+
+ <para>HornetQ provides a simple bootstrap class,
+ <literal>org.hornetq.integration.spring.SpringJmsBootstrap</literal>, for
+ integration with Spring. To use it, you configure HornetQ as you always
+ would, through its various configuration files like
+ <literal>hornetq-configuration.xml</literal>,
+ <literal>hornetq-jms.xml</literal>, and
+ <literal>hornetq-users.xml</literal>. The Spring helper class starts the
+ HornetQ server and adds any factories or destinations configured within
+ <literal>hornetq-jms.xml</literal> directly into the namespace of the Spring
+ context. Let's take this <literal>hornetq-jms.xml</literal> file for
+ instance: <programlisting><configuration xmlns="urn:hornetq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:hornetq /schema/hornetq-jms.xsd">
+ <!--the connection factory used by the example-->
+ <connection-factory name="ConnectionFactory">
+ <connectors>
+ <connector-ref connector-name="in-vm"/>
+ </connectors>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ </connection-factory>
+
+ <!--the queue used by the example-->
+ <queue name="exampleQueue">
+ <entry name="/queue/exampleQueue"/>
+ </queue>
+
+</configuration>
+</programlisting>Here we've specified a
+ <literal>javax.jms.ConnectionFactory</literal> we want bound to a
+ <literal>ConnectionFactory</literal> entry as well as a queue destination
+ bound to a <literal>/queue/exampleQueue</literal> entry. Using the
+ <literal>SpringJmsBootStrap</literal> bean will automatically populate the
+ Spring context with references to those beans so that you can use them.
+ Below is an example Spring JMS bean file taking advantage of this
+ feature:<programlisting><beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
+
+ <bean id="EmbeddedJms" class="org.hornetq.integration.spring.SpringJmsBootstrap" init-method="start"/>
+
+ <bean id="listener" class="org.hornetq.tests.integration.spring.ExampleListener"/>
+
+ <bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
+ <property name="connectionFactory" ref="ConnectionFactory"/>
+ <property name="destination" ref="/queue/exampleQueue"/>
+ <property name="messageListener" ref="listener"/>
+ </bean>
+
+
+</beans>
+</programlisting>As you can see, the
+ <literal>listenerContainer</literal> bean references the components defined
+ in the <literal>hornetq-jms.xml</literal> file. The
+ <literal>SpringJmsBootstrap</literal> class extends the EmbeddedJMS class
+ talked about in <xref
+ linkend="simple.embedded.jms" /> and the same defaults and
+ configuration options apply. Also notice that an
+ <literal>init-method</literal> must be declared with a start value so that
+ the bean's lifecycle is executed. See the javadocs for more details on other
+ properties of the bean class.</para>
+</chapter>
More information about the hornetq-commits
mailing list