THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Archive Content
Please note this page is present for reference only. QMan has been removed and is no longer a released component.
Get me up and running
Get me up...
This section describes how to install QMan.
Prerequisites
QMan only runs with Java 5 or later. Java 6 is reccomended for the best performance.
Installation
First of all, download the distribution from here and then unzip the archive into your chosen directory. Now you should have a directory structure like this :
- bin : This contains the scripts needed to run QMan (see below for further details).
- lib : This contains jars needed to run QMan (core libraries and dependencies).
- log : This will contain the QMan log (see below for further details)
That's all! Please proceed to the next section in order to see how to run & configure QMan.
...and running
You can have QMan running in the following three different ways explained below; feel free to choose the way that best fits your needs...
JMX Bridge (Standalone)
This is a standalone RMI server that is able to expose Qpid broker management interface using JMX. As conseguence of that, any Java based (management) client will be able, using JMX API, to remotely view the broker domain model, its properties, statistics and to invoke operations exposed by the management interface.
Configuration
QMan JMX Bridge needs two configuration files : qman-config.xml (optional) and log4j.xml. The first one is optional and must be used when if you wish to automatically connect to one or several brokers at startup; the log4j.xml configure logging.
qman-config.xml
Schema for this configuration file is very simple and for a better understanding let's start with an example :
<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>
- host : the hostname where the broker is running;
- port : the port where the broker is running;
- virtual-host : the virtual host as defined on the remote broker;
- user : the username used for estabilish connection;
- password : the password used for estabilish connection;
- max-pool-capacity : the maximum number of physical connections that the broker connection pool can contain;
- initial-pool-capacity : the number of physical connections to create when creating broker connection pool;
- max-wait-timeout : the maximum amount of time that a client will wait for obtaining a connection; a value of -1 means "Wait forever!".
The configuration in the example above specifies that QMan should connect to two brokers, one on localhost and one on myhost, both listening on port 5672. If you don't want connect QMan with any broker (at startup) simply leave this file empty (or without any <broker> declaration).
log4j.xml
For detailed information about how to configure log4j.xml please refer to http://logging.apache.org/log4j/1.2/manual.html
Run
To run QMan open up a shell / command prompt on 'bin' directory. After that execute ./qman-jmx-start.sh or qman-jmx.start.cmd (windows). You should see the following output on the /log/qman.log file :
2009-01-08 10:04:12,253 INFO [QMan] <QMAN-000001> : Starting Q-Man... 2009-01-08 10:04:12,253 INFO [QMan] <QMAN-000002> : Reading Q-Man configuration... ... ... ... 2009-01-08 10:04:12,847 INFO [QMan] <QMAN-000023> : Q-Man service is now available on MBeanServer. 2009-01-08 10:04:12,957 INFO [QMan] <QMAN-000019> : Q-Man open for e-business.
Stop
Simply type "q" in the shell / command prompt from which QMan has been started.
Example : using JConsole as management client
The jconsole tool (http://java.sun.com/javase/6/docs/technotes/guides/management/jconsole.html) can acts as QMan client, allowing you to browse and interact with QMan exposed MBeans.
Remember, we are using RMI as communication protocol and therefore you need to add to JConsole classpath the QMan "client" classes.
Those classes are contained on $QMAN_HOME/lib/qpid-management-client-$Version.jar. So at the end command line for running JConsole should look like this :
jconsole -J-Djava.class.path=$CLASSPATH:$JAVA_HOME/lib/jconsole.jar:$JAVA_HOME/lib/tools.jar
Where CLASSPATH contains the mentioned QMan jar and JAVA_HOME point on your JDK home.
When JConsole appears you can find QMan MBeans under the "MBeans" tab, Q-MAN domain.
WS-DM Bridge
QMan WS-DM Bridge is a HTTP server that acts as a WS-DM Adapter and enables broker remote management using this interoperable protocol. Briefly, let's say that broker management interface is exposed as a WS-Resources domain.
Configuration
QMan WS-DM Bridge needs three configuration files : qman-config.xml (optional), log4j.xml and jetty.xml. As the JMX version the qman-config.xml is optional while the other two are required. Specifically, jetty.xml is used for HTTP Server / Servlet Engine configuration and, unless you need an advanced configuration for web server, you can leave it as is.
qman-config.xml
For detailed informatiom about this file please refer to the corresponding QMan JMX section before.
log4j.xml
For detailed information about how to configure log4j.xml please refer to http://logging.apache.org/log4j/1.2/manual.html
jetty.xml
QMan WS-DM uses Jetty as Web Server / Servlet Container. Detailed information on how to configure this module can be found at http://docs.codehaus.org/display/JETTY/Configuring+Jetty)
Run
To run QMan open up a shell / command prompt on 'bin' directory. After that execute ./qman-wsdm-start.sh or qman-wsdm.start.cmd (windows).
You should see the following output on the /log/qman.log file :
2009-01-08 10:04:12,253 INFO [QMan] <QMAN-000001> : Starting Q-Man... 2009-01-08 10:04:12,253 INFO [QMan] <QMAN-000002> : Reading Q-Man configuration... ... ... ... 2009-01-08 10:04:12,847 INFO [QMan] <QMAN-000023> : Q-Man service is now available on MBeanServer. 2009-01-08 10:04:12,957 INFO [QMan] <QMAN-000019> : Q-Man open for e-business. 2009-01-08 10:04:26,502 INFO [WSDMAdapter] <QMAN-000026> : Initializing WS-DM Adapter Environment... 2009-01-08 10:04:27,455 INFO [WSDMAdapter] <QMAN-000027> : WS-DM Adapter ready for incoming requests.
and this should be (moreless) the content of the /log/server.log:
2009-01-08 10:04:10,660 INFO [log] Logging to org.slf4j.impl.Log4jLoggerAdapter(org.mortbay.log) via org.mortbay.log.Slf4jLog 2009-01-08 10:04:10,832 INFO [log] Extract jar:file:/.../qman.war!/ to /.../Jetty_0_0_0_0_8080_qman.war__qman__j84idd/webapp 2009-01-08 10:04:11,957 WARN [log] Unknown realm: default 2009-01-08 10:04:13,191 INFO [log] Started SelectChannelConnector@0.0.0.0:8080
Stop
To run QMan open up a shell / command prompt on 'bin' directory and execute ./qman-wsdm-stop.sh or qman-wsdm-stop.cmd (windows). You should see the following output on the shell :
QMan WS-DM Adapter shut down successfully.
the following on the /log/qman.log:
2009-01-09 15:37:32,589 INFO [QMan] <QMAN-000020> : Shutting down Q-Man... 2009-01-09 15:37:32,589 INFO [QMan] <QMAN-000021> : Q-Man shut down.
and the following on /log/server.log:
2009-01-09 15:36:15,444 INFO [log] Shutdown hook executing 2009-01-09 15:36:15,444 INFO [log] Shutdown hook complete
WS-DM Bridge with a preexisting Application Server
QMan WS-DM Adapter is basically a JEE standard web application. You can find the archive under the $QMAN_HOME/lib directory; it is the qman.war file.
So, generally speaking, you can get that archive and deploy it on your preferred Application Server that is J2EE 1.4 (or later) compliant.
This kind of installation (deployment) is in general useful when there's already a Web Server in your environment.
The following is a list of servers where QMan can de deployed :
- JBoss 4.2.x;
- BEA Weblogic Server 9.x;
- BEA Weblogic Server 10;
- IBM WebSphere 7.x;
- Apache Tomcat 5.x;
- Jetty 6.x
Configuration
In this scenario we are working with a third-party middleware so basically the only thing that you can configure is the qman-config.xml (see above for details).
Note that the location of the configuration file must be passed as a JVM parameter from the start command line of the server:
... java -Dqman-config=<complete path to qman-config.xml> ...
If you don't have permission to edit the server startup script please read the User Guide in order to see how to connect QMan with broker(s) at runtime.