Using Java Client tool to test Sterling Order Management System MQ queues over SSL

Once SI users have installed their containerized developer toolkit successfully, they can use the MQ Java™ Client tool packaged with the developer toolkit to connect to a queue on their cloud MQ instance over SSL.

Custom Java client implementation

A custom sample Java client implementation is bundled with developer toolkit. You can run this sample implementation as the MQ Java client tool to perform various tasks that are explained in this topic. You can use the custom sample Java implementation as a reference to do your own custom implementations to connect to Sterling™ Order Management System cloud environment MQ queues. The sample implementation also contains the logic required to reconnect to the cloud environment MQ queues when the MQ instance undergoes failover process.

The sample implementation is available in devtoolkit_docker/compose/docker/mqserver/mqjc/src/com/ibm/mq/samples/jms/JmsPutGet.java.

Prerequisites to use the Java Client tool

Before you start setting up the Java Client tool to connect to a queue on the Cloud MQ instance over SSL, ensure that you have the following information available:

  • The server to connect to, namely <tenant_code>-<env>-<envno>-mq.oms.supply-chain.ibm.com.
  • The MQ queue to test.
  • The Private key p12 file downloaded from Self Service.

Setting up the Java Client tool

Run the following command from your developer toolkit
./om-compose.sh mqjc-setup <Path to SST P12 file>

Running the Java Client tool

Run the following command from your developer toolkit:
./om-compose.sh mqjc <optional: override parameters>

Parameters to the client

  • The following parameters are set by default:
    PORT=15443
CHANNEL=SYSTEM.TLS.SVRCONN
QMGR=OM_QMGR
CIPHER=SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • Optionally, you can set one or more of the following properties in om-compose.properties to override the default values:
    MQJC_PORT=<overriden port>
MQJC_CHANNEL=<overriden channel>
MQJC_QMGR=<overriden qmgr>
MQJC_CIPHER=<overriden cipher>
    Provide appropriate values for the following properties:
    MQJC_HOST=<host name/ip address of the mq server>
MQJC_QUEUE=<name of the queue to test>
  • Optionally, pass one or more of the following as override parameters to the ./om-compose.sh mqjc call. This overrides the values in the code as well as any property set in om-compose.properties.
    -DMQJC_PORT=<overriden port> 
-DMQJC_CHANNEL=<overriden channel> 
-DMQJC_QMGR=<overriden qmgr>
-DMQJC_CIPHER=<overriden cipher> 
-DMQJC_HOST=<host name/ip address of  mq server> 
-DMQJC_QUEUE=<name of the queue to test>

Ciphers to use

Upgraded cloud environments:
  • IBM® JRE - SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Default)
  • Oracle JRE - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
Old cloud environments:
  • IBM JRE - SSL_RSA_WITH_AES_128_CBC_SHA256
  • Oracle JRE - TLS_RSA_WITH_AES_128_CBC_SHA256
Note:
  • If you are running the Java Client tool from a developer toolkit on Linux® with an extracted runtime, it will use IBM JRE. If you do not have an extracted runtime, it will use the JRE referred by your JAVA_HOME variable, which can be IBM or Oracle JRE based on what you have installed on your machine.
  • If you are running the Java Client tool from a developer toolkit on Mac, it will use the JRE that is installed on your Mac that is referred by the JAVA_HOME variable, since it is the same JRE that is copied to your extracted runtime.
Tip: To check whether the JRE is IBM JRE or Oracle JRE, run java -version. If it contains IBM J9 VM, then it is IBM JRE. If it contains Java HotSpot VM, then it is Oracle JRE.

Additional arguments

With the MQ client version 9.2.1(CD version) and later, you must use the following JVM argument for Java-based clients or tools: 
-Dcom.ibm.mq.cfg.SSL.outboundSNI=Hostname
If the third-party client or tool is C or .NET(Unmanaged), pass OutboundSNI=HOSTNAME in the SSL stanza of the mqclient.ini file. This attribute can be read by C, unmanaged .NET, IBM MQ classes for Java, and IBM MQ classes for Java, and IBM MQ classes for JMS clients only.
Note: If you are using the Oracle JDK pass, use the following JVM argument.
-Dcom.ibm.mq.cfg.useIBMCipherMappings=false
CAUTION:
Do not use 9.1.x version of clients because it might cause problems with the Server Name Indication (SNI).

Examples

  1. If you want to test the queue QUEUE.1 on server abccorp-qa-1-mq.oms.supply-chain.ibm.com, which has upgraded ciphers, using IBM JRE, then run the following command:
    ./om-compose.sh mqjc -DMQJC_HOST=abccorp-qa-1-mq.oms.supply-chain.ibm.com
-DMQJC_QUEUE=QUEUE.1
  2. If you want to test the queue QUEUE.2 on server oldcorp-dev-1-mq.oms.supply-chain.ibm.com, which uses old ciphers, using Oracle JRE, then run the following command:
    ./om-compose.sh mqjc -DMQJC_CIPHER=TLS_RSA_WITH_AES_128_CBC_SHA256
-DMQJC_HOST=oldcorp-dev-1-mq.oms.supply-chain.ibm.com  -DMQJC_QUEUE=QUEUE.2