FAQ for Open Message Queue and HermesJMS integration related issues Cannot resolve external resource into attachment. If you are interested in contributing to this FAQ, please read the Contribution Guidelines.
Q: What is HermesJMS ?
A: HermesJMS is a tool that you can use to inspect a JMS Provider (for example, the Open Message Queue broker). It provides a graphical tool that allows you to browse topics and queues, view contents of messages, copy and/or delete messages. Here is the link to the HermesJMS project website.
Q: What can I do with HermesJMS with respect to Open Message Queue ?
A: We haven't explored all the features of HermesJMS, but we have done the basic operations such as:
- Connect to a broker (or several brokers simultaneously)
- View messages in specific destinations in a broker. All the headers and properties in a destination can be examined.
- Delete messages in a destination.
- Copy messages from a destination in a broker to a local store (an XML file defined by HermesJMS)
- Copy messages from a destination (or local HermesJMS store) to another destination on the same or another broker.
HermesJMS performs the above operations by accessing the broker using the standard JMS API. This means that the above basic operations can be done out of the box without any special plugin.
Q: Can HermesJMS be used to connect to a broker running remotely (not on localhost) ?
A: Yes. See the FAQ item: 'What are the setup or configuration steps for HermesJMS so that it can be used with Open Message Queue?' There are a couple of ways to configure HermesJMS to connect to a broker running remote.
- Configuring via JNDI.
- Using a HermesJMS/MQ plugin
At this time, these are the only methods of connecting to a broker remotely with HermesJMS. If you know of another way to get this to work, please let us know at [users@mq.java.net].
Q: What are the setup or configuration steps for HermesJMS so that it can be used with Open Message Queue ?
A: There are 2 ways to configure HermesJMS to connect to the Open Message Queue broker:
- Configuring 'manually', which involves choosing which connection factory object class to use
- Configuring via JNDI, which involves referring to an existing Open Message Queue JNDI object store containing connection factory and destination objects.
Regardless of the method chosen above, a HermesJMS 'Classpath Group' needs to be created - this is a class loader which loads the jar files containing Open Message Queue client runtime classes needed by HermesJMS (or any normal JMS client for that matter) to access the broker.
The following instructions were done using HermesJMS 1.1.3 and Open Message Queue 4.3. If there are any issues with these instructions, please let us know via email at [users@mq.java.net]
Creating Open Message Queue Classpath Group
The following instructions are for configuring HermesJMS using the 'manual' approach and it allows HermesJMS to connect to a broker running on the local host on the default port, 7676.
Launch HermesJMS
The following window will appear:
Select the menu item Options->Configuration. A dialog titled 'Preferences' will appear. It has various tabs at the bottom labeled 'Sessions', 'Providers', and so on. Select the tab labeled 'Providers'.
Right click on the Classpath Groups pane to popup a menu and select 'Add Group'.
Enter a name e.g. 'OpenMQ'. An entry named 'OpenMQ' will appear. It has one item named 'Library'. Right click on 'Library' and select 'Add JAR(s)'.
Navigate to where you installed Open Message Queue and select imq.jar and fscontext.jar. For Open Message Queue 4.3 on Windows, this is located by default at:
C:\Program Files\Sun\MessageQueue\mq\lib\imq.jar
C:\Program Files\Sun\MessageQueue\mq\lib\fscontext.jar
A dialog appears asking if it is OK for HermesJMS to scan the selected jars for connection factories - select 'Scan'.
The 'Preferences' dialog should now look something like the following:
Hit the OK button to save out the new classpath group.
Configuring HermesJMS Manually
On the main HermesJMS window, select the 'sessions' node and right click to bring up the popup menu. Select the submenu 'New' and proceed to select 'New Session...'. Note: On some platforms, this popup menu is not enabled for some reason. You can perform the same task by selecting from the main toolbar: Actions->New->New Session...
The same preferences dialog as before is displayed, showing the 'Sessions' tab with 'new' as the new session name. Replace this default name with 'OpenMQ'. A connection factory has to be chosen for this new session.
First, choose the class loader we created earlier (the one that knows about imq.jar and fscontext.jar) - on the 'Connection Factory' pane, select 'OpenMQ' for the Loader.
On the same pane, the 'Class' option menu lists the connection factory classes that are available for the class loader selected. Select 'com.sun.messaging.ConnectionFactory'.
Select the OK button to complete the creation of the 'OpenMQ' session.
On the main window, there should be a new 'OpenMQ' item under the 'session' node. Right click on it and select the 'New' submenu and from there, select 'Add queue'.
The destination properties dialog should appear. Enter 'SimpleQueue' for the queue Name and hit return. Hit the OK button.
On the main window, the 'OpenMQ' session should show 'SimpleQueue' as one of it's children (along with examples.xml and fix.xml which you can delete). At this point, if a broker is running on the same host as HermesJMS and it has a queue destination named 'SimpleQueue', you can browse it's content by double clicking on the 'SimpleQueue' node:
Configuring HermesJMS Using JNDI
The following instructions are for configuring HermesJMS using the 'JNDI' approach. It allows HermesJMS to connect to any broker as specified by the connection factories in the Open Message Queue JNDI object repository used. These steps assume an object repository exists at the location
The high level steps involved in creating this Open Message Queue object store are:
- Create directory C:\openmqobjstore
- Use imqadmin or imqobjmgr to create the following objects in the object store at C:\openmqobjstore
| Lookup name |
Object type |
Attributes |
| someotherhost:7676 |
Connection Factory |
Message Server Address List = someotherhost:7676 |
| SomeOtherQueue |
Queue destination |
Destination Name = SomeOtherQueue |
Documentation on how to create an Open Message Queue object store using the GUI tool imqadmin can be found at: Open Message Queue Administration Guide: Working With Object Stores
Alternatively, you can run the command line tool imqobjmgr using the following command files. The command files can be edited (if needed) to specify the actual hosts and destination names desired.
| imqobjmgr command file |
Notes |
| add_cf.props |
Used to create connection factory object. Host/port of broker specified via the line 'obj.attrs.imqAddressList=someotherhost:7676'. |
| add_q.props |
Used to create queue destination object. Destination type specified via the line 'obj.type=q'. Destination name specified via the line 'obj.attrs.imqDestinationName=SomeOtherQueue'. |
Example usage:
imqobjmgr -i add_cf.props
imqobjmgr -i add_q.props
On the main HermesJMS window, right click on the 'contexts' node and select 'New->New Context...'. Name the context OpenMQObjStore.
A 'JNDI InitialContext' dialog appears and you can enter the new context's properties. Enter the following properties:
| Property |
Value |
| loader |
OpenMQ |
| initialContextFactory |
com.sun.jndi.fscontext.RefFSContextFactory |
| providerURL |
file:///C:/openmqobjstore |
Hit OK to complete the creation of this new context. The 'contexts' node on the HermesJMS main window should have a new child element labeled 'OpenMQObjStore'. Double click on 'OpenMQObjStore' - this should show the contents of the Open Message Queue object repository at C:/openmqobjstore (this assumes of course that it was set up in advance). The one used in this example shows 2 objects: a queue destination object with lookup name 'SomeOtherQueue' and a connection factory object with lookup name 'someotherhost:7676'.
Right click on 'someotherhost:7676' (or whatever connection factory you wish to use in your object store) and select 'Create new session...'.
A dialog will appear, prompting for the name of this new session. Enter 'OpenMQ-JNDI'.
A new item should appear under the 'sessions' node in the HermesJMS main window.
Using the same pane showing the contents of the JNDI object store, right click on 'SimpleQueue' (or whatever destination object in your object store) and select 'Addto->OpenMQ-JNDI'.
A new destination labeled 'SomeOtherQueue' should appear under the 'OpenMQ-JNDI' session. If the broker as defined by the 'someotherhost:7676' connection factory is running and it has a queue destination named 'SomeOtherQueue', you can examine it's contents by double clicking on 'SomeOtherQueue' (under the 'OpenMQ-JNDI' session) in the main HermesJMSWindow.
Using the HermesJMS/MQ Plugin You may use a HermesJMS/MQ Plugin to connect to any broker. To get this to work you will need to:
- Download the HermesJMS/MQ Plugin.
- Compile the source with lib.weaved/hermes.jar and imq.jar in your classpath.
- Build a hermes-imq.jar containing ch/post/it/common/ids/hermes/imq/*.class and hermes/impl/confighelp.properties
- Place the hermes-imq.jar into the HermesJMS lib.weaved directory.
- Modify the hermes.sh or hermes.bat scripts to insert hermes-imq.jar before hermes.jar. I modified the actual JAVACMD line to change "-classpath $LOCALCLASSPATH" to "-classpath <HermesJMS>/lib.weaved/hermes-imq.jar:$LOCALCLASSPATH". Setting LOCALCLASSPATH to include hermes-imq.jar does not insert it before hermes.jar.
- Detailed nstructions to configure HermesJMS to pick up the MQ Plugin are under the doc/ directory of the plugin.
Q: Is there a HermesJMS plugin for Open Message Queue ?
A: Yes, there is a HermesJMS plugin for Open Message Queue. If you know of others, please let us know at [users@mq.java.net].
There are some operations/features in HermesJMS that cannot be done via the standard JMS API. For example, obtaining the list of destinations on the broker and various statistics on them. To enable this functionality in HermesJMS, a plugin needs to be developed (that uses Open Message Queue specific APIs). Until then, to inspect the destinations on a broker, one has to know the exact names and types of the destinations.
An Open Message Queue plugin for HermesJMS is one of the things that our team has on the list of things to do for the future. Any update on that work will be mentioned in this FAQ/web page. Q: I followed the manual setup instructions, but I can't see my destinations after I try to add them. What's up?
A: There are some eccentricities of the HermesJMS UI. Be sure to use the "Return" or "Enter" key after you enter each item in the UI (i.e. the Queue Name or the Topic Name). If you just click the "OK" button, your entry might not register correctly.
|
new_session_choose_loader.gif (image/gif)
