Skip to main content

HermesJMS connecting to MQ 8+

I have naturally looked over a number of blogs and forums on this subject whilst attempting to set this up, but I have yet to see a complete set of instructions. There always seems to be a corner cut somewhere. Naturally, I don't want to bunk this trend, but hopefully, I will cut one or two less corners.

Having said that, I do not intend to cover MQ or HemesJMS (nor indeed any of the other topics that arise, such as PKI/SSL) in any more depth than is required to specifically set up their connections. I am happy to cover these (with the exception of HermesJMS, which I know little of) in later posts.

Happy reading! ...

First of all, I did this within SoapUI 5.3 with the embedded HermesJMS. This was a Windows install of SoapUI, but I expect both the SoapUI and HermesJMS specific instructions will translate fairly well on to UNIX.

Secondly, in the spirit of my opening paragraph I am going to do this over SSL. I will use server authentication only (and not mutual authentication) - however, mutual authentication  simply requires a key store which is set in exactly the same way as the trust store (minor googlable differences in the Java system property names) and SSLCAUTH set on the server connection channel.

To carry this out, you will minimally need HeremesJMS and the MQ 8 or above client installed on the client machine.

1) Within the SoapUI install directory, you will find a sub-directory called HermesJMS\bin.

In that directory there is a batch file called hemes.bat. Edit this to set 3 things:

- The JRE binary directory in the system PATH, e.g.

set PATH=C:\Program Files\IBM\MQ\java\jre\bin;%PATH%

- The Java home directory, e.g.

set JAVA_HOME=C:\Program Files\IBM\MQ\java\jre\

- Any required system options for the JVM (e.g. trust/key store), e.g.

start "HermesJMS" "%JAVA_HOME%\bin\javaw" -XX:NewSize=256m -Xmx1024m -Dhermes.home="%HERMES_HOME%" %HERMES_OPTS%\ssl\keyStore.jks  ...

(assume ... is the rest of the usual options found in the batch file)

You will notice that I have chosen to use the MQ JRE above - or more specifically IBM Java 8. This is for two reasons; it is compatible with HermesJMS (though not SoapUI) and seems to work with MQ SSL in this context. Unfortunately, Oracle's Java 8 was less successful with MQ SSL - another mystery.

2) If you plan to use a cipher with greater than AES128 encryption strength, as I do, you will need to find and download the Unrestricted SDK JCE policy files for IBM Java 8.

Unzipped, these should be used to replace 2 of the policy files in the equivalent directory to

C:\Program Files\IBM\MQ\java\jre\lib\security

3) Within SoapUI, update the following preferences to point at the HemesJMS installation directory.

you should then be able to invoke HermesJMS for the SoapUI Tools menu. (I think this may have been in the Files menu in previous releases - hunt around, you'll find it.)

4) Once the HemeseJMS Browser starts, create a new session and called it MQSession, for example. Switch to the Providers tab.

5) Right click and "Add Group", give the group name MQ, say. Right click on "Library" and click on "Add JAR(s)".

Navigate to C:\Program Files\IBM\MQ\java\lib (or equivalent) and choose (this bundles mqjms.jar and a bunch of others in MQ 8+)

6) Flip back to the Sessions tab and update the following:

a) On the Connection Factory section, choose from the Class drop down list and MQ for the Loader.

b) Right click within the Connection Factory space and Add Property (do this for each property you set).

c) Set an SSLCIpherSuite property (if your using SSL) and set this to the cipher suite that is equivalent to the cipher you set on your MQ SVRCONN. See the table in the following topic of the MQ KC SSL/TLS CipherSpecs and CipherSuites in IBM MQ classes for Java.

d) Set the SVRCONN channel name, hostName, port and transportType, as below. (Note that the cipher suite name begins SSL_ for this cipher, as opposed to to TLS_ used in the cipher spec for the MQ channel property SSLCIPH.)

e) Additionally - because you haven't tuned client authentication off on the queue manager (shouldn't turn it off), that's be silly - fill in the User and Password, as above (you'll need to check the checky box).

f) Add and edit your queue destinations, as above.

You should now be able to right click and browse your queues or from the HermesJMS Messages drop down menu Send (put) messages to the queue. I personally found that I was not able to Discover... queues via my session - the queue manager reported that no cipher had been sent in that case. Perhaps somebody out there can solve that mystery.