The ActiveMQ Provider

The Fabric3 ActiveMQ extension provides connectivity to ActiveMQ brokers for the JMS binding. Two modes are supported: connecting to an external broker (or cluster); and running an embedded broker. An external broker setup is recommended for production use.

Connecting to an External Broker

To connect to an external broker, the ActiveMQ embedded broker must be disabled and an ActiveMQ connection factory must be configured in the runtime systemConfig.xml. The following illustrates how disable the embedded broker and create a connection factory (ConnectionFactory1) that connects to the default ActiveMQ broker configuration:

<jms>
   <activemq broker.disabled="true"/>
   <connection.factories>
      <connection.factory name="ConnectionFactory1" broker.url="tcp://localhost:61616" type="xa"/>
   </connection.factories>
</jms>

Valid ActiveMQ broker URL schemes are supported. The type attribute indicates the connection factory type to create: XA, local, or pooled.

The connection factory can then be used by a JMS binding configuration in a composite as follows:

<channel name="TestChannel">
   <binding.jms>
      <connectionFactory jndiName="ConnectionFactory1"/>
      <destination jndiName="TestTopic"/>
   </binding.jms>
</channel>

If a topic or queue does not exist, the default behavior is to create it on the broker.

Default XA and non-XA connection factories can be setup in systemConfig.xml. If no connection factory is specified in a binding configuration, either the default XA or non-XA factory will be used depending on whether global or local transacted messaging is required for a particular operation. Below is an example of how to set up default ActiveMQ connection factories:

<jms>
   <connection.factories>
      <connection.factory name="xaDefault" broker.url="vm://broker" type="xa"/>
      <connection.factory name="default" broker.url="vm://broker"/>
   </connection.factories>
</jms>

Using the Embedded External Broker

ActiveMQ brokers can be hosted in Fabric3 to provide distributed messaging capabilities between runtimes. The broker infrastructure is integrated with the JMS binding to enable automated creation configuration of JMS queues and topics.

ActiveMQ connection factories are configured in the runtime systemConfig.xml using the in-process broker URL as follows:

<jms>
   <connection.factories>
      <connection.factory name="TheFactory" broker.url="vm://broker" type="xa"/>
   </connection.factories>
</jms>

The connection factories can then be used in binding configurations as illustrated below:

<component name="TheComponent">
   <implementation.java .../>
   <reference name="service">
      <binding.jms>
         <connectionFactory name="TheFactory"/>
         <destination name="ServiceQueue"/>
      </binding.jms>
   </reference>
</component>

Configuring the Embedded ActiveMQ Broker

The default configuration using by the embedded ActiveMQ broker may be overridden in systemConfig.xml to specify custom ActiveMQ network and transport connectors:

<jms>
   <active.mq>
      <networkConnectors>
         <networkConnector uri="multicast://default"/>
      </networkConnectors>
      <transportConnectors>
         <transportConnector name="openwire" uri="tcp://localhost:61616"/>
      </transportConnectors>
   </active.mq>
</jms>

Configuring Connection Templates

The ActiveMQ extension supports configuring connection factory templates. Connection factory templates are primarily used with durable topic subscriptions, which require unique client identifiers. Templates are specified in systemConfig.xml:

<jms>
   <connection.factory.templates>
      <connection.factory name="TheTemplate" broker.url="vm://broker" type="xa"/>
   </connection.factory.templates>
</jms>

Templates are specified on the JMS binding using the connectionFactory.template attribute on the binding.jms element:

<component name="TheComponent">
   <implementation.java .../>
   <reference name="service">
      <binding.jms connectionFactory.template="TheTemplate>
         <destination name="ServiceQueue"/>
      </binding.jms>
   </reference>
</component>

When a template is specified, the runtime will create a new connection factory based on the template configuration and use it to connect to the ActiveMQ broker.

Binding.SCA

In addition, the ActiveMQ extension is also a binding.sca provider. This means components can be wired and connected to remote channels without configuring transports or physical endpoint information – basically as if they were components locally wired. The ActiveMQ extension will manage queue setup and connections transparently.

Connection factories can be configured for use with binding.sca in systemConfig.xml using the binding.sca element. Specifically, the xa.factory and factory attributes point to an XA and non-XA connection factory configuration. When binding.sca is use for a wire or remote channel either the XA or non-XA connection factory will be used. The following demonstrates how to configure the binding.sca connection factories:

<jms>
   <connection.factories>
      <connection.factory name="xaFactory" broker.url="vm://broker" type="xa"/>
      <connection.factory name="nonXaFactory" broker.url="vm://broker" type="local"/>
   </connection.factories>

   <binding.sca xa.factory="xaFactory" factory= "nonXaFactory"/>
</jms>