[hornetq-commits] JBoss hornetq SVN: r9630 - trunk/docs/user-manual/en.

Author: bill.burke(a)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&lt;TransportConfiguration> transports = new HashSet&lt;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 @@ -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>&lt;?xml version="1.0" encoding="UTF-8"?> +>>>>>>> .r9629 -&lt;deployment xmlns="urn:jboss:bean-deployer:2.0"> - - &lt;!-- The core configuration --> - &lt;bean name="Configuration" - class="org.hornetq.core.config.impl.FileConfiguration"> - &lt;/bean> - - &lt;!-- The core server --> - &lt;bean name="HornetQServer" - class="org.hornetq.core.server.impl.HornetQServerImpl"> - &lt;constructor> - &lt;parameter> - &lt;inject bean="Configuration"/> - &lt;/parameter> - &lt;/constructor> - &lt;/bean> - &lt;/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&lt;TransportConfiguration&gt; transports = new HashSet&lt;TransportConfiguration&gt;(); + +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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; + +&lt;deployment xmlns="urn:jboss:bean-deployer:2.0"&gt; + + &lt;!-- The core configuration --&gt; + &lt;bean name="Configuration" + class="org.hornetq.core.config.impl.FileConfiguration"&gt; + &lt;/bean&gt; + + &lt;!-- The core server --&gt; + &lt;bean name="HornetQServer" + class="org.hornetq.core.server.impl.HornetQServerImpl"&gt; + &lt;constructor&gt; + &lt;parameter&gt; + &lt;inject bean="Configuration"/&gt; + &lt;/parameter&gt; + &lt;/constructor&gt; + &lt;/bean&gt; + &lt;/deployment&gt;</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>&lt;configuration xmlns="urn:hornetq" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="urn:hornetq /schema/hornetq-jms.xsd"&gt; + &lt;!--the connection factory used by the example--&gt; + &lt;connection-factory name="ConnectionFactory"&gt; + &lt;connectors&gt; + &lt;connector-ref connector-name="in-vm"/&gt; + &lt;/connectors&gt; + &lt;entries&gt; + &lt;entry name="ConnectionFactory"/&gt; + &lt;/entries&gt; + &lt;/connection-factory&gt; + + &lt;!--the queue used by the example--&gt; + &lt;queue name="exampleQueue"&gt; + &lt;entry name="/queue/exampleQueue"/&gt; + &lt;/queue&gt; + +&lt;/configuration&gt; +</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>&lt;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"&am... + + &lt;bean id="EmbeddedJms" class="org.hornetq.integration.spring.SpringJmsBootstrap" init-method="start"/&gt; + + &lt;bean id="listener" class="org.hornetq.tests.integration.spring.ExampleListener"/&gt; + + &lt;bean id="listenerContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"&gt; + &lt;property name="connectionFactory" ref="ConnectionFactory"/&gt; + &lt;property name="destination" ref="/queue/exampleQueue"/&gt; + &lt;property name="messageListener" ref="listener"/&gt; + &lt;/bean&gt; + + +&lt;/beans&gt; +</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>