JMS Admin for the WMQ guy

Simon Gormley ([email protected])

IBM Hursley Park
March 2nd, 2011
Session 8715
Agenda

• JMS Administered Objects

• Connection Factories
• Destinations
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

2
JMS Administered Objects

• What do administered objects do?

My JMS Application

Queue Manager

Administrative
Connection
Store
Factory

Destination

3
JMS Administered Objects:
Connection Factories
• Contains information about how to connect to a queue
manager.
• Used by JMS applications to create connections.
• WMQ supports three types:
• Queue Connection Factories
• Used by applications who want to use point-to-point messaging.
• Topic Connection Factories
• Used by applications to create connections to queue managers
hosting a pub/sub engine.
• Connection Factories
• Can be used by either point-to-point or publish/subscribe
applications to connect to a queue manager.
• Stored in a JNDI Repository.
4
JMS Administered Objects:
Connection Factories

JNDI Repository

Connection Factory Connection Factory Connection Factory

CF1 CF2 CF3

Queue Manager 1 Queue Manager 2

5
Agenda

• JMS Administered Objects

• Connection Factories
• Destinations
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Queue Destination Properties
• Topic Destination Properties

6
JMS Administered Objects:
Destinations

• The destination of messages sent by producers.

• The source of messages received by consumers.
• WMQ supports two types:
• Queue Destinations
• Used by applications to open queues.
• Topic Destinations
• Used by applications to publish to, or subscribe on, a topic.
• Destination definitions are stored in a JNDI Repository.

7
JMS Administered Objects:
Destinations

JNDI Repository
Connection Factory Queue Destination Topic Destination
CF1 D1 D1 Connection Factory
CF2

Queue
Topic
Queue Manager 1 Queue Manager 2

8
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

9
WMQ JMS Administration Tools:
JNDI Repositories
• The WMQ JMS Administration Tools need access to a JNDI
Repository to store connection factory and destination definitions.
• Two main types of JNDI Repository are supported.

• LDAP Directories
• Heavyweight.
• Offers high levels of security.
• Easy to share connection factory and destination objects between multiple JMS
clients running on different machines.
• Can be difficult to set up.

• File system
• Very lightweight.
• Easy to set up and get running.
• Not very secure.
• Hard to share repository between multiple JMS clients.

10
WMQ JMS Administration Tools:
JNDI Repositories
• The WMQ JMS Administration Tools can be configured to use other
Repositories if required.

• WebSphere Application Server provides it’s own Repository and tools

for creating the WMQ JMS administered objects.
• The WMQ JMS Administration Tools should not be used with this
application server.

• WebSphere MQ SupportPac ME01 allows the queue manager to be

used as a JNDI store.

11
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

12
WMQ JMS Administration Tools:
JMSAdmin

• Command line tool.

• Supported on all platforms.
• Installed into <WMQ_HOME>\java\bin.
• To run it:
• Edit JMSAdmin.config file to point to the JNDI repository that
will be used, and optionally pass in authentication credentials.
• Then enter JMSAdmin
• Can be used to run scripts
• For example “jmsadmin < myscript.txt”

13
WMQ JMS Administration Tools:
JMSAdmin

• JMSAdmin.config contains three properties

• INITIAL_CONTEXT_FACTORY
• The class used by the JNDI repository to store and retrieve objects.
• Possible values are:

com.sun.jndi.ldap.LdapCtxFactory
Used for LDAP Repositories on distributed platforms.
com.ibm.jndi.LDAPCtxFactory
Used to connect to an LDAP repository from JMS applications running on z/OS.
com.sun.jndi.fscontext.RefFSContextFactory
Used for file system Repositories

• JMSAdmin.config contains an entries for

com.ibm.ejs.ns.jndi.CNInitialContextFactory and
com.ibm.websphere.naming.WsnInitialContextFactory. These should never be
used!

14
WMQ JMS Administration Tools:
JMSAdmin

• PROVIDER_URL
• An address used by the JMSAdmin tool to access the JNDI Repository.
• Possible values are:

ldap://<hostname>/<contextname>
The hostname and port that the LDAP server is listening on, followed by
the top level directory context where the objects will be stored.
file:<drive>/<pathname>
The path to the directory where the administered object definitions will
be saved. The directory must exist before JMSAdmin can be run.

• JMSAdmin.config contains an entry for iiop://localhost/. It should never be

used!

15
WMQ JMS Administration Tools:
JMSAdmin

• SECURITY_AUTHENTICATION
• Used when connecting to a secure LDAP JNDI Repository.
• Possible values are:

none
The JMSAdmin tool does not pass any security information to LDAP.

simple
The JMSAdmin tool sends an LDAP distinguished name and password
to the Server for authentication during startup.
CRAM-MD5
The JMSAdmin tool flows an LDAP distinguished name and password
(encrypted as an MD5 hash) when connecting to the LDAP server.

16
WMQ JMS Administration Tools:
JMSAdmin

• SECURITY_AUTHENTICATION
• The distinguished name and password can be stored in JMSAdmin.config,
using the PROVIDER_USERDN and PROVIDER_PASSWORD
properties.
• If they are not specified in the file, JMSAdmin will request them before
connecting to the Respository.

17
WMQ JMS Administration Tools:
JMSAdmin
• JMSAdmin expects commands to be in the format
• Verb noun(value) noun(value)…..
• Useful verbs are:
• DEFINE
• ALTER
• DISPLAY
• Nouns include:
• CF - JMS Connection Factory
• QCF - JMS Queue Connection Factory
• TCF - JMS Topic Connection Factory
• Q - JMS Queue
• T - JMS Topic
• QMGR - Queue Manager Name
• QU - Queue Name
• TO - Topic Name
18
WMQ JMS Administration Tools:
JMSAdmin

• To create a Queue Connection Factory for the queue

manager QM1, enter the command:
• DEFINE QCF(testQCF) QMGR (QM1)
• The Queue Connection Factory will be stored in the JNDI
Repository with the name testQCF.

• To create a JMS Queue Destination that points to the

queue “test”, enter:
• DEFINE Q(testQ) QU(test)
• The object will be stored in JNDI with the name testQ.

19
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

20
WMQ JMS Administration Tools:
MQ Explorer

• To create JMS Administered Objects in MQ Explorer:

• Set up a context
• Directory-like structure where the objects will be stored.
• Select the type of JNDI repository that will be used
• File system
• LDAP
• Another JNDI repository
• Specify the address of the JNDI repository
• For file system contexts, select the directory where the Administered
Objects will be stored
• For LDAP repositories, enter the URL of the LDAP server
• Optionally enter the username and password used to connect to the
JNDI repository
• And that’s it!
21
WMQ JMS Administration Tools:
MQ Explorer

• MQ Explorer wizards provide step-by-step instructions for

creating JMS Administered Objects.

• MQ Explorer also allows Queue or Topic Destination

Administered Objects at the same time as creating the
actual Queue or Topic.
• MQ Queues and Topics can also be created from
Destination Administered Objects.

22
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

23
Connection Factory Properties:
Queue Manager Name

• The name of the queue manager that this Factory points

to.
• JMS applications will use the factory to create a connection
to this queue manager.
• JMSAdmin Property Name: QMANAGER / QMGR

24
Connection Factory Properties:
Transport Type
• The transport mechanism supported by this factory.
• JMS applications that use this Factory will attempt to connect to the
queue manager using the transport mechanism specified here.
• Possible values:
• BINDINGS
• JMS applications using this Factory will use inter-process
communication (IPC) to connect to the queue manager.
• CLIENT
• JMS applications will attempt to connect to the queue manager using
TCP/IP.
• DIRECT
• DIRECT_HTTP
• With these options, JMS applications will attempt to create direct
network connections to IBM Message Broker.

• JMSAdmin Property Name : TRANSPORT / TRANS

25
Connection Factory Properties:
Provider Version

• The version of WMQ that the queue manager this Factory

is pointing to is running on.
• The client is optimized to connect to Version 7 queue
managers, and makes use of Version 7 functionality, such as
shared conversations.
• The WMQ JMS client can be used to connect to Version 5.1
queue managers and above.
• This uses a slightly modified version of the WMQ Version 6 JMS
Client, which is embedded in the Version 7 code.

26
Connection Factory Properties:
Provider Version

• Possible Values
• Unspecified
• The JMS client will first try to connect to the queue manager as if it is
Version 7
• If this fails, it will fall back to the Version 6 (and earlier) behaviour.
• 6
• The JMS client will use the embedded Version 6 JMS Client to connect
to the queue manager.
• 7
• JMS applications that use a Factory with Provider Version set to 7 will
use the optimized connection code.

• JMSAdmin Property Name: PROVIDERVERSION / PVER

27
Connection Factory Properties:
Connection Name List

• This property specifies a list of hostnames and ports to

attempt to connect to.
• Comma-separated list of “hostname(port)” entries
• Similar to a CCDT with multiple entries.
• Can be used with client reconnection options and client
reconnection timeout to allow automatic reconnection to a
standby queue manager.
• JMSAdmin Property Name: CONNECTIONNAMELIST /
CNLIST

28
Connection Pooling Properties:
Shared Conversation Allowed
• This property specifies whether JMS applications that use
this Factory can share their connection to a Version 7
queue manager.
• For example, imagine the Connection Factory is set up to
allow shared conversations.
• If two applications running on the same Java Virtual Machine
use this Factory, they will share the same connection to the
queue manager.
• The queue manager would only show one open connection,
even if both applications are running.
• Useful to reduce the number of network connections to a
queue manager.
• Can have slight performance impact.
• Multiple JMS applications will be sending data to a queue
manager and waiting for a response over the same channel.
29
Connection Pooling Properties:
Shared Conversation Allowed

• Possible Values
• Yes
• JMS applications running in the same Java Virtual Machine can
use this Factory and share their connections to the queue
manager. The amount of sharing is controlled by the Server
Connection Channel
• No
• Every JMS application that uses this Factory will create a new
connection to the queue manager.

• JMSAdmin Property Name: SHARECONVALLOWED /

SCALD

30
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

31
Destination Properties:
Queue Name / Topic Name

• The name of the Queue or Topic that this Destination

maps to.
• JMS applications that send messages using this Destination
will either put messages to the specified queue, or publish
messages on this topic.
• JMS applications that receive incoming messages using this
Destination will either get messages from the queue, or
subscribe to the topic.

• JMSAdmin Property Name: QUEUE / Q

TOPIC / T

32
Destination Properties:
MQMD Read/Write enabled

• Determines if MQMD properties can be set via JMS get/set

message property methods.
• Allows full access to the MQMD header values
• Useful for sending or receiving messages from MQ
applications that use specific header properties.
• JMS message property names begin with
“JMS_IBM_MQMD…”

• JMSAdmin Property Name: MDREAD / MDR &

MDWRITE / MDW

33
Destination Properties:
Target Client

• This property tells the JMS application whether messages

sent to this destination are for other JMS applications, or
for non-JMS WMQ applications.
• WMQ JMS messages, by default, have an RFH2 header
containing JMS specific information.
• If a message is for a non-JMS application, this header may
cause problems, so can be turned off.
MQMD MQMD

RFH2

Data
Data

34 JMS Messages Non-JMS Messages

Destination Properties:
Target Client

• Possible Values:
• JMS
• JMS messages sent by an application to this Destination will be
consumed by another JMS application.
• The RFH2 header will be included on these messages.
• MQ
• The JMS messages sent to this destination are for a non-JMS
application.
• The message will include an MQMD, and the message body.
• The RFH2 header will not be included.
• Any information in the RFH2 will be lost.

• JMSAdmin Property Name: TARGCLIENT / TC

35
Destination Properties:
Read Ahead Allowed

• In general, messages are sent to JMS applications one at a time.

• The Read Ahead Allowed property tells the queue manager whether
non-persistent messages can be streamed to the client application in
preparation for them being consumed.
• Messages are stored in a buffer on the client.
• If the client application terminates unexpectedly, all unconsumed
non-persistent messages are discarded.

JMS Application JMS Client Queue Manager

• JMSAdmin Property Name: READAHEADALLOWED /

RAALD
36
Agenda

• JMS Administered Objects

• Connection Factories.
• Destinations.
• WMQ JMS Administration Tools
• JNDI Repositories
• JMSAdmin
• MQ Explorer
• Connection Factory Properties
• Destination Properties

37
Any questions?

• If you have any questions, or ideas for future topics, feel

free to email me at [email protected]

38
JMSAdmin Demo Screenshots

• After setting JMSAdmin.config, and running JMSAdmin,

commands can be entered, such as define qcf

39
JMSAdmin Demo Screenshots

• Use the alter qcf command to make modifications after

the object has been defined

40
JMSAdmin Demo Screenshots

• Queue destination objects created by the define q

command

41
MQ Explorer Demo Screenshots

• Create a connection to a File-

based JNDI repository. Only
the directory needs to exist.
Click Finish to create.

42
MQ Explorer Demo Screenshots

• Create a new connection

factory, and provide a name

• Select a type of connection

factory to create.

43
MQ Explorer Demo Screenshots

• Select the type of transport to

use

• Base the definition on a previously

created object if needed.

44
MQ Explorer Demo Screenshots

• Set the properties for the connection, and click Finish

45
MQ Explorer Demo Screenshots

• Create a New JMS

Queue, and tick the
box to create the
underlying MQ Queue

46
MQ Explorer Demo Screenshots

• Optionally create like an

existing destination

• Set the properties for the

destination object. The wizard
to create the MQ Queue will
start after clicking Finish.

47