...

QMan : Qpid Management Bridge

QMan is a Management bridge that exposes one (or several) Qpid broker domain model as MBeans that are accessible through the management bridge for Qpid. It allows external clients to manage and monitor one or more Qpid brokers.

QMan exposes the broker management interfaces using Java Management Extensions (JMX).

How to run QMan

Prerequisites

QMan is a standalone application that is packaged as qpid-management-client-incubating-M3.jar. To run QMan you need to add the following jars in your CLASSPATH:

• log4j-1.2.12.jar
• slf4j-api-1.4.0.jar
• slf4j-log4j12-1.4.0.jar
• commons-pool-1.4.jar
• commons-codec-1.3.jar
• commons-lang-2.2.jar
• commons-collections-3.2.jar
• commons-configuration-1.2.jar
• qpid-client-incubating-Mx.jar (were x is the current qpid version)
• qpid-common-incubating-Mx.jar (were x is the current qpid version)

alternatively you can run the following script (that add all the qpid jars to the CLASSPATH):
> CLASSPATH=`find <lib-root> -name '*.jar' | tr '\n' ":"`
Where <lib-root> is the directory containing the qpid jars (when qpid is built from source <lib-root> is equal to qpid/java/build/lib)

QMan can be connected at run time against any broker. However if you wish to automatically connect to one or several brokers you can do so by providing a configuration file as follows:

<configuration>
  <brokers>
	<broker>
	  <host>localhost</host>
	  <port>5672</port>
	  <virtual-host>test</virtual-host>
	  <user>guest</user>
	  <password>guest</password>
	  <max-pool-capacity>4</max-pool-capacity>
	  <initial-pool-capacity>0</initial-pool-capacity>
	  <max-wait-timeout>-1</max-wait-timeout>
	</broker>
        <broker>
	  <host>myhost</host>
	  <port>5672</port>
	  <virtual-host>test</virtual-host>
	  <user>guest</user>
	  <password>guest</password>
	  <max-pool-capacity>4</max-pool-capacity>
	  <initial-pool-capacity>0</initial-pool-capacity>
	  <max-wait-timeout>-1</max-wait-timeout>
	</broker>
  </brokers>
</configuration>

The configuration above specifies that QMan should connect to two brokers, one on localhos and one on myhost, both listening on port 5672.

The configuration file to use is specified through the JVM parameter "qman-config" that must point onto a valid configuration file.

Running QMan

To run QMan in a console run the following command:

java org.apache.qpid.management.domain.services.QMan

Messages similar to those should be displayed:

... [org.apache.qpid.management.domain.services.QMan] <QMAN-000001> : Starting Q-Man...
...
Type "q" to quit.

if you wish to use a configuration file <home>/myconfiguration.xml so QMan establishes a connection with one or several brokers, run the following command:

java -Dqman-config="<home>/myconfiguration.xml" org.apache.qpid.management.domain.services.QMan

Stopping QMan

Type "q" In the console from which QMan has been started.

Browsing Manageable Beams

The jconsole tool (JMX-compliant graphical tool for monitoring a Java virtual machine) can be used for monitoring and QMan Mbeans. for more information see http://java.sun.com/javase/6/docs/technotes/guides/management/jconsole.html

The jconsole executable can be found in JDK_HOME/bin, where JDK_HOME is the directory in which the JDK software is installed. If this directory is in your system path, you can start JConsole by simply typing jconsole in a console. Otherwise, you have to type the full path to the executable file.

As jconsole needs to perform operations invocation you will need to add the QMan jar in jconsole classpath. In a console type:

jconsole -J-Djava.class.path=$CLASSPATH:$JAVA_HOME/lib/jconsole.jar:$JAVA_HOME/lib/tools.jar

Where CLASSPATH contains the QMan jars and JAVA_HOME point on your JDK home.

As demonstrated on the following screenshot, once jconsole is running select the MBeans tab and select the Q-MAN set of MBeans.

 Image Removed

The screenshot above depicts the value of a queue attributes.

Invoking Operations

jconsole can be used for invoking operations. For example, the following screshot shows the queue message_queue attributes.

Image Removed

We can see that 22 messages have been enqueued when only 11 messages have been dequeued. This means that message_queue contains 11 messages. Let's delete 5 of them! For doing that we must select the operation purge of the queue message_queue. The following screeshot shows that the operation purge has one parameter that specify the number of messages to be discarded.

Image Removed

We invoke the purge operation with 5 messages. The following popup window tells us that the operation has been successfully invoked.

Image Removed

We can now check that 5 messages have been dequeued form message_queue. The following screenshot shows the updated attributes of message_queue.

Image Removed

As shown above there are now 16 messages that have been dequeued.

Deploying the QMan servlet

QMan comes with a servlet that can be deployed in any application server. In the following we show how to deploy the qman servlet within JBoss application server.

Prerequisites

You mus install JBoss:

• Download the latest stable version from: http://www.jboss.org/jbossas/downloads/
• Unzip the download archive in <jboss-home>

Deploying the QMan servlet within JBoss

First you need to copy the provided qman.war in <jboss-home>/server/default/deploy/ (note that you can use another server configuration like for example minimal)

Then run JBoss:

• Add the following option-Djboss.platform.mbeanserver to JAVA_OPTS (for example: export JAVA_OPTS=-Djboss.platform.mbeanserver)
• Execute <jboss-home>/binrun.sh (or run.bat on a windows platform)

Notes:

• If you wish to configure QMan via a configuration file so QMan establishes a connection with one or several broker at starting time then add the options -Dqman-config=myconfigFile.xml to JAVA_OPTS.
• When Qpid is built form source, the war archive qman.war is located in qpid/java/build/management/client/servlet

The following screenshot is a view on the queue message_queue obtained form the JBoss JMX viewer.

) and / or OASIS Web Services Distributed Management (WSDM). While the first one is supposed to be used by java based clients only the latter is an interoperable protocol that enables management clients to access and receive notifications of management-enabled resources using Web Services.

QMan can be easily integrated in your preexisting system in different ways :

• As a standalone application : in this case it run as a server. More specifically it enables communication via RMI (for JMX) or via HTTP (for WS-DM); Note that when the WS-DM adapter is used the JMX interface is not exposed;
• As a deployable unit : it is also available as a standard Java web application (war); This is useful when there's a preexisting Application Server in your environment and you don't want start another additional server in order to run QMan.

User Documentation

With "User Documentation" we mean all information that you need to know in order to use QMan from a user perspective. Those information include :

• Get me up and running
• User Guide

The first one is a brief quick start guide in order to get QMan up and running; the User Guide describes QMan module with its features from a functional perspective.

If you don't know where to start from, please consider having a look at the User Guide first in order to get a big picture about how things are working.

Technical Documentation

If you are interested in technical details about QMan and related technologies this is a good starting point. In general this section provides information about QMan design, interfaces, patterns and so on...

• QMan design
• JMX interface
• WS-DM interface

...