Modified: websites/production/activemq/content/virtual-destinations.html
==============================================================================
--- websites/production/activemq/content/virtual-destinations.html (original)
+++ websites/production/activemq/content/virtual-destinations.html Fri Aug 25
08:24:11 2017
@@ -32,15 +32,6 @@
</style>
<![endif]-->
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shCore.css'
rel='stylesheet' type='text/css' />
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css'
rel='stylesheet' type='text/css' />
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache ActiveMQ ™ -- Virtual Destinations
@@ -80,16 +71,13 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><p><em>Virtual Destinations</em> allow
us to create logical destinations that clients can use to produce and consume
from but which map onto one or more <em>physical destinations</em>. It allows
us to provide more flexible loosely coupled messaging configurations.</p><h2
id="VirtualDestinations-VirtualTopics">Virtual Topics</h2><p>The idea behind
<em>publish subscribe</em> is a great one. Allow producers to be decoupled from
consumers so that they do not even know how many consumers are interested in
the messages they publish. The JMS specification defines support for durable
topics however they have limitations as we will describe...</p><h3
id="VirtualDestinations-ThelimitationsofJMSdurabletopics">The limitations of
JMS durable topics</h3><p>A JMS durable subscriber MessageConsumer is created
with a unique JMS clientID and durable subscriber name. To be JMS compliant
only one JMS connection can be active at any point in time for one JMS clientI
D, and only one consumer can be active for a clientID and subscriber name.
i.e., only <strong>one</strong> thread can be actively consuming from a given
logical topic subscriber. This means we cannot implement</p><ul><li>load
balancing of messages.</li><li>fast failover of the subscriber if that one
process running that one consumer thread dies.</li></ul><p>Now <em>queue</em>
semantics in JMS offer the ability to load balance work across a number of
consumers in a reliable way - allowing many threads, processes and machines to
be used to process messages. Then we have sophisticated sticky load balancing
techniques like <a shape="rect" href="message-groups.html">Message Groups</a>
to load balance and parallelise work while maintaining ordering.</p><p>Another
added benefit of having physical queues for each logical topic subscriber is we
can them monitor the queue depths via <a shape="rect" href="jmx.html">JMX</a>
to monitor system performance together with being able to browse these
physical queues.</p><h3
id="VirtualDestinations-VirtualTopicstotherescue">Virtual Topics to the
rescue</h3><p>The idea behind virtual topics is that producers send to a topic
in the usual JMS way. Consumers can continue to use the Topic semantics in the
JMS specification. However if the topic is virtual, consumer can consume from a
physical queue for a logical topic subscription, allowing many consumers to be
running on many machines & threads to load balance the load.</p><p>E.g.,
let's say we have a topic called <strong>VirtualTopic.Orders</strong>. (Where
the prefix VirtualTopic. indicates its a virtual topic). And we logically want
to send orders to systems A and B. Now with regular durable topics we'd create
a JMS consumer for clientID_A and "A" along with clientID_B and "B".</p><p>With
virtual topics we can just go right ahead and consume to queue
<strong>Consumer.A.VirtualTopic.Orders</strong> to be a consumer for system A
or consume to <strong>Consumer.B.VirtualTopic.Orde
rs</strong> to be a consumer for system B.</p><p>We can now have a pool of
consumers for each system which then compete for messages for systems A or B
such that all the messages for system A are processed exactly once and
similarly for system B.</p><h3
id="VirtualDestinations-Customizingtheout-of-the-boxdefaults">Customizing the
out-of-the-box defaults</h3><p>The out-of-the-box defaults are described above.
Namely that the only virtual topics available must be within the
<strong>VirtualTopic.></strong> namespace and that the consumer queues are
named <strong>Consumer.*.VirtualTopic.></strong>.</p><p>You can configure
this to use whatever naming convention you wish. The following <a shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/broker/virtual/global-virtual-topics.xml";>example</a>
shows how to make all topics virtual topics. The example below is using the
name <stron
g>></strong> to indicate 'match all topics'. You could use this wildcard to
apply different virtual topic policies in different hierarchies.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><destinationInterceptors>
+<div class="wiki-content maincontent"><p><em>Virtual Destinations</em> allow
us to create logical destinations that clients can use to produce and consume
from but which map onto one or more <em>physical destinations</em>. It allows
us to provide more flexible loosely coupled messaging configurations.</p><h2
id="VirtualDestinations-VirtualTopics">Virtual Topics</h2><p>The idea behind
<em>publish subscribe</em> is a great one. Allow producers to be decoupled from
consumers so that they do not even know how many consumers are interested in
the messages they publish. The JMS specification defines support for durable
topics however they have limitations as we will describe...</p><h3
id="VirtualDestinations-ThelimitationsofJMSdurabletopics">The limitations of
JMS durable topics</h3><p>A JMS durable subscriber MessageConsumer is created
with a unique JMS clientID and durable subscriber name. To be JMS compliant
only one JMS connection can be active at any point in time for one JMS clientI
D, and only one consumer can be active for a clientID and subscriber name.
i.e., only <strong>one</strong> thread can be actively consuming from a given
logical topic subscriber. This means we cannot implement</p><ul><li>load
balancing of messages.</li><li>fast failover of the subscriber if that one
process running that one consumer thread dies.</li></ul><p>Now <em>queue</em>
semantics in JMS offer the ability to load balance work across a number of
consumers in a reliable way - allowing many threads, processes and machines to
be used to process messages. Then we have sophisticated sticky load balancing
techniques like <a shape="rect" href="message-groups.html">Message Groups</a>
to load balance and parallelise work while maintaining ordering.</p><p>Another
added benefit of having physical queues for each logical topic subscriber is we
can them monitor the queue depths via <a shape="rect" href="jmx.html">JMX</a>
to monitor system performance together with being able to browse these
physical queues.</p><h3
id="VirtualDestinations-VirtualTopicstotherescue">Virtual Topics to the
rescue</h3><p>The idea behind virtual topics is that producers send to a topic
in the usual JMS way. Consumers can continue to use the Topic semantics in the
JMS specification. However if the topic is virtual, consumer can consume from a
physical queue for a logical topic subscription, allowing many consumers to be
running on many machines & threads to load balance the load.</p><p>E.g.,
let's say we have a topic called <strong>VirtualTopic.Orders</strong>. (Where
the prefix VirtualTopic. indicates its a virtual topic). And we logically want
to send orders to systems A and B. Now with regular durable topics we'd create
a JMS consumer for clientID_A and "A" along with clientID_B and "B".</p><p>With
virtual topics we can just go right ahead and consume to queue
<strong>Consumer.A.VirtualTopic.Orders</strong> to be a consumer for system A
or consume to <strong>Consumer.B.VirtualTopic.Orde
rs</strong> to be a consumer for system B.</p><p>We can now have a pool of
consumers for each system which then compete for messages for systems A or B
such that all the messages for system A are processed exactly once and
similarly for system B.</p><h3
id="VirtualDestinations-Customizingtheout-of-the-boxdefaults">Customizing the
out-of-the-box defaults</h3><p>The out-of-the-box defaults are described above.
Namely that the only virtual topics available must be within the
<strong>VirtualTopic.></strong> namespace and that the consumer queues are
named <strong>Consumer.*.VirtualTopic.></strong>.</p><p>You can configure
this to use whatever naming convention you wish. The following <a shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/broker/virtual/global-virtual-topics.xml";>example</a>
shows how to make all topics virtual topics. The example below is using the
name <stron
g>></strong> to indicate 'match all topics'. You could use this wildcard to
apply different virtual topic policies in different hierarchies.</p><parameter
ac:name="">xml</parameter><plain-text-body><destinationInterceptors>
<virtualDestinationInterceptor>
<virtualDestinations>
<virtualTopic name=">" prefix="VirtualTopicConsumers.*."
selectorAware="false"/>
</virtualDestinations>
</virtualDestinationInterceptor>
-</destinationInterceptors></pre>
-</div></div><p>Note that making a topic virtual does add a small CPU overhead
when sending messages to the topic but it is fairly small.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh">Option</th><th colspan="1" rowspan="1"
class="confluenceTh">Default</th><th colspan="1" rowspan="1"
class="confluenceTh">Description</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">selectorAware</td><td colspan="1" rowspan="1"
class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">only messages that match one of the existing subscribers
are actually dispatched. Using this option prevents the build up of unmatched
messages when selectors are used by exclusive consumers</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">local</td><td colspan="1"
rowspan="1" class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, don't fan out messages that were receiv
ed over a network</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">concurrentSend</td><td colspan="1" rowspan="1"
class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, use an executor to fanout such that sends occur
in parallel. This allows the journal to batch writes which will reduce disk io
(5.12)</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">transactedSend</td><td colspan="1" rowspan="1"
class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, use a transaction for fanout sends such that
there is a single disk sync. A local broker transaction will be created if
there is no client transaction
(5.13)</td></tr></tbody></table></div><p> </p><h2
id="VirtualDestinations-CompositeDestinations">Composite
Destinations</h2><p>Composite Destinations allow for one-to-many relationships
on individual destinations; the main use case is for <em>composite queues</em>.
For example when a mess
age is sent to queue A you may want to forward it also to queues B and C and
topic D. Composite destinations are then a mapping from a virtual destination
to a collection of other physical destinations. In this case the mapping is
broker side and the client is unaware of the mapping between the destinations.
This is different from client side <a shape="rect"
href="composite-destinations.html">Composite Destinations</a> where the client
uses a URL notation to specify the actual physical destinations that a message
must be sent to.</p><p>The following <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/broker/virtual/composite-queue.xml";>example</a>
shows how to set up a <strong><compositeQueue/></strong> element in the
XML configuration so that when a message is sent to <code>MY.QUEUE</code> then
it is really forwarded to the physical queue <code>FOO</code> and the topic
<code>BAR</code>.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><destinationInterceptors>
+</destinationInterceptors></plain-text-body><p>Note that making a topic
virtual does add a small CPU overhead when sending messages to the topic but it
is fairly small.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh">Option</th><th colspan="1" rowspan="1"
class="confluenceTh">Default</th><th colspan="1" rowspan="1"
class="confluenceTh">Description</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">selectorAware</td><td colspan="1" rowspan="1"
class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">only messages that match one of the existing subscribers
are actually dispatched. Using this option prevents the build up of unmatched
messages when selectors are used by exclusive consumers</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">local</td><td colspan="1"
rowspan="1" class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, d
on't fan out messages that were received over a network</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">concurrentSend</td><td colspan="1"
rowspan="1" class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, use an executor to fanout such that sends occur
in parallel. This allows the journal to batch writes which will reduce disk io
(5.12)</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">transactedSend</td><td colspan="1" rowspan="1"
class="confluenceTd">false</td><td colspan="1" rowspan="1"
class="confluenceTd">when true, use a transaction for fanout sends such that
there is a single disk sync. A local broker transaction will be created if
there is no client transaction
(5.13)</td></tr></tbody></table></div><p> </p><h2
id="VirtualDestinations-CompositeDestinations">Composite
Destinations</h2><p>Composite Destinations allow for one-to-many relationships
on individual destinations; the main use case is for <em>composit
e queues</em>. For example when a message is sent to queue A you may want to
forward it also to queues B and C and topic D. Composite destinations are then
a mapping from a virtual destination to a collection of other physical
destinations. In this case the mapping is broker side and the client is unaware
of the mapping between the destinations. This is different from client side <a
shape="rect" href="composite-destinations.html">Composite Destinations</a>
where the client uses a URL notation to specify the actual physical
destinations that a message must be sent to.</p><p>The following <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/incubator/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/broker/virtual/composite-queue.xml";>example</a>
shows how to set up a <strong><compositeQueue/></strong> element in the
XML configuration so that when a message is sent to <code>MY.QUEUE</code> then
it is really forwarded to the physical
queue <code>FOO</code> and the topic <code>BAR</code>.</p><parameter
ac:name="">xml</parameter><plain-text-body><destinationInterceptors>
<virtualDestinationInterceptor>
<virtualDestinations>
<compositeQueue name="MY.QUEUE">
@@ -100,15 +88,11 @@
</compositeQueue>
</virtualDestinations>
</virtualDestinationInterceptor>
-</destinationInterceptors></pre>
-</div></div><p>By default, subscribers cannot consume messages directly from a
composite queue or topic - it is a logical construct only. Given the
configuration above, subscribers can only consume messages from
<code>FOO</code> and <code>BAR</code>; but not
<code>MY.QUEUE</code>.</p><p>This behaviour can be altered to implement use
cases such as watching a queue by sending the same messages to a notification
topic (wire tapping), by setting the optionally set <code>forwardOnly</code>
attribute to false.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><compositeQueue name="IncomingOrders"
forwardOnly="false">
+</destinationInterceptors></plain-text-body><p>By default, subscribers
cannot consume messages directly from a composite queue or topic - it is a
logical construct only. Given the configuration above, subscribers can only
consume messages from <code>FOO</code> and <code>BAR</code>; but not
<code>MY.QUEUE</code>.</p><p>This behaviour can be altered to implement use
cases such as watching a queue by sending the same messages to a notification
topic (wire tapping), by setting the optionally set <code>forwardOnly</code>
attribute to false.</p><parameter
ac:name="">xml</parameter><plain-text-body><compositeQueue
name="IncomingOrders" forwardOnly="false">
<forwardTo>
<topic physicalName="Notifications" />
</forwardTo>
-</compositeQueue></pre>
-</div></div><p>Messages sent to <code>IncomingOrders</code> will all be copied
and forwarded to <code>Notifications</code>, before being placed on the
physical <code>IncomingOrders</code> queue for consumption by
subscribers.</p><p>Where the <code>forwardOnly</code> attribute is not defined
or is set to <code>true</code>, there is no logical difference between a
<code>compositeQueue</code> and a <code>compositeTopic</code> - they can be
used interchangeably. It is only when a composite destination is made physical
through the use of <code>forwardOnly</code> that the choice of
<code>compositeTopic</code>/<code>compositeQueue</code> has an impact on
behavior.</p><h3 id="VirtualDestinations-Usingfiltereddestinations">Using
filtered destinations</h3><p>From Apache ActiveMQ <strong>4.2</strong> onwards
you can now use selectors to define virtual destinations.</p><p>You may wish to
create a virtual destination which forwards messages to multiple destinations
but applying a selector first
to decide if the message really does have to go to a particular
destination.</p><p>The following example shows how a message sent to the
virtual destination <strong>MY.QUEUE</strong> will be forwarded to
<strong>FOO</strong> and <strong>BAR</strong> if the selectors match</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><destinationInterceptors>
+</compositeQueue></plain-text-body><p>Messages sent to
<code>IncomingOrders</code> will all be copied and forwarded to
<code>Notifications</code>, before being placed on the physical
<code>IncomingOrders</code> queue for consumption by subscribers.</p><p>Where
the <code>forwardOnly</code> attribute is not defined or is set to
<code>true</code>, there is no logical difference between a
<code>compositeQueue</code> and a <code>compositeTopic</code> - they can be
used interchangeably. It is only when a composite destination is made physical
through the use of <code>forwardOnly</code> that the choice of
<code>compositeTopic</code>/<code>compositeQueue</code> has an impact on
behavior.</p><h3 id="VirtualDestinations-Usingfiltereddestinations">Using
filtered destinations</h3><p>From Apache ActiveMQ <strong>4.2</strong> onwards
you can now use selectors to define virtual destinations.</p><p>You may wish to
create a virtual destination which forwards messages to multiple destinations b
ut applying a selector first to decide if the message really does have to go
to a particular destination.</p><p>The following example shows how a message
sent to the virtual destination <strong>MY.QUEUE</strong> will be forwarded to
<strong>FOO</strong> and <strong>BAR</strong> if the selectors
match</p><parameter
ac:name="">xml</parameter><plain-text-body><destinationInterceptors>
<virtualDestinationInterceptor>
<virtualDestinations>
<compositeQueue name="MY.QUEUE">
@@ -119,17 +103,14 @@
</compositeQueue>
</virtualDestinations>
</virtualDestinationInterceptor>
-</destinationInterceptors></pre>
-</div></div><h2
id="VirtualDestinations-AvoidingDuplicateMessageinaNetworkofBrokers">Avoiding
Duplicate Message in a Network of Brokers</h2><p>You have to make sure that the
messages sent to the <strong>Consumer.*.VirtualTopic.></strong> destination
are not forwarded when you're using both queue-based and non-queue based
subscribers to the virtual topic (that is, if you have normal topic subscribers
to the virtual topic). If you use Virtual Topics in a network of brokers, it is
likely you will get duplicate messages if you use the default network
configuration. This is because a network node will not only forward message
sent to the virtual topic, but also the associated physical queues. To fix
this, you should disable forwarding messages on the associated physical
queues.</p><p>Here is an example of how to do that:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <networkConnectors>
+</destinationInterceptors></plain-text-body><h2
id="VirtualDestinations-AvoidingDuplicateMessageinaNetworkofBrokers">Avoiding
Duplicate Message in a Network of Brokers</h2><p>You have to make sure that the
messages sent to the <strong>Consumer.*.VirtualTopic.></strong> destination
are not forwarded when you're using both queue-based and non-queue based
subscribers to the virtual topic (that is, if you have normal topic subscribers
to the virtual topic). If you use Virtual Topics in a network of brokers, it is
likely you will get duplicate messages if you use the default network
configuration. This is because a network node will not only forward message
sent to the virtual topic, but also the associated physical queues. To fix
this, you should disable forwarding messages on the associated physical
queues.</p><p>Here is an example of how to do that:</p><parameter
ac:name="">xml</parameter><plain-text-body> <networkConnectors>
<networkConnector uri="static://(tcp://localhost:61617)">
<excludedDestinations>
<queue physicalName="Consumer.*.VirtualTopic.>"/>
</excludedDestinations>
</networkConnector>
</networkConnectors>
-</pre>
-</div></div></div>
+</plain-text-body></div>
</td>
<td valign="top">
<div class="navigation">
Modified: websites/production/activemq/content/xml-configuration.html
==============================================================================
--- websites/production/activemq/content/xml-configuration.html (original)
+++ websites/production/activemq/content/xml-configuration.html Fri Aug 25
08:24:11 2017
@@ -32,16 +32,6 @@
</style>
<![endif]-->
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shCore.css'
rel='stylesheet' type='text/css' />
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css'
rel='stylesheet' type='text/css' />
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache ActiveMQ ™ -- Xml Configuration
@@ -81,8 +71,7 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><p>We support an XML deployment
descriptor for configuring the ActiveMQ Message Broker. There are many things
which can be configured such as</p><ul><li><a shape="rect"
href="configuring-version-5-transports.html">transport connectors</a> which
consist of transport channels and wire formats</li><li><a shape="rect"
href="networks-of-brokers.html">network connectors</a> using network channels
or discovery agents</li><li><a shape="rect" href="persistence.html">persistence
providers</a> & locations</li><li>custom message containers (such as last
image caching etc)</li></ul><p>So we decided that using XML would make this
configuration much easier. From version 4.0 onwards we use <a shape="rect"
class="external-link" href="http://xbean.org/"; rel="nofollow">XBean</a> to
perform the XML configuration.</p><p>For details of the XML see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p><div
class="confluence-information-macro confluenc
e-information-macro-warning"><p class="title">Be careful with broker names and
URIs</p><span class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Make sure you do not use any
strange characters in the names of brokers as they are converted to URIs which
<a shape="rect" class="external-link"
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/URI.html";
rel="nofollow">do not allow things like underscores</a> in them
etc.</p></div></div><h2 id="XmlConfiguration-Examples">Examples</h2><p>The
default ActiveMQ configuration: <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/release/conf/activemq.xml";>current
default config</a>.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans
+<div class="wiki-content maincontent"><p>We support an XML deployment
descriptor for configuring the ActiveMQ Message Broker. There are many things
which can be configured such as</p><ul><li><a shape="rect"
href="configuring-version-5-transports.html">transport connectors</a> which
consist of transport channels and wire formats</li><li><a shape="rect"
href="networks-of-brokers.html">network connectors</a> using network channels
or discovery agents</li><li><a shape="rect" href="persistence.html">persistence
providers</a> & locations</li><li>custom message containers (such as last
image caching etc)</li></ul><p>So we decided that using XML would make this
configuration much easier. From version 4.0 onwards we use <a shape="rect"
class="external-link" href="http://xbean.org/"; rel="nofollow">XBean</a> to
perform the XML configuration.</p><p>For details of the XML see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p><parameter
ac:name="title">Be careful with broker
names and URIs</parameter><rich-text-body><p>Make sure you do not use any
strange characters in the names of brokers as they are converted to URIs which
<a shape="rect" class="external-link"
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/URI.html";
rel="nofollow">do not allow things like underscores</a> in them
etc.</p></rich-text-body><h2 id="XmlConfiguration-Examples">Examples</h2><p>The
default ActiveMQ configuration: <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/release/conf/activemq.xml";>current
default config</a>.</p><parameter
ac:name="">xml</parameter><plain-text-body><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.xsd
@@ -181,26 +170,13 @@
Take a look at ${ACTIVEMQ_HOME}/conf/jetty.xml for more details
-->
<import resource="jetty.xml"/>
-</beans></pre>
-</div></div><p>From a binary distribution, from version 1.1 onwards there is
an <em>activemq</em> script allowing you to run a Message Broker as a stand
alone process from the command line easily providing the $ACTIVEMQ_HOME/bin
directory is on your PATH.</p><p><strong>AMQ 4.x</strong></p><p>if myConfig.xml
is in the classpath</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq xbean:myConfig.xml
-</pre>
-</div></div><p>or to use the file path system</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq xbean:file:../conf/myConfig.xml
-</pre>
-</div></div><p><strong>AMQ 3.x</strong></p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq myConfig.xml
-</pre>
-</div></div><p>Or to use the default config file its just</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq
-</pre>
-</div></div><p>If you have a source distribution you can run a broker using
Maven specifying one of these configuration files as follows<br clear="none">
under the assembly module run :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">maven server
-Dconfig=xbean:file:src/release/conf/activemq.xml
-</pre>
-</div></div><p>If your <a shape="rect"
href="initial-configuration.html">classpath is set up correctly</a> you can
achieve the same thing from the command line</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">java org.apache.activemq.broker.Main
xbean:file:src/release/conf/activemq.xml
-</pre>
-</div></div><h2 id="XmlConfiguration-Configuringembeddedbrokers">Configuring
embedded brokers</h2><p>You can also use the XML Configuration to configure <a
shape="rect" href="how-do-i-embed-a-broker-inside-a-connection.html">embedded
brokers</a>. For example using the JNDI configuration mechanism you can do the
following<br clear="none"> <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/java/org/apache/activemq/config/BrokerXmlConfigFromJNDITest.java";>BrokerXmlConfigFromJNDITest</a><br
clear="none"> Or of you want to explicitly configure the embedded broker via
Java code you can do the following<br clear="none"> <a shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/activemq/trunk/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigStartTest.java";>BrokerXmlConfigStartTest</a></p><h2
id="XmlConfiguration-UserSubmittedConfigurations">User Submitted
Configurations</h2><p>We have a p
age which allows users to submit details of their
configurations.</p><ul><li><a shape="rect"
href="user-submitted-configurations.html">User Submitted
Configurations</a></li></ul><h2
id="XmlConfiguration-Background">Background</h2><p>Since ActiveMQ has so many
strategy pattern plugins for transports, wire formats, persistence and many
other things, we wanted to leave the configuration format open so that you the
developer can configure and extend ActiveMQ in any direction you wish.</p><p>So
we use the <a shape="rect" class="external-link"
href="http://www.springframework.org/docs/reference/beans.html#beans-basics";
rel="nofollow">Spring XML</a> configuration file format, which allows any beans
/ POJOs to be wired together and configured. However often Spring's XML can be
kinda verbose at times, so we have implemented an ActiveMQ extension to the
Spring XML which knows about the common, standard ActiveMQ things you're likely
to do (e.g. tags like connector, wireFormat, serverTransport,
persistence) - but at any time you can fall back to the normal Spring way of
doing things (with tags like bean, property etc).</p><p>To see documentation of
the XML file we use or to get access to the XSD/DTD see the <a shape="rect"
href="xml-reference.html">Xml Reference</a></p></div>
+</beans></plain-text-body><p>From a binary distribution, from version
1.1 onwards there is an <em>activemq</em> script allowing you to run a Message
Broker as a stand alone process from the command line easily providing the
$ACTIVEMQ_HOME/bin directory is on your PATH.</p><p><strong>AMQ
4.x</strong></p><p>if myConfig.xml is in the
classpath</p><plain-text-body>activemq xbean:myConfig.xml
+</plain-text-body><p>or to use the file path
system</p><plain-text-body>activemq xbean:file:../conf/myConfig.xml
+</plain-text-body><p><strong>AMQ 3.x</strong></p><plain-text-body>activemq
myConfig.xml
+</plain-text-body><p>Or to use the default config file its
just</p><plain-text-body>activemq
+</plain-text-body><p>If you have a source distribution you can run a broker
using Maven specifying one of these configuration files as follows<br
clear="none"> under the assembly module run :</p><plain-text-body>maven server
-Dconfig=xbean:file:src/release/conf/activemq.xml
+</plain-text-body><p>If your <a shape="rect"
href="initial-configuration.html">classpath is set up correctly</a> you can
achieve the same thing from the command line</p><plain-text-body>java
org.apache.activemq.broker.Main xbean:file:src/release/conf/activemq.xml
+</plain-text-body><h2
id="XmlConfiguration-Configuringembeddedbrokers">Configuring embedded
brokers</h2><p>You can also use the XML Configuration to configure <a
shape="rect" href="how-do-i-embed-a-broker-inside-a-connection.html">embedded
brokers</a>. For example using the JNDI configuration mechanism you can do the
following<br clear="none"> <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/java/org/apache/activemq/config/BrokerXmlConfigFromJNDITest.java";>BrokerXmlConfigFromJNDITest</a><br
clear="none"> Or of you want to explicitly configure the embedded broker via
Java code you can do the following<br clear="none"> <a shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/activemq/trunk/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigStartTest.java";>BrokerXmlConfigStartTest</a></p><h2
id="XmlConfiguration-UserSubmittedConfigurations">User Submitted
Configurations</h2><p>We ha
ve a page which allows users to submit details of their
configurations.</p><ul><li><a shape="rect"
href="user-submitted-configurations.html">User Submitted
Configurations</a></li></ul><h2
id="XmlConfiguration-Background">Background</h2><p>Since ActiveMQ has so many
strategy pattern plugins for transports, wire formats, persistence and many
other things, we wanted to leave the configuration format open so that you the
developer can configure and extend ActiveMQ in any direction you wish.</p><p>So
we use the <a shape="rect" class="external-link"
href="http://www.springframework.org/docs/reference/beans.html#beans-basics";
rel="nofollow">Spring XML</a> configuration file format, which allows any beans
/ POJOs to be wired together and configured. However often Spring's XML can be
kinda verbose at times, so we have implemented an ActiveMQ extension to the
Spring XML which knows about the common, standard ActiveMQ things you're likely
to do (e.g. tags like connector, wireFormat, serverTran
sport, persistence) - but at any time you can fall back to the normal Spring
way of doing things (with tags like bean, property etc).</p><p>To see
documentation of the XML file we use or to get access to the XSD/DTD see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p></div>
</td>
<td valign="top">
<div class="navigation">
