how-do-i-embed-a-broker-inside-a-connection.xml - activemq-web - Git at Google

 <div class="wiki-content maincontent"><p>In many messaging topologies there are JMS Brokers (server side) and a JMS client side. Often it makes sense to deploy a broker within your JVM. This allows you to optimise away a network hop; making the networking of JMS as efficient as pure RMI, but with all the usual JMS features of location independence, reliability, load balancing etc.</p><p>There are various ways to embed a broker in ActiveMQ depending on if you are using Java, Spring, XBean or using the ActiveMQConnectionFactory .</p><h3>Using explicit Java code</h3><p>The following Java code will create an embedded broker</p><structured-macro ac:macro-id="9eaa5bb3-576f-42b5-9c4b-04d93d7c7ee6" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();

 // configure the broker
 broker.addConnector("tcp://localhost:61616");

 broker.start();
 </plain-text-body></structured-macro><p>If you want to lazily bind the transport connector as part of start(), useful when start() will block pending a store lock (as in a slave start), you can use the following code</p><structured-macro ac:macro-id="ac608f29-1173-4703-b0cc-192bed0dd67f" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();

 TransportConnector connector = new TransportConnector();
 connector.setUri(new URI("tcp://localhost:61616"));
 broker.addConnector(connector);
 broker.start();
 </plain-text-body></structured-macro><p>In the same JVM clients can then use the <link><page ri:content-title="VM Transport Reference"></page><plain-text-link-body>vm:// transport</plain-text-link-body></link> to connect to the embedded broker - whilst external clients can use the <link><page ri:content-title="TCP Transport Reference"></page><plain-text-link-body>tcp:// protocol</plain-text-link-body></link></p><p>If you have more than one embedded broker, ensure that you give them a unique name and - e.g.</p><structured-macro ac:macro-id="ab19815a-2dfd-4e65-a5be-b8210339a28c" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();
 // configure the broker
 broker.setBrokerName("fred");
 broker.addConnector("tcp://localhost:61616");
 broker.start();
 </plain-text-body></structured-macro><p>Then if you want to connect to the broker named 'fred' from within the same JVM, you can by using the uri <strong>vm://fred</strong></p><p>It is possible to fully configure a broker through application code e.g.</p><structured-macro ac:macro-id="7e0ebf92-ef49-416b-b093-0dd90aa42955" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();
 broker.setBrokerName("fred");
 broker.setUseShutdownHook(false);
 //Add plugin
 broker.setPlugins(new BrokerPlugin[]{new JaasAuthenticationPlugin()});
 //Add a network connection
 NetworkConnector connector = answer.addNetworkConnector("static://"+"tcp://somehost:61616");
 connector.setDuplex(true);
 broker.addConnector("tcp://localhost:61616");
 broker.start();
 </plain-text-body></structured-macro><structured-macro ac:macro-id="b7967e06-0454-4e9a-af9a-5c24b63b0501" ac:name="note" ac:schema-version="1"><rich-text-body><p>Please note that you should add plugins before connectors or they will not be initialized</p></rich-text-body></structured-macro><p>For more details on the available properties you can specify, see the <a shape="rect" href="http://activemq.apache.org/maven/5.11.0/apidocs/org/apache/activemq/broker/BrokerService.html">BrokerService javadoc</a></p><h3>Using the BrokerFactory</h3><p>There is a helper class called <a shape="rect" href="http://activemq.apache.org/maven/activemq-core/apidocs/org/apache/activemq/broker/BrokerFactory.html">BrokerFactory</a> which can be used to create a broker via URI for configuration.</p><structured-macro ac:macro-id="a8d3bdfc-dd6d-4a02-aa2e-76524c94fc34" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = BrokerFactory.createBroker(new URI(someURI));
 </plain-text-body></structured-macro><p>The available values of the URI are</p><table><tbody><tr><th colspan="1" rowspan="1"><p>URI scheme</p></th><th colspan="1" rowspan="1"><p>Example</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p>xbean:</p></td><td colspan="1" rowspan="1"><p>xbean:activemq.xml</p></td><td colspan="1" rowspan="1"><p>Searches the classpath (and file system) for an XML document with the given URI (activemq.xml in this case) which will then be used as the <link><page ri:content-title="Xml Configuration"></page></link></p></td></tr><tr><td colspan="1" rowspan="1"><p>broker:</p></td><td colspan="1" rowspan="1"><p>broker:tcp://localhost:61616</p></td><td colspan="1" rowspan="1"><p>Uses the <link><page ri:content-title="Broker Configuration URI"></page></link> to confgure the broker</p></td></tr></tbody></table><h3>Using Spring</h3><p>There is a factory bean that can refer to an external ActiveMQ XML configuration file</p><structured-macro ac:macro-id="2243664c-6d07-401c-94c7-af12ccb45fbf" ac:name="code" ac:schema-version="1"><plain-text-body>&lt;bean id="broker" class="org.apache.activemq.xbean.BrokerFactoryBean"&gt;
     &lt;property name="config" value="classpath:org/apache/activemq/xbean/activemq.xml" /&gt;
     &lt;property name="start" value="true" /&gt;
   &lt;/bean&gt;
 </plain-text-body></structured-macro><p>In this case the usual Spring 'classpath:org/apache/activemq/xbean/activemq.xml' resource mechanism is being used so that the activemq.xml file would be found on the classpath by looking inside all the directories on the classpath then looking for 'org/apache/activemq/xbean/activemq.xml'. You can of course change this to any value you like. e.g. use classpath:activemq.xml if you just want to drop it in a directory that is in the classpath; like WEB-INF/classes in a web application.</p><p>If you wish you can use a URL instead using the <strong>file:* or *http:</strong> prefixes. For more details see how <a shape="rect" href="http://static.springframework.org/spring/docs/1.2.x/reference/beans.html#context-functionality-resources">Spring deals with resources</a></p><h3>Using XBean</h3><p>If you are already using <a shape="rect" href="http://geronimo.apache.org/xbean/">XBean</a> then you can just mix and match your Spring/XBean <a shape="rect" href="https://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-core/src/test/resources/org/apache/activemq/xbean/activemq.xml">XML configuration</a> with ActiveMQ's configuration.</p><structured-macro ac:macro-id="8349179f-1e83-4dd6-801a-e787987af165" ac:name="code" ac:schema-version="1"><plain-text-body>&lt;beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
   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-2.0.xsd
   http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd"&gt;

   &lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/&gt;

   &lt;broker useJmx="true" xmlns="http://activemq.apache.org/schema/core"&gt;

     &lt;persistenceFactory&gt;
       &lt;kahaDB directory="${basedir}/target" /&gt;
     &lt;/persistenceFactory&gt;

     &lt;transportConnectors&gt;
       &lt;transportConnector uri="tcp://localhost:61636" /&gt;
     &lt;/transportConnectors&gt;

   &lt;/broker&gt;
 &lt;/beans&gt;
 </plain-text-body></structured-macro><h3>Using Spring 2.0</h3><p>If you are using Spring 2.0 and ActiveMQ 4.1 or later (and xbean-spring 2.5 or later) you can embed the ActiveMQ broker XML inside any regular Spring.xml file without requiring the above factory bean. e.g. here is an <a shape="rect" href="http://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-core/src/test/resources/spring-embedded-xbean.xml">example</a> of a regular Spring XML file in Spring 2.0 which also configures a broker.</p><structured-macro ac:macro-id="fe131cb2-ea4a-4f1f-a40a-fc78932b400b" ac:name="code" ac:schema-version="1"><plain-text-body>&lt;beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
   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-2.0.xsd
   http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd"&gt;

   &lt;!--  lets create an embedded ActiveMQ Broker --&gt;
   &lt;amq:broker useJmx="false" persistent="false"&gt;
     &lt;amq:transportConnectors&gt;
       &lt;amq:transportConnector uri="tcp://localhost:0" /&gt;
     &lt;/amq:transportConnectors&gt;
   &lt;/amq:broker&gt;

    &lt;!--  ActiveMQ destinations to use  --&gt;
   &lt;amq:queue id="destination"  physicalName="org.apache.activemq.spring.Test.spring.embedded"/&gt;

   &lt;!-- JMS ConnectionFactory to use, configuring the embedded broker using XML --&gt;
   &lt;amq:connectionFactory id="jmsFactory" brokerURL="vm://localhost"/&gt;


   &lt;!-- Spring JMS Template --&gt;
   &lt;bean id="myJmsTemplate" class="org.springframework.jms.core.JmsTemplate"&gt;
     &lt;property name="connectionFactory"&gt;
       &lt;!-- lets wrap in a pool to avoid creating a connection per send --&gt;
       &lt;bean class="org.springframework.jms.connection.SingleConnectionFactory"&gt;
         &lt;property name="targetConnectionFactory"&gt;
           &lt;ref local="jmsFactory" /&gt;
         &lt;/property&gt;
       &lt;/bean&gt;
     &lt;/property&gt;
   &lt;/bean&gt;

   &lt;bean id="consumerJmsTemplate" class="org.springframework.jms.core.JmsTemplate"&gt;
     &lt;property name="connectionFactory" ref="jmsFactory"/&gt;
   &lt;/bean&gt;

   &lt;!-- a sample POJO which uses a Spring JmsTemplate --&gt;
   &lt;bean id="producer" class="org.apache.activemq.spring.SpringProducer"&gt;
     &lt;property name="template"&gt;
       &lt;ref bean="myJmsTemplate"&gt;&lt;/ref&gt;
     &lt;/property&gt;

     &lt;property name="destination"&gt;
       &lt;ref bean="destination" /&gt;
     &lt;/property&gt;

     &lt;property name="messageCount"&gt;
       &lt;value&gt;10&lt;/value&gt;
     &lt;/property&gt;
   &lt;/bean&gt;

   &lt;!-- a sample POJO consumer --&gt;
   &lt;bean id="consumer" class="org.apache.activemq.spring.SpringConsumer"&gt;
     &lt;property name="template" ref="consumerJmsTemplate"/&gt;
     &lt;property name="destination" ref="destination"/&gt;
   &lt;/bean&gt;

 &lt;/beans&gt;
 </plain-text-body></structured-macro><h3>Using ActiveMQConnectionFactory</h3><p>An embedded broker can also be created using an ActiveMQConnectionFactory and using a vm connector as a uri. e.g.</p><structured-macro ac:macro-id="3f36f9a1-bc84-4200-9611-e572416daf76" ac:name="code" ac:schema-version="1"><plain-text-body>ActiveMQConnectionFactory cf = new ActiveMQConnectionFactory("vm://localhost?broker.persistent=false");
 </plain-text-body></structured-macro><p>Use the query parameters "broker.&lt;property&gt;" to configure the broker, where &lt;property&gt; matches the bean properties on the BrokerService.</p><p>The broker will be created upon creation of the first connection.</p><p>You can turn off auto creation by setting the create property on the VM Transport to false:</p><structured-macro ac:macro-id="5d37b378-935e-4ddb-872f-10e99dce2b27" ac:name="code" ac:schema-version="1"><plain-text-body>ActiveMQConnectionFactory cf = new ActiveMQConnectionFactory("vm://localhost?create=false");
 </plain-text-body></structured-macro></div>
	<div class="wiki-content maincontent"><p>In many messaging topologies there are JMS Brokers (server side) and a JMS client side. Often it makes sense to deploy a broker within your JVM. This allows you to optimise away a network hop; making the networking of JMS as efficient as pure RMI, but with all the usual JMS features of location independence, reliability, load balancing etc.</p><p>There are various ways to embed a broker in ActiveMQ depending on if you are using Java, Spring, XBean or using the ActiveMQConnectionFactory .</p><h3>Using explicit Java code</h3><p>The following Java code will create an embedded broker</p><structured-macro ac:macro-id="9eaa5bb3-576f-42b5-9c4b-04d93d7c7ee6" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();

	// configure the broker
	broker.addConnector("tcp://localhost:61616");

	broker.start();
	</plain-text-body></structured-macro><p>If you want to lazily bind the transport connector as part of start(), useful when start() will block pending a store lock (as in a slave start), you can use the following code</p><structured-macro ac:macro-id="ac608f29-1173-4703-b0cc-192bed0dd67f" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();

	TransportConnector connector = new TransportConnector();
	connector.setUri(new URI("tcp://localhost:61616"));
	broker.addConnector(connector);
	broker.start();
	</plain-text-body></structured-macro><p>In the same JVM clients can then use the <link><page ri:content-title="VM Transport Reference"></page><plain-text-link-body>vm:// transport</plain-text-link-body></link> to connect to the embedded broker - whilst external clients can use the <link><page ri:content-title="TCP Transport Reference"></page><plain-text-link-body>tcp:// protocol</plain-text-link-body></link></p><p>If you have more than one embedded broker, ensure that you give them a unique name and - e.g.</p><structured-macro ac:macro-id="ab19815a-2dfd-4e65-a5be-b8210339a28c" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();
	// configure the broker
	broker.setBrokerName("fred");
	broker.addConnector("tcp://localhost:61616");
	broker.start();
	</plain-text-body></structured-macro><p>Then if you want to connect to the broker named 'fred' from within the same JVM, you can by using the uri <strong>vm://fred</strong></p><p>It is possible to fully configure a broker through application code e.g.</p><structured-macro ac:macro-id="7e0ebf92-ef49-416b-b093-0dd90aa42955" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = new BrokerService();
	broker.setBrokerName("fred");
	broker.setUseShutdownHook(false);
	//Add plugin
	broker.setPlugins(new BrokerPlugin[]{new JaasAuthenticationPlugin()});
	//Add a network connection
	NetworkConnector connector = answer.addNetworkConnector("static://"+"tcp://somehost:61616");
	connector.setDuplex(true);
	broker.addConnector("tcp://localhost:61616");
	broker.start();
	</plain-text-body></structured-macro><structured-macro ac:macro-id="b7967e06-0454-4e9a-af9a-5c24b63b0501" ac:name="note" ac:schema-version="1"><rich-text-body><p>Please note that you should add plugins before connectors or they will not be initialized</p></rich-text-body></structured-macro><p>For more details on the available properties you can specify, see the <a shape="rect" href="http://activemq.apache.org/maven/5.11.0/apidocs/org/apache/activemq/broker/BrokerService.html">BrokerService javadoc</a></p><h3>Using the BrokerFactory</h3><p>There is a helper class called <a shape="rect" href="http://activemq.apache.org/maven/activemq-core/apidocs/org/apache/activemq/broker/BrokerFactory.html">BrokerFactory</a> which can be used to create a broker via URI for configuration.</p><structured-macro ac:macro-id="a8d3bdfc-dd6d-4a02-aa2e-76524c94fc34" ac:name="code" ac:schema-version="1"><plain-text-body>BrokerService broker = BrokerFactory.createBroker(new URI(someURI));
	</plain-text-body></structured-macro><p>The available values of the URI are</p><table><tbody><tr><th colspan="1" rowspan="1"><p>URI scheme</p></th><th colspan="1" rowspan="1"><p>Example</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p>xbean:</p></td><td colspan="1" rowspan="1"><p>xbean:activemq.xml</p></td><td colspan="1" rowspan="1"><p>Searches the classpath (and file system) for an XML document with the given URI (activemq.xml in this case) which will then be used as the <link><page ri:content-title="Xml Configuration"></page></link></p></td></tr><tr><td colspan="1" rowspan="1"><p>broker:</p></td><td colspan="1" rowspan="1"><p>broker:tcp://localhost:61616</p></td><td colspan="1" rowspan="1"><p>Uses the <link><page ri:content-title="Broker Configuration URI"></page></link> to confgure the broker</p></td></tr></tbody></table><h3>Using Spring</h3><p>There is a factory bean that can refer to an external ActiveMQ XML configuration file</p><structured-macro ac:macro-id="2243664c-6d07-401c-94c7-af12ccb45fbf" ac:name="code" ac:schema-version="1"><plain-text-body><bean id="broker" class="org.apache.activemq.xbean.BrokerFactoryBean">
	<property name="config" value="classpath:org/apache/activemq/xbean/activemq.xml" />
	<property name="start" value="true" />
	</bean>
	</plain-text-body></structured-macro><p>In this case the usual Spring 'classpath:org/apache/activemq/xbean/activemq.xml' resource mechanism is being used so that the activemq.xml file would be found on the classpath by looking inside all the directories on the classpath then looking for 'org/apache/activemq/xbean/activemq.xml'. You can of course change this to any value you like. e.g. use classpath:activemq.xml if you just want to drop it in a directory that is in the classpath; like WEB-INF/classes in a web application.</p><p>If you wish you can use a URL instead using the <strong>file:* or *http:</strong> prefixes. For more details see how <a shape="rect" href="http://static.springframework.org/spring/docs/1.2.x/reference/beans.html#context-functionality-resources">Spring deals with resources</a></p><h3>Using XBean</h3><p>If you are already using <a shape="rect" href="http://geronimo.apache.org/xbean/">XBean</a> then you can just mix and match your Spring/XBean <a shape="rect" href="https://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-core/src/test/resources/org/apache/activemq/xbean/activemq.xml">XML configuration</a> with ActiveMQ's configuration.</p><structured-macro ac:macro-id="8349179f-1e83-4dd6-801a-e787987af165" ac:name="code" ac:schema-version="1"><plain-text-body><beans
	xmlns="http://www.springframework.org/schema/beans"
	xmlns:amq="http://activemq.apache.org/schema/core"
	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-2.0.xsd
	http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd">

	<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>

	<broker useJmx="true" xmlns="http://activemq.apache.org/schema/core">

	<persistenceFactory>
	<kahaDB directory="${basedir}/target" />
	</persistenceFactory>

	<transportConnectors>
	<transportConnector uri="tcp://localhost:61636" />
	</transportConnectors>

	</broker>
	</beans>
	</plain-text-body></structured-macro><h3>Using Spring 2.0</h3><p>If you are using Spring 2.0 and ActiveMQ 4.1 or later (and xbean-spring 2.5 or later) you can embed the ActiveMQ broker XML inside any regular Spring.xml file without requiring the above factory bean. e.g. here is an <a shape="rect" href="http://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-core/src/test/resources/spring-embedded-xbean.xml">example</a> of a regular Spring XML file in Spring 2.0 which also configures a broker.</p><structured-macro ac:macro-id="fe131cb2-ea4a-4f1f-a40a-fc78932b400b" ac:name="code" ac:schema-version="1"><plain-text-body><beans
	xmlns="http://www.springframework.org/schema/beans"
	xmlns:amq="http://activemq.apache.org/schema/core"
	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-2.0.xsd
	http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd">

	<!-- lets create an embedded ActiveMQ Broker -->
	<amq:broker useJmx="false" persistent="false">
	<amq:transportConnectors>
	<amq:transportConnector uri="tcp://localhost:0" />
	</amq:transportConnectors>
	</amq:broker>

	<!-- ActiveMQ destinations to use -->
	<amq:queue id="destination" physicalName="org.apache.activemq.spring.Test.spring.embedded"/>

	<!-- JMS ConnectionFactory to use, configuring the embedded broker using XML -->
	<amq:connectionFactory id="jmsFactory" brokerURL="vm://localhost"/>


	<!-- Spring JMS Template -->
	<bean id="myJmsTemplate" class="org.springframework.jms.core.JmsTemplate">
	<property name="connectionFactory">
	<!-- lets wrap in a pool to avoid creating a connection per send -->
	<bean class="org.springframework.jms.connection.SingleConnectionFactory">
	<property name="targetConnectionFactory">
	<ref local="jmsFactory" />
	</property>
	</bean>
	</property>
	</bean>

	<bean id="consumerJmsTemplate" class="org.springframework.jms.core.JmsTemplate">
	<property name="connectionFactory" ref="jmsFactory"/>
	</bean>

	<!-- a sample POJO which uses a Spring JmsTemplate -->
	<bean id="producer" class="org.apache.activemq.spring.SpringProducer">
	<property name="template">
	<ref bean="myJmsTemplate"></ref>
	</property>

	<property name="destination">
	<ref bean="destination" />
	</property>

	<property name="messageCount">
	<value>10</value>
	</property>
	</bean>

	<!-- a sample POJO consumer -->
	<bean id="consumer" class="org.apache.activemq.spring.SpringConsumer">
	<property name="template" ref="consumerJmsTemplate"/>
	<property name="destination" ref="destination"/>
	</bean>

	</beans>
	</plain-text-body></structured-macro><h3>Using ActiveMQConnectionFactory</h3><p>An embedded broker can also be created using an ActiveMQConnectionFactory and using a vm connector as a uri. e.g.</p><structured-macro ac:macro-id="3f36f9a1-bc84-4200-9611-e572416daf76" ac:name="code" ac:schema-version="1"><plain-text-body>ActiveMQConnectionFactory cf = new ActiveMQConnectionFactory("vm://localhost?broker.persistent=false");
	</plain-text-body></structured-macro><p>Use the query parameters "broker.<property>" to configure the broker, where <property> matches the bean properties on the BrokerService.</p><p>The broker will be created upon creation of the first connection.</p><p>You can turn off auto creation by setting the create property on the VM Transport to false:</p><structured-macro ac:macro-id="5d37b378-935e-4ddb-872f-10e99dce2b27" ac:name="code" ac:schema-version="1"><plain-text-body>ActiveMQConnectionFactory cf = new ActiveMQConnectionFactory("vm://localhost?create=false");
	</plain-text-body></structured-macro></div>