This article applies to ActiveMQ version 5.4.0 or newer. If you use an older version proceed to the following article.

Introduction

All ActiveMQ modules are packaged as OSGi bundles and can be used in any OSGi container. This article will provide more details on how to use ActiveMQ in Apache Karaf, small OSGi based runtime. Apache Karaf was previously know as ServiceMix kernel, so informations found here are applicable to Apache ServiceMix Enterprise Service Bus as well.

Procedures described in this article requires Apache Karaf 2.0.0 or newer

Installation

ActiveMQ provides Karaf features which will help you integrate and use the broker in OSGi environment. For starters you need to add the features URL to Karaf. For version 5.4.0 you can do it like this

karaf@root> features:addUrl mvn:org.apache.activemq/activemq-karaf/5.4.0/xml/features

After that you should see newly added features

karaf@root> features:list
State         Version         Name                 Repository
[uninstalled] [3.0.3.RELEASE] spring               karaf-2.0.0
[uninstalled] [1.2.0        ] spring-dm            karaf-2.0.0
[uninstalled] [2.0.0        ] wrapper              karaf-2.0.0
[uninstalled] [2.0.0        ] obr                  karaf-2.0.0
[uninstalled] [2.0.0        ] http                 karaf-2.0.0
[uninstalled] [2.0.0        ] war                  karaf-2.0.0
[uninstalled] [2.0.0        ] webconsole           karaf-2.0.0
[installed  ] [2.0.0        ] ssh                  karaf-2.0.0
[installed  ] [2.0.0        ] management           karaf-2.0.0
[uninstalled] [5.4-SNAPSHOT ] activemq             activemq-5.4-SNAPSHOT
[uninstalled] [5.4-SNAPSHOT ] activemq-spring      activemq-5.4-SNAPSHOT
[uninstalled] [5.4-SNAPSHOT ] activemq-blueprint   activemq-5.4-SNAPSHOT
[uninstalled] [5.4-SNAPSHOT ] activemq-web-console activemq-5.4-SNAPSHOT

From this point on you can choose to install ActiveMQ with Spring or Blueprint support, by doing

karaf@root> features:install activemq-spring

or

karaf@root> features:install activemq-blueprint

respectively.

Commands

After these simple steps you have all necessary libraries installed in the container. Also, now you have specific commands on your disposal that you can use to manage your broker:

  browse                Display selected messages in a specified destination
  bstat                 Displays useful broker statistics
  create-broker         Creates a broker instance.
  destroy-broker        Destroys a broker instance.
  list                  Lists all available brokers in the specified JMX context
  purge                 Delete selected destination's messages that matches the message selector
  query                 Display selected broker component's attributes and statistics

Help on commands
To obtain some detailed help on a given command, you can run:

activemq:[command] --help

Broker creation

By default, no broker is created, but the following command can be used to create one:

karaf@root> activemq:create-broker
Creating file: xxx/deploy/localhost-broker.xml

Default ActiveMQ Broker (localhost) configuration file created at: xxx/deploy/localhost-broker.xml
Please review the configuration and modify to suite your needs.

It creates a broker with a sensible default configuration, but you can easily edit the mentioned file to modify the broker's configuration. Along with the broker, a pooled JMS ConnectionFactory is registered in OSGi and the broker is integrated with the transaction manager embedded in ServiceMix. The broker is also registered in the local JMX mbean server.

If you want to create multiple brokers, you need to give them some names. This can be done this way:

karaf@root> activemq:create-broker --name mybroker 
Creating file: xxx/deploy/mybroker-broker.xml

Default ActiveMQ Broker (mybroker) configuration file created at: xxx/deploy/mybroker-broker.xml
Please review the configuration and modify to suite your needs.

By default the command will use Spring configuration. If you want to use Blueprint configuration use

karaf@root> activemq:create-broker --type blueprint

Broker destruction

To remove an existing broker, simply run the following command:

karaf@root> activemq:destroy-broker

Default ActiveMQ Broker (localhost) configuration file created at: xxx/deploy/localhost-broker.xml removed.

To destroy a named broker, run the following command:

karaf@root> activemq:destroy-broker --name mybroker

Default ActiveMQ Broker (localhost) configuration file created at: xxx/deploy/mybroker-broker.xml removed.

Broker querying

Several commands are available to query the broker. To address local brokers, you need to use the --jmxlocal parameter.

The following command displays available brokers:

karaf@root> activemq:list --jmxlocal
BrokerName = mybroker

To have more detailed informations, run:

karaf@root> activemq:query --jmxlocal

It will display informations about the connectors, list of queues, etc...

You can also browse or purge queues using the activemq:browse and activemq:purge commands.

Web Console

Web Console is included in ActiveMQ distribution and you'll probably want to have it installed in Karaf as well to monitor your broker.

In order to use web console you need first to install war feature

karaf@root> features:install war

Now you can do something like:

karaf@root> features:install activemq-web-console

This will install and start the web console (with embedded broker), which you can use at

http://localhost:8181/activemqweb/

Web console can fail to start if you have another broker already running in the container

There a big chance that you don't want to monitor an embedded broker, but the broker you have started separately (in the OSGi runtime or elsewhere). To configure your web console to do that, you have to do the following. First, exit your OSGi runtime. Now edit the etc/system.properties file and add some configuration details. The following configuration snippet

webconsole.type=properties
webconsole.jms.url=tcp://localhost:61616
webconsole.jmx.url=service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root
webconsole.jmx.user=karaf
webconsole.jmx.password=karaf

should work fine with default broker started in the Karaf (ServiceMix). Adapt it to your specific needs. When you start you container again, the web console should be monitoring the remote broker.