MQSeries®


Using Java

SC34-5456-07
MQSeries®


Using Java

SC34-5456-07
 Note!
Before using this information and the product it supports, be sure to read the general information under “Appendix H.
Notices” on page 373.

Eighth edition (June 2001)

This edition applies to IBM® MQSeries classes for Java Version 5.2.0 and MQSeries classes for Java Message Service
Version 5.2, and to any subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1997, 2001. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Figures . . . . . . . . . . . . . . . ix Tracing the sample applet . . . . . . . . 17
Tracing the sample application . . . . . . . 17
Tables . . . . . . . . . . . . . . . xi Error messages . . . . . . . . . . . . 18

About this book . . . . . . . . . . xiii Chapter 4. Using MQSeries classes for

Abbreviations used in this book . . . . . . . xiii Java Message Service (MQ JMS) . . . 19
Who this book is for . . . . . . . . . . . xiii Post installation setup . . . . . . . . . . . 19
What you need to know to understand this book xiii Additional setup for Publish/Subscribe mode . . 20
How to use this book . . . . . . . . . . . xiv Queues that require authorization for
non-privileged users . . . . . . . . . . 21
Running the point-to-point IVT . . . . . . . . 22
Summary of changes . . . . . . . . xv
Point-to-point verification without JNDI . . . . 22
| Changes to this edition (SC34-5456-07) . . . . . xv
Point-to-point verification with JNDI . . . . . 23
Changes to the seventh edition (SC34-5456-06) . . xv
IVT error recovery . . . . . . . . . . . 25
Changes to the sixth edition (SC34-5456-05) . . . xvi
The Publish/Subscribe Installation Verification Test 25
Publish/Subscribe verification without JNDI . . 26
Part 1. Guidance for users . . . . . 1 Publish/Subscribe verification with JNDI . . . 27
PSIVT error recovery . . . . . . . . . . 28
Chapter 1. Getting started . . . . . . . 3 Running your own MQ JMS programs . . . . . 28
What is MQSeries classes for Java? . . . . . . . 3 Solving problems . . . . . . . . . . . . 29
What is MQSeries classes for Java Message Service? 3 Tracing programs . . . . . . . . . . . 29
Who should use MQ Java? . . . . . . . . . 3 Logging . . . . . . . . . . . . . . 29
Connection options . . . . . . . . . . . . 4
Client connection . . . . . . . . . . . . 5 Chapter 5. Using the MQ JMS
Using VisiBroker for Java . . . . . . . . . 5 administration tool . . . . . . . . . 31
Bindings connection . . . . . . . . . . . 6 Invoking the Administration tool . . . . . . . 31
Prerequisites . . . . . . . . . . . . . . 6 Configuration . . . . . . . . . . . . . 32
Configuring for WebSphere . . . . . . . . 33
Chapter 2. Installation procedures . . . 7 Security . . . . . . . . . . . . . . 33
| Obtaining MQSeries classes for Java and MQSeries Administration commands . . . . . . . . . 34
| classes for Java Message Service . . . . . . . . 7 Manipulating subcontexts . . . . . . . . . 35
Installing MQSeries classes for Java and MQSeries Administering JMS objects . . . . . . . . . 35
classes for Java Message Service . . . . . . . . 7 Object types . . . . . . . . . . . . . 35
Installing on UNIX . . . . . . . . . . . 8 Verbs used with JMS objects . . . . . . . . 36
| Installing on z/OS & OS/390 . . . . . . . . 9 Creating objects . . . . . . . . . . . . 37
Installing on iSeries & AS/400 . . . . . . . 9 Properties . . . . . . . . . . . . . . 38
Installing on Linux . . . . . . . . . . . 9 Property dependencies . . . . . . . . . 41
Installing on Windows. . . . . . . . . . 10 The ENCODING property . . . . . . . . 42
Installation directories . . . . . . . . . . 10 Sample error conditions . . . . . . . . . 43
Environment variables . . . . . . . . . . 11
Web server configuration . . . . . . . . . . 12 Part 2. Programming with MQ base
Java . . . . . . . . . . . . . . . 45
Chapter 3. Using MQSeries classes for
Java (MQ base Java). . . . . . . . . 13 Chapter 6. Introduction for
Using the sample applet to verify the TCP/IP client 13
Using the sample applet on iSeries or AS/400 . . 13
programmers . . . . . . . . . . . . 47
Configuring your queue manager to accept client Why should I use the Java interface? . . . . . . 47
connections . . . . . . . . . . . . . 13 The MQSeries classes for Java interface . . . . . 48
Running from appletviewer . . . . . . . . 15 Java Development Kit . . . . . . . . . . . 48
Customizing the verification applet . . . . . 15 MQSeries classes for Java class library . . . . . 49
Verifying with the sample application . . . . . 16
Using VisiBroker connectivity . . . . . . . 17 Chapter 7. Writing MQ base Java
Running your own MQ base Java programs . . . 17 programs . . . . . . . . . . . . . 51
Solving MQ base Java problems . . . . . . . 17 Should I write applets or applications? . . . . . 51

© Copyright IBM Corp. 1997, 2001 iii

Connection differences. . . . . . . . . . . 51 Constructors. . . . . . . . . . . . . 100
Client connections . . . . . . . . . . . 51 Methods . . . . . . . . . . . . . . 100
Bindings mode . . . . . . . . . . . . 52 MQMessage . . . . . . . . . . . . . . 102
Defining which connection to use . . . . . . 52 Variables . . . . . . . . . . . . . . 102
Example code fragments . . . . . . . . . . 52 Constructors. . . . . . . . . . . . . 110
Example applet code . . . . . . . . . . 52 Methods . . . . . . . . . . . . . . 110
Example application code . . . . . . . . 56 MQMessageTracker . . . . . . . . . . . 121
Operations on queue managers . . . . . . . . 58 Variables . . . . . . . . . . . . . . 121
Setting up the MQSeries environment . . . . 58 MQPoolServices . . . . . . . . . . . . 123
Connecting to a queue manager . . . . . . 58 Constructors. . . . . . . . . . . . . 123
Accessing queues and processes . . . . . . . 59 Methods . . . . . . . . . . . . . . 123
Handling messages . . . . . . . . . . . . 60 MQPoolServicesEvent . . . . . . . . . . 124
Handling errors . . . . . . . . . . . . . 61 Variables . . . . . . . . . . . . . . 124
Getting and setting attribute values . . . . . . 61 Constructors. . . . . . . . . . . . . 124
Multithreaded programs . . . . . . . . . . 62 Methods . . . . . . . . . . . . . . 125
Writing user exits . . . . . . . . . . . . 63 MQPoolToken . . . . . . . . . . . . . 126
Connection pooling. . . . . . . . . . . . 64 Constructors. . . . . . . . . . . . . 126
Controlling the default connection pool . . . . 64 MQProcess . . . . . . . . . . . . . . 127
The default connection pool and multiple Constructors. . . . . . . . . . . . . 127
components . . . . . . . . . . . . . 66 Methods . . . . . . . . . . . . . . 127
Supplying a different connection pool . . . . 67 MQPutMessageOptions . . . . . . . . . . 129
Supplying your own ConnectionManager . . . 68 Variables . . . . . . . . . . . . . . 129
Compiling and testing MQ base Java programs . . 69 Constructors. . . . . . . . . . . . . 131
Running MQ base Java applets . . . . . . . 70 MQQueue . . . . . . . . . . . . . . 132
Running MQ base Java applications . . . . . 70 Constructors. . . . . . . . . . . . . 132
Tracing MQ base Java programs . . . . . . 70 Methods . . . . . . . . . . . . . . 132
MQQueueManager . . . . . . . . . . . 140
Chapter 8. Environment-dependent Variables . . . . . . . . . . . . . . 140
behavior . . . . . . . . . . . . . . 73 Constructors. . . . . . . . . . . . . 140
Methods . . . . . . . . . . . . . . 142
Core details . . . . . . . . . . . . . . 73
MQSimpleConnectionManager . . . . . . . 150
Restrictions and variations for core classes . . . . 74
Variables . . . . . . . . . . . . . . 150
Version 5 extensions operating in other
Constructors. . . . . . . . . . . . . 150
environments . . . . . . . . . . . . . . 75
Methods . . . . . . . . . . . . . . 150
MQC . . . . . . . . . . . . . . . . 152
Chapter 9. The MQ base Java classes MQPoolServicesEventListener . . . . . . . . 153
and interfaces . . . . . . . . . . . 79 Methods . . . . . . . . . . . . . . 153
MQChannelDefinition . . . . . . . . . . . 80 MQConnectionManager . . . . . . . . . . 154
Variables . . . . . . . . . . . . . . 80 MQReceiveExit . . . . . . . . . . . . . 155
Constructors . . . . . . . . . . . . . 81 Methods . . . . . . . . . . . . . . 155
MQChannelExit . . . . . . . . . . . . . 82 MQSecurityExit . . . . . . . . . . . . 157
Variables . . . . . . . . . . . . . . 82 Methods . . . . . . . . . . . . . . 157
Constructors . . . . . . . . . . . . . 84 MQSendExit. . . . . . . . . . . . . . 159
MQDistributionList . . . . . . . . . . . . 85 Methods . . . . . . . . . . . . . . 159
Constructors . . . . . . . . . . . . . 85 ManagedConnection . . . . . . . . . . . 161
Methods . . . . . . . . . . . . . . 85 Methods . . . . . . . . . . . . . . 161
MQDistributionListItem . . . . . . . . . . 87 ManagedConnectionFactory . . . . . . . . 164
Variables . . . . . . . . . . . . . . 87 Methods . . . . . . . . . . . . . . 164
Constructors . . . . . . . . . . . . . 87 ManagedConnectionMetaData . . . . . . . . 166
MQEnvironment. . . . . . . . . . . . . 88 Methods . . . . . . . . . . . . . . 166
Variables . . . . . . . . . . . . . . 88
Constructors . . . . . . . . . . . . . 91
Methods . . . . . . . . . . . . . . 91
Part 3. Programming with MQ JMS 167
MQException . . . . . . . . . . . . . . 93
Variables . . . . . . . . . . . . . . 93 Chapter 10. Writing MQ JMS programs 169
Constructors . . . . . . . . . . . . . 93 The JMS model . . . . . . . . . . . . . 169
MQGetMessageOptions . . . . . . . . . . 95 Building a connection . . . . . . . . . . 170
Variables . . . . . . . . . . . . . . 95 Retrieving the factory from JNDI . . . . . . 170
Constructors . . . . . . . . . . . . . 98 Using the factory to create a connection . . . 171
MQManagedObject . . . . . . . . . . . . 99 Creating factories at runtime . . . . . . . 171
Variables . . . . . . . . . . . . . . 99 Choosing client or bindings transport . . . . 172

iv MQSeries Using Java

Obtaining a session . . . . . . . . . . . 172 ASFClient1.java. . . . . . . . . . . . 220
Sending a message . . . . . . . . . . . 173 Load2.java . . . . . . . . . . . . . 222
Setting properties with the ‘set’ method . . . 174 LoggingMessageListenerFactory.java. . . . . 222
Message types . . . . . . . . . . . . 175 ASFClient2.java. . . . . . . . . . . . 222
Receiving a message . . . . . . . . . . . 175 TopicLoad.java . . . . . . . . . . . . 223
Message selectors . . . . . . . . . . . 176 ASFClient3.java. . . . . . . . . . . . 224
Asynchronous delivery . . . . . . . . . 177 ASFClient4.java. . . . . . . . . . . . 225
Closing down . . . . . . . . . . . . . 177
Java Virtual Machine hangs at shutdown . . . 177 Chapter 14. JMS interfaces and
Handling errors . . . . . . . . . . . . 177 classes . . . . . . . . . . . . . . 227
Exception listener . . . . . . . . . . . 178
Sun Java Message Service classes and interfaces 227
MQSeries JMS classes . . . . . . . . . . 230
Chapter 11. Programming BytesMessage . . . . . . . . . . . . . 232
Publish/Subscribe applications. . . . 179 Methods . . . . . . . . . . . . . . 232
Writing a simple Publish/Subscribe application 179 Connection . . . . . . . . . . . . . . 240
Import required packages . . . . . . . . 179 Methods . . . . . . . . . . . . . . 240
Obtain or create JMS objects . . . . . . . 179 ConnectionConsumer. . . . . . . . . . . 243
Publish messages . . . . . . . . . . . 181 Methods . . . . . . . . . . . . . . 243
Receive subscriptions . . . . . . . . . . 181 ConnectionFactory. . . . . . . . . . . . 244
Close down unwanted resources . . . . . . 181 MQSeries constructor. . . . . . . . . . 244
Using topics . . . . . . . . . . . . . . 181 Methods . . . . . . . . . . . . . . 244
Topic names . . . . . . . . . . . . . 181 ConnectionMetaData . . . . . . . . . . . 248
Creating topics at runtime . . . . . . . . 182 MQSeries constructor. . . . . . . . . . 248
Subscriber options . . . . . . . . . . . . 183 Methods . . . . . . . . . . . . . . 248
Creating non-durable subscribers . . . . . . 184 DeliveryMode . . . . . . . . . . . . . 250
Creating durable subscribers . . . . . . . 184 Fields . . . . . . . . . . . . . . . 250
Using message selectors . . . . . . . . . 184 Destination . . . . . . . . . . . . . . 251
Suppressing local publications . . . . . . . 184 MQSeries constructors . . . . . . . . . 251
Combining the subscriber options . . . . . 185 Methods . . . . . . . . . . . . . . 251
Configuring the base subscriber queue . . . . 185 ExceptionListener . . . . . . . . . . . . 253
Solving Publish/Subscribe problems. . . . . . 187 Methods . . . . . . . . . . . . . . 253
Incomplete Publish/Subscribe close down . . . 187 MapMessage . . . . . . . . . . . . . 254
Handling broker reports . . . . . . . . . 188 Methods . . . . . . . . . . . . . . 254
Message . . . . . . . . . . . . . . . 262
Chapter 12. JMS messages . . . . . 191 Fields . . . . . . . . . . . . . . . 262
Message selectors . . . . . . . . . . . . 191 Methods . . . . . . . . . . . . . . 262
Mapping JMS messages onto MQSeries messages 195 MessageConsumer . . . . . . . . . . . 275
The MQRFH2 header. . . . . . . . . . 196 Methods . . . . . . . . . . . . . . 275
JMS fields and properties with corresponding MessageListener . . . . . . . . . . . . 277
MQMD fields . . . . . . . . . . . . 199 Methods . . . . . . . . . . . . . . 277
Mapping JMS fields onto MQSeries fields MessageProducer . . . . . . . . . . . . 278
(outgoing messages) . . . . . . . . . . 200 MQSeries constructors . . . . . . . . . 278
Mapping MQSeries fields onto JMS fields Methods . . . . . . . . . . . . . . 278
(incoming messages) . . . . . . . . . . 204 MQQueueEnumeration * . . . . . . . . . 282
Mapping JMS to a native MQSeries application 205 Methods . . . . . . . . . . . . . . 282
Message body . . . . . . . . . . . . 206 ObjectMessage . . . . . . . . . . . . . 283
Methods . . . . . . . . . . . . . . 283
Queue . . . . . . . . . . . . . . . . 284
Chapter 13. MQ JMS Application
MQSeries constructors . . . . . . . . . 284
Server Facilities . . . . . . . . . . 209 Methods . . . . . . . . . . . . . . 284
ASF classes and functions . . . . . . . . . 209 QueueBrowser . . . . . . . . . . . . . 286
ConnectionConsumer. . . . . . . . . . 209 Methods . . . . . . . . . . . . . . 286
Planning an application . . . . . . . . . 210 QueueConnection . . . . . . . . . . . . 288
Error handling . . . . . . . . . . . . 214 Methods . . . . . . . . . . . . . . 288
Application server sample code . . . . . . . 215 QueueConnectionFactory . . . . . . . . . 290
MyServerSession.java. . . . . . . . . . 217 MQSeries constructor. . . . . . . . . . 290
MyServerSessionPool.java . . . . . . . . 217 Methods . . . . . . . . . . . . . . 290
MessageListenerFactory.java . . . . . . . 218 QueueReceiver . . . . . . . . . . . . . 292
Examples of ASF use . . . . . . . . . . . 219 Methods . . . . . . . . . . . . . . 292
Load1.java . . . . . . . . . . . . . 219 QueueRequestor . . . . . . . . . . . . 293
CountingMessageListenerFactory.java . . . . 220 Constructors. . . . . . . . . . . . . 293

Contents v
 Methods . . . . . . . . . . . . . . 293 Appendix B. Scripts provided with
QueueSender . . . . . . . . . . . . . 295 MQSeries classes for Java Message
Methods . . . . . . . . . . . . . . 295
Service . . . . . . . . . . . . . . 351
QueueSession . . . . . . . . . . . . . 298
Methods . . . . . . . . . . . . . . 298
Session . . . . . . . . . . . . . . . 301 Appendix C. LDAP schema definition
Fields . . . . . . . . . . . . . . . 301 for storing Java objects . . . . . . . 353
Methods . . . . . . . . . . . . . . 301 Checking your LDAP server configuration . . . 353
StreamMessage . . . . . . . . . . . . . 306 | Attribute definitions . . . . . . . . . . . 354
Methods . . . . . . . . . . . . . . 306 | objectClass definitions . . . . . . . . . . 355
TemporaryQueue . . . . . . . . . . . . 314 | Server-specific configuration details . . . . . . 356
Methods . . . . . . . . . . . . . . 314 | Netscape Directory (4.1 and earlier) . . . . . 356
TemporaryTopic . . . . . . . . . . . . 315 | Microsoft® Active Directory . . . . . . . 356
MQSeries constructor. . . . . . . . . . 315 | Sun Microsystems’ Schema Modification
Methods . . . . . . . . . . . . . . 315 | Applications. . . . . . . . . . . . . 357
TextMessage . . . . . . . . . . . . . . 316 | iSeries OS/400 V4R5 Schema Modification . . 357
Methods . . . . . . . . . . . . . . 316
Topic . . . . . . . . . . . . . . . . 317 Appendix D. Connecting to MQSeries
MQSeries constructor. . . . . . . . . . 317 Integrator V2. . . . . . . . . . . . 359
Methods . . . . . . . . . . . . . . 317
Publish/subscribe . . . . . . . . . . . . 359
TopicConnection . . . . . . . . . . . . 319
Transformation and routing . . . . . . . . 360
Methods . . . . . . . . . . . . . . 319
TopicConnectionFactory . . . . . . . . . . 321
MQSeries constructor. . . . . . . . . . 321 Appendix E. JMS JTA/XA interface
Methods . . . . . . . . . . . . . . 321 with WebSphere . . . . . . . . . . 361
TopicPublisher . . . . . . . . . . . . . 324 Using the JMS interface with WebSphere . . . . 361
Methods . . . . . . . . . . . . . . 324 Administered objects . . . . . . . . . . 361
TopicRequestor . . . . . . . . . . . . . 327 Container-managed versus bean-managed
Constructors. . . . . . . . . . . . . 327 transactions . . . . . . . . . . . . . 362
Methods . . . . . . . . . . . . . . 327 Two-phase commit versus one-phase
TopicSession. . . . . . . . . . . . . . 329 optimization. . . . . . . . . . . . . 362
MQSeries constructor. . . . . . . . . . 329 Defining administered objects . . . . . . . 362
Methods . . . . . . . . . . . . . . 329 Retrieving administration objects . . . . . . 362
TopicSubscriber. . . . . . . . . . . . . 333 Samples . . . . . . . . . . . . . . . 362
Methods . . . . . . . . . . . . . . 333 Sample1 . . . . . . . . . . . . . . 363
XAConnection . . . . . . . . . . . . . 334 Sample2 . . . . . . . . . . . . . . 364
XAConnectionFactory . . . . . . . . . . 335 Sample3 . . . . . . . . . . . . . . 364
XAQueueConnection . . . . . . . . . . . 336
Methods . . . . . . . . . . . . . . 336 | Appendix F. Using MQ Java in applets
XAQueueConnectionFactory . . . . . . . . 337 | with Java 1.2 or later . . . . . . . . 367
Methods . . . . . . . . . . . . . . 337 | Changing browser security settings . . . . . . 367
XAQueueSession . . . . . . . . . . . . 339 | Copying package class files. . . . . . . . . 368
Methods . . . . . . . . . . . . . . 339
XASession . . . . . . . . . . . . . . 340
Methods . . . . . . . . . . . . . . 340
| Appendix G. Information for
XATopicConnection . . . . . . . . . . . 342 | SupportPac MA1G . . . . . . . . . 369
Methods . . . . . . . . . . . . . . 342 | Environments supported by SupportPac MA1G 369
XATopicConnectionFactory . . . . . . . . . 344 | Obtaining and installing SupportPac MA1G . . . 369
Methods . . . . . . . . . . . . . . 344 | Verifying installation using the sample program 370
XATopicSession. . . . . . . . . . . . . 346 | Features not provided by SupportPac MA1G . . . 370
Methods . . . . . . . . . . . . . . 346 | Running MQ base Java applications under CICS
| Transaction Server for OS/390 . . . . . . . . 371
| Restrictions under CICS Transaction Server . . . 371
Part 4. Appendixes . . . . . . . . 347
Appendix H. Notices . . . . . . . . 373
Appendix A. Mapping between Trademarks . . . . . . . . . . . . . . 374
Administration tool properties and
programmable properties . . . . . . 349 Glossary of terms and abbreviations 375

Bibliography . . . . . . . . . . . . 379

vi MQSeries Using Java

MQSeries cross-platform publications . . . . . 379 Windows Help format . . . . . . . . . 381
MQSeries platform-specific publications . . . . 379 MQSeries information available on the Internet . . 381
Softcopy books . . . . . . . . . . . . . 380
HTML format . . . . . . . . . . . . 380 Index . . . . . . . . . . . . . . . 383
Portable Document Format (PDF) . . . . . 380
BookManager® format . . . . . . . . . 381
Sending your comments to IBM . . . 389
PostScript format . . . . . . . . . . . 381

Contents vii
viii MQSeries Using Java
Figures
1. MQSeries classes for Java example applet 53 5. JMS to MQSeries mapping model . . . . . 206
2. MQSeries classes for Java example application 56 6. ServerSessionPool and ServerSession
3. MQSeries classes for Java Message Service functionality . . . . . . . . . . . . 216
topic name hierarchy . . . . . . . . . 182 7. MQSeries Integrator message flow . . . . 359
4. JMS to MQSeries mapping model . . . . . 195

© Copyright IBM Corp. 1997, 2001 ix

x MQSeries Using Java
 Tables
1. Platforms and connection modes . . . . . . 5 | 25. Outgoing message JMS provider specific
2. Product installation directories . . . . . . 10 | property mapping . . . . . . . . . . 201
3. Sample CLASSPATH statements for the | 26. Incoming message JMS header field mapping 204
product . . . . . . . . . . . . . . 11 | 27. Incoming message property mapping 205
4. Environment variables for the product . . . 11 | 28. Incoming message provider specific JMS
5. Classes that are tested by IVT . . . . . . 25 | property mapping . . . . . . . . . . 205
6. Administration verbs . . . . . . . . . 34 29. Load1 parameters and defaults . . . . . 220
7. Syntax and description of commands used to 30. ASFClient1 parameters and defaults . . . . 221
manipulate subcontexts . . . . . . . . 35 31. TopicLoad parameters and defaults . . . . 223
8. The JMS object types that are handled by the 32. ASFClient3 parameters and defaults . . . . 224
administration tool . . . . . . . . . . 35 33. Interface Summary. . . . . . . . . . 227
9. Syntax and description of commands used to 34. Class Summary . . . . . . . . . . . 229
manipulate administered objects . . . . . 36 35. Package ’com.ibm.mq.jms’ class Summary 230
10. Property names and valid values . . . . . 38 36. Package ’com.ibm.jms’ class summary 231
11. The valid combinations of property and object 37. Comparison of representations of property
type . . . . . . . . . . . . . . . 40 values within the administration tool and
12. Core classes restrictions and variations . . . 74 within programs. . . . . . . . . . . 349
13. Character set identifiers . . . . . . . . 105 38. Utilities supplied with MQSeries classes for
14. Set methods on MQQueueConnectionFactory 171 Java Message Service . . . . . . . . . 351
15. Property names for queue URIs . . . . . 174 | 39. Attribute settings for javaCodebase . . . . 354
16. Symbolic values for queue properties 175 | 40. Attribute settings for javaClassName 354
17. Possible values for NameValueCCSID field 197 | 41. Attribute settings for javaClassNames 354
18. MQRFH2 folders and properties used by JMS 197 | 42. Attribute settings for javaFactory . . . . . 355
19. Property datatype values and definitions 198 | 43. Attribute settings for javaReferenceAddress 355
| 20. JMS header fields mapping to MQMD fields 199 | 44. Attribute settings for javaSerializedData 355
| 21. JMS properties mapping to MQMD fields 200 | 45. objectClass definition for javaSerializedObject 355
| 22. JMS provider specific properties mapping to | 46. objectClass definition for javaObject . . . . 356
| MQMD fields . . . . . . . . . . . 200 | 47. objectClass definition for javaContainer 356
| 23. Outgoing message field mapping . . . . . 201 | 48. objectClass definition for
| 24. Outgoing message JMS property mapping 201 | javaNamingReference . . . . . . . . . 356

© Copyright IBM Corp. 1997, 2001 xi

xii MQSeries Using Java
 About this book
This book describes:
v MQSeries classes for Java, which can be used to access MQSeries systems
v MQSeries classes for Java Message Service, which can be used to access both
Java™ Message Service (JMS) and MQSeries applications
Notes:
1. This documentation is available in softcopy format only (PDF and HTML) as
part of the product, and from the MQSeries family Web site at:
http://www.ibm.com/software/mqseries/

It cannot be ordered as a printed book.

| 2. The README file should be consulted for information that expands and
| corrects information in this book. The README file is installed with the MQ
| Java code and can be found in the doc subdirectory.

Abbreviations used in this book

The following abbreviations are used throughout this book:
MQ Java MQSeries classes for Java and MQSeries classes for Java Message
Service combined
MQ base Java MQSeries classes for Java
MQ JMS MQSeries classes for Java Message Service

Who this book is for

This information is written for programmers who are familiar with the procedural
MQSeries application programming interface as described in the MQSeries
Application Programming Guide, and shows how to transfer this knowledge to
become productive with the MQ Java programming interfaces.

What you need to know to understand this book

You should have:
v Knowledge of the Java programming language
v Understanding of the purpose of the Message Queue Interface (MQI) as
described in the chapter about the Message Queue Interface in the MQSeries
Application Programming Guide and the chapter about Call Descriptions in the
MQSeries Application Programming Reference book
v Experience of MQSeries programs in general, or familiarity with the content of
the other MQSeries publications

Users intending to use the MQ base Java with CICS® Transaction Server for
OS/390® should also be familiar with:
v Customer Information Control System (CICS) concepts
v Using the CICS Java Application Programming Interface (API)
v Running Java programs from within CICS

© Copyright IBM Corp. 1997, 2001 xiii

 About this book
Users intending to use VisualAge® for Java to develop OS/390 UNIX® System
Services High Performance Java (HPJ) applications should be familiar with the
Enterprise Toolkit for OS/390 (supplied with VisualAge for Java Enterprise Edition
for OS/390, Version 2).

How to use this book

Part 1 of this book describes the use of MQ base Java and MQ JMS, Part 2
provides assistance for programmers wanting to use MQ base Java, and Part 3
provides assistance for programmers wanting to use MQ JMS.

First, read the chapters in Part 1 that introduce you to MQ base Java and MQ JMS.
Then, use the programming guidance in Part 2 or 3 to understand how to use the
classes to send and receive MQSeries messages in the environment you wish to
use.

There is a glossary and bibliography at the back of this book.

| Remember to check the README file installed with the MQ Java code for later or
| more specific information for your environment.

xiv MQSeries Using Java

 Summary of changes
This section describes changes in this edition of MQSeries Using Java. Changes since
the previous edition of the book are marked by vertical lines to the left of the
changes.

| Changes to this edition (SC34-5456-07)

| This edition:
| v Includes information about updated support for z/OS & OS/390 and iSeries &
| AS/400®.
| v Has a rewritten appendix describing LDAP support.
| See “Appendix C. LDAP schema definition for storing Java objects” on page 353.
| v Has a new appendix describing how to run applets using MQ Java with Java 1.2
| or later.
| See “Appendix F. Using MQ Java in applets with Java 1.2 or later” on page 367.
| v Has a separate appendix containing information for SupportPac™ MA1G.
| See “Appendix G. Information for SupportPac MA1G” on page 369.
| v Has miscellaneous changes to improve usability and accessibility.
|
Changes to the seventh edition (SC34-5456-06)
This edition includes updates for the new function introduced by MQ Java V5.2.
This includes:
v Updates to the installation procedures. See “Chapter 2. Installation procedures”
on page 7.
v Support for connection pooling, which can improve performance for applications
and middleware that use multiple connections to MQSeries queue managers.
See:
– “Connection pooling” on page 64
– “MQEnvironment” on page 88
– “MQPoolServices” on page 123
– “MQPoolServicesEvent” on page 124
– “MQPoolToken” on page 126
– “MQQueueManager” on page 140
– “MQSimpleConnectionManager” on page 150
– “MQConnectionManager” on page 154
– “MQPoolServicesEventListener” on page 153
– “ManagedConnection” on page 161
– “ManagedConnectionFactory” on page 164
– “ManagedConnectionMetaData” on page 166
v New subscriber queue configuration options to provide both a multiple queue
and a shared queue approach for publish/subscribe applications. See:
– “Properties” on page 38
– “Configuring the base subscriber queue” on page 185
– “Topic” on page 317

© Copyright IBM Corp. 1997, 2001 xv

Changes
– “TopicConnectionFactory” on page 321
v A new subscriber cleanup utility, to avoid any problems that result from the
non-graceful closure of subscriber objects. See “Subscriber cleanup utility” on
page 188.
v Support for Application Server Facilities, that is the concurrent processing of
messages. See:
– “Chapter 13. MQ JMS Application Server Facilities” on page 209
– “ConnectionConsumer” on page 243
– “QueueConnection” on page 288
– “Session” on page 301
– “TopicConnection” on page 319
v Updates to LDAP server configuration information. See “Appendix C. LDAP
schema definition for storing Java objects” on page 353.
v Support for distributed transactions using the X/Open XA protocol. That is, MQ
JMS includes XA classes so that MQ JMS can participate in a two-phase commit
that is coordinated by an appropriate transaction manager. See:
– “Appendix E. JMS JTA/XA interface with WebSphere” on page 361
– “XAConnection” on page 334
– “XAConnectionFactory” on page 335
– “XAQueueConnection” on page 336
– “XAQueueConnectionFactory” on page 337
– “XAQueueSession” on page 339
– “XASession” on page 340
– “XATopicConnection” on page 342
– “XATopicConnectionFactory” on page 344
– “XATopicSession” on page 346

Changes to the sixth edition (SC34-5456-05)

Support for Linux included.

xvi MQSeries Using Java

 Part 1. Guidance for users
Chapter 1. Getting started . . . . . . . . . 3 Publish/Subscribe verification with JNDI . . . 27
What is MQSeries classes for Java? . . . . . . . 3 PSIVT error recovery . . . . . . . . . . 28
What is MQSeries classes for Java Message Service? 3 Running your own MQ JMS programs . . . . . 28
Who should use MQ Java? . . . . . . . . . 3 Solving problems . . . . . . . . . . . . 29
Connection options . . . . . . . . . . . . 4 Tracing programs . . . . . . . . . . . 29
Client connection . . . . . . . . . . . . 5 Logging . . . . . . . . . . . . . . 29
Using VisiBroker for Java . . . . . . . . . 5
Bindings connection . . . . . . . . . . . 6 Chapter 5. Using the MQ JMS administration tool 31
Prerequisites . . . . . . . . . . . . . . 6 Invoking the Administration tool . . . . . . . 31
Configuration . . . . . . . . . . . . . 32
Chapter 2. Installation procedures . . . . . . 7 Configuring for WebSphere . . . . . . . . 33
| Obtaining MQSeries classes for Java and MQSeries Security . . . . . . . . . . . . . . 33
| classes for Java Message Service . . . . . . . . 7 Administration commands . . . . . . . . . 34
Installing MQSeries classes for Java and MQSeries Manipulating subcontexts . . . . . . . . . 35
classes for Java Message Service . . . . . . . . 7 Administering JMS objects . . . . . . . . . 35
Installing on UNIX . . . . . . . . . . . 8 Object types . . . . . . . . . . . . . 35
| Installing on z/OS & OS/390 . . . . . . . . 9 Verbs used with JMS objects . . . . . . . . 36
Installing on iSeries & AS/400 . . . . . . . 9 Creating objects . . . . . . . . . . . . 37
Installing on Linux . . . . . . . . . . . 9 LDAP naming considerations . . . . . . 37
Installing on Windows. . . . . . . . . . 10 Properties . . . . . . . . . . . . . . 38
Installation directories . . . . . . . . . . 10 Property dependencies . . . . . . . . . 41
Environment variables . . . . . . . . . . 11 The ENCODING property . . . . . . . . 42
Web server configuration . . . . . . . . . . 12 Sample error conditions . . . . . . . . . 43

Chapter 3. Using MQSeries classes for Java (MQ

base Java) . . . . . . . . . . . . . . 13
Using the sample applet to verify the TCP/IP client 13
Using the sample applet on iSeries or AS/400 . . 13
Configuring your queue manager to accept client
connections . . . . . . . . . . . . . 13
TCP/IP client. . . . . . . . . . . . 14
Running from appletviewer . . . . . . . . 15
Customizing the verification applet . . . . . 15
Verifying with the sample application . . . . . 16
Using VisiBroker connectivity . . . . . . . 17
Running your own MQ base Java programs . . . 17
Solving MQ base Java problems . . . . . . . 17
Tracing the sample applet . . . . . . . . 17
Tracing the sample application . . . . . . . 17
Error messages . . . . . . . . . . . . 18

Chapter 4. Using MQSeries classes for Java

Message Service (MQ JMS) . . . . . . . . 19
Post installation setup . . . . . . . . . . . 19
Additional setup for Publish/Subscribe mode . . 20
| For a broker running on a remote queue
| manager . . . . . . . . . . . . . 21
Queues that require authorization for
non-privileged users . . . . . . . . . . 21
Running the point-to-point IVT . . . . . . . . 22
Point-to-point verification without JNDI . . . . 22
Point-to-point verification with JNDI . . . . . 23
IVT error recovery . . . . . . . . . . . 25
The Publish/Subscribe Installation Verification Test 25
Publish/Subscribe verification without JNDI . . 26

© Copyright IBM Corp. 1997, 2001 1

2 MQSeries Using Java
Chapter 1. Getting started
This chapter gives an overview of MQSeries classes for Java and MQSeries classes
for Java Message Service, and their uses.

What is MQSeries classes for Java?

MQSeries classes for Java (MQ base Java) allows a program written in the Java
programming language to:
v Connect to MQSeries as an MQSeries client
v Connect directly to an MQSeries server

It enables Java applets, applications, and servlets to issue calls and queries to
MQSeries. This gives access to mainframe and legacy applications, typically over
the Internet, without necessarily having any other MQSeries code on the client
machine. With MQ base Java, the user of an Internet terminal can become a true
participant in transactions, rather than just a giver and receiver of information.

What is MQSeries classes for Java Message Service?

MQSeries classes for Java Message Service (MQ JMS) is a set of Java classes that
implement Sun’s Java Message Service (JMS) interfaces to enable JMS programs to
access MQSeries systems. Both the point-to-point and publish-and-subscribe
models of JMS are supported.

The use of MQ JMS as the API to write MQSeries applications has a number of
benefits. Some advantages derive from JMS being an open standard with multiple
implementations. Other advantages result from additional features that are present
in MQ JMS, but not in MQ base Java.

Benefits arising from the use of an open standard include:

v The protection of investment, both in skills and application code
v The availability of people skilled in JMS application programming
v The ability to plug in different JMS implementations to fit different requirements
More information about the benefits of the JMS API is on Sun’s Web site at
http://java.sun.com.

The extra function provided over MQ base Java includes:

v Asynchronous message delivery
v Message selectors
v Support for publish/subscribe messaging
v Structured message classes

Who should use MQ Java?

If your enterprise fits any of the following scenarios, you can gain significant
advantage by using MQSeries classes for Java and MQSeries classes for Java
Message Service:
v A medium or large enterprise that is introducing intranet-based client/server
solutions. Here, Internet technology provides low cost easy access to global

© Copyright IBM Corp. 1997, 2001 3

Who should use MQ Java
communications, while MQSeries connectivity provides high integrity with
assured delivery and time independence.
v A medium or large enterprise with a need for reliable business-to-business
communications with partner enterprises. Here again, the Internet provides
low-cost easy access to global communications, while MQSeries connectivity
provides high integrity with assured delivery and time independence.
v A medium or large enterprise that wishes to provide access from the public
Internet to some of its enterprise applications. Here, the Internet provides global
reach at a low cost, while MQSeries connectivity provides high integrity through
the queuing paradigm. In addition to low cost, the business can achieve
improved customer satisfaction through 24 hour a day availability, fast response,
and improved accuracy.
v An Internet Service provider, or other Value Added Network provider. These
companies can exploit the low cost and easy communications provided by the
Internet. They can also add value with the high integrity provided by MQSeries
connectivity. An Internet Service provider that exploits MQSeries can
immediately acknowledge receipt of input data from a Web browser, guarantee
delivery, and provide an easy way for the user of the Web browser to monitor
the status of the message.

MQSeries and MQSeries classes for Java Message Service provide an excellent
infrastructure for access to enterprise applications and for development of complex
Web applications. A service request from a Web browser can be queued then
processed when possible, thus allowing a timely response to be sent to the end
user, regardless of system loading. By placing this queue ’close’ to the user in
network terms, the load on the network does not impact the timeliness of the
response. Also, the transactional nature of MQSeries messaging means that a
simple request from the browser can be expanded safely into a sequence of
individual back-end processes in a transactional manner.

MQSeries classes for Java also enables application developers to exploit the power
of the Java programming language to create applets and applications that can run
on any platform that supports the Java runtime environment. These factors
combine to reduce the development time for multi-platform MQSeries applications
significantly. Also, if there are enhancements to applets in the future, end users
automatically pick these up as the applet code is downloaded.

Connection options
Programmable options allow MQ Java to connect to MQSeries in either of the
following ways:
v As an MQSeries client using Transmission Control Protocol/Internet Protocol
(TCP/IP)
v In bindings mode, connecting directly to MQSeries
MQ base Java on Windows NT® can also connect using VisiBroker for Java. Table 1
on page 5 shows the connection modes that can be used for each platform.

4 MQSeries Using Java

 Connections
Table 1. Platforms and connection modes
Server platform Standard Client VisiBroker Bindings
Client
Windows NT yes yes yes
®
Windows 2000 yes no yes
®
AIX yes no yes
Sun OS (v4.1.4 and earlier) yes no no
Sun Solaris (v2.6, v2.8, V7, or yes no yes
SunOS v5.6, v5.7)
OS/2® yes no yes
®
OS/400 yes no yes
HP-UX yes no yes
AT&T GIS UNIX yes no no
SINIX and DC/OSx yes no no
OS/390 no no yes
Linux yes no no

Notes:
1. HP-UX Java bindings support is available only for HP-UXv11 systems running
the POSIX draft 10 pthreaded version of MQSeries. You also require the HP-UX
Developer’s Kit for Java 1.1.7 (JDK™), Release C.01.17.01 or above.
2. On HP-UXv10.20, Linux, Windows 95, and Windows 98, only TCP/IP client
connectivity is supported.

The following sections describe these options in more detail.

Client connection
To use MQ Java as an MQSeries client, you can install it either on the MQSeries
server machine, which may also contain a Web server, or on a separate machine. If
you install MQ Java on the same machine as a Web server, an advantage is that
you can download and run MQSeries client applications on machines that do not
have MQ Java installed locally.

Wherever you choose to install the client, you can run it in three different modes:
From within any Java-enabled Web browser
In this mode, the locations of the MQSeries queue managers that can be
accessed may be constrained by the security restrictions of the browser that
is used.
Using an appletviewer
To use this method, you must have the Java Development Kit (JDK) or
Java Runtime Environment (JRE) installed on the client machine.
As a standalone Java program or in a Web application server
To use this method, you must have the Java Development Kit (JDK) or
Java Runtime Environment (JRE) installed on the client machine.

Using VisiBroker for Java

On the Windows platform, connection using VisiBroker is provided as an
alternative to using the standard MQSeries client protocols. This support is

Chapter 1. Getting started 5

 Connections
provided by VisiBroker for Java in conjunction with Netscape Navigator, and
requires VisiBroker for Java and an MQSeries object server on the MQSeries server
machine. A suitable object server is provided with MQ base Java.

Bindings connection
When used in bindings mode, MQ Java uses the Java Native Interface (JNI) to call
directly into the existing queue manager API, rather than communicating through
a network. This provides better performance for MQSeries applications than using
network connections. Unlike the client mode, applications that are written using
the bindings mode cannot be downloaded as applets.

To use the bindings connection, MQ Java must be installed on the MQSeries server.

Prerequisites
To run MQ base Java, you require the following software:
v MQSeries for the server platform you wish to use.
v Java Development Kit (JDK) for the server platform.
v Java Development Kit, or Java Runtime Environment (JRE), or Java-enabled Web
browser for client platforms. (See “Client connection” on page 5.)
v VisiBroker for Java (only if running on Windows with a VisiBroker connection).
| v For z/OS & OS/390, OS/390 Version 2 Release 9 or higher, or z/OS, with UNIX
| System Services (USS).
v For OS/400, the AS/400 Developer Kit for Java, 5769-JV1, and the Qshell
Interpreter, OS/400 (5769-SS1) Option 30.

To use the MQ JMS administration tool (see “Chapter 5. Using the MQ JMS
administration tool” on page 31), you require the following additional software:
v At least one of the following service provider packages:
– Lightweight Directory Access Protocol (LDAP) - ldap.jar, providerutil.jar.
– File system - fscontext.jar, providerutil.jar.
v A Java Naming and Directory Service (JNDI) service provider. This is the
resource that stores physical representations of the administered objects. Users of
MQ JMS will probably use an LDAP server for this purpose, but the tool also
supports the use of the file system context service provider. If an LDAP server is
used, it must be configured to store JMS objects. For information to assist with
this configuration, refer to “Appendix C. LDAP schema definition for storing
Java objects” on page 353.

To use the XOpen/XA facilities of MQ JMS, you require MQSeries V5.2.

6 MQSeries Using Java

 Chapter 2. Installation procedures
This chapter describes how to install the MQSeries classes for Java and MQSeries
classes for Java Message Service product.

| Obtaining MQSeries classes for Java and MQSeries classes for Java
| Message Service
| This product is available for the AIX, iSeries & AS/400, HP-UX, Linux, Sun Solaris,
| z/OS & OS/390, and Windows platforms. It contains:
| v MQSeries classes for Java (MQ base Java) Version 5.2.0
| v MQSeries classes for Java Message Service (MQ JMS) Version 5.2

| For the connectivity available on each specific platform, refer to “Connection

| options” on page 4.

| The product is supplied as compressed files that are available from the MQSeries
| Web site, http://www.ibm.com/software/mqseries/. The files are supplied as part
| of SupportPac MA88. Follow links to “Download” and then “SupportPacs” to find
| the MQ Java code.

| Note: Before installing or using MQ Java, remember to consult the README file
| that is found in the doc subdirectory with the installed code. This may
| contain information that corrects or supplements this book.
|
Installing MQSeries classes for Java and MQSeries classes for Java
Message Service
For the latest versions of just the MQ base Java classes, you can install MQ base
Java Version 5.2.0 alone. To use MQ JMS applications, you must install both MQ
base Java and MQ JMS (together known as MQ Java).

MQ base Java is contained in the following Java .jar files:

com.ibm.mq.jar This code includes support for all the connection
options.
com.ibm.mq.iiop.jar This code supports only the VisiBroker connection.
It is supplied only on the Windows platform.
com.ibm.mqbind.jar This code supports only the bindings connection
and is not supplied or supported on all platforms.
We recommend that you do not use it in any new
applications.

MQ JMS is contained in the following Java .jar file:

com.ibm.mqjms.jar

The following Java libraries from Sun Microsystems are redistributed with the MQ
JMS product:
connector.jar Version 1.0 Public Draft

© Copyright IBM Corp. 1997, 2001 7

 Installing MQ base Java and MQ JMS
fscontext.jar Early Access 4 Release
jms.jar Version 1.0.2
| jndi.jar Version 1.1.2 (except for z/OS & OS/390)
| ldap.jar Version 1.0.3 (except for z/OS & OS/390)
providerutil.jar Version 1.0

For installation instructions, see the section that is relevant to the platform you
require:
AIX, HP-UX, and Sun Solaris “Installing on UNIX”
| z/OS and OS/390 “Installing on z/OS & OS/390” on page 9
| iSeries & AS/400 “Installing on iSeries & AS/400” on page 9
Linux “Installing on Linux” on page 9
Windows “Installing on Windows” on page 10

When installation is complete, files and samples are installed in the locations
shown in “Installation directories” on page 10.

After installation, you must update your environment variables, as shown in

“Environment variables” on page 11.

Note: Take care if you install the product, then subsequently install or reinstall
base MQSeries. Make sure that you do not install MQ base Java version 5.1,
because your MQSeries Java support will revert back a level.

Installing on UNIX
This section describes how to install MQ Java on AIX, HP-UX, and Sun Solaris. For
information about installing MQ base Java on Linux, see “Installing on Linux” on
page 9.

| Note: If this is a client-only installation (that is, an MQSeries server is not

installed), you must set up the group and user ID mqm. For more
information, please see the MQSeries Quick Beginnings manual relevant to
your platform.
1. Log on as root.
2. Copy the file ma88_xxx.tar.Z in binary format, and store it in the directory
/tmp, where xxx is the appropriate platform identifier:
v aix AIX
v hp10 HP-UXv10
v hp11 HP-UXv11
v sol Sun Solaris
3. Enter the following commands (where xxx is the appropriate platform
identifier):
uncompress -fv /tmp/ma88_xxx.tar.Z
tar -xvf /tmp/ma88_xxx.tar
rm /tmp/ma88_xxx.tar

These commands create the necessary files and directories.

4. Use the appropriate installation tool for each platform:
v For AIX, use smitty and:

8 MQSeries Using Java

 Installing on UNIX
a. Uninstall all components that begin with mqm.java.
b. Install components from the /tmp directory.
v For HP-UX, use sam and install from the file ma88_hp10 or ma88_hp11, as
appropriate.

Note: Java does not support code page 1051 (which is the default for
HP-UX). To run the Publish/Subscribe broker on HP-UX, you may
need to change the CCSID of the broker’s queue manager to an
alternative value, for example 819.
v For Sun Solaris, enter the following command and select the options you
require:
pkgadd -d /tmp mqjava

Then, enter the following command:

rm -R /tmp/mqjava

| Installing on z/OS & OS/390

| This section describes how to install MQ base Java on z/OS & OS/390.
| 1. Select an installation directory for the product in a USS HFS (for example,
| /usr/lpp). If this directory is not in your home directory, you may need
| appropriate authority.
| 2. Copy the file ma88_zos.tar.Z into your home directory in USS.
| 3. Change directory to your selected installation directory; for example: cd
| /usr/lpp
| 4. Enter the following command:
| tar -xozf ∼/ma88_zos.tar.Z

| This creates and populates a directory named mqm in the current directory.

| Installing on iSeries & AS/400

| This section describes how to install MQ Java on AS/400.
| 1. Copy the file ma88_iSeries.zip to a directory on your PC.
| 2. Uncompress the file using InfoZip’s Unzip facility.
| This creates the file ma88_iSeries.savf.
| 3. Create a save file called MA88 in a suitable library on the iSeries or AS/400; for
| example, in the QGPL library:
| CRTSAVF FILE(QGPL/MA88)
| 4. Transfer ma88_iSeries.savf into this save file as a binary image. If you use FTP
| to do this, the put command should be similar to:
| PUT C:\TEMP\MA88_ISERIES.SAVF QGPL/MA88
| 5. Install MQSeries classes for Java, product number 5648C60, using RSTLICPGM:
| RSTLICPGM LICPGM(5648C60) DEV(*SAVF) SAVF(QGPL/MA88)
| 6. Delete the save file created in step 3:
| DLTF FILE(QGPL/MA88)

| Installing on Linux
This section describes how to install MQ Java on Linux.

For Linux, there are two installation files available, ma88_linux.tgz and
MQSeriesJava-5.2.0-1.noarch.rpm. Each file provides an identical installation.

Chapter 2. Installation procedures 9

 Installing on Linux
If you have root access to the target system, or use a Red Hat Package Manager
(RPM) database to install packages, use MQSeriesJava-5.2.0-1.noarch.rpm.

If you do not have root access to the target system, or the target system does not
have RPM installed, use ma88_linux.tgz.

To install using ma88_linux.tgz:

1. Select an installation directory for the product (for example, /opt).
If this directory is not in your home directory, you may need to log in as root.
2. Copy the file ma88_linux.tgz into your home directory.
3. Change directory to your selected installation directory, for example:
cd /opt
4. Enter the following command:
tar -xpzf ∼/ma88_linux.tgz

This creates and populates a directory named mqm in the current directory (for
example, /opt).

To install using MQSeriesJava-5.2.0-1.noarch.rpm:

1. Log in as root.
2. Copy MQSeriesJava-5.2.0-1.noarch.rpm into a working directory.
3. Enter the following command:
rpm -i MQSeriesJava-5.2.0-1.noarch.rpm

This installs the product to /opt/mqm/. It is possible to install to a different

path (please refer to your RPM documentation for further details).

Installing on Windows
This section describes how to install MQ Java on Windows.
1. Create an empty directory called tmp and make it the current directory.
2. Copy the file ma88_win.zip to this directory.
3. Uncompress ma88_win.zip using InfoZip’s Unzip facility.
4. Run setup.exe from this directory and follow the prompts on the resulting
windows.

Note: If you wish to install MQ base Java only, select the relevant options at
this stage.

Installation directories
The MQ Java V5.2 files are installed in the directories shown in Table 2.
Table 2. Product installation directories
Platform Directory
AIX usr/mqm/java/
| z/OS & OS/390 install_dir/mqm/java/
| iSeries & AS/400 /QIBM/ProdData/mqm/java/
HP-UX and Sun Solaris opt/mqm/java/
Linux install_dir/mqm/java/
Windows 95, 98, 2000, and NT install_dir\

10 MQSeries Using Java

 Installation directories
Table 2. Product installation directories (continued)
Platform Directory
| Note: install_dir is the directory in which you installed the product. On Linux, this is likely
| to be /opt and on z/OS & OS/390 it is likely to be /usr/lpp.

Environment variables
After installation, you must update your CLASSPATH environment variable to
include the MQ base Java code and samples directories. Table 3 shows typical
CLASSPATH settings for the various platforms.
Table 3. Sample CLASSPATH statements for the product
Platform Sample CLASSPATH
AIX CLASSPATH=/usr/mqm/java/lib/com.ibm.mq.jar:
/usr/mqm/java/lib/connector.jar:
/usr/mqm/java/lib:
/usr/mqm/java/samples/base:
HP-UX and CLASSPATH=/opt/mqm/java/lib/com.ibm.mq.jar:
Sun Solaris /opt/mqm/java/lib/connector.jar:
/opt/mqm/java/lib:
/opt/mqm/java/samples/base:
Windows 95, 98, CLASSPATH=install_dir\lib\com.ibm.mq.jar;
2000, and NT install_dir\lib\com.ibm.mq.iiop.jar;
install_dir\lib\connector.jar;
install_dir\lib\;
install_dir\samples\base\;
| z/OS & OS/390 CLASSPATH=install_dir/mqm/java/lib/com.ibm.mq.jar:
| install_dir/mqm/java/lib/connector.jar:
| install_dir/mqm/java/lib:
| install_dir/mqm/java/samples/base:
| iSeries & AS/400 CLASSPATH=/QIBM/ProdData/mqm/java/lib/com.ibm.mq.jar:
| /QIBM/ProdData/mqm/java/lib/connector.jar:
| /QIBM/ProdData/mqm/java/lib:
| /QIBM/ProdData/mqm/java/samples/base:
Linux CLASSPATH=install_dir/mqm/java/lib/com.ibm.mq.jar:
install_dir/mqm/java/lib/connector.jar:
install_dir/mqm/java/lib:
install_dir/mqm/java/samples/base:

Notes:
1. jdk_dir is the directory in which the JDK is installed
2. install_dir is the directory in which you installed the product

To use MQ JMS, you must include additional jar files in the classpath. These are
listed in “Post installation setup” on page 19.

If there are existing applications with a dependency on the deprecated bindings

package com.ibm.mqbind, you must also add the file com.ibm.mqbind.jar to your
classpath.

You must update additional environment variables on some platforms, as shown in

Table 4 on page 12.

Chapter 2. Installation procedures 11

 Installation directories
Table 4. Environment variables for the product
Platform Environment variable
AIX LD_LIBRARY_PATH=/usr/mqm/java/lib
HP_UX SHLIB_PATH=/opt/mqm/java/lib
Sun Solaris LD_LIBRARY_PATH=/opt/mqm/java/lib
Windows 95, 98, PATH=install_dir\lib
2000, and NT
| z/OS & OS/390 LIBPATH=install_dir/mqm/java/lib
Note: install_dir is the installation directory for the product

Notes:
1. To use MQSeries Bindings for Java on OS/400, ensure that the library
QMQMJAVA is in your library list.
2. Ensure that you append the MQSeries variables and do not overwrite any of
the existing system environment variables. If you overwrite existing system
environment variables, the application might fail during compilation or at
runtime.

Web server configuration

If you install MQSeries Java on a Web server, you can download and run MQSeries
Java applications on machines that do not have MQSeries Java installed locally. To
make the MQSeries Java files accessible to your Web server, you must set up your
Web server configuration to point to the directory where the client is installed.
Consult your Web server documentation for details of how to configure this.

| Note: On z/OS & OS/390, the installed classes do not support client connection
and cannot be usefully downloaded to clients. However, jar files from
| another platform can be transferred to z/OS or OS/390 and served to
clients.

12 MQSeries Using Java

 Chapter 3. Using MQSeries classes for Java (MQ base Java)
This chapter describes:
v How to configure your system to run the sample applet and application
programs to verify your MQ base Java installation.
v How to modify the procedures to run your own programs.

| Remember to check the README file installed with the MQ Java code for later or
| more specific information for your environment.

The procedures depend on the connection option you want to use. Follow the
instructions in the section that is appropriate for your requirements.

Using the sample applet to verify the TCP/IP client

| MQ base Java includes an installation verification applet, mqjavac.html. You can
| use the applet to verify the TCP/IP connected client mode of MQ base Java except
| on the z/OS & OS/390 platform. On the z/OS & OS/390 platform applets are not
| supported, so you must use the sample application for verification instead. For
| instructions on how to do this, see “Verifying with the sample application” on
| page 16.

| In addition, the standard security settings for applets in Java 1.2 and higher require
| that all referenced classes are loaded from the same location as the applet you wish
| to run. For information on ways to get applets that use MQ Java to work, see
| “Appendix F. Using MQ Java in applets with Java 1.2 or later” on page 367.

The applet connects to a given queue manager, exercises all the MQSeries calls,
and produces diagnostic messages if there are any failures.

You can run the applet from the appletviewer supplied with your JDK. The
appletviewer can access a queue manager on any host.

In all cases, if the applet does not complete successfully, follow the advice given in
the diagnostic messages and try to run the applet again.

Using the sample applet on iSeries or AS/400

The OS/400 operating system does not have a native Graphical User Interface
(GUI). To run the sample applet, you need to use the Remote Abstract Window
Toolkit for Java (AWT), or the Class Broker for Java (CBJ), on graphics capable
hardware. You can also verify the client from the command line (see “Verifying
with the sample application” on page 16).

Configuring your queue manager to accept client connections

Use the following procedures to configure your queue manager to accept incoming
connection requests from the clients.

© Copyright IBM Corp. 1997, 2001 13

 Verifying client mode
TCP/IP client
1. Define a server connection channel using the following procedures:
| For the iSeries or AS/400 platform:
| a. Start your queue manager by using the STRMQM command.
| b. Define a sample channel called JAVA.CHANNEL by issuing the
| following command:
| CRTMQMCHL CHLNAME(JAVA.CHANNEL) CHLTYPE(*SVRCN) MQMNAME(QMGRNAME)
| MCAUSERID(SOMEUSERID) TEXT('Sample channel for MQSeries Client for Java')

| where QMGRNAME is the name of your queue manager, and

| SOMEUSERID is an iSeries or AS/400 user ID with appropriate
| authority to the MQSeries resources.
| For z/OS or OS/390 platforms:

| Note: You must have the Client attachment feature installed on your
| target queue manager in order to connect via TCP/IP.
| a. Start your queue manager by using the START QMGR command.
| b. Define a sample channel called JAVA.CHANNEL by issuing the
| following command:
| DEF CHL('JAVA.CHANNEL') CHLTYPE(SVRCONN) TRPTYPE(TCP)
| DESCR('Sample channel for MQSeries Client for Java')
| For other platforms:
| a. Start your queue manager by using the strmqm command.
| b. Type the following command to start the runmqsc program:
| runmqsc
| c. Define a sample channel called JAVA.CHANNEL by issuing the
| following command:
| DEF CHL('JAVA.CHANNEL') CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER(' ') +
| DESCR('Sample channel for MQSeries Client for Java')
| 2. Start a listener program with the following commands:
For OS/2 and NT operating systems:
Issue the command:
runmqlsr -t tcp [-m QMNAME] -p 1414

Note: If you use the default queue manager, you can omit the -m
option.
Using VisiBroker for Java on the Windows NT operating system:
Start the IIOP (Internet Inter-ORB Protocol) server with the following
command:
java com.ibm.mq.iiop.Server

Note: To stop the IIOP server, issue the following command:

java com.ibm.mq.iiop.samples.AdministrationApplet shutdown
For UNIX operating systems:
Configure the inetd daemon, so that the inetd starts the MQSeries
channels. See MQSeries Clients for instructions on how to do this.
For the OS/400 operating system:
Issue the command:
STRMQMLSR MQMNAME(QMGRNAME)

14 MQSeries Using Java

 Verifying client mode
where QMGRNAME is the name of your queue manager.
| For the z/OS or OS/390 operating system:
| a. Ensure your channel initiator is started. If not, start it by issuing the
| START CHINIT command.
| b. Start the listener by issuing the command START LISTENER
| TRPTYPE(TCP) PORT(1414)

Running from appletviewer

To use this method, you must have the Java Development Kit (JDK) installed on
your machine.
Local installation procedure
1. Change to your samples directory for your language.
2. Type:
appletviewer mqjavac.html
Web server installation procedure:
Enter the command:
appletviewer http://Web.server.host/MQJavaclient/mqjavac.html
Notes:
1. On some platforms, the command is “applet”, and not “appletviewer”.
2. On some platforms, you may need to select Properties from the Applet menu at
the top left of your screen, and then set Network Access to “Unrestricted”.

By using this technique, you should be able to connect to any queue manager
running on any host to which you have TCP/IP access.

Customizing the verification applet

The mqjavac.html file includes some optional parameters. These parameters allow
you to modify the applet to suit your requirements. Each parameter is defined in a
line of HTML, which looks like the following:
<!PARAM name="xxx" value="yyy">

To specify a parameter value, remove the initial exclamation mark, and edit the
value as desired. You can specify the following parameters:
hostname The value to display initially in the hostname edit box.
port The value to display initially in the port number edit box.
channel The value to display initially in the channel edit box.
queueManager
The value to display initially in the queue manager edit box.
userID Uses the specified user ID when connecting to the queue manager.
password Uses the specified password when connecting to the queue
manager.
trace Causes MQ base Java to write a trace log. Use this option only at
the direction of IBM service.

Chapter 3. Using MQSeries classes for Java (MQ base Java) 15

 Installation verification program

Verifying with the sample application

An installation verification program, MQIVP, is supplied with MQ base Java. You
can use this application to test all the connection modes of MQ base Java. The
program prompts for a number of choices and other data to determine which
connection mode you want to verify. Use the following procedure to verify your
installation:
1. To test a client connection:
a. Configure your queue manager, as described in “Configuring your queue
manager to accept client connections” on page 13.
b. Carry out the rest of this procedure on the client machine.

To test a bindings connection, carry out the rest of this procedure on the
MQSeries server machine.
2. Change to your samples directory.
3. Type:
java MQIVP

The program tries to:

a. Connect to, and disconnect from, the named queue manager.
b. Open, put, get, and, close the system default local queue.
c. Return a message if the operations are successful.
4. At prompt (1), leave the default “MQSeries”.
5. At prompt (2):
v To use a TCP/IP connection, enter an MQSeries server hostname.
v To use native connection (bindings mode), leave the field blank. (Do not
enter a name.)

Here is an example of the prompts and responses you may see. The actual prompts
and your responses depend on your MQSeries network.
Please enter the type of connection (MQSeries) : (MQSeries)(1)
Please enter the IP address of the MQSeries server : myhost(2)
Please enter the port to connect to : (1414)(3)
Please enter the server connection channel name : JAVA.CHANNEL(3)
Please enter the queue manager name :
Success: Connected to queue manager.
Success: Opened SYSTEM.DEFAULT.LOCAL.QUEUE
Success: Put a message to SYSTEM.DEFAULT.LOCAL.QUEUE
Success: Got a message from SYSTEM.DEFAULT.LOCAL.QUEUE
Success: Closed SYSTEM.DEFAULT.LOCAL.QUEUE
Success: Disconnected from queue manager

Tests complete -
SUCCESS: This transport is functioning correctly.
Press Enter to continue...
Notes:
1. If you choose server connection, you do not see the prompts marked (3).
| 2. On z/OS & OS/390, leave the field blank at prompt (2).
3. On OS/400, you can run the command java MQIVP only from the Qshell
interactive interface (the Qshell is option 30 of OS/400, 5769-SS1). Alternatively,
you can run the application by using the CL command RUNJVA CLASS(MQIVP).
4. To use the MQSeries bindings for Java on OS/400, you must ensure that the
library QMQMJAVA is in your library list.

16 MQSeries Using Java

 Installation verification program
Using VisiBroker connectivity
If you are using VisiBroker, the procedures described in “Configuring your queue
manager to accept client connections” on page 13 are not required.

To test an installation that is using VisiBroker, use the procedures described in

“Verifying with the sample application” on page 16, but at prompt (1), type
VisiBroker, using the exact case.

Running your own MQ base Java programs

To run your own Java applets or applications, use the procedures described for the
verification programs, substituting your application name in place of
“mqjavac.html” or “MQIVP”.

For information on writing MQ base Java applications and applets, see “Part 2.
Programming with MQ base Java” on page 45.

Solving MQ base Java problems

If a program does not complete successfully, run the installation verification applet
or installation verification program, and follow the advice given in the diagnostic
messages. Both of these programs are described in “Chapter 3. Using MQSeries
classes for Java (MQ base Java)” on page 13.

If the problems continue and you need to contact the IBM service team, you may
be asked to turn on the trace facility. The method to do this depends on whether
you are running in client mode or bindings mode. Refer to the following sections
for the appropriate procedures for your system.

Tracing the sample applet

To run trace with the sample applet, edit the mqjavac.html file. Find the following
line:
<!PARAM name="trace" value="1">

Remove the exclamation mark and change the value from 1 to a number from 1 to
5, depending on the level of detail required. (The greater the number, the more
information is gathered.) The line should then read:
<PARAM name="trace" value="n">

where “n” is a number between 1 and 5.

The trace output appears in the Java console or in your Web browser’s Java log
file.

Tracing the sample application

To trace the MQIVP program, enter the following:
java MQIVP -trace n

where “n” is a number between 1 and 5, depending on the level of detail required.
(The greater the number, the more information is gathered.)

For more information about how to use trace, see “Tracing MQ base Java
programs” on page 70.

Chapter 3. Using MQSeries classes for Java (MQ base Java) 17

Error messages
Error messages
Here are some of the more common error messages that you may see:
Unable to identify local host IP address
The server is not connected to the network.
Recommended Action: Connect the server to the network and retry.
Unable to load file gatekeeper.ior
This failure can occur on a Web server deploying VisiBroker applets, when
the gatekeeper.ior file is not located in the correct place.
Recommended Action: Restart the VisiBroker Gatekeeper from the directory
in which the applet is deployed. The gatekeeper file will be written to this
directory.
Failure: Missing software, may be MQSeries, or VBROKER_ADM variable
This failure occurs in the MQIVP sample program if your Java software
environment is incomplete.
Recommended Action: On the client, ensure that the VBROKER_ADM
environment variable is set to address the VisiBroker for Java
administration (adm) directory, and retry.
On the server, ensure that the most recent version of MQ base Java is
installed, and retry.
NO_IMPLEMENT
There is a communications problem involving VisiBroker Smart Agents.
Recommended Action: Consult your VisiBroker documentation.
COMM_FAILURE
There is a communications problem involving VisiBroker Smart Agents.
Recommended Action: Use the same port number for all VisiBroker Smart
Agents and retry. Consult your VisiBroker documentation.
MQRC_ADAPTER_NOT_AVAILABLE
If you get this error when you attempt to use VisiBroker, probably the
JAVA class org.omg.CORBA.ORB cannot be found in the CLASSPATH.
Recommended Action: Ensure that your CLASSPATH statement includes the
path to the VisiBroker vbjorb.jar and vbjapp.jar files.
MQRC_ADAPTER_CONN_LOAD_ERROR
If you see this error while running on OS/390, ensure that the MQSeries
SCSQANLE, and SCSQAUTH datasets are in your STEPLIB statement.

18 MQSeries Using Java

 Chapter 4. Using MQSeries classes for Java Message Service
(MQ JMS)
This chapter describes the following tasks:
v How to set up your system to use the Test and sample programs
v How to run the point-to-point Installation Verification Test (IVT) program to
verify your MQSeries classes for Java Message Service installation
v How to run the sample Publish/Subscribe Installation Verification Test (PSIVT)
program to verify your Publish/Subscribe installation
v How to run your own programs

Post installation setup

| Note: Remember to check the README file installed with the MQ Java programs
| for information that may supersede this book.

To make all the necessary resources available to MQ JMS programs, you need to
update the following system variables:
Classpath
Successful operation of JMS programs requires a number of Java packages
to be available to the JVM. You must specify these on the classpath after
you have obtained and installed the necessary packages.
Add the following .jar files to the classpath:
v com.ibm.mq.jar
v com.ibm.mqjms.jar
v connector.jar
v jms.jar
| v jndi.jar1
v jta.jar
| v ldap.jar1
v providerutil.jar
Environment variables
There are a number of scripts in the bin subdirectory of the MQ JMS
installation. These are intended for use as convenient shortcuts for a
number of common actions. Many of these scripts assume that the
environment variable MQ_JAVA_INSTALL_PATH is defined, and that it points
to the directory in which MQ JMS is installed. It is not mandatory to set
this variable, but if you do not set it, you must edit the scripts in the bin
directory accordingly.

On Windows NT, you can set the classpath and new environment variable by
using the Environment tab of the System Properties. On UNIX, these would

1. For z/OS & OS/390, use ibmjndi.jar and jndi.jar from /usr/lpp/ldap/lib instead of jndi.jar and ldap.jar. These files are
supplied with the operating system.

© Copyright IBM Corp. 1997, 2001 19

 Setup
normally be set from each user’s logon scripts. On any platform, you can choose to
use scripts to maintain different classpaths and other environment variables for
different projects.

Additional setup for Publish/Subscribe mode

Before you can use the MQ JMS implementation of JMS Publish/Subscribe, some
additional setup is required:
Ensure that the Broker is Running
To verify that the MQSeries Publish/Subscribe broker is installed and is
running, use the command:
dspmqbrk -m MY.QUEUE.MANAGER

where MY.QUEUE.MANAGER is the name of the queue manager on which the

broker is running. If the broker is running, a message similar to the
following is displayed:
MQSeries message broker for queue manager MY.QUEUE.MANAGER running.

If the operating system reports that it cannot run the dspmqbrk command,
ensure that the MQSeries Publish/Subscribe broker is installed properly.

If the operating system reports that the broker is not active, start it using
the command:
strmqbrk -m MY.QUEUE.MANAGER
Create the MQ JMS System Queues
For the MQ JMS Publish/Subscribe implementation to work correctly, a
number of system queues must be created. A script is supplied, in the bin
subdirectory of the MQ JMS installation, to assist with this task. To use the
script, enter the following commands:
| For iSeries & AS/400:
| 1. Copy the script from the integrated file system to a native file
| system library using a command similar to
| CPYFRMSTMF FROMSTMF('/QIBM/ProdData/mqm/java/bin/MQJMS_PSQ.mqsc')
| TOMBR('/QSYS.LIB/QGPL.LIB/QCLSRC.FILE/MQJMS_PSQ.MBR')
| 2. Call the script file using STRMQMMQSC:
| STRMQMMQSC SRCMBR(MQJMS_PSQ) SRCFILE(QGPL/QCLSRC)
| For z/OS & OS/390:
| 1. Copy the script from the HFS into a PDS using a TSO
| command similar to
| OGET '/usr/lpp/mqm/java/bin/MQJMS_PSQ.mqsc' 'USERID.MQSC(MQJMSPSQ)'

| The PDS should be of fixed-block format with a record length

| of 80.
| 2. Either use the CSQUTIL application to execute this command
| script, or add the script to the CSQINP2 DD concatenation in
| your queue manager’s started task JCL. In either case, refer to
| the MQSeries for OS/390 System Management Guide book for
| further details.
| For other platforms:
| runmqsc MY.QUEUE.MANAGER < MQJMS_PSQ.mqsc

20 MQSeries Using Java

 Publish/Subscribe setup
| If an error occurs, check that you typed the queue manager name correctly,
and check that the queue manager is running.

| For a broker running on a remote queue manager

| For operation with a broker running on a remote queue manager, further setup is
| required.
| 1. Define a transmission queue on the remote queue manager with a queue name
| matching the local queue manager. These names must match for correct routing
| of messages by MQSeries.
| 2. Define a sender channel on the remote queue manager and a receiver channel
| on the local queue manager. The sender channel should use the transmission
| queue defined in step 1.
| 3. Setup the local queue manager for communication with the remote broker:
| a. Define a local transmission queue. You must give it the same name as the
| queue manager running the remote broker.
| b. Define local sender and remote receiver channels to the remote broker
| queue manager. The sender channel should use the transmission queue
| defined in step 3a.
| 4. To operate the remote broker, take the following steps:
| a. Start the remote broker queue manager.
| b. Start a listener for the remote broker queue manager (TCP/IP channels).
| c. Start the sender and receiver channels to the local queue manager.
| d. Start the broker on the remote queue manager.
| An example command is
| strmqbrk -m MyBrokerMgr
| 5. To operate the local queue manager to communicate with the remote broker,
| take the following steps:
| a. Start the local queue manager.
| b. Start a listener for the local queue manager.
| c. Start the sender and receiver channels to the remote broker queue manager.

Queues that require authorization for non-privileged users

Non-privileged users need authorization granted to access the queues used by
JMS. For details about access control in MQSeries, see the chapter about protecting
MQSeries objects in MQSeries System Administration.

For JMS point-to-point mode, the access control issues are similar to those for the
MQSeries classes for Java:
v Queues that are used by QueueSender require put authority.
v Queues that are used by QueueReceivers and QueueBrowsers require get, inq
and browse authorities.
v The QueueSession.createTemporaryQueue method requires access to the model
queue that is defined in the QueueConnectionFactory temporaryModel field (by
default this will be SYSTEM.DEFAULT.MODEL.QUEUE).

For JMS publish/subscribe mode, the following system queues are used:
SYSTEM.JMS.ADMIN.QUEUE
SYSTEM.JMS.REPORT.QUEUE
SYSTEM.JMS.MODEL.QUEUE
SYSTEM.JMS.PS.STATUS.QUEUE

Chapter 4. Using MQSeries classes for Java Message Service (MQ JMS) 21
 Publish/Subscribe setup
SYSTEM.JMS.ND.SUBSCRIBER.QUEUE
SYSTEM.JMS.D.SUBSCRIBER.QUEUE
SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE
SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE
SYSTEM.BROKER.CONTROL.QUEUE

Also, any application that publishes messages requires access to the STREAM
queue that is specified in the topic connection factory being used. The default
value for this is:
SYSTEM.BROKER.DEFAULT.STREAM

| If you use the functionality of ConnectionConsumer, additional authorization may

| be needed. Queues to be read by the ConnectionConsumer must have get, inq and
| browse authorities. The system dead-letter queue, and any backout-requeue queue
| or report queue used by the ConnectionConsumer must have put and passall
| authorities.

Running the point-to-point IVT

This section describes the point-to-point installation verification test program (IVT)
that is supplied with MQ JMS.

The IVT attempts to verify the installation by connecting to the default queue
manager on the local machine, using the MQ JMS in bindings mode. It then sends
a message to the SYSTEM.DEFAULT.LOCAL.QUEUE queue and reads it back again.

You can run the program in one of two possible modes.

With JNDI lookup of administered objects
JNDI mode forces the program to obtain its administered objects from a
JNDI namespace, which is the expected operation of JMS client
applications. (See “Administering JMS objects” on page 35 for a description
of administered objects). This invocation method has the same
prerequisites as the administration tool (see “Chapter 5. Using the MQ JMS
administration tool” on page 31).
Without JNDI lookup of administered objects
If you do not wish to use JNDI, the administered objects can be created at
runtime by running the IVT in non-JNDI mode. Because a JNDI-based
repository is relatively complex to set up, we recommend that the IVT is
first run without JNDI.

Point-to-point verification without JNDI

A script, named IVTRun on UNIX, or IVTRun.bat on Windows NT, is provided to
run the IVT. This file is installed in the bin subdirectory of the installation.

To run the test without JNDI, issue the following command:

| IVTRun -nojndi [-m <qmgr>]

For client mode, to run the test without JNDI, issue the following command:
IVTRun -nojndi -client -m <qmgr> -host <hostname> [-port <port>]
[-channel <channel>]

where:

22 MQSeries Using Java

 Point-to-point IVT
qmgr is the name of the queue manager to which you wish to connect
hostname is the host on which the queue manager is running
port is the TCP/IP port on which the queue manager’s listener is
running (default 1414)
channel is the client connection channel (default SYSTEM.DEF.SVRCONN)

If the test completes successfully, you should see output similar to the following:
5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
MQSeries Classes for Java(tm) Message Service - Installation Verification Test

Creating a QueueConnectionFactory
Creating a Connection
Creating a Session
Creating a Queue
Creating a QueueSender
Creating a QueueReceiver
Creating a TextMessage
Sending the message to SYSTEM.DEFAULT.LOCAL.QUEUE
Reading the message back again

Got message: Message Class: jms_text JMSType: null

JMSDeliveryMode: 2 JMSExpiration: 0
JMSPriority: 4 JMSMessageID: ID:414d5120716
d312020202020202020203000c43713400000
JMSTimestamp: 935592657000 JMSCorrelationID: null
JMSDestination: queue:///SYSTEM.DEFAULT.LOCAL.QUEUE
JMSReplyTo: null
JMSRedelivered: false
JMS_IBM_Format:MQSTR JMS_IBM_PutApplType:11
JMSXGroupSeq:1 JMSXDeliveryCount:0
JMS_IBM_MsgType:8 JMSXUserID:kingdon
JMSXApplID:D:\jdk1.1.8\bin\java.exe
A simple text message from the MQJMSIVT program
Reply string equals original string
Closing QueueReceiver
Closing QueueSender
Closing Session
Closing Connection
IVT completed OK
IVT finished

Point-to-point verification with JNDI

To run the IVT with JNDI, the LDAP server must be running and must be
configured to accept Java objects. If the following message occurs, it indicates that
there is a connection to the LDAP server, but the server is not correctly configured:
Unable to bind to object

This message means that either the server is not storing Java objects, or the
permissions on the objects or the suffix are not correct. See “Checking your LDAP
server configuration” on page 353.

Also, the following administered objects must be retrievable from a JNDI

namespace:
v MQQueueConnectionFactory
v MQQueue
A script, named IVTSetup on UNIX, or IVTSetup.bat on Windows NT, is provided
to create these objects automatically. Enter the command:
IVTSetup

Chapter 4. Using MQSeries classes for Java Message Service (MQ JMS) 23
Point-to-point IVT
The script invokes the MQ JMS Administration tool (see “Chapter 5. Using the MQ
JMS administration tool” on page 31) and creates the objects in a JNDI namespace.

The MQQueueConnectionFactory is bound under the name ivtQCF (for LDAP,

cn=ivtQCF). All the properties are default values:
TRANSPORT(BIND)
PORT(1414)
HOSTNAME(localhost)
CHANNEL(SYSTEM.DEF.SVRCONN)
VERSION(1)
CCSID(819)
TEMPMODEL(SYSTEM.DEFAULT.MODEL.QUEUE)
QMANAGER()

The MQQueue is bound under the name ivtQ (cn=ivtQ). The value of the QUEUE
property becomes QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE). All other properties have
default values:
PERSISTENCE(APP)
QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE)
EXPIRY(APP)
TARGCLIENT(JMS)
ENCODING(NATIVE)
VERSION(1)
CCSID(1208)
PRIORITY(APP)
QMANAGER()

Once the administered objects are created in the JNDI namespace, run the IVTRun
(IVTRun.bat on Windows NT) script using the following command:
IVTRun [ -t ] -url <"providerURL"> [ -icf <initCtxFact> ]

where:
-t means turn tracing on (by default, tracing is off)
providerURL is the JNDI location of the administered objects. If the default
initial context factory is in use, this is an LDAP URL of the form:
ldap://hostname.company.com/contextName

If a file system service provider is used, (see initCtxFact below),

the URL is of the form:
file://directorySpec

Note: Enclose the providerURL string in quotation marks (″).

initCtxFact is the classname of the initial context factory. The default is for an
LDAP service provider, and has the value:
com.sun.jndi.ldap.LdapCtxFactory

If a file system service provider is used, set this parameter to:

com.sun.jndi.fscontext.RefFSContextFactory

If the test completes successfully, the output is similar to the non-JNDI output,
except that the ’create’ QueueConnectionFactory and Queue lines indicate retrieval
of the object from JNDI. The following code fragment shows an example.
5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
MQSeries Classes for Java(tm) Message Service - Installation Verification Test

Using administered objects, please ensure that these are available

24 MQSeries Using Java

 Point-to-point IVT

Retrieving a QueueConnectionFactory from JNDI

Creating a Connection
Creating a Session
Retrieving a Queue from JNDI
Creating a QueueSender
...
...

Although not strictly necessary, it is good practice to remove objects that are
created by the IVTSetup script from the JNDI namespace. A script called IVTTidy
(IVTTidy.bat on Windows NT) is provided for this purpose.

IVT error recovery

If the test is not successful, the following notes may be helpful:
v For assistance with any error messages involving classpath, check that your
classpath is set correctly, as described in “Post installation setup” on page 19.
v The IVT might fail with a message “failed to create MQQueueManager”, with an
additional message including the number 2059. This indicates that MQSeries
failed to connect to the default local queue manager on the machine on which
you ran the IVT. Check that the queue manager is running, and that it is marked
as the default queue manager.
v A message “failed to open MQ queue” indicates that MQSeries connected to the
default queue manager, but could not open the
SYSTEM.DEFAULT.LOCAL.QUEUE. This may indicate that either the queue
does not exist on your default queue manager, or the queue is not enabled for
PUT and GET. Add or enable the queue for the duration of the test.

Table 5 lists the classes that are tested by IVT, and the package that they come
from:
Table 5. Classes that are tested by IVT
Class Jar file
MQSeries JMS classes com.ibm.mqjms.jar
com.ibm.mq.MQMessage com.ibm.mq.jar
javax.jms.Message jms.jar
javax.naming.InitialContext jndi.jar
javax.resource.cci.Connection connector.jar
javax.transaction.xa.XAException jta.jar
com/sun/jndi/toolkit/ComponentDirContext providerutil.jar
com.sun.jndi.ldap.LdapCtxFactory ldap.jar

The Publish/Subscribe Installation Verification Test

The Publish/Subscribe Installation Verification Test (PSIVT) program is supplied
only in compiled form. It is in the com.ibm.mq.jms package.

| The test requires a broker such as the MQSeries publish/subscribe broker

| (SupportPac MA0C) or MQSeries Integrator V2 to be installed and running.

The PSIVT attempts to:

1. Create a publisher, p, publishing on the topic MQJMS/PSIVT/Information

Chapter 4. Using MQSeries classes for Java Message Service (MQ JMS) 25
 Publish/Subscribe IVT
2. Create a subscriber, s, subscribing on the topic MQJMS/PSIVT/Information
3. Use p to publish a simple text message
4. Use s to receive a message waiting on its input queue

When you run the PSIVT, the publisher publishes the message, and the subscriber
receives and displays the message. The publisher publishes to the broker’s default
stream. The subscriber is non-durable, does not perform message selection, and
accepts messages from local connections. It performs a synchronous receive,
waiting a maximum of 5 seconds for a message to arrive.

You can run the PSIVT, like the IVT, in either JNDI mode or standalone mode.
JNDI mode uses JNDI to retrieve a TopicConnectionFactory and a Topic from a
JNDI namespace. If JNDI is not used, these objects are created at runtime.

Publish/Subscribe verification without JNDI

A script named PSIVTRun (PSIVTRun.bat on Windows NT) is provided to run
PSIVT. The file is in the bin subdirectory of the installation.

To run the test without JNDI, issue the following command:

| PSIVTRun -nojndi [-m <qmgr>] [-bqm <broker>] [-t]

For client mode, to run the test without JNDI, issue the following command:
| PSIVTRun -nojndi -client -m <qmgr> -host <hostname> [-port <port>]
| [-channel <channel>] [-bqm <broker>] [-t]

where:
-nojndi means no JNDI lookup of the administered objects
qmgr is the name of the queue manager to which you wish to connect
hostname is the host on which the queue manager is running
port is the TCP/IP port on which the queue manager’s listener is
running (default 1414)
channel is the client connection channel (default SYSTEM.DEF.SVRCONN)
| broker is the name of the remote queue manager on which the broker is
| running. If this is not specified, the value used for qmgr is
| assumed.
-t means turn tracing on (default is off)

If the test completes successfully, output is similar to the following:

5648-C60 (c) Copyright IBM Corp. 1999. All Rights Reserved.
MQSeries Classes for Java(tm) Message Service
Publish/Subscribe Installation Verification Test
Creating a TopicConnectionFactory
Creating a Topic
Creating a Connection
Creating a Session
Creating a TopicPublisher
Creating a TopicSubscriber
Creating a TextMessage
Adding Text
Publishing the message to topic://MQJMS/PSIVT/Information
Waiting for a message to arrive...

Got message:

26 MQSeries Using Java

 Publish/Subscribe IVT
JMS Message class: jms_text
JMSType: null
JMSDeliveryMode: 2
JMSExpiration: 0
JMSPriority: 4
JMSMessageID: ID:414d5120514d2e504f4c415249532e4254b7dc3753700000
JMSTimestamp: 937232048000
JMSCorrelationID:ID:414d51580000000000000000000000000000000000000000
JMSDestination: topic
://MQJMS/PSIVT/Information
JMSReplyTo: null
JMSRedelivered: false
JMS_IBM_Format:MQSTR
UNIQUE_CONNECTION_ID:937232047753
JMS_IBM_PutApplType:26
JMSXGroupSeq:1
JMSXDeliveryCount:0
JMS_IBM_MsgType:8
JMSXUserID:hollingl
JMSXApplID:QM.POLARIS.BROKER
A simple text message from the MQJMSPSIVT program

Reply string equals original string

Closing TopicSubscriber
Closing TopicPublisher
Closing Session
Closing Connection
PSIVT completed OK
PSIVT finished

Publish/Subscribe verification with JNDI

To run the PSIVT in JNDI mode, two administered objects must be retrievable from
a JNDI namespace:
v A TopicConnectionFactory bound under the name ivtTCF
v A Topic bound under the name ivtT

You can define these objects by using the MQ JMS Administration Tool (see
“Chapter 5. Using the MQ JMS administration tool” on page 31) and using the
following commands:
DEFINE TCF(ivtTCF)

This command defines the TopicConnectionFactory.

DEFINE T(ivtT) TOPIC(MQJMS/PSIVT/Information)

This command defines the Topic.

These definitions assume that a default queue manager, on which the broker is
running, is available. For details on configuring these objects to use a non-default
queue manager, see “Administering JMS objects” on page 35. These objects should
reside in a context pointed to by the -url command-line parameter described
below.

To run the test in JNDI mode, enter the following command:

PSIVTRun -url <purl> [-icf <initcf>] [-t]

where:
-t means turn tracing on (by default, tracing is off)
-url <purl> is the URL of the JNDI location in which the administered objects
reside

Chapter 4. Using MQSeries classes for Java Message Service (MQ JMS) 27
Publish/Subscribe IVT
-icf <initcf> is the initialContextFactory for JNDI
[com.sun.jndi.ldap.LdapCtxFactory ]

If the test completes successfully, output is similar to the non-JNDI output, except
that the “create” QueueConnectionFactory and Queue lines indicate retrieval of the
object from JNDI.

PSIVT error recovery

If the test is not successful, the following notes may be helpful:
v If you see the following message:
*** The broker is not running! Please start it using 'strmqbrk' ***

this indicates that the broker is installed on the target queue manager, but its
control queue contains some outstanding messages. This indicates that the
broker is not running. To start it, use the strmqbrk command. (See “Additional
setup for Publish/Subscribe mode” on page 20.)
v If the following message is displayed:
Unable to connect to queue manager: <default>

ensure that your MQSeries system has configured a default queue manager.
v If the following message is displayed:
Unable to connect to queue manager: ...

ensure that the administered TopicConnectionFactory that the PSIVT uses is

configured with a valid queue manager name. Alternatively, if you used the
-nojndi option, ensure that you supplied a valid queue manager (use the -m
option).
v If the following message is displayed:
Unable to access broker control queue on queue manager: ...
Please ensure the broker is installed on this queue manager

ensure that the administered TopicConnectionFactory that the PSIVT uses is

configured with the name of the queue manager on which the broker is
installed. If you used the -nojndi option, ensure that you supplied a queue
manager name (use the -m option).

Running your own MQ JMS programs

For information on writing your own MQ JMS programs, see “Chapter 10. Writing
MQ JMS programs” on page 169.

MQ JMS includes a utility file, runjms (runjms.bat on Windows NT), to help you
to run the supplied programs and programs that you have written.

The utility provides default locations for the trace and log files, and enables you to
add any application runtime parameters that your application needs. The supplied
script assumes that the environment variable MQ_JAVA_INSTALL_PATH is set to
the directory in which the MQ JMS is installed. The script also assumes that the
subdirectories trace and log within that directory are used for trace and log
output, respectively. These are only suggested locations, and you can edit the script
to use any directory you choose.

Use the following command to run your application:

runjms <classname of application> [application-specific arguments]

28 MQSeries Using Java

 Running MQ JMS programs
For information on writing MQ JMS applications and applets, see “Part 3.
Programming with MQ JMS” on page 167.

Solving problems
If a program does not complete successfully, run the installation verification
program, which is described in “Chapter 4. Using MQSeries classes for Java
Message Service (MQ JMS)” on page 19, and follow the advice given in the
diagnostic messages.

Tracing programs
The MQ JMS trace facility is provided to help IBM staff to diagnose customer
problems.

Trace is disabled by default, because the output rapidly becomes large, and is
unlikely to be of use in normal circumstances.

If you are asked to provide trace output, you can enable it by setting the Java
property MQJMS_TRACE_LEVEL to one of the following values:
on traces MQ JMS calls only
base traces both MQ JMS calls and the underlying MQ base Java calls

For example:
java -DMQJMS_TRACE_LEVEL=base MyJMSProg

To disable trace, set MQJMS_TRACE_LEVEL to off.

By default, trace is output to a file named mqjms.trc in the current working

directory. You can redirect it to a different directory by using the Java property
MQJMS_TRACE_DIR.

For example:
java -DMQJMS_TRACE_LEVEL=base -DMQJMS_TRACE_DIR=/somepath/tracedir MyJMSProg

The runjms utility script sets these properties by using the environment variables
MQJMS_TRACE_LEVEL and MQ_JAVA_INSTALL_PATH, as follows:
java -DMQJMS_LOG_DIR=%MQ_JAVA_INSTALL_PATH%\log
-DMQJMS_TRACE_DIR=%MQ_JAVA_INSTALL_PATH%\trace
-DMQJMS_TRACE_LEVEL=%MQJMS_TRACE_LEVEL% %1 %2 %3 %4 %5 %6 %7 %8 %9

This is only a suggestion, and you can modify it as required.

Logging
The MQ JMS log facility is provided to report serious problems, particularly those
that may indicate configuration errors rather than programming errors. By default,
log output is sent to the System.err stream, which usually appears on the stderr
of the console in which the JVM is run.

You can redirect the output to a file by using a Java property that specifies the new
location, for example:
java -DMQJMS_LOG_DIR=/mydir/forlogs MyJMSProg

The utility script runjms, in the bin directory of the MQ JMSinstallation, sets this
property to:

Chapter 4. Using MQSeries classes for Java Message Service (MQ JMS) 29
Logging
<MQ_JAVA_INSTALL_PATH>/log

where MQ_JAVA_INSTALL_PATH is the path to your MQ JMS installation. This is a

suggestion, which you can modify as required.

When the log is redirected to a file, it is output in a binary form. To view the log,
the utility formatLog (formatLog.bat on Windows NT) is provided, which converts
the file to plain text format. The utility is stored in the bin directory of your MQ
JMS installation. Run the conversion as follows:
formatLog <inputfile> <outputfile>

30 MQSeries Using Java

Chapter 5. Using the MQ JMS administration tool
The administration tool enables administrators to define the properties of eight
types of MQ JMS object and to store them within a JNDI namespace. Then, JMS
clients can retrieve these administered objects from the namespace by using JNDI
and use them.

The JMS objects that you can administer by using the tool are:
v MQQueueConnectionFactory
v MQTopicConnectionFactory
v MQQueue
v MQTopic
v MQXAQueueConnectionFactory
v MQXATopicConnectionFactory
v JMSWrapXAQueueConnectionFactory
v JMSWrapXATopicConnectionFactory

For details about these objects, refer to “Administering JMS objects” on page 35.

Note: JMSWrapXAQueueConnectionFactory and

JMSWrapXATopicConnectionFactory are classes that are specific to
WebSphere™. They are contained in the package com.ibm.ejs.jms.mq.

The tool also allows administrators to manipulate directory namespace subcontexts

within the JNDI. See “Manipulating subcontexts” on page 35.

Invoking the Administration tool

The administration tool has a command line interface. You can use this
interactively, or use it to start a batch process. The interactive mode provides a
command prompt where you can enter administration commands. In the batch
mode, the command to start the tool includes the name of a file which contains an
administration command script.

To start the tool in interactive mode, enter the command:

JMSAdmin [-t] [-v] [-cfg config_filename]

where:
-t Enables trace (default is trace off)
-v Produces verbose output (default is terse output)
-cfg config_filename The name of an alternative configuration file (see
“Configuration” on page 32)

A command prompt is displayed, which indicates that the tool is ready to accept
administration commands. This prompt initially appears as:
InitCtx>

indicating that the current context (that is, the JNDI context to which all naming
and directory operations currently refer) is the initial context defined in the
PROVIDER_URL configuration parameter (see “Configuration” on page 32).

© Copyright IBM Corp. 1997, 2001 31

 Invoking the Administration tool
As you traverse the directory namespace, the prompt changes to reflect this, so
that the prompt always displays the current context.

To start the tool in batch mode, enter the command:

JMSAdmin <test.scp

where test.scp is a script file that contains administration commands (see

“Administration commands” on page 34). The last command in the file must be the
END command.

Configuration
You must configure the administration tool with values for the following three
parameters:
INITIAL_CONTEXT_FACTORY
This indicates the service provider that the tool uses. There are currently
three supported values for this property:
v com.sun.jndi.ldap.LdapCtxFactory (for LDAP)
v com.sun.jndi.fscontext.RefFSContextFactory (for file system context)
v com.ibm.ejs.ns.jndi.CNInitialContextFactory (to work with WebSphere’s
CosNaming repository)

| On z/OS & OS/390, com.ibm.jndi.LDAPCtxFactory is also supported and

| provides access to an LDAP server. However, note that it is incompatable
| with com.sun.jndi.ldap.LdapCtxFactory, in that objects created using one
| Initial Context Factory cannot be read or modified using the other.
PROVIDER_URL
This indicates the URL of the session’s initial context, the root of all JNDI
operations carried out by the tool. Three forms of this property are
currently supported:
v ldap://hostname/contextname (for LDAP)
v file:[drive:]/pathname (for file system context)
v iiop://hostname[:port] /[?TargetContext=ctx] (to access “base”
WebSphere CosNaming namespace)
SECURITY_AUTHENTICATION
This indicates whether JNDI passes over security credentials to your
service provider. This parameter is used only when an LDAP service
provider is used. This property can currently take one of three values:
v none (anonymous authentication)
v simple (simple authentication)
v CRAM-MD5 (CRAM-MD5 authentication mechanism)

If a valid value is not supplied, the property defaults to none. See

“Security” on page 33 for more details about security with the
administration tool.

These parameters are set in a configuration file. When you invoke the tool, you can
specify this configuration by using the -cfg command-line parameter, as described
in “Invoking the Administration tool” on page 31. If you do not specify a
configuration file name, the tool attempts to load the default configuration file
(JMSAdmin.config). It looks for this file first in the current directory, and then in the
| <MQ_JAVA_INSTALL_PATH>/bin directory, where “<MQ_JAVA_INSTALL_PATH>” is the
| path to your MQ JMS installation.

32 MQSeries Using Java

 Configuration
The configuration file is a plain-text file that consists of a set of key-value pairs,
separated by an “=”. This is shown in the following example:
#Set the service provider
INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory
#Set the initial context
PROVIDER_URL=ldap://polaris/o=ibm_us,c=us
#Set the authentication type
SECURITY_AUTHENTICATION=none

(A “#” in the first column of the line indicates a comment, or a line that is not
used.)

The installation comes with a sample configuration file that is called

JMSAdmin.config, and is found in the <MQ_JAVA_INSTALL_PATH>/bin directory. Edit
this file to suit the setup of your system.

Configuring for WebSphere

For the administration tool (or any client application that needs to do subsequent
lookups) to work with WebSphere’s CosNaming repository, you require the
following configuration:
v CLASSPATH must include WebSphere’s JNDI-related jar files:
– For WebSphere V3.5:
<WSAppserver>\lib\ujc.jar
v PATH for WebSphere V.3.5 must include:
<WSAppserver>\jdk\jre\bin

where “<WSAppserver>” is the install path for WebSphere.

Security
Administrators need to know about the effect of the SECURITY_AUTHENTICATION
property described in “Configuration” on page 32.
v If this parameter is set to none, JNDI does not pass any security credentials to
the service provider, and “anonymous authentication” is performed.
v If the parameter is set to either simple or CRAM-MD5, security credentials are
passed through JNDI to the underlying service provider. These security
credentials are in the form of a user distinguished name (User DN) and
password.
If security credentials are required, then the user will be prompted for these when
the tool initializes.

Note: The text typed is echoed to the screen, and this includes the password.
Therefore, take care that passwords are not disclosed to unauthorized users.

The tool does no authentication itself; the task is delegated to the LDAP server. It
is the responsibility of the LDAP server administrator to set up and maintain
access privileges to different parts of the directory. If authentication fails, the tool
displays an appropriate error message and terminates.

More detailed information about security and JNDI is in the documentation at

Sun’s Java website (http://java.sun.com).

Chapter 5. Using the MQ JMS administration tool 33

Administration commands

Administration commands
When the command prompt is displayed, the tool is ready to accept commands.
Administration commands are generally of the following form:
verb [param]*

where verb is one of the administration verbs listed in Table 6. All valid commands
consist of at least one (and only one) verb, which appears at the beginning of the
command in either its standard or short form.

The parameters a verb may take depend on the verb. For example, the END verb
cannot take any parameters, but the DEFINE verb may take anything between 1 and
20 parameters. Details of the verbs that take at least one parameter are discussed
in later sections of this chapter.
Table 6. Administration verbs
Verb Short form Description
ALTER ALT Change at least one of the properties of a given
administered object
DEFINE DEF Create and store an administered object, or create a new
subcontext
DISPLAY DIS Display the properties of one or more stored administered
objects, or the contents of the current context
DELETE DEL Remove one or more administered objects from the
namespace, or remove an empty subcontext
CHANGE CHG Alter the current context, allowing the user to traverse the
directory namespace anywhere below the initial context
(pending security clearance)
COPY CP Make a copy of a stored administered object, storing it
under an alternative name
MOVE MV Alter the name under which an administered object is
stored
END Close the administration tool

Verb names are not case-sensitive.

Usually, to terminate commands, you press the carriage return key. However, you
can override this by typing the “+” symbol directly before the carriage return. This
enables you to enter multi-line commands, as shown in the following example:
DEFINE Q(BookingsInputQueue) +
QMGR(QM.POLARIS.TEST) +
QUEUE(BOOKINGS.INPUT.QUEUE) +
PORT(1415) +
CCSID(437)

Lines beginning with one of the characters *, #, or / are treated as comments, or

lines that are ignored.

34 MQSeries Using Java

 Manipulating subcontexts

Manipulating subcontexts
You can use the verbs CHANGE, DEFINE, DISPLAY and DELETE to manipulate directory
namespace subcontexts. Their use is described in Table 7.
Table 7. Syntax and description of commands used to manipulate subcontexts
Command syntax Description
DEFINE CTX(ctxName) Attempts to create a new child subcontext of the current
context, having the name ctxName. Fails if there is a
security violation, if the subcontext already exists, or if the
name supplied is invalid.
DISPLAY CTX Displays the contents of the current context. Administered
objects are annotated with ‘a’, subcontexts with ‘[D]’. The
Java type of each object is also displayed.
DELETE CTX(ctxName) Attempts to delete the current context’s child context
having the name ctxName. Fails if the context is not found,
is non-empty, or if there is a security violation.
CHANGE CTX(ctxName) Alters the current context, so that it now refers to the child
context having the name ctxName. One of two special
values of ctxName may be supplied:
=UP which moves to the current context’s parent
=INIT which moves directly to the initial context

Fails if the specified context does not exist, or if there is a

security violation.

Administering JMS objects

This section describes the eight types of object that the administration tool can
handle. It includes details about each of their configurable properties and the verbs
that can manipulate them.

Object types
Table 8 shows the eight types of administered objects. The Keyword column shows
the strings that you can substitute for TYPE in the commands shown in Table 9 on
page 36.
Table 8. The JMS object types that are handled by the administration tool
Object Type Keyword Description
MQQueueConnectionFactory QCF The MQSeries implementation of the
JMS QueueConnectionFactory
interface. This represents a factory
object for creating connections in the
point-to-point domain of JMS.
MQTopicConnectionFactory TCF The MQSeries implementation of the
JMS TopicConnectionFactory interface.
This represents a factory object for
creating connections in the
publish/subscribe domain of JMS.
MQQueue Q The MQSeries implementation of the
JMS Queue interface. This represents
a destination for messages in the
point-to-point domain of JMS.

Chapter 5. Using the MQ JMS administration tool 35

Administering JMS objects
Table 8. The JMS object types that are handled by the administration tool (continued)
Object Type Keyword Description
MQTopic T The MQSeries implementation of the
JMS Topic interface. This represents a
destination for messages in the
publish/subscribe domain of JMS.
MQXAQueueConnectionFactory1 XAQCF The MQSeries implementation of the
JMS XAQueueConnectionFactory
interface. This represents a factory
object for creating connections in the
point-to-point domain of JMS that use
the XA versions of JMS classes.
MQXATopicConnectionFactory1 XATCF The MQSeries implementation of the
JMS XATopicConnectionFactory
interface. This represents a factory
object for creating connections in the
publish/subscribe domain of JMS that
use the XA versions of JMS classes.
JMSWrapXAQueueConnectionFactory2 WSQCF The MQSeries implementation of the
JMS QueueConnectionFactory
interface. This represents a factory
object for creating connections in the
point-to-point domain of JMS that use
the XA versions of JMS classes with
WebSphere.
JMSWrapXATopicConnectionFactory2 WSTCF The MQSeries implementation of the
JMS TopicConnectionFactory interface.
This represents a factory object for
creating connections in the
publish/subscribe domain of JMS that
use the XA versions of JMS classes
with WebSphere.

1. These classes are provided for use by vendors of application servers. They are unlikely
to be directly useful to application programmers.
2. Use this style of ConnectionFactory if you wish your JMS sessions to participate in
global transactions that are coordinated by WebSphere.

Verbs used with JMS objects

You can use the verbs ALTER, DEFINE, DISPLAY, DELETE, COPY, and MOVE to manipulate
administered objects in the directory namespace. Table 9 summarizes their use.
Substitute TYPE with the keyword that represents the required administered object,
as listed in Table 8 on page 35.
Table 9. Syntax and description of commands used to manipulate administered objects
Command syntax Description
ALTER TYPE(name) [property]* Attempts to update the given administered object’s
properties with the ones supplied. Fails if there is a
security violation, if the specified object cannot be
found, or if the new properties supplied are invalid.

36 MQSeries Using Java

 Administering JMS objects
Table 9. Syntax and description of commands used to manipulate administered
objects (continued)
Command syntax Description
DEFINE TYPE(name) [property]* Attempts to create an administered object of type
TYPE with the supplied properties, and tries to store it
under the name name in the current context. Fails if
there is a security violation, if the supplied name is
invalid or already exists, or if the properties supplied
are invalid.
DISPLAY TYPE(name) Displays the properties of the administered object of
type TYPE, bound under the name name in the current
context. Fails if the object does not exist, or if there is
a security violation.
DELETE TYPE(name) Attempts to remove the administered object of type
TYPE, having the name name, from the current context.
Fails if the object does not exist, or if there is a
security violation.
COPY TYPE(nameA) Makes a copy of the administered object of type TYPE,
TYPE(nameB) having the name nameA, naming the copy nameB. This
all occurs within the scope of the current context.
Fails if the object to be copied does not exist, if an
object of name nameB already exists, or if there is a
security violation.
MOVE TYPE(nameA) Moves (renames) the administered object of type
TYPE(nameB) TYPE, having the name nameA, to nameB. This all occurs
within the scope of the current context. Fails if the
object to be moved does not exist, if an object of
name nameB already exists, or if there is a security
violation.

Creating objects
Objects are created and stored in a JNDI namespace using the following command
syntax:
DEFINE TYPE(name) [property]*

That is, the DEFINE verb, followed by a TYPE(name) administered object reference,
followed by zero or more properties (see “Properties” on page 38).

LDAP naming considerations

To store your objects in an LDAP environment, their names must comply with
certain conventions. One of these is that object and subcontext names must include
a prefix, such as cn= (common name), or ou= (organizational unit).

The administration tool simplifies the use of LDAP service providers by allowing
you to refer to object and context names without a prefix. If you do not supply a
prefix, the tool automatically adds a default prefix (currently cn=) to the name you
supply.

Chapter 5. Using the MQ JMS administration tool 37

Administering JMS objects
This is shown in the following example.
InitCtx> DEFINE Q(testQueue)

InitCtx> DISPLAY CTX

Contents of InitCtx

a cn=testQueue com.ibm.mq.jms.MQQueue

1 Object(s)
0 Context(s)
1 Binding(s), 1 Administered

Note that although the object name supplied (testQueue) does not have a prefix,
the tool automatically adds one to ensure compliance with the LDAP naming
convention. Likewise, submitting the command DISPLAY Q(testQueue) also causes
this prefix to be added.

You may need to configure your LDAP server to store Java objects. Information to
assist with this configuration is provided in “Appendix C. LDAP schema definition
for storing Java objects” on page 353.

Properties
A property consists of a name-value pair in the format:
PROPERTY_NAME(property_value)

Property names are not case-sensitive, and are restricted to the set of recognized
names shown in Table 10. This table also shows the valid property values for each
property.
Table 10. Property names and valid values
Property Short form Valid values (defaults in bold)
DESCRIPTION DESC Any string
TRANSPORT TRAN v BIND - Connections use MQSeries bindings.
v CLIENT - Client connection is used
CLIENTID CID Any string
QMANAGER QMGR Any string
HOSTNAME HOST Any string
PORT Any positive integer
CHANNEL CHAN Any string
CCSID CCS Any positive integer
RECEXIT RCX Any string
RECEXITINIT RCXI Any string
SECEXIT SCX Any string
SECEXITINIT SCXI Any string
SENDEXIT SDX Any string
SENDXITINIT SDXI Any string
TEMPMODEL TM Any string

38 MQSeries Using Java

 Administering JMS objects
Table 10. Property names and valid values (continued)
Property Short form Valid values (defaults in bold)
MSGRETENTION MRET v Yes - Unwanted messages remain on the input
queue
v No - Unwanted messages are dealt with according
to their disposition options
BROKERVER BVER V1 - The only value currently allowed.
BROKERPUBQ BPUB Any string (default is
SYSTEM.BROKER.DEFAULT.STREAM)
BROKERSUBQ BSUB Any string (default is
SYSTEM.JMS.ND.SUBSCRIPTION.QUEUE)
BROKERDURSUBQ BDSUB Any string (default is
SYSTEM.JMS.D.SUBSCRIPTION.QUEUE)
BROKERCCSUBQ CCSUB Any string (default is
SYSTEM.JMS.ND.CC.SUBSCRIPTION.QUEUE)
BROKERCCDSUBQ CCDSUB Any string (default is
SYSTEM.JMS.D.CC.SUBSCRIPTION.QUEUE)
BROKERQMGR BQM Any string
BROKERCONQ BCON Any string
EXPIRY EXP v APP - Expiry may be defined by the JMS
application.
v UNLIM - No expiry occurs.
v Any positive integer representing expiry in
milliseconds.
PRIORITY PRI v APP - Priority may be defined by the JMS
application.
v QDEF - Priority takes the value of the queue
default.
v Any integer in the range 0-9.
PERSISTENCE PER v APP - Persistence may be defined by the JMS
application.
v QDEF - Persistence takes the value of the queue
default.
v PERS - Messages are persistent.
v NON - messages are non-persistent.
TARGCLIENT TC v JMS - The target of the message is a JMS
application.
v MQ - The target of the message is a non-JMS,
traditional MQSeries application.
ENCODING ENC See “The ENCODING property” on page 42
QUEUE QU Any string
TOPIC TOP Any string

Many of the properties are relevant only to a specific subset of the object types.
| Table 11 on page 40 shows for each property which object types are valid, and
gives a brief description of each property. The object types are identified using
keywords; refer to Table 8 on page 35 for an explanation of these.

Chapter 5. Using the MQ JMS administration tool 39

Administering JMS objects
Table 11. The valid combinations of property and object type
Property QCF TCF Q T WSQCF WSTCF Description
XAQCF XATCF
DESCRIPTION Y Y Y Y Y Y A description of the stored object
1 1
TRANSPORT Y Y Y Y Whether connections will use the MQ
Bindings, or a client connection
CLIENTID Y Y Y Y A string identifier for the client
QMANAGER Y Y Y Y Y The name of the queue manager to
connect to
PORT Y Y The port on which the queue manager
listens
HOSTNAME Y Y The name of the host on which the
queue manager resides
CHANNEL Y Y The name of the client connection
channel being used
CCSID Y Y Y Y The coded-character-set-ID to be used
on connections
RECEXIT Y Y Fully-qualified class name of the
receive exit being used
RECEXITINIT Y Y Receive exit initialization string
SECEXIT Y Y Fully-qualified class name of the
security exit being used
SECEXITINIT Y Y Security exit initialization string
SENDEXIT Y Y Fully-qualified class name of the send
exit being used
SENDEXITINIT Y Y Send exit initialization string
TEMPMODEL Y Y Name of the model queue from which
temporary queues are created
MSGRETENTION Y Y Whether or not the connection
consumer keeps unwanted messages
on the input queue
BROKERVER Y Y The version of the broker being used
BROKERPUBQ Y Y The name of the broker input queue
(stream queue)
BROKERSUBQ Y Y The name of the queue from which
non-durable subscription messages are
retrieved
BROKERDURSUBQ Y The name of the queue from which
durable subscription messages are
retrieved
BROKERCCSUBQ Y Y The name of the queue from which
non-durable subscription messages are
retrieved for a ConnectionConsumer
BROKERCCDSUBQ Y The name of the queue from which
durable subscription messages are
retrieved for a ConnectionConsumer
BROKERQMGR Y Y The queue manager on which the
broker is running
BROKERCONQ Y Y Broker’s control queue name

40 MQSeries Using Java

 Administering JMS objects
Table 11. The valid combinations of property and object type (continued)
Property QCF TCF Q T WSQCF WSTCF Description
XAQCF XATCF
EXPIRY Y Y The period after which messages at a
destination expire
PRIORITY Y Y The priority for messages sent to a
destination
PERSISTENCE Y Y The persistence of messages sent to a
destination
TARGCLIENT Y Y Field indicates whether the MQSeries
RFH2 format is used to exchange
information with target applications
ENCODING Y Y The encoding scheme used for this
destination
QUEUE Y The underlying name of the queue
representing this destination
TOPIC Y The underlying name of the topic
representing this destination

Notes:
1. For WSTCF, WSQCF, XATCF, and XAQCF objects, only the BIND transport
type is allowed.
2. “Appendix A. Mapping between Administration tool properties and
programmable properties” on page 349 shows the relationship between
properties set by the tool and programmable properties.
3. The TARGCLIENT property indicates whether the MQSeries RFH2 format is
used to exchange information with target applications.
The MQJMS_CLIENT_JMS_COMPLIANT constant indicates that the RFH2
format is used to send information. Applications that use MQ JMS understand
the RFH2 format. You should set the MQJMS_CLIENT_JMS_COMPLIANT
constant when you exchange information with a target MQ JMS application.
The MQJMS_CLIENT_NONJMS_MQ constant indicates that the RFH2 format is
not used to send information. Typically, this value is used for an existing
MQSeries application (that is, one that does not handle RFH2).

Property dependencies
Some properties have dependencies on each other. This may mean that it is
meaningless to supply a property unless another property is set to a particular
value. The two specific property groups where this can occur are Client properties
and Exit initialization strings.
Client properties
If the TRANSPORT(CLIENT) property has not been explicitly set on a
connection factory, the transport used on connections provided by the
factory is MQ Bindings. Consequently, none of the client properties on this
connection factory can be configured. These are:
v HOST
v PORT
v CHANNEL
v CCSID
v RECEXIT

Chapter 5. Using the MQ JMS administration tool 41

Administering JMS objects
v RECEXITINIT
v SECEXIT
v SECEXITINIT
v SENDEXIT
v SENDEXITINIT

If you attempt to set any of these properties without setting the TRANSPORT
property to CLIENT, there will be an error.
Exit initialization strings
It is invalid to set any of the exit initialization strings unless the
corresponding exit name has been supplied. The exit initialization
properties are:
v RECEXITINIT
v SECEXITINIT
v SENDEXITINIT

For example, specifying RECEXITINIT(myString) without specifying

RECEXIT(some.exit.classname) causes an error.

The ENCODING property

The valid values that the ENCODING property can take are more complex than the
rest of the properties. The encoding property is constructed from three
sub-properties:
integer encoding this is either normal or reversed
decimal encoding this is either normal or reversed
floating-point encoding this is IEEE normal, IEEE reversed, or System/390®

The ENCODING is expressed as a three-character string with the following syntax:

{N|R}{N|R}{N|R|3}

In this string:
v N denotes normal
v R denotes reversed
v 3 denotes System/390
v the first character represents integer encoding
v the second character represents decimal encoding
v the third character represents floating-point encoding
This provides a set of twelve possible values for the ENCODING property.

There is an additional value, the string NATIVE, which sets appropriate encoding
values for the Java platform.

The following examples show valid combinations for ENCODING:

ENCODING(NNR)
ENCODING(NATIVE)
ENCODING(RR3)

42 MQSeries Using Java

 Administering JMS objects
Sample error conditions
This section provides examples of the error conditions that may arise during the
creation of an object.
Unknown property
InitCtx/cn=Trash> DEFINE QCF(testQCF) PIZZA(ham and mushroom)
Unable to create a valid object, please check the parameters supplied
Unknown property: PIZZA
Invalid property for object
InitCtx/cn=Trash> DEFINE QCF(testQCF) PRIORITY(4)
Unable to create a valid object, please check the parameters supplied
Invalid property for a QCF: PRI
Invalid type for property value
InitCtx/cn=Trash> DEFINE QCF(testQCF) CCSID(english)
Unable to create a valid object, please check the parameters supplied
Invalid value for CCS property: English
Property value outside valid range
InitCtx/cn=Trash> DEFINE Q(testQ) PRIORITY(12)
Unable to create a valid object, please check the parameters supplied
Invalid value for PRI property: 12
Property clash - client/bindings
InitCtx/cn=Trash> DEFINE QCF(testQCF) HOSTNAME(polaris.hursley.ibm.com)
Unable to create a valid object, please check the parameters supplied
Invalid property in this context: Client-bindings attribute clash
Property clash - Exit initialization
InitCtx/cn=Trash> DEFINE QCF(testQCF) SECEXITINIT(initStr)
Unable to create a valid object, please check the parameters supplied
Invalid property in this context: ExitInit string supplied
without Exit string

Chapter 5. Using the MQ JMS administration tool 43

Administering JMS objects

44 MQSeries Using Java

Part 2. Programming with MQ base Java
Chapter 6. Introduction for programmers . . . 47 Variables . . . . . . . . . . . . . . 87
Why should I use the Java interface? . . . . . . 47 Constructors . . . . . . . . . . . . . 87
The MQSeries classes for Java interface . . . . . 48 MQEnvironment. . . . . . . . . . . . . 88
Java Development Kit . . . . . . . . . . . 48 Variables . . . . . . . . . . . . . . 88
MQSeries classes for Java class library . . . . . 49 Constructors . . . . . . . . . . . . . 91
Methods . . . . . . . . . . . . . . 91
Chapter 7. Writing MQ base Java programs. . . 51 MQException . . . . . . . . . . . . . . 93
Should I write applets or applications? . . . . . 51 Variables . . . . . . . . . . . . . . 93
Connection differences. . . . . . . . . . . 51 Constructors . . . . . . . . . . . . . 93
Client connections . . . . . . . . . . . 51 MQGetMessageOptions . . . . . . . . . . 95
Bindings mode . . . . . . . . . . . . 52 Variables . . . . . . . . . . . . . . 95
Defining which connection to use . . . . . . 52 Constructors . . . . . . . . . . . . . 98
Example code fragments . . . . . . . . . . 52 MQManagedObject . . . . . . . . . . . . 99
Example applet code . . . . . . . . . . 52 Variables . . . . . . . . . . . . . . 99
Changing the connection to use VisiBroker for Constructors. . . . . . . . . . . . . 100
Java . . . . . . . . . . . . . . . 55 Methods . . . . . . . . . . . . . . 100
Example application code . . . . . . . . 56 MQMessage . . . . . . . . . . . . . . 102
Operations on queue managers . . . . . . . . 58 Variables . . . . . . . . . . . . . . 102
Setting up the MQSeries environment . . . . 58 Constructors. . . . . . . . . . . . . 110
Connecting to a queue manager . . . . . . 58 Methods . . . . . . . . . . . . . . 110
Accessing queues and processes . . . . . . . 59 MQMessageTracker . . . . . . . . . . . 121
Handling messages . . . . . . . . . . . . 60 Variables . . . . . . . . . . . . . . 121
Handling errors . . . . . . . . . . . . . 61 MQPoolServices . . . . . . . . . . . . 123
Getting and setting attribute values . . . . . . 61 Constructors. . . . . . . . . . . . . 123
Multithreaded programs . . . . . . . . . . 62 Methods . . . . . . . . . . . . . . 123
Writing user exits . . . . . . . . . . . . 63 MQPoolServicesEvent . . . . . . . . . . 124
Connection pooling. . . . . . . . . . . . 64 Variables . . . . . . . . . . . . . . 124
Controlling the default connection pool . . . . 64 Constructors. . . . . . . . . . . . . 124
The default connection pool and multiple Methods . . . . . . . . . . . . . . 125
components . . . . . . . . . . . . . 66 MQPoolToken . . . . . . . . . . . . . 126
Supplying a different connection pool . . . . 67 Constructors. . . . . . . . . . . . . 126
Supplying your own ConnectionManager . . . 68 MQProcess . . . . . . . . . . . . . . 127
Compiling and testing MQ base Java programs . . 69 Constructors. . . . . . . . . . . . . 127
Running MQ base Java applets . . . . . . . 70 Methods . . . . . . . . . . . . . . 127
Running MQ base Java applications . . . . . 70 MQPutMessageOptions . . . . . . . . . . 129
Tracing MQ base Java programs . . . . . . 70 Variables . . . . . . . . . . . . . . 129
Constructors. . . . . . . . . . . . . 131
Chapter 8. Environment-dependent behavior . . 73 MQQueue . . . . . . . . . . . . . . 132
Core details . . . . . . . . . . . . . . 73 Constructors. . . . . . . . . . . . . 132
Restrictions and variations for core classes . . . . 74 Methods . . . . . . . . . . . . . . 132
Version 5 extensions operating in other MQQueueManager . . . . . . . . . . . 140
environments . . . . . . . . . . . . . . 75 Variables . . . . . . . . . . . . . . 140
Constructors. . . . . . . . . . . . . 140
Chapter 9. The MQ base Java classes and Methods . . . . . . . . . . . . . . 142
interfaces . . . . . . . . . . . . . . 79 MQSimpleConnectionManager . . . . . . . 150
MQChannelDefinition . . . . . . . . . . . 80 Variables . . . . . . . . . . . . . . 150
Variables . . . . . . . . . . . . . . 80 Constructors. . . . . . . . . . . . . 150
Constructors . . . . . . . . . . . . . 81 Methods . . . . . . . . . . . . . . 150
MQChannelExit . . . . . . . . . . . . . 82 MQC . . . . . . . . . . . . . . . . 152
Variables . . . . . . . . . . . . . . 82 MQPoolServicesEventListener . . . . . . . . 153
Constructors . . . . . . . . . . . . . 84 Methods . . . . . . . . . . . . . . 153
MQDistributionList . . . . . . . . . . . . 85 MQConnectionManager . . . . . . . . . . 154
Constructors . . . . . . . . . . . . . 85 MQReceiveExit . . . . . . . . . . . . . 155
Methods . . . . . . . . . . . . . . 85 Methods . . . . . . . . . . . . . . 155
MQDistributionListItem . . . . . . . . . . 87 MQSecurityExit . . . . . . . . . . . . 157
Methods . . . . . . . . . . . . . . 157

© Copyright IBM Corp. 1997, 2001 45

MQSendExit. . . . . . . . . . . . . . 159
Methods . . . . . . . . . . . . . . 159
ManagedConnection . . . . . . . . . . . 161
Methods . . . . . . . . . . . . . . 161
ManagedConnectionFactory . . . . . . . . 164
Methods . . . . . . . . . . . . . . 164
ManagedConnectionMetaData . . . . . . . . 166
Methods . . . . . . . . . . . . . . 166

46 MQSeries Using Java

Chapter 6. Introduction for programmers
This chapter contains general information for programmers. For more detailed
information about writing programs, see “Chapter 7. Writing MQ base Java
programs” on page 51.

Why should I use the Java interface?

The MQSeries classes for Java programming interface makes the many benefits of
Java available to you as a developer of MQSeries applications:
v The Java programming language is easy to use.
There is no need for header files, pointers, structures, unions, and operator
overloading. Programs written in Java are easier to develop and debug than
their C and C++ equivalents.
v Java is object-oriented.
The object-oriented features of Java are comparable to those of C++, but there is
no multiple inheritance. Instead, Java uses the concept of an interface.
v Java is inherently distributed.
The Java class libraries contain a library of routines for coping with TCP/IP
protocols like HTTP and FTP. Java programs can access URLs as easily as
accessing a file system.
v Java is robust.
Java puts a lot of emphasis on early checking for possible problems, dynamic
(runtime) checking, and the elimination of situations that are error prone. Java
uses a concept of references that eliminates the possibility of overwriting
memory and corrupting data.
v Java is secure.
Java is intended to be run in networked or distributed environments, and a lot
of emphasis has been placed on security. Java programs cannot overrun their
runtime stack and cannot corrupt memory outside of their process space. When
Java programs are downloaded from the Internet, they cannot even read or write
local files.
v Java programs are portable.
There are no ″implementation-dependent″ aspects of the Java specification. The
Java compiler generates an architecture-neutral object file format. The compiled
code is executable on many processors, as long as the Java runtime system is
present.
If you write your application using MQSeries classes for Java, users can download
the Java byte codes (called applets) for your program from the Internet. Users can
then run these applets on their own machines. This means that users with access to
your Web server can load and run your application with no prior installation
needed on their machines.

When an update to the program is required, you update the copy on the Web
server. The next time that users access the applet, they automatically receive the
latest version. This can significantly reduce the costs involved in installing and
updating traditional client applications where a large number of desktops are
involved.

© Copyright IBM Corp. 1997, 2001 47

 Advantages of Java
If you place your applet on a Web server that is accessible outside the corporate
firewall, anyone on the Internet can download and use your application. This
means that you can get messages into your MQSeries system from anywhere on
the internet. This opens the door to building a whole new set of Internet accessible
service, support, and electronic commerce applications.

The MQSeries classes for Java interface

The procedural MQSeries application programming interface is built around the
following verbs:
MQBACK, MQBEGIN, MQCLOSE, MQCMIT, MQCONN, MQCONNX,
MQDISC, MQGET, MQINQ, MQOPEN, MQPUT, MQPUT1, MQSET

These verbs all take, as a parameter, a handle to the MQSeries object on which
they are to operate. Because Java is object-oriented, the Java programming interface
turns this round. Your program consists of a set of MQSeries objects, which you act
upon by calling methods on those objects, as in the following example.

When you use the procedural interface, you disconnect from a queue manager by
using the call MQDISC(Hconn, CompCode, Reason), where Hconn is a handle to
the queue manager.

In the Java interface, the queue manager is represented by an object of class

MQQueueManager. You disconnect from the queue manager by calling the
disconnect() method on that class.
// declare an object of type queue manager
MQQueueManager queueManager=new MQQueueManager();
...
// do something...
...
// disconnect from the queue manager
queueManager.disconnect();

Java Development Kit

Before you can compile any applets or applications that you write, you must have
access to a Java Development Kit (JDK) for your development platform. The JDK
contains all the standard Java classes, variables, constructors, and interfaces on
which the MQSeries classes for Java classes depend. It also contains the tools
required to compile and run the applets and programs on each supported
platform.

You can download IBM Developer Kits for Java from the IBM Software Download
Catalog, which is available on the World Wide Web at location:
http://www.ibm.com/software/download

You can also develop applications by using the Developer Kit that is included with
the integrated development environment of IBM VisualAge for Java.

| To compile Java applications on the iSeries & AS/400 platforms, you must first
| install:
| v The AS/400 Developer Kit for Java, 5769-JV1
| v The Qshell Interpreter, OS/400 (5769-SS1) Option 30

48 MQSeries Using Java

 MQ base Java class library

MQSeries classes for Java class library

MQSeries classes for Java is a set of Java classes that enable Java applets and
applications to interact with MQSeries.

The following classes are provided:

v MQChannelDefinition
v MQChannelExit
v MQDistributionList
v MQDistributionListItem
v MQEnvironment
v MQException
v MQGetMessageOptions
v MQManagedObject
v MQMessage
v MQMessageTracker
v MQPoolServices
v MQPoolServicesEvent
v MQPoolToken
v MQPutMessageOptions
v MQProcess
v MQQueue
v MQQueueManager
v MQSimpleConnectionManager

The following Java interfaces are provided:

v MQC
v MQPoolServicesEventListener
v MQReceiveExit
v MQSecurityExit
v MQSendExit

Implementation of the following Java interfaces are also provided. However, these
interfaces are not intended for direct use by applications:
v MQConnectionManager
v javax.resource.spi.ManagedConnection
v javax.resource.spi.ManagedConnectionFactory
v javax.resource.spi.ManagedConnectionMetaData

In Java, a package is a mechanism for grouping sets of related classes together. The
MQSeries classes and interfaces are shipped as a Java package called com.ibm.mq.
To include the MQSeries classes for Java package in your program, add the
following line at the top of your source file:
import com.ibm.mq.*;

Chapter 6. Introduction for programmers 49

MQ base Java class library

50 MQSeries Using Java

 Chapter 7. Writing MQ base Java programs
To use MQSeries classes for Java to access MQSeries queues, you write Java
programs that contain calls that put messages onto, and get messages from,
MQSeries queues. The programs can take the form of Java applets, Java servlets, or
Java applications.

This chapter provides information to assist with writing Java applets, servlets, and
applications to interact with MQSeries systems. For details of individual classes,
see “Chapter 9. The MQ base Java classes and interfaces” on page 79.

Should I write applets or applications?

Whether you write applets, servlets, or applications depends on the connection
that you want to use and from where you want to run the programs.

The main differences between applets and applications are:

v Applets are run with an applet viewer or in a Web browser, servlets are run in a
Web application server, and applications are run standalone.
v Applets can be downloaded from a Web server to a Web browser machine, but
applications and servlets are not.
| v Applets run with additional security rules limiting what they can do. These
| rules are more restrictive from Java 1.2.
| See “Appendix F. Using MQ Java in applets with Java 1.2 or later” on page 367
| for more information about this.

The following general rules apply:

v If you want to run your programs from machines that do not have MQSeries
classes for Java installed locally, you should write applets.
v The native bindings mode of MQSeries classes for Java does not support applets.
Therefore, if you want to use your programs in all connection modes, including
the native bindings mode, you must write servlets or applications.

Connection differences
The way you program for MQSeries classes for Java has some dependencies on the
connection modes you want to use.

Client connections
When MQSeries classes for Java is used as a client, it is similar to the MQSeries C
client, but has the following differences:
v It supports only TCP/IP.
v It does not support connection tables.
v It does not read any MQSeries environment variables at startup.
v Information that would be stored in a channel definition and in environment
variables is stored in a class called MQEnvironment. Alternatively, this
information can be passed as parameters when the connection is made.
v Error and exception conditions are written to a log specified in the MQException
class. The default error destination is the Java console.

© Copyright IBM Corp. 1997, 2001 51

Connection differences
The MQSeries classes for Java clients do not support the MQBEGIN verb or fast
bindings.

For general information on MQSeries clients, see the MQSeries Clients book.

Note: When you use the VisiBroker connection, the userid and password settings
in MQEnvironment are not forwarded to the MQSeries server. The effective
userid is the one that applies to the IIOP server.

Bindings mode
The bindings mode of MQSeries classes for Java differs from the client modes in
the following ways:
v Most of the parameters provided by the MQEnvironment class are ignored
v The bindings support the MQBEGIN verb and fast bindings into the MQSeries
queue manager

Note: MQSeries for AS/400 does not support the use of MQBEGIN to initiate
global units of work that are coordinated by the queue manager.

Defining which connection to use

The connection is determined by the setting of variables in the MQEnvironment
class.
MQEnvironment.properties
This can contain the following key/value pairs:
v For client and bindings connections:
MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES
v For VisiBroker connections:
MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_VISIBROKER
MQC.ORB_PROPERTY, orb
MQEnvironment.hostname
Set the value of this variable follows:
v For client connections, set this to the hostname of the MQSeries server to
which you want to connect
v For bindings mode, set this to null

Example code fragments

This section includes two example code fragments; Figure 1 on page 53 and
Figure 2 on page 56. Each one uses a particular connection and includes notes to
describe the changes needed to use alternative connections.

Example applet code

The following code fragment demonstrates an applet that uses a TCP/IP
connection to:
1. Connect to a queue manager
2. Put a message onto SYSTEM.DEFAULT.LOCAL.QUEUE
3. Get the message back

52 MQSeries Using Java

 Example code
// ===========================================================================
//
// Licensed Materials - Property of IBM
//
// 5639-C34
//
// (c) Copyright IBM Corp. 1995,1999
//
// ===========================================================================
// MQSeries Client for Java sample applet
//
// This sample runs as an applet using the appletviewer and HTML file,
// using the command :-
// appletviewer MQSample.html
// Output is to the command line, NOT the applet viewer window.
//
// Note. If you receive MQSeries error 2 reason 2059 and you are sure your
// MQSeries and TCP/IP setup is correct,
// you should click on the "Applet" selection in the Applet viewer window
// select properties, and change "Network access" to unrestricted.
import com.ibm.mq.*; // Include the MQSeries classes for Java package

public class MQSample extends java.applet.Applet

{

private String hostname = "your_hostname"; // define the name of your

// host to connect to
private String channel = "server_channel"; // define name of channel
// for client to use
// Note. assumes MQSeries Server
// is listening on the default
// TCP/IP port of 1414
private String qManager = "your_Q_manager"; // define name of queue
// manager object to
// connect to.

private MQQueueManager qMgr; // define a queue manager object

// When the class is called, this initialization is done first.

public void init()

{
// Set up MQSeries environment
MQEnvironment.hostname = hostname; // Could have put the
// hostname & channel
MQEnvironment.channel = channel; // string directly here!

MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,//Set TCP/IP or server

MQC.TRANSPORT_MQSERIES);//Connection

} // end of init

Figure 1. MQSeries classes for Java example applet (Part 1 of 3)

Chapter 7. Writing MQ base Java programs 53

Example code
public void start()
{

try {
// Create a connection to the queue manager
qMgr = new MQQueueManager(qManager);

// Set up the options on the queue we wish to open...

// Note. All MQSeries Options are prefixed with MQC in Java.
int openOptions = MQC.MQOO_INPUT_AS_Q_DEF |
MQC.MQOO_OUTPUT ;
// Now specify the queue that we wish to open, and the open options...

MQQueue system_default_local_queue =
qMgr.accessQueue("SYSTEM.DEFAULT.LOCAL.QUEUE",
openOptions);

// Define a simple MQSeries message, and write some text in UTF format..

MQMessage hello_world = new MQMessage();

hello_world.writeUTF("Hello World!");

// specify the message options...

MQPutMessageOptions pmo = new MQPutMessageOptions(); // accept the defaults,

// same as
// MQPMO_DEFAULT
// constant
// put the message on the queue

system_default_local_queue.put(hello_world,pmo);

// get the message back again...

// First define a MQSeries message buffer to receive the message into..

MQMessage retrievedMessage = new MQMessage();

retrievedMessage.messageId = hello_world.messageId;

// Set the get message options..

MQGetMessageOptions gmo = new MQGetMessageOptions(); // accept the defaults

// same as
// MQGMO_DEFAULT
// get the message off the queue..

system_default_local_queue.get(retrievedMessage, gmo);

// And prove we have the message by displaying the UTF message text

String msgText = retrievedMessage.readUTF();

System.out.println("The message is: " + msgText);

// Close the queue

system_default_local_queue.close();

// Disconnect from the queue manager

qMgr.disconnect();

// If an error has occurred in the above, try to identify what went wrong.
// Was it an MQSeries error?

Figure 1. MQSeries classes for Java example applet (Part 2 of 3)

54 MQSeries Using Java

 Example code

catch (MQException ex)

{
System.out.println("An MQSeries error occurred : Completion code " +
ex.completionCode +
" Reason code " + ex.reasonCode);
}
// Was it a Java buffer space error?
catch (java.io.IOException ex)
{
System.out.println("An error occurred whilst writing to the
message buffer: " + ex);
}

} // end of start

} // end of sample

Figure 1. MQSeries classes for Java example applet (Part 3 of 3)

Changing the connection to use VisiBroker for Java

Modify the line:
MQEnvironment.properties.put (MQC.TRANSPORT_PROPERTY,
MQC.TRANSPORT_MQSERIES);

to:
MQEnvironment.properties.put (MQC.TRANSPORT_PROPERTY,
MQC.TRANSPORT_VISIBROKER);

and add the following lines to initialize the ORB (object request broker):
ORB orb=ORB.init(this,null);
MQEnvironment.properties.put(MQC.ORB_PROPERTY,orb);

You also need to add the following import statement to the beginning of the file:
import org.omg.CORBA.ORB;

You do not need to specify port number or channel if you are using VisiBroker.

Chapter 7. Writing MQ base Java programs 55

Example code
Example application code
The following code fragment demonstrates a simple application that uses bindings
mode to:
1. Connect to a queue manager
2. Put a message onto SYSTEM.DEFAULT.LOCAL.QUEUE
3. Get the message back again

// ======================================================================
// Licensed Materials - Property of IBM
// 5639-C34
// (c) Copyright IBM Corp. 1995, 1999
// ======================================================================
// MQSeries classes for Java sample application
//
// This sample runs as a Java application using the command :- java MQSample

import com.ibm.mq.*; // Include the MQSeries classes for Java package

public class MQSample

{
private String qManager = "your_Q_manager"; // define name of queue
// manager to connect to.
private MQQueueManager qMgr; // define a queue manager
// object
public static void main(String args[]) {
new MQSample();
}

public MQSample() {
try {

// Create a connection to the queue manager

qMgr = new MQQueueManager(qManager);

// Set up the options on the queue we wish to open...

// Note. All MQSeries Options are prefixed with MQC in Java.

int openOptions = MQC.MQOO_INPUT_AS_Q_DEF |

MQC.MQOO_OUTPUT ;

// Now specify the queue that we wish to open,

// and the open options...

MQQueue system_default_local_queue =
qMgr.accessQueue("SYSTEM.DEFAULT.LOCAL.QUEUE",
openOptions);

// Define a simple MQSeries message, and write some text in UTF format..

MQMessage hello_world = new MQMessage();

hello_world.writeUTF("Hello World!");

// specify the message options...

MQPutMessageOptions pmo = new MQPutMessageOptions(); // accept the // defaults,

// same as MQPMO_DEFAULT

Figure 2. MQSeries classes for Java example application (Part 1 of 2)

56 MQSeries Using Java

 Example code
// put the message on the queue

system_default_local_queue.put(hello_world,pmo);

// get the message back again...

// First define a MQSeries message buffer to receive the message into..

MQMessage retrievedMessage = new MQMessage();

retrievedMessage.messageId = hello_world.messageId;

// Set the get message options...

MQGetMessageOptions gmo = new MQGetMessageOptions(); // accept the defaults

// same as MQGMO_DEFAULT
// get the message off the queue...

system_default_local_queue.get(retrievedMessage, gmo);

// And prove we have the message by displaying the UTF message text

String msgText = retrievedMessage.readUTF();

System.out.println("The message is: " + msgText);
// Close the queue...
system_default_local_queue.close();
// Disconnect from the queue manager

qMgr.disconnect();
}
// If an error has occurred in the above, try to identify what went wrong
// Was it an MQSeries error?
catch (MQException ex)
{
System.out.println("An MQSeries error occurred : Completion code " +
ex.completionCode + " Reason code " + ex.reasonCode);
}
// Was it a Java buffer space error?
catch (java.io.IOException ex)
{
System.out.println("An error occurred whilst writing to the message buffer: " + ex);
}
}
} // end of sample

Figure 2. MQSeries classes for Java example application (Part 2 of 2)

Chapter 7. Writing MQ base Java programs 57

Queue manager operations

Operations on queue managers

This section describes how to connect to, and disconnect from, a queue manager
using MQSeries classes for Java.

Setting up the MQSeries environment

Note: This step is not necessary when using MQSeries classes for Java in bindings
mode. In that case, go directly to “Connecting to a queue manager”. Before
you use the client connection to connect to a queue manager, you must take
care to set up the MQEnvironment.

The ″C″ based MQSeries clients rely on environment variables to control the
behavior of the MQCONN call. Because Java applets have no access to
environment variables, the Java programming interface includes a class
MQEnvironment. This class allows you to specify the following details that are to
be used during the connection attempt:
v Channel name
v Hostname
v Port number
v User ID
v Password

To specify the channel name and hostname, use the following code:
MQEnvironment.hostname = "host.domain.com";
MQEnvironment.channel = "java.client.channel";

This is equivalent to an MQSERVER environment variable setting of:

"java.client.channel/TCP/host.domain.com".

By default, the Java clients attempt to connect to an MQSeries listener at port 1414.
To specify a different port, use the code:
MQEnvironment.port = nnnn;

The user ID and password default to blanks. To specify a non-blank user ID or

password, use the code:
MQEnvironment.userID = "uid"; // equivalent to env var MQ_USER_ID
MQEnvironment.password = "pwd"; // equivalent to env var MQ_PASSWORD

Note: If you are setting up a connection using VisiBroker for Java, see “Changing
the connection to use VisiBroker for Java” on page 55.

Connecting to a queue manager

You are now ready to connect to a queue manager by creating a new instance of
the MQQueueManager class:
MQQueueManager queueManager = new MQQueueManager("qMgrName");

To disconnect from a queue manager, call the disconnect() method on the queue
manager:
queueManager.disconnect();

58 MQSeries Using Java

 Queue manager operations
If you call the disconnect method, all open queues and processes that you have
accessed through that queue manager will be closed. However, it is good
programming practice to close these resources explicitly when you finish using
them. To do this, use the close() method.

The commit() and backout() methods on a queue manager replace the MQCMIT
and MQBACK calls that are used with the procedural interface.

Accessing queues and processes

To access queues and processes, you use the MQQueueManager class. The MQOD
(object descriptor structure) is collapsed into the parameters of these methods. For
example, to open a queue on a queue manager ″queueManager″, use the following
code:
MQQueue queue = queueManager.accessQueue("qName",
MQC.MQOO_OUTPUT,
"qMgrName",
"dynamicQName",
"altUserId");

The options parameter is the same as the Options parameter in the MQOPEN call.

The accessQueue method returns a new object of class MQQueue.

When you have finished using the queue, use the close() method to close it, as in
the following example:
queue.close();

With MQSeries classes for Java, you can also create a queue by using the
MQQueue constructor. The parameters are exactly the same as for the accessQueue
method, with the addition of a queue manager parameter. For example:
MQQueue queue = new MQQueue(queueManager,
"qName",
MQC.MQOO_OUTPUT,
"qMgrName",
"dynamicQName",
"altUserId");

Constructing a queue object in this way enables you to write your own subclasses
of MQQueue.

To access a process, use the accessProcess method in place of accessQueue. This

method does not have a dynamic queue name parameter, because this does not apply
to processes.

The accessProcess method returns a new object of class MQProcess.

When you have finished using the process object, use the close() method to close it,
as in the following example:
process.close();

With MQSeries classes for Java, you can also create a process by using the
MQProcess constructor. The parameters are exactly the same as for the
accessProcess method, with the addition of a queue manager parameter.
Constructing a process object in this way enables you to write your own subclasses
of MQProcess.

Chapter 7. Writing MQ base Java programs 59

Message handling

Handling messages
You put messages onto queues using the put() method of the MQQueue class. You
get messages from queues using the get() method of the MQQueue class. Unlike
the procedural interface, where MQPUT and MQGET put and get arrays of bytes,
the Java programming language puts and gets instances of the MQMessage class.
The MQMessage class encapsulates the data buffer that contains the actual
message data, together with all the MQMD (message descriptor) parameters that
describe that message.

To build a new message, create a new instance of the MQMessage class, and use
the writeXXX methods to put data into the message buffer.

When the new message instance is created, all the MQMD parameters are
automatically set to their default values, as defined in the MQSeries Application
Programming Reference. The put() method of MQQueue also takes an instance of the
MQPutMessageOptions class as a parameter. This class represents the MQPMO
structure. The following example creates a message and puts it onto a queue:
// Build a new message containing my age followed by my name
MQMessage myMessage = new MQMessage();
myMessage.writeInt(25);

String name = "Wendy Ling";

myMessage.writeInt(name.length());
myMessage.writeBytes(name);

// Use the default put message options...

MQPutMessageOptions pmo = new MQPutMessageOptions();

// put the message!

queue.put(myMessage,pmo);

The get() method of MQQueue returns a new instance of MQMessage, which

represents the message just taken from the queue. It also takes an instance of the
MQGetMessageOptions class as a parameter. This class represents the MQGMO
structure.

You do not need to specify a maximum message size, because the get() method
automatically adjusts the size of its internal buffer to fit the incoming message. Use
the readXXX methods of the MQMessage class to access the data in the returned
message.

The following example shows how to get a message from a queue:

// Get a message from the queue
MQMessage theMessage = new MQMessage();
MQGetMessageOptions gmo = new MQGetMessageOptions();
queue.get(theMessage,gmo); // has default values

// Extract the message data

int age = theMessage.readInt();
int strLen = theMessage.readInt();
byte[] strData = new byte[strLen];
theMessage.readFully(strData,0,strLen);
String name = new String(strData,0);

You can alter the number format that the read and write methods use by setting
the encoding member variable.

60 MQSeries Using Java

 Message handling
You can alter the character set to use for reading and writing strings by setting the
characterSet member variable.

See “MQMessage” on page 102 for more details.

Note: The writeUTF() method of MQMessage automatically encodes the length of

the string as well as the Unicode bytes it contains. When your message will
be read by another Java program (using readUTF()), this is the simplest way
to send string information.

Handling errors
Methods in the Java interface do not return a completion code and reason code.
Instead, they throw an exception whenever the completion code and reason code
resulting from an MQSeries call are not both zero. This simplifies the program
logic so that you do not have to check the return codes after each call to MQSeries.
You can decide at which points in your program you want to deal with the
possibility of failure. At these points, you can surround your code with ’try’ and
’catch’ blocks, as in the following example:
try {
myQueue.put(messageA,putMessageOptionsA);
myQueue.put(messageB,putMessageOptionsB);
}
catch (MQException ex) {
// This block of code is only executed if one of
// the two put methods gave rise to a non-zero
// completion code or reason code.
System.out.println("An error occurred during the put operation:" +
"CC = " + ex.completionCode +
"RC = " + ex.reasonCode);
}

| The MQSeries call reason codes reported back in Java exceptions are documented
| in a chapter called “Return Codes” in the MQSeries Application Programming
| Reference book.

Getting and setting attribute values

For many of the common attributes, the classes MQManagedObject, MQQueue,
MQProcess, and MQQueueManager contain getXXX() and setXXX() methods.
These methods allow you to get and set their attribute values. Note that for
MQQueue, the methods will work only if you specify the appropriate “inquire”
and “set” flags when you open the queue.

For less common attributes, the MQQueueManager, MQQueue, and MQProcess

classes all inherit from a class called MQManagedObject. This class defines the
inquire() and set() interfaces.

When you create a new queue manager object by using the new operator, it is
automatically opened for “inquiry”. When you use the accessProcess() method to
access a process object, that object is automatically opened for “inquiry”. When
you use the accessQueue() method to access a queue object, that object is not
automatically opened for either “inquire” or “set” operations. This is because
adding these options automatically can cause problems with some types of remote
queues. To use the inquire, set, getXXX, and setXXX methods on a queue, you
must specify the appropriate “inquire” and “set” flags in the openOptions
parameter of the accessQueue() method.

Chapter 7. Writing MQ base Java programs 61

Using attribute values
The inquire and set methods take three parameters:
v selectors array
v intAttrs array
v charAttrs array
You do not need the SelectorCount, IntAttrCount, and CharAttrLength parameters
that are found in MQINQ, because the length of an array in Java is always known.
The following example shows how to make an inquiry on a queue:
// inquire on a queue
final static int MQIA_DEF_PRIORITY = 6;
final static int MQCA_Q_DESC = 2013;
final static int MQ_Q_DESC_LENGTH = 64;

int[] selectors = new int[2];

int[] intAttrs = new int[1];
byte[] charAttrs = new byte[MQ_Q_DESC_LENGTH]

selectors[0] = MQIA_DEF_PRIORITY;
selectors[1] = MQCA_Q_DESC;

queue.inquire(selectors,intAttrs,charAttrs);

System.out.println("Default Priority = " + intAttrs[0]);

System.out.println("Description : " + new String(charAttrs,0));

Multithreaded programs
Multithreaded programs are hard to avoid in Java. Consider a simple program that
connects to a queue manager and opens a queue at startup. The program displays
a single button on the screen. When a user presses that button, the program fetches
a message from the queue.

The Java runtime environment is inherently multithreaded. Therefore, your

application initialization occurs in one thread, and the code that executes in
response to the button press executes in a separate thread (the user interface
thread).

With the “C” based MQSeries client, this would cause a problem, because handles
cannot be shared across multiple threads. MQSeries classes for Java relaxes this
constraint, allowing a queue manager object (and its associated queue and process
objects) to be shared across multiple threads.

The implementation of MQSeries classes for Java ensures that, for a given
connection (MQQueueManager object instance), all access to the target MQSeries
queue manager is synchronized. Therefore, a thread wishing to issue a call to a
queue manager is blocked until all other calls in progress for that connection are
complete. If you require simultaneous access to the same queue manager from
multiple threads within your program, create a new MQQueueManager object for
each thread that requires concurrent access. (This is equivalent to issuing a
separate MQCONN call for each thread.)

62 MQSeries Using Java

 Writing user exits

Writing user exits

MQSeries classes for Java allows you to provide your own send, receive, and
security exits.

To implement an exit, you define a new Java class that implements the appropriate
interface. Three exit interfaces are defined in the MQSeries package:
v MQSendExit
v MQReceiveExit
v MQSecurityExit

The following sample defines a class that implements all three:

class MyMQExits implements MQSendExit, MQReceiveExit, MQSecurityExit {

// This method comes from the send exit

public byte[] sendExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefParms,
byte agentBuffer[])
{
// fill in the body of the send exit here
}

// This method comes from the receive exit

public byte[] receiveExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefParms,
byte agentBuffer[])
{
// fill in the body of the receive exit here
}

// This method comes from the security exit

public byte[] securityExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefParms,
byte agentBuffer[])
{
// fill in the body of the security exit here
}

Each exit is passed an MQChannelExit and an MQChannelDefinition object

instance. These objects represent the MQCXP and MQCD structures defined in the
procedural interface.

For a Send exit, the agentBuffer parameter contains the data that is about to be sent.
For a Receive exit or a Security exit, the agentBuffer parameter contains the data
that has just been received. You do not need a length parameter, because the
expression agentBuffer.length indicates the length of the array.

For the Send and Security exits, your exit code should return the byte array that
you wish to send to the server. For a Receive exit, your exit code should return the
modified data that you wish MQSeries classes for Java to interpret.

The simplest possible exit body is:

{
return agentBuffer;
}

Chapter 7. Writing MQ base Java programs 63

Writing user exits
If your program is to run as a downloaded Java applet, the security restrictions
that apply mean that you cannot read or write any local files. If your exit needs a
configuration file, you can place the file on the Web and use the java.net.URL class
to download it and examine its contents.

Connection pooling
MQSeries classes for Java Version 5.2 provides additional support for applications
that deal with multiple connections to MQSeries queue managers. When a
connection is no longer required, instead of destroying it, it can be pooled, and
later reused. This can provide a substantial performance enhancement for
applications and middleware that connect serially to arbitrary queue managers.

MQSeries provides a default connection pool. Applications can activate or

deactivate this connection pool by registering and deregistering tokens through the
MQEnvironment class. If the pool is active, when MQ base Java constructs an
MQQueueManager object, it searches this default pool and reuses any suitable
connection. When an MQQueueManager.disconnect() call occurs, the underlying
connection is returned to the pool.

Alternatively, applications can construct an MQSimpleConnectionManager

connection pool for a particular use. Then, the application can either specify that
pool during construction of an MQQueueManager object, or pass that pool to
MQEnvironment for use as the default connection pool.

Also, MQ base Java provides a partial implementation of the Java 2 Platform

Enterprise Edition (J2EE) Connector Architecture. Applications running under a
Java 2 v1.3 JVM with JAAS 1.0 (Java Authentication and Authorization Service) can
provide their own connection pool by implementing the
javax.resource.spi.ConnectionManager interface. Again, this interface can be
specified on the MQQueueManager constructor, or specified as the default
connection pool.

Controlling the default connection pool

Consider the following example application, MQApp1:
import com.ibm.mq.*;
public class MQApp1
{
public static void main(String[] args) throws MQException
{
for (int i=0; i<args.length; i++) {
MQQueueManager qmgr=new MQQueueManager(args[i]);
:
: (do something with qmgr)
:
qmgr.disconnect();
}
}
}

MQApp1 takes a list of local queue managers from the command line, connects to
each in turn, and performs some operation. However, when the command line lists
the same queue manager many times, it is more efficient to connect only once, and
to reuse that connection many times.

64 MQSeries Using Java

 Connection pooling
MQ base Java provides a default connection pool that you can use to do this. To
enable the pool, use one of the MQEnvironment.addConnectionPoolToken()
methods. To disable the pool, use MQEnvironment.removeConnectionPoolToken().

The following example application, MQApp2, is functionally identical to MQApp1,

but connects only once to each queue manager.
import com.ibm.mq.*;
public class MQApp2
{
public static void main(String[] args) throws MQException
{
MQPoolToken token=MQEnvironment.addConnectionPoolToken();

for (int i=0; i<args.length; i++) {

MQQueueManager qmgr=new MQQueueManager(args[i]);
:
: (do something with qmgr)
:
qmgr.disconnect();
}

MQEnvironment.removeConnectionPoolToken(token);

}
}

The first bold line activates the default connection pool, by registering an
MQPoolToken object with MQEnvironment.

The MQQueueManager constructor now searches this pool for an appropriate

connection and only creates a connection to the queue manager if it cannot find an
existing one. The qmgr.disconnect() call returns the connection to the pool for later
reuse. These API calls are the same as the sample application MQApp1.

The second highlighted line deactivates the default connection pool, which
destroys any queue manager connections stored in the pool. This is important
because otherwise, the application would terminate with a number of live queue
manager connections in the pool. This situation could cause errors that would
appear in the queue manager logs.

The default connection pool stores a maximum of ten unused connections, and
keeps unused connections active for a maximum of five minutes. The application
can alter this (for details, see “Supplying a different connection pool” on page 67).

Instead of using MQEnvironment to supply an MQPoolToken, the application can

construct its own:
MQPoolToken token=new MQPoolToken();
MQEnvironment.addConnectionPoolToken(token);

Some applications or middleware vendors may provide subclasses of

MQPoolToken in order to pass information to a custom connection pool. They can
be constructed and passed to addConnectionPoolToken() in this way so that extra
information can be passed to the connection pool.

Chapter 7. Writing MQ base Java programs 65

Connection pooling
The default connection pool and multiple components
MQEnvironment holds a static set of registered MQPoolToken objects. To add or
remove MQPoolTokens from this set, use the following methods:
v MQEnvironment.addConnectionPoolToken()
v MQEnvironment.removeConnectionPoolToken()

An application might consist of many components that exist independently and

perform work using a queue manager. In such an application, each component
should add an MQPoolToken to the MQEnvironment set for its lifetime.

For example, the example application MQApp3 creates ten threads and starts each
one. Each thread registers its own MQPoolToken, waits for a length of time, then
connects to the queue manager. After the thread disconnects, it removes its own
MQPoolToken.

The default connection pool remains active while there is at least one token in the
set of MQPoolTokens, so it will remain active for the duration of this application.
The application does not need to keep a master object in overall control of the
threads.
import com.ibm.mq.*;
public class MQApp3
{
public static void main(String[] args)
{
for (int i=0; i<10; i++) {
MQApp3_Thread thread=new MQApp3_Thread(i*60000);
thread.start();
}
}
}

class MQApp3_Thread extends Thread

{
long time;

public MQApp3_Thread(long time)

{
this.time=time;
}

public synchronized void run()

{
MQPoolToken token=MQEnvironment.addConnectionPoolToken();
try {
wait(time);
MQQueueManager qmgr=new MQQueueManager("my.qmgr.1");
:
: (do something with qmgr)
:
qmgr.disconnect();
}
catch (MQException mqe) {System.err.println("Error occurred!");}
catch (InterruptedException ie) {}

MQEnvironment.removeConnectionPoolToken(token);
}
}

66 MQSeries Using Java

 Connection pooling
Supplying a different connection pool
This section describes how to use the class
com.ibm.mq.MQSimpleConnectionManager to supply a different connection pool.
This class provides basic facilities for connection pooling, and applications can use
this class to customize the behavior of the pool.

Once it is instantiated, an MQSimpleConnectionManager may be specified on the

MQQueueManager constructor. The MQSimpleConnectionManager then manages
the connection that underlies the constructed MQQueueManager. If the
MQSimpleConnectionManager contains a suitable pooled connection, that
connection will be reused, and it will be returned to the
MQSimpleConnectionManager after an MQQueueManager.disconnect() call.

The following code fragment demonstrates this behavior:

MQSimpleConnectionManager myConnMan=new MQSimpleConnectionManager();
myConnMan.setActive(MQSimpleConnectionManager.MODE_ACTIVE);
MQQueueManager qmgr=new MQQueueManager("my.qmgr.1", myConnMan);
:
: (do something with qmgr)
:
qmgr.disconnect();

MQQueueManager qmgr2=new MQQueueManager("my.qmgr.1", myConnMan);

:
: (do something with qmgr2)
:
qmgr2.disconnect();
myConnMan.setActive(MQSimpleConnectionManager.MODE_INACTIVE);

The connection that is forged during the first MQQueueManager constructor is

stored in myConnMan after the qmgr.disconnect() call. The connection is then
reused during the second call to the MQQueueManager constructor.

The second line enables the MQSimpleConnectionManager. The last line disables
MQSimpleConnectionManager, destroying any connections held in the pool. An
MQSimpleConnectionManager is, by default, in MODE_AUTO, which is described
later in this section.

An MQSimpleConnectionManager allocates connections on a most-recently-used

basis, and destroys connections on a least-recently-used basis. By default, a
connection is destroyed if it has not been used for five minutes, or if there are
more than ten unused connections in the pool. You can alter these values using:
v MQSimpleConnectionManager.setTimeout()
v MQSimpleConnectionManager.setHighThreshold()

It is also possible to set up an MQSimpleConnectionManager for use as the default

connection pool, to be used when no Connection Manager is supplied on the
MQQueueManager constructor.

Chapter 7. Writing MQ base Java programs 67

Connection pooling
The following application demonstrates this:
import com.ibm.mq.*;
public class MQApp4
{
public static void main(String[] args)
{
MQSimpleConnectionManager myConnMan=new MQSimpleConnectionManager();
myConnMan.setActive(MQSimpleConnectionManager.MODE_AUTO);
myConnMan.setTimeout(3600000);
myConnMan.setHighThreshold(50);
MQEnvironment.setDefaultConnectionManager(myConnMan);
MQApp3.main(args);
}
}

The bold lines set up an MQSimpleConnectionManager. This is set to:

v destroy connections that have not been used for an hour
v limit the number of unused connections held in the pool to 50
v MODE_AUTO (actually the default). This means that the pool is active only if it
is the default connection manager, and there is at least one token in the set of
MQPoolTokens held by MQEnvironment.
The new MQSimpleConnectionManager is then set as the default connection
manager.

In the last line, the application calls MQApp3.main(). This runs a number of
threads, where each thread uses MQSeries independently. These threads will now
use myConnMan when they forge connections.

Supplying your own ConnectionManager

Under Java 2 v1.3, with JAAS 1.0 installed, applications and middleware providers
can provide alternative implementations of connection pools. MQ base Java
provides a partial implementation of the J2EE Connector Architecture.
Implementations of javax.resource.spi.ConnectionManager can either be used as
the default Connection Manager or be specified on the MQQueueManager
constructor.

MQ base Java complies with the Connection Management contract of the J2EE
Connector Architecture. Please read this section in conjunction with the Connection
Management contract of the J2EE Connector Architecture (refer to Sun’s Web site at
http://java.sun.com).

The ConnectionManager interface defines only one method:

package javax.resource.spi;
public interface ConnectionManager {
Object allocateConnection(ManagedConnectionFactory mcf,
ConnectionRequestInfo cxRequestInfo);
}

The MQQueueManager constructor calls allocateConnection on the appropriate

ConnectionManager. It passes appropriate implementations of
ManagedConnectionFactory and ConnectionRequestInfo as parameters to describe
the connection required.

The ConnectionManager searches its pool for a

javax.resource.spi.ManagedConnection object that has been created with identical
ManagedConnectionFactory and ConnectionRequestInfo objects. If the

68 MQSeries Using Java

 Connection pooling
ConnectionManager finds any suitable ManagedConnection objects, it creates a
java.util.Set that contains the candidate ManagedConnections. Then, the
ConnectionManager calls the following:
ManagedConnection mc=mcf.matchManagedConnections(connectionSet, subject,
cxRequestInfo);

The MQSeries implementation of ManagedConnectionFactory ignores the subject

parameter. This method selects and returns a suitable ManagedConnection from
the set, or returns null if it does not find a suitable ManagedConnection. If there is
not a suitable ManagedConnection in the pool, the ConnectionManager can create
one by using:
ManagedConnection mc=mcf.createManagedConnection(subject, cxRequestInfo);

Again, the subject parameter is ignored. This method connects to an MQSeries

queue manager and returns an implementation of
javax.resource.spi.ManagedConnection that represents the newly-forged connection.
Once the ConnectionManager has obtained a ManagedConnection (either from the
pool or freshly created), it creates a connection handle using:
Object handle=mc.getConnection(subject, cxRequestInfo);

This connection handle can be returned from allocateConnection().

A ConnectionManager should register an interest in the ManagedConnection

through:
mc.addConnectionEventListener()

The ConnectionEventListener is notified if a severe error occurs on the connection,

or when MQQueueManager.disconnect() is called. When
MQQueueManager.disconnect() is called, the ConnectionEventListener can do
either of the following:
v reset the ManagedConnection using the mc.cleanup() call, then return the
ManagedConnection to the pool
v destroy the ManagedConnection using the mc.destroy() call

If the ConnectionManager is intended to be the default ConnectionManager, it can

also register an interest in the state of the MQEnvironment-managed set of
MQPoolTokens. To do so, first construct an MQPoolServices object, then register an
MQPoolServicesEventListener object with the MQPoolServices object:
MQPoolServices mqps=new MQPoolServices();
mqps.addMQPoolServicesEventListener(listener);

The listener is notified when an MQPoolToken is added or removed from the set,
or when the default ConnectionManager changes. The MQPoolServices object also
provides a way to query the current size of the set of MQPoolTokens.

Compiling and testing MQ base Java programs

Before compiling MQ base Java programs, you must ensure that your MQSeries
classes for Java installation directory is in your CLASSPATH environment variable,
as described in “Chapter 2. Installation procedures” on page 7.

To compile a class “MyClass.java”, use the command:

javac MyClass.java

Chapter 7. Writing MQ base Java programs 69

Running MQ base Java applets
Running MQ base Java applets
If you write an applet (subclass of java.applet.Applet), you must create an HTML
file referencing your class before you can run it. A sample HTML file might look as
follows:
<html>
<body>
<applet code="MyClass.class" width=200 height=400>
</applet>
</body>
</html>

Run your applet either by loading this HTML file into a Java enabled Web browser,
or by using the appletviewer that comes with the Java Development Kit (JDK).

To use the applet viewer, enter the command:

appletviewer myclass.html

Running MQ base Java applications

If you write an application (a class that contains a main() method), using either the
client or the bindings mode, run your program using the Java interpreter. Use the
command:
java MyClass

Note: The “.class” extension is omitted from the class name.

Tracing MQ base Java programs

MQ base Java includes a trace facility, which you can use to produce diagnostic
messages if you suspect that there might be a problem with the code. (You will
normally need to use this facility only at the request of IBM service.)

Tracing is controlled by the enableTracing and disableTracing methods of the

MQEnvironment class. For example:
MQEnvironment.enableTracing(2); // trace at level 2
... // these commands will be traced
MQEnvironment.disableTracing(); // turn tracing off again

The trace is written to the Java console (System.err).

If your program is an application, or if you run it from your local disk using the
appletviewer command, you can also redirect the trace output to a file of your
choice. The following code fragment shows an example of how to redirect the trace
output to a file called myapp.trc:
import java.io.*;

try {
FileOutputStream
traceFile = new FileOutputStream("myapp.trc");
MQEnvironment.enableTracing(2,traceFile);
}
catch (IOException ex) {
// couldn't open the file,
// trace to System.err instead
MQEnvironment.enableTracing(2);
}

There are five different levels of tracing:

70 MQSeries Using Java

 Tracing MQ base Java programs
1. Provides entry, exit, and exception tracing
2. Provides parameter information in addition to 1
3. Provides transmitted and received MQSeries headers and data blocks in
addition to 2
4. Provides transmitted and received user message data in addition to 3
5. Provides tracing of methods in the Java Virtual Machine in addition to 4

To trace methods in the Java Virtual Machine with trace level 5:

v For an application, run it by issuing the command java_g (instead of java)
v For an applet, run it by issuing the command appletviewer_g (instead of
appletviewer)

| Note: java_g is not supported on OS/400, but similar function is provided by

| using OPTION(*VERBOSE) on the RUNJVA command.

Chapter 7. Writing MQ base Java programs 71

Tracing MQ base Java programs

72 MQSeries Using Java

 Chapter 8. Environment-dependent behavior
This chapter describes the behavior of the Java classes in the various environments
in which you can use them. The MQSeries classes for Java classes allow you to
create applications that can be used in the following environments:
1. MQSeries Client for Java connected to an MQSeries V2.x server on UNIX or
Windows platforms
2. MQSeries Client for Java connected to an MQSeries V5 server on UNIX or
Windows platforms
| 3. MQSeries Client for Java connected to an MQSeries for OS/390 server
4. MQSeries Bindings for Java executing on an MQSeries V5 server on UNIX or
Windows platforms
5. MQSeries Bindings for Java executing on an MQSeries for OS/390 server

In all cases, the MQSeries classes for Java code uses services that are provided by
the underlying MQSeries server. There are differences in the level of function (for
example, MQSeries V5 provides a superset of the function of V2). There are also
differences in the behavior of some API calls and options. Most behavior
differences are minor, and most of them are between the OS/390 servers and the
servers on other platforms.

| In the list of environments above, an MQSeries for OS/390 server can be running
| any of the following supported queue managers:
| v MQSeries for MVS/ESA™ V1R2
| v MQSeries for OS/390 V2R1
| v MQSeries for OS/390 V5R2

MQSeries classes for Java provides a “core” of classes, which provide consistent
function and behavior in all the environments. It also provides “V5 extensions”,
which are designed for use only in environments 2 and 4. The following sections
describe the core and extensions.

Core details
| MQSeries classes for Java contains the following core set of classes, which can be
used in all environments with only the minor variations listed in “Restrictions and
variations for core classes” on page 74.
v MQEnvironment
v MQException
v MQGetMessageOptions
Excluding:
– MatchOptions
– GroupStatus
– SegmentStatus
– Segmentation
v MQManagedObject
Excluding:
– inquire()
– set()
v MQMessage
Excluding:

© Copyright IBM Corp. 1997, 2001 73

 Core details
– groupId
– messageFlags
– messageSequenceNumber
– offset
– originalLength
v MQPoolServices
v MQPoolServicesEvent
v MQPoolServicesEventListener
v MQPoolToken
v MQPutMessageOptions
Excluding:
– knownDestCount
– unknownDestCount
– invalidDestCount
– recordFields
v MQProcess
v MQQueue
v MQQueueManager
Excluding:
– begin()
– accessDistributionList()
v MQSimpleConnectionManager
v MQC
Notes:
1. Some constants are not included in the core (see “Restrictions and variations for
core classes” for details), and you should not use them in completely portable
programs.
2. Some platforms do not support all connection modes. On these platforms, you
can use only the core classes and options that relate to the supported modes.
(See Table 1 on page 5.)

Restrictions and variations for core classes

Although the core classes generally behave consistently across all environments,
there are some minor restrictions and variations, which are documented in
Table 12.

Apart from these documented variations, the core classes provide consistent
behavior across all environments, even if the equivalent MQSeries classes normally
have environment differences. In general, the behavior will be the same as in
environments 2 and 4.
Table 12. Core classes restrictions and variations
Class or element Restrictions and variations
| MQGMO_LOCK Cause MQRC_OPTIONS_ERROR when used in environments 3 or 5.
MQGMO_UNLOCK
MQGMO_BROWSE_MSG_UNDER_CURSOR
MQPMO_NEW_MSG_ID Give errors except in environments 2 and 4. (See V5 extensions.)
MQPMO_NEW_CORREL_ID
MQPMO_LOGICAL_ORDER
MQGMO_LOGICAL_ORDER Give errors except in environments 2 and 4. (See V5 extensions.)
MQGMO_COMPLETE_MESSAGE
MQGMO_ALL_MSGS_AVAILABLE
MQGMO_ALL_SEGMENTS_AVAILABLE

74 MQSeries Using Java

 Restrictions
Table 12. Core classes restrictions and variations (continued)
Class or element Restrictions and variations
MQGMO_SYNCPOINT_IF_PERSISTENT Gives errors in environment 1. (See V5 extensions.)
| MQGMO_MARK_SKIP_BACKOUT Causes MQRC_OPTIONS_ERROR except in environments 3 and 5.
MQCNO_FASTPATH_BINDING Supported only in environment 4. (See V5 extensions.)
MQPMRF_* fields Supported only in environments 2 and 4.
Putting a message with Rejected with MQCC_FAILED and MQRC_PRIORITY_ERROR in
| MQQueue.priority > MaxPriority environments 3 and 5.

Other environments accept it with the warnings MQCC_WARNING

and MQRC_PRIORITY_EXCEEDS_MAXIMUM and treat the
message as if it were put with MaxPriority.
| BackoutCount Environments 3 and 5 return a maximum backout count of 255, even
if the message has been backed out more than 255 times.
| Default dynamic queue name CSQ.* for environments 3 and 5. AMQ.* for other systems.
MQMessage.report options: Not supported if a report message is generated by an OS/390 queue
MQRO_EXCEPTION_WITH_FULL_DATA manager, although they may be set in all environments. This issue
MQRO_EXPIRATION_WITH_FULL_DATA affects all Java environments, because the OS/390 queue manager
MQRO_COA_WITH_FULL_DATA could be distant from the Java application. Avoid relying on any of
MQRO_COD_WITH_FULL_DATA these options if there is a chance that an OS/390 queue manager
MQRO_DISCARD_MSG could be involved.
| MQQueueManager constructor In environment 5, if the options present in MQEnvironment (and the
| optional properties argument) imply a client connection, the
| constructor fails with MQRC_ENVIRONMENT_ERROR.

| In environment 5, the constructor may also return

| MQRC_CHAR_CONVERSION_ERROR. Ensure that the National
| Language Resources component of the OS/390 Language
| Environment® is installed. In particular, ensure that conversions are
| available between the IBM-1047 and ISO8859-1 code pages.

| In environment 5, the constructor may also return

| MQRC_UCS2_CONVERSION_ERROR. The MQSeries classes for
| Java attempt to convert from Unicode to the queue manager code
| page, and default to IBM-500 if a specific code page is unavailable.
| Ensure that you have appropriate conversion tables for Unicode,
| which should be installed as part of the OS/390 C/C++ optional
| feature, and ensure that the Language Environment can locate the
| tables. See the OS/390 C/C++ Programming Guide, SC09-2362, for
| more information about enabling UCS-2 conversions.

Version 5 extensions operating in other environments

MQSeries classes for Java contains the following functions that are specifically
designed to use the API extensions introduced in MQSeries V5. These functions
operate as designed only in environments 2 and 4. This topic describes how they
would behave in other environments.
MQQueueManager constructor option
The MQQueueManager constructor includes an optional integer argument.
This maps onto the MQI’s MQCNO.options field, and is used to switch
between normal and fastpath connection. This extended form of the
constructor is accepted in all environments, provided that the only options
used are MQCNO_STANDARD_BINDING or
MQCNO_FASTPATH_BINDING. Any other options cause the constructor

Chapter 8. Environment-dependent behavior 75

 V5 extensions
to fail with MQRC_OPTIONS_ERROR. The fastpath option
MQC.MQCNO_FASTPATH_BINDING is only honored when used in the
MQSeries V5 bindings (environment 4). If this option is used in any other
environment, it is ignored.
MQQueueManager.begin() method
This can be used only in environment 4. In any other environment, it fails
with MQRC_ENVIRONMENT_ERROR. MQSeries for AS/400 does not
support the use of the begin() method to initiate global units of work that
are coordinated by the queue manager.
MQPutMessageOptions options
The following flags may be set into the MQPutMessageOptions options
fields in any environment. However, if these flags are used with a
subsequent MQQueue.put() in any environment other than 2 or 4, the put()
fails with MQRC_OPTIONS_ERROR.
v MQPMO_NEW_MSG_ID
v MQPMO_NEW_CORREL_ID
v MQPMO_LOGICAL_ORDER
MQGetMessageOptions options
The following flags may be set into the MQGetMessageOptions options
fields in any environment. However, if these flags are used with a
subsequent MQQueue.get() in any environment other than 2 or 4, the get()
fails with MQRC_OPTIONS_ERROR.
v MQGMO_LOGICAL_ORDER
v MQGMO_COMPLETE_MESSAGE
v MQGMO_ALL_MSGS_AVAILABLE
v MQGMO_ALL_SEGMENTS_AVAILABLE

The following flag may be set into the MQGetMessageOptions options

fields in any environment. However, if this flag is used with a subsequent
MQQueue.get() in environment 1, the get() fails with
MQRC_OPTIONS_ERROR.
v MQGMO_SYNCPOINT_IF_PERSISTENT
MQGetMessageOptions fields
Values may be set into the following fields, regardless of the environment.
However, if the MQGetMessageOptions used on a subsequent
MQQueue.get() contains non-default values when running in any
environment other than 2 or 4, the get() fails with MQRC_GMO_ERROR.
| In environments other than 2 or 4, these fields are always set to their initial
values after every successful get().
v MatchOptions
v GroupStatus
v SegmentStatus
v Segmentation

| Note: With MQSeries for OS/390 V2R1 or MQSeries for OS/390 V5R2
| running on the server, the MatchOptions field does support the flags
| MQMO_MATCH_MSG_ID and MQMO_MATCH_CORREL_ID.
| Other flags cause the get() to fail with MQRC_GMO_ERROR.
Distribution Lists
The following classes are used to create Distribution Lists:
v MQDistributionList
v MQDistributionListItem
v MQMessageTracker

76 MQSeries Using Java

 V5 extensions
You can create and populate MQDistributionList and
MQDistributionListItems in any environment, but you can only create and
open MQDistributionList successfully in environments 2 and 4. An attempt
to create and open one in any other environment is rejected with
MQRC_OD_ERROR.
MQPutMessageOptions fields
Four fields in MQPMO are rendered as the following member variables in
the MQPutMessageOptions class:
v knownDestCount
v unknownDestCount
v invalidDestCount
v recordFields

Although primarily intended for use with distribution lists, the MQSeries
V5 server also fills in the DestCount fields after an MQPUT to a single
queue. For example, if the queue resolves to a local queue,
knownDestCount is set to 1 and the other two fields are set to 0. In
environments 2 and 4, the values set by the V5 server are returned in the
MQPutMessageOptions class. In the other environments, return values are
simulated as follows:
v If the put() succeeds, unknownDestCount is set to 1, and the others are
set to 0.
v If the put() fails, invalidDestCount is set to 1, and the others are set to 0.
recordFields is used with distribution lists. A value may be written into
recordFields at any time, regardless of the environment. However, it is
ignored if the MQPutMessage options are used on a subsequent
MQQueue.put(), rather than MQDistributionList.put().
MQMD fields
The following MQMD fields are largely concerned with message
segmentation:
v GroupId
v MsgSeqNumber
v Offset MsgFlags
v OriginalLength

If an application sets any of these MQMD fields to non-default values, and

then does a put() to or get() in an environment other than 2 or 4, the put()
or get() raises an exception (MQRC_MD_ERROR). A successful put() or
get() in an environment other than 2 or 4, always leaves the new MQMD
fields set to their default values. A grouped or segmented message should
not normally be sent to a Java application that runs against a queue
manager that is not MQSeries Version 5 or higher. If such an application
does issue a get, and the physical message to be retrieved is part of a
group or segmented message (it has non-default values for the MQMD
fields), it is retrieved without error. However, the MQMD fields in the
MQMessage are not updated. The MQMessage format property is set to
MQFMT_MD_EXTENSION, and the true message data is prefixed with an
MQMDE structure that contains the values for the new fields.

Chapter 8. Environment-dependent behavior 77

V5 extensions

78 MQSeries Using Java

Chapter 9. The MQ base Java classes and interfaces
This chapter describes all the MQSeries classes for Java classes and interfaces. It
includes details of the variables, constructors, and methods in each class and
interface.

The following classes are described:

v MQChannelDefinition
v MQChannelExit
v MQDistributionList
v MQDistributionListItem
v MQEnvironment
v MQException
v MQGetMessageOptions
v MQManagedObject
v MQMessage
v MQMessageTracker
v MQPoolServices
v MQPoolServicesEvent
v MQPoolToken
v MQPutMessageOptions
v MQProcess
v MQQueue
v MQQueueManager
v MQSimpleConnectionManager
The following interfaces are described:
v MQC
v MQPoolServicesEventListener
v MQConnectionManager
v MQReceiveExit
v MQSecurityExit
v MQSendExit
v ManagedConnection
v ManagedConnectionFactory
v ManagedConnectionMetaData

© Copyright IBM Corp. 1997, 2001 79

MQChannelDefinition

MQChannelDefinition

java.lang.Object
│
└─ com.ibm.mq.MQChannelDefinition

public class MQChannelDefinition

extends Object

The MQChannelDefinition class is used to pass information concerning the

connection to the queue manager to the send, receive and security exits.

Note: This class does not apply when connecting directly to MQSeries in bindings
mode.

Variables
channelName
public String channelName
The name of the channel through which the connection is established.
queueManagerName
public String queueManagerName
The name of the queue manager to which the connection is made.
maxMessageLength
public int maxMessageLength
The maximum length of message that can be sent to the queue manager.
securityUserData
public String securityUserData
A storage area for the security exit to use. Information placed here is
preserved across invocations of the security exit, and is also available to
the send and receive exits.
sendUserData
public String sendUserData
A storage area for the send exit to use. Information placed here is
preserved across invocations of the send exit, and is also available to the
security and receive exits.
receiveUserData
public String receiveUserData
A storage area for the receive exit to use. Information placed here is
preserved across invocations of the receive exit, and is also available to the
send and security exits.
connectionName
public String connectionName
The TCP/IP hostname of the machine on which the queue manager
resides.

80 MQSeries Using Java

 MQChannelDefinition
remoteUserId
public String remoteUserId
The user id used to establish the connection.
remotePassword
public String remotePassword
The password used to establish the connection.

Constructors
MQChannelDefinition
public MQChannelDefinition()

Chapter 9. The MQ base Java classes and interfaces 81

MQChannelExit

MQChannelExit

java.lang.Object
│
└─ com.ibm.mq.MQChannelExit

public class MQChannelExit

extends Object

This class defines context information passed to the send, receive, and security
exits when they are invoked. The exitResponse member variable should be set by
the exit to indicate what action the MQSeries Client for Java should take next.

Note: This class does not apply when connecting directly to MQSeries in bindings
mode.

Variables
MQXT_CHANNEL_SEC_EXIT
public final static int MQXT_CHANNEL_SEC_EXIT
MQXT_CHANNEL_SEND_EXIT
public final static int MQXT_CHANNEL_SEND_EXIT
MQXT_CHANNEL_RCV_EXIT
public final static int MQXT_CHANNEL_RCV_EXIT
MQXR_INIT
public final static int MQXR_INIT
MQXR_TERM
public final static int MQXR_TERM
MQXR_XMIT
public final static int MQXR_XMIT
MQXR_SEC_MSG
public final static int MQXR_SEC_MSG
MQXR_INIT_SEC
public final static int MQXR_INIT_SEC
MQXCC_OK
public final static int MQXCC_OK
MQXCC_SUPPRESS_FUNCTION
public final static int MQXCC_SUPPRESS_FUNCTION
MQXCC_SEND_AND_REQUEST_SEC_MSG
public final static int MQXCC_SEND_AND_REQUEST_SEC_MSG
MQXCC_SEND_SEC_MSG
public final static int MQXCC_SEND_SEC_MSG
MQXCC_SUPPRESS_EXIT
public final static int MQXCC_SUPPRESS_EXIT
MQXCC_CLOSE_CHANNEL
public final static int MQXCC_CLOSE_CHANNEL

82 MQSeries Using Java

 MQChannelExit
exitID public int exitID
The type of exit that has been invoked. For an MQSecurityExit this is
always MQXT_CHANNEL_SEC_EXIT. For an MQSendExit this is always
MQXT_CHANNEL_SEND_EXIT, and for an MQReceiveExit this is always
MQXT_CHANNEL_RCV_EXIT.
exitReason
public int exitReason
The reason for invoking the exit. Possible values are:
MQXR_INIT
Exit initialization; called after the channel connection conditions
have been negotiated, but before any security flows have been
sent.
MQXR_TERM
Exit termination; called after the disconnect flows have been sent
but before the socket connection is destroyed.
MQXR_XMIT
For a send exit, indicates that data is to be transmitted to the
queue manager.
For a receive exit, indicates that data has been received from the
queue manager.
MQXR_SEC_MSG
Indicates to the security exit that a security message has been
received from the queue manager.
MQXR_INIT_SEC
Indicates that the exit is to initiate the security dialog with the
queue manager.
exitResponse
public int exitResponse
Set by the exit to indicate the action that MQSeries classes for Java should
take next. Valid values are:
MQXCC_OK
Set by the security exit to indicate that security exchanges are
complete.
Set by send exit to indicate that the returned data is to be
transmitted to the queue manager.
Set by the receive exit to indicate that the returned data is available
for processing by the MQSeries Client for Java.
MQXCC_SUPPRESS_FUNCTION
Set by the security exit to indicate that communications with the
queue manager should be shut down.
MQXCC_SEND_AND_REQUEST_SEC_MSG
Set by the security exit to indicate that the returned data is to be
transmitted to the queue manager, and that a response is expected
from the queue manager.

Chapter 9. The MQ base Java classes and interfaces 83

MQChannelExit
MQXCC_SEND_SEC_MSG
Set by the security exit to indicate that the returned data is to be
transmitted to the queue manager, and that no response is
expected.
MQXCC_SUPPRESS_EXIT
Set by any exit to indicate that it should no longer be called.
MQXCC_CLOSE_CHANNEL
Set by any exit to indicate that the connection to the queue
manager should be closed.
maxSegmentLength
public int maxSegmentLength
The maximum length for any one transmission to a queue manager.
If the exit returns data that is to be sent to the queue manager, the length
of the returned data should not exceed this value.
exitUserArea
public byte exitUserArea[]
A storage area available for the exit to use.
Any data placed in the exitUserArea is preserved by the MQSeries Client
for Java across exit invocations with the same exitID. (That is, the send,
receive, and security exits each have their own, independent, user areas.)
capabilityFlags
public static final int capabilityFlags
Indicates the capability of the queue manager.
Only the MQC.MQCF_DIST_LISTS flag is supported.
fapLevel
public static final int fapLevel
The negotiated Format and Protocol (FAP) level.

Constructors
MQChannelExit
public MQChannelExit()

84 MQSeries Using Java

 MQDistributionList

MQDistributionList

java.lang.Object
│
└─ com.ibm.mq.MQManagedObject
│
└─ com.ibm.mq.MQDistributionList

public class MQDistributionList

extends MQManagedObject (See page 99.)

Note: You can use this class only when connected to an MQSeries Version 5 (or
higher) queue manager.

An MQDistributionList is created by using the MQDistributionList constructor, or

by using the accessDistributionList method for MQQueueManager.

A distribution list represents a set of open queues to which messages can be sent
using a single call to the put() method. (See ″Distribution lists″ in the MQSeries
Application Programming Guide.)

Constructors
MQDistributionList
public MQDistributionList(MQQueueManager qMgr,
MQDistributionListItem[] litems,
int openOptions,
String alternateUserId)
throws MQException

qMgr is the queue manager where the list is to be opened.

litems are the items to be included in the distribution list.

See “accessDistributionList” on page 148 for details of the remaining

parameters.

Methods
put
public synchronized void put(MQMessage message,
MQPutMessageOptions putMessageOptions )
throws MQException

Puts a message to the queues on the distribution list.

Parameters
message
An input/output parameter containing the message descriptor
information and the returned message data.
putMessageOptions
Options that control the action of MQPUT. (See
“MQPutMessageOptions” on page 129 for details.)
Throws MQException if the put fails.

Chapter 9. The MQ base Java classes and interfaces 85

MQDistributionList
getFirstDistributionListItem
public MQDistributionListItem getFirstDistributionListItem()
Returns the first item in the distribution list, or null if the list is empty.
getValidDestinationCount
public int getValidDestinationCount()
Returns the number of items in the distribution list that were opened
successfully.
getInvalidDestinationCount
public int getInvalidDestinationCount()
Returns the number of items in the distribution list that failed to open
successfully.

86 MQSeries Using Java

 MQDistributionListItem

MQDistributionListItem

java.lang.Object
│
└─ com.ibm.mq.MQMessageTracker
│
└─ com.ibm.mq.MQDistributionListItem

public class MQDistributionListItem

extends MQMessageTracker (See page 121.)

Note: You can use this class only when connected to an MQSeries Version 5 (or
higher) queue manager.

An MQDistributionListItem represents a single item (queue) within a distribution

list.

Variables
completionCode
public int completionCode
The completion code resulting from the last operation on this item. If this
was the construction of an MQDistributionList, the completion code relates
to the opening of the queue. If it was a put operation, the completion code
relates to the attempt to put a message onto this queue.
The initial value is ″0″.
queueName
public String queueName
The name of a queue you want to use with a distribution list. This cannot
be the name of a model queue.
The initial value is ″″.
queueManagerName
public String queueManagerName
The name of the queue manager on which the queue is defined.
The initial value is ″″.
reasonCode
public int reasonCode
The reason code resulting from the last operation on this item. If this was
the construction of an MQDistributionList, the reason code relates to the
opening of the queue. If it was a put operation, the reason code relates to
the attempt to put a message onto this queue.
The initial value is ″0″.

Constructors
MQDistributionListItem
public MQDistributionListItem()
Construct a new MQDistributionListItem object.

Chapter 9. The MQ base Java classes and interfaces 87

MQEnvironment

MQEnvironment

java.lang.Object
│
└─ com.ibm.mq.MQEnvironment

public class MQEnvironment

extends Object

Note: All the methods and attributes of this class apply to the MQSeries classes for
Java client connections, but only enableTracing, disableTracing, properties,
and version_notice apply to bindings connections.

MQEnvironment contains static member variables that control the environment in

which an MQQueueManager object (and its corresponding connection to
MQSeries) is constructed.

Values set in the MQEnvironment class take effect when the MQQueueManager
constructor is called, so you should set the values in the MQEnvironment class
before you construct an MQQueueManager instance.

Variables
Note: Variables marked with * do not apply when connecting directly to MQSeries
in bindings mode.
version_notice
public final static String version_notice
The current version of MQSeries classes for Java.
securityExit*
public static MQSecurityExit securityExit
A security exit allows you to customize the security flows that occur
when an attempt is made to connect to a queue manager.
To provide your own security exit, define a class that implements
the MQSecurityExit interface, and assign securityExit to an instance
of that class. Otherwise, you can leave securityExit set to null, in
which case no security exit will be called.
See also “MQSecurityExit” on page 157.
sendExit*
public static MQSendExit sendExit
A send exit allows you to examine, and possibly alter, the data sent
to a queue manager. It is normally used in conjunction with a
corresponding receive exit at the queue manager.
To provide your own send exit, define a class that implements the
MQSendExit interface, and assign sendExit to an instance of that
class. Otherwise, you can leave sendExit set to null, in which case
no send exit will be called.
See also “MQSendExit” on page 159.

88 MQSeries Using Java

 MQEnvironment
receiveExit*
public static MQReceiveExit receiveExit
A receive exit allows you to examine, and possibly alter, data
received from a queue manager. It is normally used in conjunction
with a corresponding send exit at the queue manager.
To provide your own receive exit, define a class that implements the
MQReceiveExit interface, and assign receiveExit to an instance of
that class. Otherwise, you can leave receiveExit set to null, in which
case no receive exit will be called.
See also “MQReceiveExit” on page 155.
hostname*
public static String hostname
The TCP/IP hostname of the machine on which the MQSeries server
resides. If the hostname is not set, and no overriding properties are
set, bindings mode is used to connect to the local queue manager.
port* public static int port
The port to connect to. This is the port on which the MQSeries
server is listening for incoming connection requests. The default
value is 1414.
channel*
public static String channel
The name of the channel to connect to on the target queue manager.
You must set this member variable, or the corresponding property,
before constructing an MQQueueManager instance for use in client
mode.
userID*
public static String userID
Equivalent to the MQSeries environment variable MQ_USER_ID.
If a security exit is not defined for this client, the value of userID is
transmitted to the server and will be available to the server security
exit when it is invoked. The value may be used to verify the identity
of the MQSeries client.
The default value is ″″.
password*
public static String password
Equivalent to the MQSeries environment variable MQ_PASSWORD.
If a security exit is not defined for this client, the value of password
is transmitted to the server and is available to the server security
exit when it is invoked. The value may be used to verify the identity
of the MQSeries client.
The default value is ″″.
properties
public static java.util.Hashtable properties
A set of key/value pairs defining the MQSeries environment.
This hash table allows you to set environment properties as
key/value pairs rather than as individual variables.

Chapter 9. The MQ base Java classes and interfaces 89

MQEnvironment
The properties can also be passed as a hash table in a parameter on
the MQQueueManager constructor. Properties passed on the
constructor take precedence over values set with this properties
variable, but they are otherwise interchangeable. The order of
precedence of finding properties is:
1. properties parameter on MQQueueManager constructor
2. MQEnvironment.properties
3. Other MQEnvironment variables
4. Constant default values

The possible Key/value pairs are shown in the following table:

Key Value
MQC.CCSID_PROPERTY Integer (overrides MQEnvironment.CCSID)
MQC.CHANNEL_PROPERTY String (overrides MQEnvironment.channel)
MQC.CONNECT_OPTIONS_PROPERTY Integer, defaults to MQC.MQCNO_NONE
MQC.HOST_NAME_PROPERTY String (overrides MQEnvironment.hostname)
MQC.ORB_PROPERTY org.omg.CORBA.ORB (optional)
MQC.PASSWORD_PROPERTY String (overrides MQEnvironment.password)
MQC.PORT_PROPERTY Integer (overrides MQEnvironment.port)
MQC.RECEIVE_EXIT_PROPERTY MQReceiveExit (overrides
MQEnvironment.receiveExit)
MQC.SECURITY_EXIT_PROPERTY MQSecurityExit (overrides
MQEnvironment.securityExit)
MQC.SEND_EXIT_PROPERTY MQSendExit (overrides
MQEnvironment.sendExit.)
MQC.TRANSPORT_PROPERTY MQC.TRANSPORT_MQSERIES_BINDINGS
or
MQC.TRANSPORT_MQSERIES_CLIENT
or
MQC.TRANSPORT_VISIBROKER
or
MQC.TRANSPORT_MQSERIES (the default,
which selects bindings or client, based on
the value of ″hostname″.)
MQC.USER_ID_PROPERTY String (overrides MQEnvironment.userID.)

CCSID*
public static int CCSID
The CCSID used by the client.
Changing this value affects the way that the queue manager you
connect to translates information in the MQSeries headers. All data
in MQSeries headers is drawn from the invariant part of the ASCII
codeset, except for the data in the applicationIdData and the
putApplicationName fields of the MQMessage class. (See
“MQMessage” on page 102.)
If you avoid using characters from the variant part of the ASCII
codeset for these two fields, you are then safe to change the CCSID
from 819 to any other ASCII codeset.

90 MQSeries Using Java

 MQEnvironment
If you change the client’s CCSID to be the same as that of the queue
manager to which you are connecting, you gain a performance
benefit at the queue manager because it does not attempt to
translate the message headers.
The default value is 819.

Constructors
MQEnvironment
public MQEnvironment()

Methods
disableTracing
public static void disableTracing()
Turns off the MQSeries Client for Java trace facility.
enableTracing
public static void enableTracing(int level)
Turns on the MQSeries Client for Java trace facility.
Parameters
level The level of tracing required, from 1 to 5 (5 being the most
detailed).
enableTracing
public static void enableTracing(int level,
OutputStream stream)

Turns on the MQSeries Client for Java trace facility.

Parameters:
level The level of tracing required, from 1 to 5 (5 being the most
detailed).
stream The stream to which the trace is written.
setDefaultConnectionManager
public static void setDefaultConnectionManager(MQConnectionManager cxManager)

Sets the supplied MQConnectionManager to be the default

ConnectionManager. The default ConnectionManager is used when there is
no ConnectionManager specified on the MQQueueManager constructor.
This method also empties the set of MQPoolTokens.

Parameters:
cxManager
The MQConnectionManager to be the default ConnectionManager.

Chapter 9. The MQ base Java classes and interfaces 91

MQEnvironment
setDefaultConnectionManager
public static void setDefaultConnectionManager
(javax.resource.spi.ConnectionManager cxManager)

Sets the default ConnectionManager, and empties the set of

MQPoolTokens. The default ConnectionManager is used when there is no
ConnectionManager specified on the MQQueueManager constructor.

This method requires a JVM at Java 2 v1.3 or later, with JAAS 1.0 or later
installed.

Parameters:
cxManager
The default ConnectionManager (which implements the
javax.resource.spi.ConnectionManager interface).
getDefaultConnectionManager
public static javax.resource.spi.ConnectionManager
getDefaultConnectionManager()

Returns the default ConnectionManager. If the default ConnectionManager

is actually an MQConnectionManager, returns null.
addConnectionPoolToken
public static void addConnectionPoolToken(MQPoolToken token)

Adds the supplied MQPoolToken to the set of tokens. A default

ConnectionManager can use this as a hint; typically, it are enabled only
while there is at least one token in the set.

Parameters:
token The MQPoolToken to add to the set of tokens.
addConnectionPoolToken
public static MQPoolToken addConnectionPoolToken()

Constructs an MQPoolToken and adds it to the set of tokens. The

MQPoolToken is returned to the application to be passed later into
removeConnectionPoolToken().
removeConnectionPoolToken
public static void removeConnectionPoolToken(MQPoolToken token)

Removes the specified MQPoolToken from the set of tokens. If that

MQPoolToken is not in the set, there is no action.

Parameters:
token The MQPoolToken to remove from the set of tokens.

92 MQSeries Using Java

 MQException

MQException

java.lang.Object
│
└─ java.lang.Throwable
│
└─ java.lang.Exception
│
└─ com.ibm.mq.MQException

public class MQException

extends Exception

An MQException is thrown whenever an MQSeries error occurs. You can change

the output stream for the exceptions that are logged by setting the value of
MQException.log. The default value is System.err. This class contains definitions of
completion code and error code constants. Constants beginning MQCC_ are
MQSeries completion codes, and constants beginning MQRC_ are MQSeries reason
codes. The MQSeries Application Programming Reference contains a full description of
these errors and their probable causes.

Variables
log public static java.io.outputStreamWriter log
Stream to which exceptions are logged. (The default is System.err.) If you
set this to null, no logging occurs.
completionCode
public int completionCode
MQSeries completion code giving rise to the error. The possible values are:
v MQException.MQCC_WARNING
v MQException.MQCC_FAILED
reasonCode
public int reasonCode
MQSeries reason code describing the error. For a full explanation of the
reason codes, refer to the MQSeries Application Programming Reference.
exceptionSource
public Object exceptionSource
The object instance that threw the exception. You can use this as part of
your diagnostics when determining the cause of an error.

Constructors
MQException
public MQException(int completionCode,
int reasonCode,
Object source)

Construct a new MQException object.

Parameters
completionCode
The MQSeries completion code.

Chapter 9. The MQ base Java classes and interfaces 93

MQException
reasonCode
The MQSeries reason code.
source The object in which the error occurred.

94 MQSeries Using Java

 MQGetMessageOptions

MQGetMessageOptions

java.lang.Object
│
└─ com.ibm.mq.MQGetMessageOptions

public class MQGetMessageOptions

extends Object

This class contains options that control the behavior of MQQueue.get().

Note: The behavior of some of the options available in this class depends on the
environment in which they are used. These elements are marked with a *.
See “Chapter 8. Environment-dependent behavior” on page 73 for details.

Variables
options
public int options
Options that control the action of MQQueue.get. Any or none of the
following values can be specified. If more than one option is required, the
values can be added together or combined using the bitwise OR operator.
MQC.MQGMO_NONE
MQC.MQGMO_WAIT
Wait for a message to arrive.
MQC.MQGMO_NO_WAIT
Return immediately if there is no suitable message.
MQC.MQGMO_SYNCPOINT
Get the message under syncpoint control; the message is marked
as being unavailable to other applications, but it is deleted from
the queue only when the unit of work is committed. The message
is made available again if the unit of work is backed out.
MQC.MQGMO_NO_SYNCPOINT
Get message without syncpoint control.
MQC.MQGMO_BROWSE_FIRST
Browse from start of queue.
MQC.MQGMO_BROWSE_NEXT
Browse from the current position in the queue.
MQC.MQGMO_BROWSE_MSG_UNDER_CURSOR*
Browse message under browse cursor.
MQC.MQGMO_MSG_UNDER_CURSOR
Get message under browse cursor.
MQC.MQGMO_LOCK*
Lock the message that is browsed.
MQC.MQGMO_UNLOCK*
Unlock a previously locked message.
MQC.MQGMO_ACCEPT_TRUNCATED_MSG
Allow truncation of message data.

Chapter 9. The MQ base Java classes and interfaces 95

MQGetMessageOptions
MQC.MQGMO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing.
MQC.MQGMO_CONVERT
Request the application data to be converted, to conform to the
characterSet and encoding attributes of the MQMessage, before the
data is copied into the message buffer. Because data conversion is
also applied as the data is retrieved from the message buffer,
applications do not usually set this option.
MQC.MQGMO_SYNCPOINT_IF_PERSISTENT*
Get message with syncpoint control if message is persistent.
MQC.MQGMO_MARK_SKIP_BACKOUT*
Allow a unit of work to be backed out without reinstating the
message on the queue.

Segmenting and grouping MQSeries messages can be sent or received as a

single entity, can be split into several segments for sending and receiving,
and can also be linked to other messages in a group.

Each piece of data that is sent is known as a physical message, which can
be a complete logical message, or a segment of a longer logical message.

Each physical message usually has a different MsgId. All the segments of a
single logical message have the same groupId value and MsgSeqNumber
value, but the Offset value is different for each segment. The Offset field
gives the offset of the data in the physical message from the start of the
logical message. The segments usually have different MsgId values, because
they are individual physical messages.

Logical messages that form part of a group have the same groupId value,
but each message in the group has a different MsgSeqNumber value.
Messages in a group can also be segmented.

The following options can be used for dealing with segmented or grouped
messages:
MQC.MQGMO_LOGICAL_ORDER*
Return messages in groups, and segments of logical messages, in
logical order.
MQC.MQGMO_COMPLETE_MSG*
Retrieve only complete logical messages.
MQC.MQGMO_ALL_MSGS_AVAILABLE*
Retrieve messages from a group only when all the messages in the
group are available.
MQC.MQGMO_ALL_SEGMENTS_AVAILABLE*
Retrieve the segments of a logical message only when all the
segments in the group are available.
waitInterval
public int waitInterval
The maximum time (in milliseconds) that an MQQueue.get call waits for a
suitable message to arrive (used in conjunction with
MQC.MQGMO_WAIT). A value of MQC.MQWI_UNLIMITED indicates
that an unlimited wait is required.

96 MQSeries Using Java

 MQGetMessageOptions
resolvedQueueName
public String resolvedQueueName
This is an output field that the queue manager sets to the local name of the
queue from which the message was retrieved. This will be different from
the name used to open the queue if an alias queue or model queue was
opened.
matchOptions*
public int matchOptions
Selection criteria that determine which message is retrieved. The following
match options can be set:
MQC.MQMO_MATCH_MSG_ID
Message id to be matched.
MQC.MQMO_MATCH_CORREL_ID
Correlation id to be matched.
MQC.MQMO_MATCH_GROUP_ID
Group id to be matched.
MQC.MQMO_MATCH_MSG_SEQ_NUMBER
Match message sequence number.
MQC.MQMO_NONE
No matching required.
groupStatus*
public char groupStatus
This is an output field which indicates whether the retrieved message is in
a group, and if it is, whether it is the last in the group. Possible values are:
MQC.MQGS_NOT_IN_GROUP
Message is not in a group.
MQC.MQGS_MSG_IN_GROUP
Message is in a group, but is not the last in the group.
MQC.MQGS_LAST_MSG_IN_GROUP
Message is the last in the group. This is also the value returned if
the group consists of only one message.
segmentStatus*
public char segmentStatus
This is an output field that indicates whether the retrieved message is a
segment of a logical message. If the message is a segment, the flag
indicates whether or not it is the last segment. Possible values are:
MQC.MQSS_NOT_A_SEGMENT
Message is not a segment.
MQC.MQSS_SEGMENT
Message is a segment, but is not the last segment of the logical
message.
MQC.MQSS_LAST_SEGMENT
Message is the last segment of the logical message. This is also the
value returned if the logical message consists of only one segment.

Chapter 9. The MQ base Java classes and interfaces 97

MQGetMessageOptions
segmentation*
public char segmentation
This is an output field that indicates whether or not segmentation is
allowed for the retrieved message is a segment of a logical message.
Possible values are:
MQC.MQSEG_INHIBITED
Segmentation not allowed.
MQC.MQSEG_ALLOWED
Segmentation allowed.

Constructors
MQGetMessageOptions
public MQGetMessageOptions()
Construct a new MQGetMessageOptions object with options set to
MQC.MQGMO_NO_WAIT, a wait interval of zero, and a blank resolved
queue name.

98 MQSeries Using Java

 MQManagedObject

MQManagedObject

java.lang.Object
│
└─ com.ibm.mq.MQManagedObject

public class MQManagedObject

extends Object

MQManagedObject is a superclass for MQQueueManager, MQQueue and

MQProcess. It provides the ability to inquire and set attributes of these resources.

Variables
alternateUserId
public String alternateUserId
The alternate user id (if any) specified when this resource was opened.
Setting this attribute has no effect.
name public String name
The name of this resource (either the name supplied on the access method,
or the name allocated by the queue manager for a dynamic queue). Setting
this attribute has no effect.
openOptions
public int openOptions
The options specified when this resource was opened. Setting this attribute
has no effect.
isOpen
public boolean isOpen
Indicates whether this resource is currently open. This attribute is
deprecated and setting it has no effect.
connectionReference
public MQQueueManager connectionReference
The queue manager to which this resource belongs. Setting this attribute
has no effect.
closeOptions
public int closeOptions
Set this attribute to control the way the resource is closed. The default
value is MQC.MQCO_NONE, and this is the only permissible value for all
resources other than permanent dynamic queues, and temporary dynamic
queues that are being accessed by the objects that created them. For these
queues, the following additional values are permissible:
MQC.MQCO_DELETE
Delete the queue if there are no messages.
MQC.MQCO_DELETE_PURGE
Delete the queue, purging any messages on it.

Chapter 9. The MQ base Java classes and interfaces 99

MQManagedObject
Constructors
MQManagedObject
protected MQManagedObject()
Constructor method.

Methods
getDescription
public String getDescription()

Throws MQException.

Return the description of this resource as held at the queue manager.

If this method is called after the resource has been closed, an MQException
is thrown.
inquire
public void inquire(int selectors[],
int intAttrs[],
byte charAttrs[])

throws MQException.

Returns an array of integers and a set of character strings containing the

attributes of an object (queue, process or queue manager).

The attributes to be queried are specified in the selectors array. Refer to the
MQSeries Application Programming Reference for details of the permissible
selectors and their corresponding integer values.

Note that many of the more common attributes can be queried using the
getXXX() methods defined in MQManagedObject, MQQueue,
MQQueueManager, and MQProcess.

Parameters
selectors
Integer array identifying the attributes with values to be inquired
on.
intAttrs
The array in which the integer attribute values are returned.
Integer attribute values are returned in the same order as the
integer attribute selectors in the selectors array.
charAttrs
The buffer in which the character attributes are returned,
concatenated. Character attributes are returned in the same order
as the character attribute selectors in the selectors array. The length
of each attribute string is fixed for each attribute.

Throws MQException if the inquire fails.

isOpen
public boolean isOpen()
Returns the value of the isOpen variable.

100 MQSeries Using Java

 MQManagedObject
set
public synchronized void set(int selectors[],
int intAttrs[],
byte charAttrs[])

throws MQException.

Set the attributes defined in the selector’s vector.

The attributes to be set are specified in the selectors array. Refer to the
MQSeries Application Programming Reference for details of the permissible
selectors and their corresponding integer values.

Note that some queue attributes can be set using the setXXX() methods
defined in MQQueue.

Parameters
selectors
Integer array identifying the attributes with values to be set.
intAttrs
The array of integer attribute values to be set. These values must
be in the same order as the integer attribute selectors in the
selectors array.
charAttrs
The buffer in which the character attributes to be set are
concatenated. These values must be in the same order as the
character attribute selectors in the selectors array. The length of
each character attribute is fixed.

Throws MQException if the set fails.

close
public synchronized void close()

throws MQException.

Close the object. No further operations against this resource are permitted
after this method has been called. The behavior of the close method may
be altered by setting the closeOptions attribute.

Throws MQException if the MQSeries call fails.

Chapter 9. The MQ base Java classes and interfaces 101

MQMessage

MQMessage

java.lang.Object
│
└─ com.ibm.mq.MQMessage

public class MQMessage

implements DataInput, DataOutput

MQMessage represents both the message descriptor and the data for an MQSeries
message. There is group of readXXX methods for reading data from a message,
and a group of writeXXX methods for writing data into a message. The format of
numbers and strings used by these read and write methods can be controlled by
the encoding and characterSet member variables. The remaining member variables
contain control information that accompanies the application message data when a
message travels between sending and receiving applications. The application can
set values into the member variable before putting a message to a queue and can
read values after retrieving a message from a queue.

Variables
report public int report
A report is a message about another message. This member variable
enables the application sending the original message to specify which
report messages are required, whether the application message data is to
be included in them, and also how the message and correlation identifiers
in the report or reply are to be set. Any, all or none of the following report
types can be requested:
v Exception
v Expiration
v Confirm on arrival
v Confirm on delivery

For each type, only one of the three corresponding values below should be
specified, depending on whether the application message data is to be
included in the report message.

Note: Values marked with ** in the following list are not supported by
MVS queue managers and should not be used if your application is
likely to access an MVS queue manager, regardless of the platform
on which the application is running.

The valid values are:

v MQC.MQRO_EXCEPTION
v MQC.MQRO_EXCEPTION_WITH_DATA
v MQC.MQRO_EXCEPTION_WITH_FULL_DATA**
v MQC.MQRO_EXPIRATION
v MQC.MQRO_EXPIRATION_WITH_DATA
v MQC.MQRO_EXPIRATION_WITH_FULL_DATA**
v MQC.MQRO_COA
v MQC.MQRO_COA_WITH_DATA
v MQC.MQRO_COA_WITH_FULL_DATA**
v MQC.MQRO_COD
v MQC.MQRO_COD_WITH_DATA
v MQC.MQRO_COD_WITH_FULL_DATA**

102 MQSeries Using Java

 MQMessage
You can specify one of the following to control how the message Id is
generated for the report or reply message:
v MQC.MQRO_NEW_MSG_ID
v MQC.MQRO_PASS_MSG_ID

You can specify one of the following to control how the correlation Id of
the report or reply message is to be set:
v MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID
v MQC.MQRO_PASS_CORREL_ID

You can specify one of the following to control the disposition of the
original message when it cannot be delivered to the destination queue:
v MQC.MQRO_DEAD_LETTER_Q
v MQC.MQRO_DISCARD_MSG **

If no report options are specified, the default is:

MQC.MQRO_NEW_MSG_ID |
MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID |
MQC.MQRO_DEAD_LETTER_Q

You can specify one or both of the following to request that the receiving
application send a positive action or negative action report message.
v MQRO_PAN
v MQRO_NAN
messageType
public int messageType
Indicates the type of the message. The following values are currently
defined by the system:
v MQC.MQMT_DATAGRAM
v MQC.MQMT_REQUEST
v MQC.MQMT_REPLY
v MQC.MQMT_REPORT

Application-defined values can also be used. These should be in the range

MQC.MQMT_APPL_FIRST to MQC.MQMT_APPL_LAST.

The default value of this field is MQC.MQMT_DATAGRAM.

expiry public int expiry
An expiry time expressed in tenths of a second, set by the application that
puts the message. After a message’s expiry time has elapsed, it is eligible
to be discarded by the queue manager. If the message specified one of the
MQC.MQRO_EXPIRATION flags, a report is generated when the message
is discarded.
The default value is MQC.MQEI_UNLIMITED, meaning that the message
never expires.
feedback
public int feedback
This is used with a message of type MQC.MQMT_REPORT to indicate the
nature of the report. The following feedback codes are defined by the
system:
v MQC.MQFB_EXPIRATION
v MQC.MQFB_COA
v MQC.MQFB_COD

Chapter 9. The MQ base Java classes and interfaces 103

MQMessage
v MQC.MQFB_QUIT
v MQC.MQFB_PAN
v MQC.MQFB_NAN
v MQC.MQFB_DATA_LENGTH_ZERO
v MQC.MQFB_DATA_LENGTH_NEGATIVE
v MQC.MQFB_DATA_LENGTH_TOO_BIG
v MQC.MQFB_BUFFER_OVERFLOW
v MQC.MQFB_LENGTH_OFF_BY_ONE
v MQC.MQFB_IIH_ERROR

Application-defined feedback values in the range

MQC.MQFB_APPL_FIRST to MQC.MQFB_APPL_LAST can also be used.

The default value of this field is MQC.MQFB_NONE, indicating that no

feedback is provided.
encoding
public int encoding
This member variable specifies the representation used for numeric values
in the application message data; this applies to binary, packed decimal, and
floating point data. The behavior of the read and write methods for these
numeric formats is altered accordingly.
The following encodings are defined for binary integers:
MQC.MQENC_INTEGER_NORMAL
Big-endian integers, as in Java
MQC.MQENC_INTEGER_REVERSED
Little-endian integers, as used by PCs.

The following encodings are defined for packed-decimal integers:

MQC.MQENC_DECIMAL_NORMAL
Big-endian packed-decimal, as used by System/390.
MQC.MQENC_DECIMAL_REVERSED
Little-endian packed-decimal.

The following encodings are defined for floating-point numbers:

MQC.MQENC_FLOAT_IEEE_NORMAL
Big-endian IEEE floats, as in Java.
MQC.MQENC_FLOAT_IEEE_REVERSED
Little-endian IEEE floats, as used by PCs.
MQC.MQENC_FLOAT_S390
System/390 format floating points.

A value for the encoding field should be constructed by adding together

one value from each of these three sections (or using the bitwise OR
operator). The default value is:
MQC.MQENC_INTEGER_NORMAL |
MQC.MQENC_DECIMAL_NORMAL |
MQC.MQENC_FLOAT_IEEE_NORMAL

For convenience, this value is also represented by MQC.MQENC_NATIVE.

This setting causes writeInt() to write a big-endian integer, and readInt() to
read a big-endian integer. If the flag MQC.MQENC_INTEGER_REVERSED

104 MQSeries Using Java

 MQMessage
flag had been set instead, writeInt() would write a little-endian integer, and
readInt() would read a little-endian integer.

Note that a loss in precision can occur when converting from IEEE format
floating points to System/390 format floating points.
characterSet
public int characterSet
This specifies the coded character set identifier of character data in the
application message data. The behavior of the readString, readLine and
writeString methods is altered accordingly.
The default value for this field is MQC.MQCCSI_Q_MGR. If the default
value is used, CharacterSet 819 (iso-8859-1/latin/ibm819) is assumed. The
character set values shown in Table 13 are supported.
Table 13. Character set identifiers
characterSet Description

819 iso-8859-1 / latin1 / ibm819

912 iso-8859-2 / latin2 / ibm912
913 iso-8859-3 / latin3 / ibm913
914 iso-8859-4 / latin4 / ibm914
915 iso-8859-5 / cyrillic / ibm915
1089 iso-8859-6 / arabic / ibm1089
813 iso-8859-7 / greek / ibm813
916 iso-8859-8 / hebrew / ibm916
920 iso-8859-9 / latin5 / ibm920
37 ibm037
273 ibm273
277 ibm277
278 ibm278
280 ibm280
284 ibm284
285 ibm285
297 ibm297
420 ibm420
424 ibm424
437 ibm437 / PC Original
500 ibm500
737 ibm737 / PC Greek
775 ibm775 / PC Baltic
838 ibm838
850 ibm850 / PC Latin 1
852 ibm852 / PC Latin 2
855 ibm855 / PC Cyrillic
856 ibm856
857 ibm857 / PC Turkish
860 ibm860 / PC Portuguese
861 ibm861 / PC Icelandic
862 ibm862 / PC Hebrew
863 ibm863 / PC Canadian French
864 ibm864 / PC Arabic
865 ibm865 / PC Nordic
866 ibm866 / PC Russian
868 ibm868
869 ibm869 / PC Modern Greek

Chapter 9. The MQ base Java classes and interfaces 105

MQMessage
Table 13. Character set identifiers (continued)
characterSet Description

870 ibm870
871 ibm871
874 ibm874
875 ibm875
918 ibm918
921 ibm921
922 ibm922
930 ibm930
933 ibm933
935 ibm935
937 ibm937
939 ibm939
942 ibm942
948 ibm948
949 ibm949
950 ibm950 / Big 5 Traditional Chinese
964 ibm964 / CNS 11643 Traditional Chinese
970 ibm970
1006 ibm1006
1025 ibm1025
1026 ibm1026
1097 ibm1097
1098 ibm1098
1112 ibm1112
1122 ibm1122
1123 ibm1123
1124 ibm1124
1381 ibm1381
1383 ibm1383
2022 JIS
932 PC Japanese
954 EUCJIS
1250 Windows Latin 2
1251 Windows Cyrillic
1252 Windows Latin 1
1253 Windows Greek
1254 Windows Turkish
1255 Windows Hebrew
1256 Windows Arabic
1257 Windows Baltic
1258 Windows Vietnamese
33722 ibm33722
5601 ksc-5601 Korean
1200 Unicode
1208 UTF-8

106 MQSeries Using Java

 MQMessage
format
public String format
A format name used by the sender of the message to indicate the nature of
the data in the message to the receiver. You can use your own format
names, but names beginning with the letters ″MQ″ have meanings that are
defined by the queue manager. The queue manager built-in formats are:
MQC.MQFMT_NONE
No format name.
MQC.MQFMT_ADMIN
Command server request/reply message.
MQC.MQFMT_COMMAND_1
Type 1 command reply message.
MQC.MQFMT_COMMAND_2
Type 2 command reply message.
MQC.MQFMT_DEAD_LETTER_HEADER
Dead-letter header.
MQC.MQFMT_EVENT
Event message.
MQC.MQFMT_PCF
User-defined message in programmable command format.
MQC.MQFMT_STRING
Message consisting entirely of characters.
MQC.MQFMT_TRIGGER
Trigger message
MQC.MQFMT_XMIT_Q_HEADER
Transmission queue header.

The default value is MQC.MQFMT_NONE.

priority
public int priority
The message priority. The special value
MQC.MQPRI_PRIORITY_AS_Q_DEF can also be set in outbound
messages, in which case the priority for the message is taken from the
default priority attribute of the destination queue.
The default value is MQC.MQPRI_PRIORITY_AS_Q_DEF.
persistence
public int persistence
Message persistence. The following values are defined:
v MQC.MQPER_PERSISTENT
v MQC.MQPER_NOT_PERSISTENT
v MQC.MQPER_PERSISTENCE_AS_Q_DEF

The default value is MQC.MQPER_PERSISTENCE_AS_Q_DEF, which

indicates that the persistence for the message should be taken from the
default persistence attribute of the destination queue.

Chapter 9. The MQ base Java classes and interfaces 107

MQMessage
messageId
public byte messageId[]
For an MQQueue.get() call, this field specifies the message identifier of the
message to be retrieved. Normally, the queue manager returns the first
message with a message identifier and correlation identifier that match
those specified. The special value MQC.MQMI_NONE allows any message
identifier to match.
For an MQQueue.put() call, this specifies the message identifier to use. If
MQC.MQMI_NONE is specified, the queue manager generates a unique
message identifier when the message is put. The value of this member
variable is updated after the put to indicate the message identifier that was
used.
The default value is MQC.MQMI_NONE.
correlationId
public byte correlationId[]
For an MQQueue.get() call, this field specifies the correlation identifier of
the message to be retrieved. Normally the queue manager returns the first
message with a message identifier and correlation identifier that match
those specified. The special value MQC.MQCI_NONE allows any
correlation identifier to match.
For an MQQueue.put() call, this specifies the correlation identifier to use.
The default value is MQC.MQCI_NONE.
backoutCount
public int backoutCount
A count of the number of times the message has previously been returned
by an MQQueue.get() call as part of a unit of work, and subsequently
backed out.
The default value is zero.
replyToQueueName
public String replyToQueueName
The name of the message queue to which the application that issued the
get request for the message should send MQC.MQMT_REPLY and
MQC.MQMT_REPORT messages.
The default value is ″″.
replyToQueueManagerName
public String replyToQueueManagerName
The name of the queue manager to which reply or report messages should
be sent.
The default value is ″″.
If the value is ″″ on an MQQueue.put() call, the QueueManager fills in the
value.
userId public String userId
Part of the identity context of the message; it identifies the user that
originated this message.
The default value is ″″.

108 MQSeries Using Java

 MQMessage
accountingToken
public byte accountingToken[]
Part of the identity context of the message; it allows an application to
cause work done as a result of the message to be appropriately charged.
The default value is ″MQC.MQACT_NONE″.
applicationIdData
public String applicationIdData
Part of the identity context of the message; it is information that is defined
by the application suite, and can be used to provide additional information
about the message or its originator.
The default value is ″″.
putApplicationType
public int putApplicationType
The type of application that put the message. This may be a
system-defined or user-defined value. The following values are defined by
the system:
v MQC.MQAT_AIX
v MQC.MQAT_CICS
v MQC.MQAT_DOS
v MQC.MQAT_IMS
v MQC.MQAT_MVS
v MQC.MQAT_OS2
v MQC.MQAT_OS400
v MQC.MQAT_QMGR
v MQC.MQAT_UNIX
v MQC.MQAT_WINDOWS
v MQC.MQAT_JAVA

The default value is the special value MQC.MQAT_NO_CONTEXT, which

indicates that no context information is present in the message.
putApplicationName
public String putApplicationName
The name of the application that put the message. The default value is ″″.
putDateTime
public GregorianCalendar putDateTime
The time and date that the message was put.
applicationOriginData
public String applicationOriginData
Information defined by the application that can be used to provide
additional information about the origin of the message.
The default value is ″″.
groupId
public byte[] groupId
A byte string that identifies the message group to which the physical
message belongs.
The default value is ″MQC.MQGI_NONE″.

Chapter 9. The MQ base Java classes and interfaces 109

MQMessage
messageSequenceNumber
public int messageSequenceNumber
The sequence number of a logical message within a group.
offset public int offset
In a segmented message, the offset of data in a physical message from the
start of a logical message.
messageFlags
public int messageFlags
Flags controlling the segmentation and status of a message.
originalLength
public int originalLength
The original length of a segmented message.

Constructors
MQMessage
public MQMessage()
Create a new message with default message descriptor information and an
empty message buffer.

Methods
getTotalMessageLength
public int getTotalMessageLength()
The total number of bytes in the message as stored on the message queue
from which this message was retrieved (or attempted to be retrieved).
When an MQQueue.get() method fails with a message-truncated error
code, this method tells you the total size of the message on the queue.
See also “MQQueue.get” on page 133.
getMessageLength
public int getMessageLength

Throws IOException.

The number of bytes of message data in this MQMessage object.

getDataLength
public int getDataLength()

Throws MQException.

The number of bytes of message data remaining to be read.

110 MQSeries Using Java

 MQMessage
seek
public void seek(int pos)

Throws IOException.

Move the cursor to the absolute position in the message buffer given by
pos. Subsequent reads and writes will act at this position in the buffer.

Throws EOFException if pos is outside the message data length.

setDataOffset
public void setDataOffset(int offset)

Throws IOException.

Move the cursor to the absolute position in the message buffer. This
method is a synonym for seek(), and is provided for cross-language
compatibility with the other MQSeries APIs.
getDataOffset
public int getDataOffset()

Throws IOException.

Return the current cursor position within the message data (the point at
which read and write operations take effect).
clearMessage
public void clearMessage()

Throws IOException.

Discard any data in the message buffer and set the data offset back to zero.
getVersion
public int getVersion()
Returns the version of the structure in use.
resizeBuffer
public void resizeBuffer(int size)

Throws IOException.

A hint to the MQMessage object about the size of buffer that may be
required for subsequent get operations. If the message currently contains
message data, and the new size is less than the current size, the message
data is truncated.
readBoolean
public boolean readBoolean()

Throws IOException.

Read a (signed) byte from the current position in the message buffer.

Chapter 9. The MQ base Java classes and interfaces 111

MQMessage
readChar
public char readChar()

Throws IOException, EOFException.

Read a Unicode character from the current position in the message buffer.
readDouble
public double readDouble()

Throws IOException, EOFException.

Read a double from the current position in the message buffer. The value
of the encoding member variable determines the behavior of this method.

Values of MQC.MQENC_FLOAT_IEEE_NORMAL and

MQC.MQENC_FLOAT_IEEE_REVERSED read IEEE standard doubles in
big-endian and little-endian formats respectively.

A value of MQC.MQENC_FLOAT_S390 reads a System/390 format floating

point number.
readFloat
public float readFloat()

Throws IOException, EOFException.

Read a float from the current position in the message buffer. The value of
the encoding member variable determines the behavior of this method.

Values of MQC.MQENC_FLOAT_IEEE_NORMAL and

MQC.MQENC_FLOAT_IEEE_REVERSED read IEEE standard floats in
big-endian and little-endian formats respectively.

A value of MQC.MQENC_FLOAT_S390 reads a System/390 format floating

point number.
readFully
public void readFully(byte b[])

Throws Exception, EOFException.

Fill the byte array b with data from the message buffer.
readFully
public void readFully(byte b[],
int off,
int len)

Throws IOException, EOFException.

Fill len elements of the byte array b with data from the message buffer,
starting at offset off.

112 MQSeries Using Java

 MQMessage
readInt
public int readInt()

Throws IOException, EOFException.

Read an integer from the current position in the message buffer. The value
of the encoding member variable determines the behavior of this method.

A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian integer,

a value of MQC.MQENC_INTEGER_REVERSED reads a little-endian
integer.
readInt4
public int readInt4()

Throws IOException, EOFException.

Synonym for readInt(), provided for cross-language MQSeries API

compatibility.
readLine
public String readLine()

Throws IOException.

Converts from the codeset identified in the characterSet member variable

to Unicode, and then reads in a line that has been terminated by \n, \r,
\r\n, or EOF.
readLong
public long readLong()

Throws IOException, EOFException.

Read a long from the current position in the message buffer. The value of
the encoding member variable determines the behavior of this method.

A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian long, a

value of MQC.MQENC_INTEGER_REVERSED reads a little-endian long.
readInt8
public long readInt8()

Throws IOException, EOFException.

Synonym for readLong(), provided for cross-language MQSeries API

compatibility.
readObject
public Object readObject()

Throws OptionalDataException, ClassNotFoundException, IOException.

Read an object from the message buffer. The class of the object, the
signature of the class, and the value of the non-transient and non-static
fields of the class are all read.

Chapter 9. The MQ base Java classes and interfaces 113

MQMessage
readShort
public short readShort()

Throws IOException, EOFException.

readInt2
public short readInt2()

Throws IOException, EOFException.

Synonym for readShort(), provided for cross-language MQSeries API

compatibility.
readUTF
public String readUTF()

Throws IOException.

Read a UTF string, prefixed by a 2-byte length field, from the current
position in the message buffer.
readUnsignedByte
public int readUnsignedByte()

Throws IOException, EOFException.

Read an unsigned byte from the current position in the message buffer.
readUnsignedShort
public int readUnsignedShort()

Throws IOException, EOFException.

Read an unsigned short from the current position in the message buffer.
The value of the encoding member variable determines the behavior of this
method.

A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian

unsigned short, a value of MQC.MQENC_INTEGER_REVERSED reads a
little-endian unsigned short.
readUInt2
public int readUInt2()

Throws IOException, EOFException.

Synonym for readUnsignedShort(), provided for cross-language MQSeries

API compatibility.

114 MQSeries Using Java

 MQMessage
readString
public String readString(int length)

Throws IOException, EOFException.

Read a string in the codeset identified by the characterSet member

variable, and convert it into Unicode.

Parameters:
length The number of characters to read (which may differ from the
number of bytes according to the codeset, because some codesets
use more than one byte per character).
readDecimal2
public short readDecimal2()

Throws IOException, EOFException.

Read a 2-byte packed decimal number (-999..999). The behavior of this

method is controlled by the value of the encoding member variable. A
value of MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed
decimal number, and a value of MQC.MQENC_DECIMAL_REVERSED
reads a little-endian packed decimal number.
readDecimal4
public int readDecimal4()

Throws IOException, EOFException.

Read a 4-byte packed decimal number (-9999999..9999999). The behavior of

this method is controlled by the value of the encoding member variable. A
value of MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed
decimal number, and a value of MQC.MQENC_DECIMAL_REVERSED
reads a little-endian packed decimal number.
readDecimal8
public long readDecimal8()

Throws IOException, EOFException.

Read an 8-byte packed decimal number (-999999999999999 to

999999999999999). The behavior of this method is controlled by the
encoding member variable. A value of
MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed decimal
number, and MQC.MQENC_DECIMAL_REVERSED reads a little-endian
packed decimal number.
setVersion
public void setVersion(int version)

Specifies which version of the structure to use. Possible values are:

v MQC.MQMD_VERSION_1
v MQC.MQMD_VERSION_2
You should not normally need to call this method unless you wish to force
the client to use a version 1 structure when connected to a queue manager

Chapter 9. The MQ base Java classes and interfaces 115

MQMessage
that is capable of handling version 2 structures. In all other situations, the
client determines the correct version of the structure to use by querying the
queue manager’s capabilities.
skipBytes
public int skipBytes(int n)

Throws IOException, EOFException.

Move forward n bytes in the message buffer.

This method blocks until one of the following occurs:

v All the bytes are skipped
v The end of message buffer is detected
v An exception is thrown

Returns the number of bytes skipped, which is always n.

write
public void write(int b)

Throws IOException.

Write a byte into the message buffer at the current position.

write
public void write(byte b[])

Throws IOException.

Write an array of bytes into the message buffer at the current position.
write
public void write(byte b[],
int off,
int len)

Throws IOException.

Write a series of bytes into the message buffer at the current position. len
bytes will be written, taken from offset off in the array b.
writeBoolean
public void writeBoolean(boolean v)

Throws IOException.

Write a boolean into the message buffer at the current position.

writeByte
public void writeByte(int v)

Throws IOException.

Write a byte into the message buffer at the current position.

116 MQSeries Using Java

 MQMessage
writeBytes
public void writeBytes(String s)

Throws IOException.

Writes out the string to the message buffer as a sequence of bytes. Each
character in the string is written out in sequence by discarding its high
eight bits.
writeChar
public void writeChar(int v)

Throws IOException.

Write a Unicode character into the message buffer at the current position.
writeChars
public void writeChars(String s)

Throws IOException.

Write a string as a sequence of Unicode characters into the message buffer

at the current position.
writeDouble
public void writeDouble(double v)

Throws IOException

Write a double into the message buffer at the current position. The value of
the encoding member variable determines the behavior of this method.

Values of MQC.MQENC_FLOAT_IEEE_NORMAL and

MQC.MQENC_FLOAT_IEEE_REVERSED write IEEE standard floats in
Big-endian and Little-endian formats respectively.

A value of MQC.MQENC_FLOAT_S390 writes a System/390 format

floating point number. Note that the range of IEEE doubles is greater than
the range of S/390® double precision floating point numbers, and so very
large numbers cannot be converted.
writeFloat
public void writeFloat(float v)

Throws IOException.

Write a float into the message buffer at the current position. The value of
the encoding member variable determines the behavior of this method.

Values of MQC.MQENC_FLOAT_IEEE_NORMAL and

MQC.MQENC_FLOAT_IEEE_REVERSED write IEEE standard floats in
big-endian and little-endian formats respectively.

A value of MQC.MQENC_FLOAT_S390 will write a System/390 format

floating point number.

Chapter 9. The MQ base Java classes and interfaces 117

MQMessage
writeInt
public void writeInt(int v)

Throws IOException.

Write an integer into the message buffer at the current position. The value
of the encoding member variable determines the behavior of this method.

A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian

integer, a value of MQC.MQENC_INTEGER_REVERSED writes a
little-endian integer.
writeInt4
public void writeInt4(int v)

Throws IOException.

Synonym for writeInt(), provided for cross-language MQSeries API

compatibility.
writeLong
public void writeLong(long v)

Throws IOException.

Write a long into the message buffer at the current position. The value of
the encoding member variable determines the behavior of this method.

A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian long, a

value of MQC.MQENC_INTEGER_REVERSED writes a little-endian long.
writeInt8
public void writeInt8(long v)

Throws IOException.

Synonym for writeLong(), provided for cross-language MQSeries API

compatibility.
writeObject
public void writeObject(Object obj)

Throws IOException.

Write the specified object to the message buffer. The class of the object, the
signature of the class, and the values of the non-transient and non-static
fields of the class and all its supertypes are all written.

118 MQSeries Using Java

 MQMessage
writeShort
public void writeShort(int v)

Throws IOException.

Write a short into the message buffer at the current position. The value of
the encoding member variable determines the behavior of this method.

A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian short,

a value of MQC.MQENC_INTEGER_REVERSED writes a little-endian
short.
writeInt2
public void writeInt2(int v)

Throws IOException.

Synonym for writeShort(), provided for cross-language MQSeries API

compatibility.
writeDecimal2
public void writeDecimal2(short v)

Throws IOException.

Write a 2-byte packed decimal format number into the message buffer at
the current position. The value of the encoding member variable
determines the behavior of this method.

A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian

packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a
little-endian packed decimal.

Parameters
v can be in the range -999 to 999.
writeDecimal4
public void writeDecimal4(int v)

Throws IOException.

Write a 4-byte packed decimal format number into the message buffer at
the current position. The value of the encoding member variable
determines the behavior of this method.

A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian

packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a
little-endian packed decimal.

Parameters
v can be in the range -9999999 to 9999999.

Chapter 9. The MQ base Java classes and interfaces 119

MQMessage
writeDecimal8
public void writeDecimal8(long v)

Throws IOException.

Write an 8-byte packed decimal format number into the message buffer at
the current position. The value of the encoding member variable
determines the behavior of this method.

A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian

packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a
little-endian packed decimal.

Parameters:
v can be in the range -999999999999999 to 999999999999999.
writeUTF
public void writeUTF(String str)

Throws IOException.

Write a UTF string, prefixed by a 2-byte length field, into the message
buffer at the current position.
writeString
public void writeString(String str)

Throws IOException.

Write a string into the message buffer at the current position, converting it
to the codeset identified by the characterSet member variable.

120 MQSeries Using Java

 MQMessageTracker

MQMessageTracker

java.lang.Object
│
└─ com.ibm.mq.MQMessageTracker

public abstract class MQMessageTracker

extends Object

Note: You can use this class only when connected to an MQSeries Version 5 (or
higher) queue manager.

This class is inherited by MQDistributionListItem (on page 87) where it is used to

tailor message parameters for a given destination in a distribution list.

Variables
feedback
public int feedback
This is used with a message of type MQC.MQMT_REPORT to indicate the
nature of the report. The following feedback codes are defined by the
system:
v MQC.MQFB_EXPIRATION
v MQC.MQFB_COA
v MQC.MQFB_COD
v MQC.MQFB_QUIT
v MQC.MQFB_PAN
v MQC.MQFB_NAN
v MQC.MQFB_DATA_LENGTH_ZERO
v MQC.MQFB_DATA_LENGTH_NEGATIVE
v MQC.MQFB_DATA_LENGTH_TOO_BIG
v MQC.MQFB_BUFFER_OVERFLOW
v MQC.MQFB_LENGTH_OFF_BY_ONE
v MQC.MQFB_IIH_ERROR

Application defined feedback values in the range

MQC.MQFB_APPL_FIRST to MQC.MQFB_APPL_LAST can also be used.

The default value of this field is MQC.MQFB_NONE, indicating that no

feedback is provided.
messageId
public byte messageId[]
This specifies the message identifier to use when the message is put. If
MQC.MQMI_NONE is specified, the queue manager generates a unique
message identifier when the message is put. The value of this member
variable is updated after the put to indicate the message identifier that was
used.
The default value is MQC.MQMI_NONE.

Chapter 9. The MQ base Java classes and interfaces 121

MQMessageTracker
correlationId
public byte correlationId[]
This specifies the correlation identifier to use when the message is put.
The default value is MQC.MQCI_NONE.
accountingToken
public byte accountingToken[]
This is part of the identity context of the message. It allows an application
to cause work done as a result of the message to be appropriately charged.
The default value is MQC.MQACT_NONE.
groupId
public byte[] groupId
A byte string that identifies the message group to which the physical
message belongs.
The default value is MQC.MQGI_NONE.

122 MQSeries Using Java

 MQPoolServices

MQPoolServices

java.lang.Object
│
└─ com.ibm.mq.MQPoolServices

public class MQPoolServices

extends Object

Note: Normally, applications do not use this class.

The MQPoolServices class can be used by implementations of ConnectionManager

that are intended for use as the default ConnectionManager for MQSeries
connections.

A ConnectionManager can construct an MQPoolServices object and, through it,

register a listener. This listener receives events that relate to the set of
MQPoolTokens that MQEnvironment manages. The ConnectionManager can use
this information to perform any necessary startup or cleanup work.

See also “MQPoolServicesEvent” on page 124 and “MQPoolServicesEventListener”

on page 153.

Constructors
MQPoolServices
public MQPoolServices()

Construct a new MQPoolServices object.

Methods
addMQPoolServicesEventListener
public void addMQPoolServicesEventListener
(MQPoolServicesEventListener listener)

Add an MQPoolServicesEventListener. The listener receives an event

whenever a token is added or removed from the set of MQPoolTokens that
MQEnvironment controls, or whenever the default ConnectionManager
changes.
removeMQPoolServicesEventListener
public void removeMQPoolServicesEventListener
(MQPoolServicesEventListener listener)

Remove an MQPoolServicesEventListener.
getTokenCount
public int getTokenCount()

Returns the number of MQPoolTokens that are currently registered with

MQEnvironment.

Chapter 9. The MQ base Java classes and interfaces 123

MQPoolServicesEvent

MQPoolServicesEvent

java.lang.Object
│
└─ java.util.EventObject
│
└─ com.ibm.mq.MQPoolServicesEvent

Note: Normally, applications do not use this class.

An MQPoolServicesEvent is generated whenever an MQPoolToken is added to, or

removed from, the set of tokens that MQEnvironment controls. An event is also
generated when the default ConnectionManager is changed.

See also “MQPoolServices” on page 123 and “MQPoolServicesEventListener” on

page 153.

Variables
TOKEN_ADDED
public static final int TOKEN_ADDED
The event ID used when an MQPoolToken is added to the set.
TOKEN_REMOVED
public static final int TOKEN_REMOVED
The event ID used when an MQPoolToken is removed from the set.
DEFAULT_POOL_CHANGED
public static final int DEFAULT_POOL_CHANGED
The event ID used when the default ConnectionManager changes.
ID protected int ID
The event ID. Valid values are:
TOKEN_ADDED
TOKEN_REMOVED
DEFAULT_POOL_CHANGED
token protected MQPoolToken token
The token. When the event ID is DEFAULT_POOL_CHANGED, this is
null.

Constructors
MQPoolServicesEvent
public MQPoolServicesEvent(Object source, int eid, MQPoolToken token)

Constructs an MQPoolServicesEvent based on the event ID and the token.

MQPoolServicesEvent
public MQPoolServicesEvent(Object source, int eid)

Constructs an MQPoolServicesEvent based on the event ID.

124 MQSeries Using Java

 MQPoolServicesEvent
Methods
getId public int getId()
Gets the event ID.
Returns
The event ID, with one of the following values:
TOKEN_ADDED
TOKEN_REMOVED
DEFAULT_POOL_CHANGED
getToken
public MQPoolToken getToken()
Returns the token that was added to, or removed from, the set. If the event
ID is DEFAULT_POOL_CHANGED, this is null.

Chapter 9. The MQ base Java classes and interfaces 125

MQPoolToken

MQPoolToken

java.lang.Object
│
└─ com.ibm.mq.MQPoolToken

public class MQPoolToken

extends Object

An MQPoolToken can be used to enable the default connection pool.

MQPoolTokens are registered with the MQEnvironment class before an application
component connects to MQSeries. Later, they are deregistered when the component
has finished using MQSeries. Typically, the default ConnectionManager is active
while the set of registered MQPoolTokens is not empty.

MQPoolToken provides no methods or variables. ConnectionManager providers

can choose to extend MQPoolToken so that hints can be passed to the
ConnectionManager.

See “MQEnvironment.addConnectionPoolToken” on page 92 and

“MQEnvironment.removeConnectionPoolToken” on page 92.

Constructors
MQPoolToken
public MQPoolToken()

Construct a new MQPoolToken object.

126 MQSeries Using Java

 MQProcess

MQProcess

java.lang.Object
│
└─ com.ibm.mq.MQManagedObject
│
└─ com.ibm.mq.MQProcess

public class MQProcess

extends MQManagedObject. (See page 99.)

MQProcess provides inquire operations for MQSeries processes.

Constructors
MQProcess
public MQProcess(MQQueueManager qMgr,
String processName,
int openOptions,
String queueManagerName,
String alternateUserId)
throws MQException

Access a process on the queue manager qMgr. See accessProcess in the

“MQQueueManager” on page 140 for details of the remaining parameters.

Methods
getApplicationId
public String getApplicationId()
A character string that identifies the application to be started. This
information is for use by a trigger monitor application that processes
messages on the initiation queue; the information is sent to the initiation
queue as part of the trigger message.
Throws MQException if you call this method after you have closed the
process.
getApplicationType
public int getApplicationType()
Throws MQException (see page 93).
This identifies the nature of the program to be started in response to the
receipt of a trigger message. The application type can take any value, but
the following values are recommended for standard types:
v MQC.MQAT_AIX
v MQC.MQAT_CICS
v MQC.MQAT_DOS
v MQC.MQAT_IMS
v MQC.MQAT_MVS
v MQC.MQAT_OS2
v MQC.MQAT_OS400
v MQC.MQAT_UNIX
v MQC.MQAT_WINDOWS
v MQC.MQAT_WINDOWS_NT
v MQC.MWQAT_USER_FIRST (lowest value for user-defined application
type)

Chapter 9. The MQ base Java classes and interfaces 127

MQProcess
v MQC.MQAT_USER_LAST (highest value for user-defined application
type)
getEnvironmentData
public String getEnvironmentData()

Throws MQException.

A string containing environment-related information pertaining to the

application to be started.
getUserData
public String getUserData()

Throws MQException.

A string containing user information relevant to the application to be

started.
close
public synchronized void close()

Throws MQException.

Override of “MQManagedObject.close” on page 101.

128 MQSeries Using Java

 MQPutMessageOptions

MQPutMessageOptions

java.lang.Object
│
└─ com.ibm.mq.MQPutMessageOptions

public class MQPutMessageOptions

extends Object

This class contains options that control the behavior of MQQueue.put().

Note: The behavior of some of the options available in this class depends on the
environment in which they are used. These elements are marked with a *.
See “Version 5 extensions operating in other environments” on page 75 for
details.

Variables
options
public int options
Options that control the action of MQQueue.put. Any or none of the
following values can be specified. If more than one option is required the
values can be added together or combined using the bitwise OR operator.
MQC.MQPMO_SYNCPOINT
Put a message with syncpoint control. The message is not visible
outside the unit of work until the unit of work is committed. If the
unit of work is backed out, the message is deleted.
MQC.MQPMO_NO_SYNCPOINT
Put a message without syncpoint control. Note that, if the
syncpoint control option is not specified, a default of ‘no
syncpoint’ is assumed. This applies for all supported platforms,
including OS/390.
MQC.MQPMO_NO_CONTEXT
No context is to be associated with the message.
MQC.MQPMO_DEFAULT_CONTEXT
Associate default context with the message.
MQC.MQPMO_SET_IDENTITY_CONTEXT
Set identity context from the application.
MQC.MQPMO_SET_ALL_CONTEXT
Set all context from the application.
MQC.MQPMO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing.
MQC.MQPMO_NEW_MSG_ID*
Generate a new message id for each sent message.
MQC.MQPMO_NEW_CORREL_ID*
Generate a new correlation id for each sent message.
MQC.MQPMO_LOGICAL_ORDER*
Put logical messages and segments in message groups into their
logical order.

Chapter 9. The MQ base Java classes and interfaces 129

MQPutMessageOptions
MQC.MQPMO_NONE
No options specified. Do not use in conjunction with other options.
MQC.MQPMO_PASS_IDENTITY_CONTEXT
Pass identity context from an input queue handle.
MQC.MQPMO_PASS_ALL_CONTEXT
Pass all context from an input queue handle.
contextReference
public MQQueue ContextReference
This is an input field which indicates the source of the context information.
If the options field includes MQC.MQPMO_PASS_IDENTITY_CONTEXT,
or MQC.MQPMO_PASS_ALL_CONTEXT, set this field to refer to the
MQQueue from which the context information should be taken.
The initial value of this field is null.
recordFields *
public int recordFields
Flags indicating which fields are to be customized on a per-queue basis
when putting a message to a distribution list. One or more of the following
flags can be specified:
MQC.MQPMRF_MSG_ID
Use the messageId attribute in the MQDistributionListItem.
MQC.MQPMRF_CORREL_ID
Use the correlationId attribute in the MQDistributionListItem.
MQC.MQPMRF_GROUP_ID
Use the groupId attribute in the MQDistributionListItem.
MQC.MQPMRF_FEEDBACK
Use the feedback attribute in the MQDistributionListItem.
MQC.MQPMRF_ACCOUNTING_TOKEN
Use the accountingToken attribute in the MQDistributionListItem.

The special value MQC.MQPMRF_NONE indicates that no fields are to be

customized.
resolvedQueueName
public String resolvedQueueName
This is an output field that is set by the queue manager to the name of the
queue on which the message is placed. This may be different from the
name used to open the queue if the opened queue was an alias or model
queue.
resolvedQueueManagerName
public String resolvedQueueManagerName
This is an output field set by the queue manager to the name of the queue
manager that owns the queue specified by the remote queue name. This
may be different from the name of the queue manager from which the
queue was accessed if the queue is a remote queue.

130 MQSeries Using Java

 MQPutMessageOptions
knownDestCount *
public int knownDestCount
This is an output field set by the queue manager to the number of
messages that the current call has sent successfully to queues that resolve
to local queues. This field is also set when opening a single queue that is
not part of a distribution list.
unknownDestCount *
public int unknownDestCount
This is an output field set by the queue manager to the number of
messages that the current call has sent successfully to queues that resolve
to remote queues. This field is also set when opening a single queue that is
not part of a distribution list.
invalidDestCount *
public int invalidDestCount
This is an output field set by the queue manager to the number of
messages that could not be sent to queues in a distribution list. The count
includes queues that failed to open as well as queues that were opened
successfully, but for which the put operation failed. This field is also set
when opening a single queue that is not part of a distribution list.

Constructors
MQPutMessageOptions
public MQPutMessageOptions()
Construct a new MQPutMessageOptions object with no options set, and a
blank resolvedQueueName and resolvedQueueManagerName.

Chapter 9. The MQ base Java classes and interfaces 131

MQQueue

MQQueue

java.lang.Object
│
└─ com.ibm.mq.MQManagedObject
│
└─ com.ibm.mq.MQQueue

public class MQQueue

extends MQManagedObject. (See page 99.)

MQQueue provides inquire, set, put, and get operations for MQSeries queues. The
inquire and set capabilities are inherited from MQ.MQManagedObject.

See also “MQQueueManager.accessQueue” on page 145.

Constructors
MQQueue
public MQQueue(MQQueueManager qMgr, String queueName, int openOptions,
String queueManagerName, String dynamicQueueName,
String alternateUserId )
throws MQException

Access a queue on the queue manager qMgr.

See “MQQueueManager.accessQueue” on page 145 for details of the

remaining parameters.

Methods
get
public synchronized void get(MQMessage message,
MQGetMessageOptions getMessageOptions,
int MaxMsgSize)

Throws MQException.

Retrieves a message from the queue, up to a maximum specified message

size.

This method takes an MQMessage object as a parameter. It uses some of

the fields in the object as input parameters - in particular the messageId
and correlationId, so it is important to ensure that these are set as required.
(See “Message” on page 262.)

If the get fails, the MQMessage object is unchanged. If it succeeds the

message descriptor (member variables) and message data portions of the
MQMessage are completely replaced with the message descriptor and
message data from the incoming message.

Note that all calls to MQSeries from a given MQQueueManager are

synchronous. Therefore, if you perform a get with wait, all other threads
using the same MQQueueManager are blocked from making further
MQSeries calls until the get completes. If you need multiple threads to
access MQSeries simultaneously, each thread must create its own
MQQueueManager object.

132 MQSeries Using Java

 MQQueue
Parameters
message
An input/output parameter containing the message descriptor
information and the returned message data.
getMessageOptions
Options controlling the action of the get. (See
“MQGetMessageOptions” on page 95.)
MaxMsgSize
The largest message this call will be able to receive. If the message
on the queue is larger than this size, one of two things can occur:
1. If the MQC.MQGMO_ACCEPT_TRUNCATED_MSG flag is set
in the options member variable of the MQGetMessageOptions
object, the message is filled with as much of the message data
as will fit in the specified buffer size, and an exception is
thrown with completion code MQException.MQCC_WARNING
and reason code
MQException.MQRC_TRUNCATED_MSG_ACCEPTED.
2. If the MQC.MQGMO_ACCEPT_TRUNCATED_MSG flag is not
set, the message is left on the queue and an MQException is
raised with completion code MQException.MQCC_WARNING
and reason code
MQException.MQRC_TRUNCATED_MSG_FAILED.

Throws MQException if the get fails.

get
public synchronized void get(MQMessage message,
MQGetMessageOptions getMessageOptions)

Throws MQException.

Retrieves a message from the queue, regardless of the size of the message.
For large messages, the get method may have to issue two calls to
MQSeries on your behalf, one to establish the required buffer size and one
to get the message data itself.

This method takes an MQMessage object as a parameter. It uses some of

the fields in the object as input parameters - in particular the messageId
and correlationId, so it is important to ensure that these are set as required.
(See “Message” on page 262.)

If the get fails, the MQMessage object is unchanged. If it succeeds, the

message descriptor (member variables) and message data portions of the
MQMessage are completely replaced with the message descriptor and
message data from the incoming message.

Note that all calls to MQSeries from a given MQQueueManager are

synchronous. Therefore, if you perform a get with wait, all other threads
using the same MQQueueManager are blocked from making further
MQSeries calls until the get completes. If you need multiple threads to
access MQSeries simultaneously, each thread must create its own
MQQueueManager object.

Chapter 9. The MQ base Java classes and interfaces 133

MQQueue
Parameters
message
An input/output parameter containing the message descriptor
information and the returned message data.
getMessageOptions
Options controlling the action of the get. (See
“MQGetMessageOptions” on page 95 for details.)

Throws MQException if the get fails.

get
public synchronized void get(MQMessage message)

This is a simplified version of the get method previously described.

Parameters
MQMessage
An input/output parameter containing the message descriptor
information and the returned message data.

This method uses a default instance of MQGetMessageOptions to do the

get. The message option used is MQGMO_NOWAIT.
put
public synchronized void put(MQMessage message,
MQPutMessageOptions putMessageOptions)

Throws MQException.

Places a message onto the queue.

This method takes an MQMessage object as a parameter. The message

descriptor properties of this object may be altered as a result of this
method. The values they have immediately after the completion of this
method are the values that were put onto the MQSeries queue.

Modifications to the MQMessage object after the put has completed do not
affect the actual message on the MQSeries queue.

A put updates the messageId and correlationId. This must be considered

when making further calls to put/get using the same MQMessage object.
Also, calling put does not clear the message data, so:
msg.writeString("a");
q.put(msg,pmo);
msg.writeString("b");
q.put(msg,pmo);

puts two messages. The first contains ″a″ and the second ″ab″.

134 MQSeries Using Java

 MQQueue
Parameters
message
Message Buffer containing the Message Descriptor data and
message to be sent.
putMessageOptions
Options controlling the action of the put. (See
“MQPutMessageOptions” on page 129)

Throws MQException if the put fails.

put
public synchronized void put(MQMessage message)

This is a simplified version of the put method previously described.

Parameters
MQMessage
Message Buffer containing the Message Descriptor data and
message to be sent.

This method uses a default instance of MQPutMessageOptions to do the

put.

Note: All the following methods throw MQException if you call the method after
you have closed the queue.
getCreationDateTime
public GregorianCalendar getCreationDateTime()

Throws MQException.

The date and time that this queue was created.

getQueueType
public int getQueueType()
Throws MQException
Returns
The type of this queue with one of the following values:
v MQC.MQQT_ALIAS
v MQC.MQQT_LOCAL
v MQC.MQQT_REMOTE
v MQC.MQQT_CLUSTER
getCurrentDepth
public int getCurrentDepth()

Throws MQException.

Get the number of messages currently on the queue. This value is

incremented during a put call, and during backout of a get call. It is
decremented during a non-browse get and during backout of a put call.

Chapter 9. The MQ base Java classes and interfaces 135

MQQueue
getDefinitionType
public int getDefinitionType()

Throws MQException.

Indicates how the queue was defined.

Returns
One of the following:
v MQC.MQQDT_PREDEFINED
v MQC.MQQDT_PERMANENT_DYNAMIC
v MQC.MQQDT_TEMPORARY_DYNAMIC
getMaximumDepth
public int getMaximumDepth()

Throws MQException.

The maximum number of messages that can exist on the queue at any one
time. An attempt to put a message to a queue that already contains this
many messages fails with reason code MQException.MQRC_Q_FULL.
getMaximumMessageLength
public int getMaximumMessageLength()

Throws MQException.

This is the maximum length of the application data that can exist in each
message on this queue. An attempt to put a message larger than this value
fails with reason code MQException.MQRC_MSG_TOO_BIG_FOR_Q.
getOpenInputCount
public int getOpenInputCount()

Throws MQException.

The number of handles that are currently valid for removing messages
from the queue. This is the total number of such handles known to the
local queue manager, not just those created by the MQSeries classes for
Java (using accessQueue).
getOpenOutputCount
public int getOpenOutputCount()

Throws MQException.

The number of handles that are currently valid for adding messages to the
queue. This is the total number of such handles known to the local queue
manager, not just those created by the MQSeries classes for Java (using
accessQueue).

136 MQSeries Using Java

 MQQueue
getShareability
public int getShareability()

Throws MQException.

Indicates whether the queue can be opened for input multiple times.
Returns
One of the following:
v MQC.MQQA_SHAREABLE
v MQC.MQQA_NOT_SHAREABLE
getInhibitPut
public int getInhibitPut()

Throws MQException.

Indicates whether or not put operations are allowed for this queue.
Returns
One of the following:
v MQC.MQQA_PUT_INHIBITED
v MQC.MQQA_PUT_ALLOWED
setInhibitPut
public void setInhibitPut(int inhibit)

Throws MQException.

Controls whether or not put operations are allowed for this queue. The
permissible values are:
v MQC.MQQA_PUT_INHIBITED
v MQC.MQQA_PUT_ALLOWED
getInhibitGet
public int getInhibitGet()

Throws MQException.

Indicates whether or not get operations are allowed for this queue.
Returns
The possible values are:
v MQC.MQQA_GET_INHIBITED
v MQC.MQQA_GET_ALLOWED
setInhibitGet
public void setInhibitGet(int inhibit)

Throws MQException.

Controls whether or not get operations are allowed for this queue. The
permissible values are:
v MQC.MQQA_GET_INHIBITED
v MQC.MQQA_GET_ALLOWED

Chapter 9. The MQ base Java classes and interfaces 137

MQQueue
getTriggerControl
public int getTriggerControl()

Throws MQException.

Indicates whether or not trigger messages are written to an initiation

queue, in order to cause an application to be started to service the queue.
Returns
The possible values are:
v MQC.MQTC_OFF
v MQC.MQTC_ON
setTriggerControl
public void setTriggerControl(int trigger)

Throws MQException.

Controls whether or not trigger messages are written to an initiation

queue, in order to cause an application to be started to service the queue.
The permissible values are:
v MQC.MQTC_OFF
v MQC.MQTC_ON
getTriggerData
public String getTriggerData()

Throws MQException.

The free-format data that the queue manager inserts into the trigger
message when a message arriving on this queue causes a trigger message
to be written to the initiation queue.
setTriggerData
public void setTriggerData(String data)

Throws MQException.

Sets the free-format data that the queue manager inserts into the trigger
message when a message arriving on this queue causes a trigger message
to be written to the initiation queue. The maximum permissible length of
the string is given by MQC.MQ_TRIGGER_DATA_LENGTH.
getTriggerDepth
public int getTriggerDepth()

Throws MQException.

The number of messages that have to be on the queue before a trigger

message is written when trigger type is set to MQC.MQTT_DEPTH.
setTriggerDepth
public void setTriggerDepth(int depth)

Throws MQException.

Sets the number of messages that have to be on the queue before a trigger
message is written when trigger type is set to MQC.MQTT_DEPTH.

138 MQSeries Using Java

 MQQueue
getTriggerMessagePriority
public int getTriggerMessagePriority()

Throws MQException.

This is the message priority below which messages do not contribute to the
generation of trigger messages (that is, the queue manager ignores these
messages when deciding whether a trigger should be generated). A value
of zero causes all messages to contribute to the generation of trigger
messages.
setTriggerMessagePriority
public void setTriggerMessagePriority(int priority)

Throws MQException.

Sets the message priority below which messages do not contribute to the
generation of trigger messages (that is, the queue manager ignores these
messages when deciding whether a trigger should be generated). A value
of zero causes all messages to contribute to the generation of trigger
messages.
getTriggerType
public int getTriggerType()

Throws MQException.

The conditions under which trigger messages are written as a result of

messages arriving on this queue.
Returns
The possible values are:
v MQC.MQTT_NONE
v MQC.MQTT_FIRST
v MQC.MQTT_EVERY
v MQC.MQTT_DEPTH
setTriggerType
public void setTriggerType(int type)

Throws MQException.

Sets the conditions under which trigger messages are written as a result of
messages arriving on this queue. The possible values are:
v MQC.MQTT_NONE
v MQC.MQTT_FIRST
v MQC.MQTT_EVERY
v MQC.MQTT_DEPTH
close
public synchronized void close()

Throws MQException.

Override of “MQManagedObject.close” on page 101.

Chapter 9. The MQ base Java classes and interfaces 139

MQQueueManager

MQQueueManager

java.lang.Object
│
└─ com.ibm.mq.MQManagedObject
│
└─ com.ibm.mq.MQQueueManager

public class MQQueueManager

extends MQManagedObject. (See page 99.)

Note: The behavior of some of the options available in this class depends on the
environment in which they are used. These elements are marked with a *.
See “Chapter 8. Environment-dependent behavior” on page 73 for details.

Variables
isConnected
public boolean isConnected
True if the connection to the queue manager is still open.

Constructors
MQQueueManager
public MQQueueManager(String queueManagerName)

Throws MQException.

Create a connection to the named queue manager.

Note: When using MQSeries classes for Java, the hostname, channel name
and port to use during the connection request are specified in the
MQEnvironment class. This must be done before calling this
constructor.

The following example shows a connection to a queue manager ″MYQM″,

running on a machine with hostname fred.mq.com.
MQEnvironment.hostname = "fred.mq.com"; // host to connect to
MQEnvironment.port = 1414; // port to connect to.
// If I don't set this,
// it defaults to 1414
// (the default MQSeries port)
MQEnvironment.channel = "channel.name"; // the CASE-SENSITIVE
// name of the
// SVR CONN channel on
// the queue manager
MQQueueManager qMgr = new MQQueueManager("MYQM");

If the queue manager name is left blank (null or ″″), a connection is made
to the default queue manager.

See also “MQEnvironment” on page 88.

140 MQSeries Using Java

 MQQueueManager
MQQueueManager
public MQQueueManager(String queueManagerName,
MQConnectionManager cxManager)

Throws MQException.

This constructor connects to the specified Queue Manager, using the

properties in MQEnvironment. The specified MQConnectionManager
manages the connection.
MQQueueManager
public MQQueueManager(String queueManagerName,
ConnectionManager cxManager)

Throws MQException.

This constructor connects to the specified Queue Manager, using the

properties in MQEnvironment. The specified ConnectionManager manages
the connection.

This method requires a JVM at Java 2 v1.3 or later, with JAAS 1.0 or later
installed.
MQQueueManager
public MQQueueManager(String queueManagerName,
int options)

Throws MQException.

This version of the constructor is intended for use only in bindings mode
and it uses the extended connection API (MQCONNX) to connect to the
queue manager. The options parameter allows you to choose fast or normal
bindings. Possible values are:
v MQC.MQCNO_FASTPATH_BINDING for fast bindings *.
v MQC.MQCNO_STANDARD_BINDING for normal bindings.
MQQueueManager
public MQQueueManager(String queueManagerName,
int options,
MQConnectionManager cxManager)

Throws MQException.

This constructor performs an MQCONNX, passing the supplied options.

The specified MQConnectionManager manages the connection.
MQQueueManager
public MQQueueManager(String queueManagerName,
int options,
ConnectionManager cxManager)

Throws MQException.

This constructor performs an MQCONNX, passing the supplied options.

The specified ConnectionManager manages the connection.

This method requires a JVM at Java 2 v1.3 or later, with JAAS 1.0 or later
installed.

Chapter 9. The MQ base Java classes and interfaces 141

MQQueueManager
MQQueueManager
public MQQueueManager(String queueManagerName,
java.util.Hashtable properties)

The properties parameter takes a series of key/value pairs that describe

the MQSeries environment for this particular queue manager. These
properties, where specified, override the values set by the MQEnvironment
class, and allow the individual properties to be set on a queue manager by
queue manager basis. See “″MQEnvironment.properties″” on page 89.
MQQueueManager
public MQQueueManager(String queueManagerName,
Hashtable properties,
MQConnectionManager cxManager)

Throws MQException.

This constructor connects to the named Queue Manager, using the

supplied Hashtable of properties to override those in MQEnvironment. The
specified MQConnectionManager manages the connection.
MQQueueManager
public MQQueueManager(String queueManagerName,
Hashtable properties,
ConnectionManager cxManager)

Throws MQException.

This constructor connects to the named Queue Manager, using the

supplied Hashtable of properties to override those in MQEnvironment. The
specified ConnectionManager manages the connection.

This method requires a JVM at Java 2 v1.3 or later, with JAAS 1.0 or later
installed.

Methods
getCharacterSet
public int getCharacterSet()

Throws MQException.

Returns the CCSID (Coded Character Set Identifier) of the queue

manager’s codeset. This defines the character set used by the queue
manager for all character string fields in the application programming
interface.

Throws MQException if you call this method after disconnecting from the
queue manager.
getMaximumMessageLength
public int getMaximumMessageLength()

Throws MQException.

Returns the maximum length of a message (in bytes) that can be handled
by the queue manager. No queue can be defined with a maximum message
length greater than this.

142 MQSeries Using Java

 MQQueueManager
Throws MQException if you call this method after disconnecting from the
queue manager.
getCommandLevel
public int getCommandLevel()

Throws MQException.

Indicates the level of system control commands supported by the queue

manager. The set of system control commands that correspond to a
particular command level varies according to the architecture of the
platform on which the queue manager is running. See the MQSeries
documentation for your platform for further details.

Throws MQException if you call this method after disconnecting from the
queue manager.
Returns
One of the MQC.MQCMDL_LEVEL_xxx constants
getCommandInputQueueName
public String getCommandInputQueueName()

Throws MQException.

Returns the name of the command input queue defined on the queue
manager. This is a queue to which applications can send commands, if
authorized to do so.

Throws MQException if you call this method after disconnecting from the
queue manager.
getMaximumPriority
public int getMaximumPriority()

Throws MQException.

Returns the maximum message priority supported by the queue manager.

Priorities range from zero (lowest) to this value.

Throws MQException if you call this method after disconnecting from the
queue manager.
getSyncpointAvailability
public int getSyncpointAvailability()

Throws MQException.

Indicates whether the queue manager supports units of work and

syncpointing with the MQQueue.get and MQQueue.put methods.

Returns
v MQC.MQSP_AVAILABLE if syncpointing is available.
v MQC.MQSP_NOT_AVAILABLE if syncpointing is not available.

Throws MQException if you call this method after disconnecting from the
queue manager.

Chapter 9. The MQ base Java classes and interfaces 143

MQQueueManager
getDistributionListCapable
public boolean getDistributionListCapable()

Indicates whether the queue manager supports distribution lists.

disconnect
public synchronized void disconnect()

Throws MQException.

Terminates the connection to the queue manager. All open queues and
processes accessed by this queue manager are closed, and hence become
unusable. When you have disconnected from a queue manager the only
way to reconnect is to create a new MQQueueManager object.

Normally, any work performed as part of a unit of work is committed.

However, if this connection is managed by a ConnectionManager, rather
than an MQConnectionManager, the unit of work might be rolled back.
commit
public synchronized void commit()

Throws MQException.

Calling this method indicates to the queue manager that the application
has reached a syncpoint, and that all of the message gets and puts that
have occurred since the last syncpoint are to be made permanent.
Messages put as part of a unit of work (with the
MQC.MQPMO_SYNCPOINT flag set in the options field of
MQPutMessageOptions) are made available to other applications. Messages
retrieved as part of a unit of work (with the MQC.MQGMO_SYNCPOINT
flag set in the options field of MQGetMessageOptions) are deleted.

See also the description of ″backout″ that follows.

backout
public synchronized void backout()

Throws MQException.

Calling this method indicates to the queue manager that all the message
gets and puts that have occurred since the last syncpoint are to be backed
out. Messages put as part of a unit of work (with the
MQC.MQPMO_SYNCPOINT flag set in the options field of
MQPutMessageOptions) are deleted; messages retrieved as part of a unit of
work (with the MQC.MQGMO_SYNCPOINT flag set in the options field of
MQGetMessageOptions) are reinstated on the queue.

See also the description of ″commit″ above.

144 MQSeries Using Java

 MQQueueManager
accessQueue
public synchronized MQQueue accessQueue
(
String queueName, int openOptions,
String queueManagerName,
String dynamicQueueName,
String alternateUserId
)

Throws MQException.

Establishes access to an MQSeries queue on this queue manager to get or

browse messages, put messages, inquire about the attributes of the queue
or set the attributes of the queue.

If the queue named is a model queue, then a dynamic local queue is

created. The name of the created queue can be determined by inspecting
the name attribute of the returned MQQueue object.

Parameters
queueName
Name of queue to open.
openOptions
Options that control the opening of the queue. Valid options are:
MQC.MQOO_BROWSE
Open to browse message.
MQC.MQOO_INPUT_AS_Q_DEF
Open to get messages using queue-defined default.
MQC.MQOO_INPUT_SHARED
Open to get messages with shared access.
MQC.MQOO_INPUT_EXCLUSIVE
Open to get messages with exclusive access.
MQC.MQOO_OUTPUT
Open to put messages.
MQC.MQOO_INQUIRE
Open for inquiry - required if you wish to query
properties.
MQC.MQOO_SET
Open to set attributes.
MQC.MQOO_SAVE_ALL_CONTEXT
Save context when message retrieved*.
MQC.MQOO_SET_IDENTITY_CONTEXT
Allows identity context to be set.
MQC.MQOO_SET_ALL_CONTEXT
Allows all context to be set.
MQC.MQOO_ALTERNATE_USER_AUTHORITY
Validate with the specified user identifier.
MQC.MQOO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing.

Chapter 9. The MQ base Java classes and interfaces 145

MQQueueManager
MQC.MQOO_BIND_AS_QDEF
Use default binding for queue.
MQC.MQOO_BIND_ON_OPEN
Bind handle to destination when queue is opened.
MQC.MQOO_BIND_NOT_FIXED
Do not bind to a specific destination.
MQC.MQOO_PASS_ALL_CONTEXT
Allow all context to be passed.
MQC.MQOO_PASS_IDENTITY_CONTEXT
Allow identity context to be passed.

If more than one option is required, the values can be added

together or combined using the bitwise OR operator. See the
MQSeries MQSeries Application Programming Reference for a fuller
description of these options.
queueManagerName
Name of the queue manager on which the queue is defined. A
name which is entirely blank, or which is null, denotes the queue
manager to which this MQQueueManager object is connected.
dynamicQueueName
This parameter is ignored unless queueName specifies the name of
a model queue. If it does, this parameter specifies the name of the
dynamic queue to be created. A blank or null name is not valid if
queueName specifies the name of a model queue. If the last
non-blank character in the name is an asterisk (*), the queue
manager replaces the asterisk with a string of characters that
guarantees that the name generated for the queue is unique on this
queue manager.
alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the
openOptions parameter, this parameter specifies the alternate user
identifier that is used to check the authorization for the open. If
MQOO_ALTERNATE_USER_AUTHORITY is not specified, this
parameter can be left blank (or null).
Returns
MQQueue that has been successfully opened.

Throws MQException if the open fails.

See also “″accessProcess″” on page 147.

146 MQSeries Using Java

 MQQueueManager
accessQueue
public synchronized MQQueue accessQueue
(
String queueName,
int openOptions
)

Throws MQException if you call this method after disconnecting from the
queue manager.

Parameters
queueName
Name of queue to open
openOptions
Options that control the opening of the queue

See “MQQueueManager.accessQueue” on page 145 for details of the

parameters.

queueManagerName, dynamicQueueName, and alternateUserId are set to ″″.

accessProcess
public synchronized MQProcess accessProcess
(
String processName,
int openOptions,
String queueManagerName,
String alternateUserId
)

Throws MQException.

Establishes access to an MQSeries process on this queue manager to

inquire about the process attributes.

Parameters
processName
Name of process to open.
openOptions
Options that control the opening of the process. Inquire is
automatically added to the options specified, so there is no need to
specify it explicitly.
Valid options are:
MQC.MQOO_ALTERNATE_USER_AUTHORITY
Validate with the specified user id
MQC.MQOO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing

If more than one option is required, the values can be added

together or combined using the bitwise OR operator. See the
MQSeries Application Programming Reference for a fuller description
of these options.

Chapter 9. The MQ base Java classes and interfaces 147

MQQueueManager
queueManagerName
Name of the queue manager on which the process is defined.
Applications should leave this parameter blank or null.
alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the
openOptions parameter, this parameter specifies the alternate user
identifier that is used to check the authorization for the open. If
MQOO_ALTERNATE_USER_AUTHORITY is not specified, this
parameter can be left blank (or null).
Returns
MQProcess that has been successfully opened.

Throws MQException if the open fails.

See also “MQQueueManager.accessQueue” on page 145.

accessProcess
This is a simplified version of the AccessProcess method previously
described.
public synchronized MQProcess accessProcess
(
String processName,
int openOptions
)

This is a simplified version of the AccessQueue method previously

described.

Parameters
processName
The name of the process to open.
openOptions
Options that control the opening of the process.

See “″accessProcess″” on page 147 for details of the options.

queueManagerName and alternateUserId are set to ″″.

accessDistributionList
public synchronized MQDistributionList accessDistributionList
(
MQDistributionListItem[] litems, int openOptions,
String alternateUserId
)

Throws MQException.

Parameters
litems The items to be included in the distribution list.
openOptions
Options that control the opening of the distribution list.

148 MQSeries Using Java

 MQQueueManager
alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the
openOptions parameter, this parameter specifies the alternate user
identifier that is used to check the authorization for the open. If
MQOO_ALTERNATE_USER_AUTHORITY is not specified, this
parameter can be left blank (or null).
Returns
A newly created MQDistributionList which is open and ready for
put operations.

Throws MQException if the open fails.

See also “MQQueueManager.accessQueue” on page 145.

accessDistributionList
This is a simplified version of the AccessDistributionList method
previously described.
public synchronized MQDistributionList accessDistributionList
(
MQDistributionListItem[] litems,
int openOptions,
)

Parameters
litems The items to be included in the distribution list.
openOptions
Options that control the opening of the distribution list.

See “accessDistributionList” on page 148 for details of the parameters.

alternateUserId is set to ″″.

begin* (bindings connection only)
public synchronized void begin()
Throws MQException.
This method is supported only by the MQSeries classes for Java in
bindings mode and it signals to the queue manager that a new unit of
work is starting.
Do not use this method for applications that use local one-phase
transactions.
isConnected
public boolean isConnected()

Returns the value of the isConnected variable.

Chapter 9. The MQ base Java classes and interfaces 149

MQSimpleConnectionManager

MQSimpleConnectionManager

java.lang.Object com.ibm.mq.MQConnectionManager
│ │
└─ com.ibm.mq.MQSimpleConnectionManager

public class MQSimpleConnectionManager

implements MQConnectionManager (See page 154.)

An MQSimpleConnectionManager provides basic connection pooling functionality.

You can use an MQSimpleConnectionManager either as the default Connection
Manager, or as a parameter to an MQQueueManager constructor. When an
MQQueueManager is constructed, the most-recently-used connection in the pool is
used.

Connections are destroyed (by a separate thread) when they are unused for a
specified period, or when there are more than a specified number of unused
connections in the pool. You can specify the timeout period and the maximum
number of unused connections.

Variables
MODE_AUTO
public static final int MODE_AUTO. See “setActive”.
MODE_ACTIVE
public static final int MODE_ACTIVE. See “setActive”.
MODE_INACTIVE
public static final int MODE_INACTIVE. See “setActive”.

Constructors
MQSimpleConnectionManager
public MQSimpleConnectionManager()
Constructs an MQSimpleConnectionManager.

Methods
setActive
public void setActive(int mode)
Sets the active mode of the connection pool.
Parameters
mode The required active mode of the connection pool. Valid values are:
MODE_AUTO
The connection pool is active while the Connection
Manager is the default Connection Manager and there is at
least one token in the set of MQPoolTokens held by
MQEnvironment. This is the default mode.
MODE_ACTIVE
The connection pool is always active. When
MQQueueManager.disconnect() is called, the underlying
connection is pooled, and potentially reused the next time
that an MQQueueManager object is constructed.

150 MQSeries Using Java

 MQSimpleConnectionManager
Connections will be destroyed by a separate thread if they
are unused for longer than the Timeout period, or if the
size of the pool exceeds HighThreshold.
MODE_INACTIVE
The connection pool is always inactive. When this mode is
entered, the pool of connections to MQSeries is cleared.
When MQQueueManager.disconnect() is called, the
connection that underlies any active MQQueueManager
object is destroyed.
getActive
public int getActive()
Gets the mode of the connection pool.
Returns
The current active mode of the connection pool, with one of the following
values (see “setActive” on page 150):
MODE_AUTO
MODE_ACTIVE
MODE_INACTIVE
setTimeout
public void setTimeout(long timeout)
Sets the Timeout value, where connections that remain unused for this
length of time are destroyed by a separate thread.
Parameters
timeout
The value of the timeout in milliseconds.
getTimeout
public long getTimeout()
Returns the Timeout value.
setHighThreshold
public void setHighThreshold(int threshold)
Sets the HighThreshold. If the number of unused connections in the pool
exceeds this value, the oldest unused connection in the pool is destroyed.
Parameters
threshold
The maximum number of unused connections in the pool.
getHighThreshold
public int getHighThreshold ()
Returns the HighThreshold value.

Chapter 9. The MQ base Java classes and interfaces 151

MQC

MQC
public interface MQC
extends Object

The MQC interface defines all the constants used by the MQ Java programming
interface (except for completion code constants and error code constants). To refer
to one of these constants from within your programs, prefix the constant name
with ″MQC.″. For example, you can set the close options for a queue as follows:
MQQueue queue;
...
queue.closeOptions = MQC.MQCO_DELETE; // delete the
// queue when
// it is closed
...

A full description of these constants is in the MQSeries Application Programming

Reference.

Completion code and error code constants are defined in the MQException class.
See “MQException” on page 93.

152 MQSeries Using Java

 MQPoolServicesEventListener

MQPoolServicesEventListener
public interface MQPoolServicesEventListener
extends Object

Note: Normally, applications do not use this interface.

MQPoolServicesEventListener is for implementation by providers of default

ConnectionManagers. When an MQPoolServicesEventListener is registered with an
MQPoolServices object, the event listener receives an event whenever an
MQPoolToken is added to, or removed from, the set of MQPoolTokens that
MQEnvironment manages. It also receives an event whenever the default
ConnectionManager changes.

See also “MQPoolServices” on page 123 and “MQPoolServicesEvent” on page 124.

Methods
tokenAdded
public void tokenAdded(MQPoolServicesEvent event)

Called when an MQPoolToken is added to the set.

tokenRemoved
public void tokenRemoved(MQPoolServicesEvent event)

Called when an MQPoolToken is removed from the set.

defaultConnectionManagerChanged
public void defaultConnectionManagerChanged(MQPoolServicesEvent event)

Called when the default ConnectionManager is set. The set of

MQPoolTokens will have been cleared.

Chapter 9. The MQ base Java classes and interfaces 153

MQConnectionManager

MQConnectionManager
This is a private interface that cannot be implemented by applications. MQSeries
classes for Java supplies an implementation of this interface
(MQSimpleConnectionManager), which you can specify on the MQQueueManager
constructor, or through MQEnvironment.setDefaultConnectionManager.

See “MQSimpleConnectionManager” on page 150.

Applications or middleware that wish to provide their own ConnectionManager

should implement javax.resource.spi.ConnectionManager. This requires Java 2 v1.3
with JAAS 1.0 installed.

154 MQSeries Using Java

 MQReceiveExit

MQReceiveExit
public interface MQReceiveExit
extends Object

The receive exit interface allows you to examine and possibly alter the data
received from the queue manager by the MQSeries classes for Java.

Note: This interface does not apply when connecting directly to MQSeries in
bindings mode.

To provide your own receive exit, define a class that implements this interface.
Create a new instance of your class and assign the MQEnvironment.receiveExit
variable to it before constructing your MQQueueManager object. For example:

// in MyReceiveExit.java
class MyReceiveExit implements MQReceiveExit {
// you must provide an implementation
// of the receiveExit method
public byte[] receiveExit(
MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte[] agentBuffer)
{
// your exit code goes here...
}
}
// in your main program...
MQEnvironment.receiveExit = new MyReceiveExit();
... // other initialization
MQQueueManager qMgr = new MQQueueManager("");

Methods
receiveExit
public abstract byte[] receiveExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte agentBuffer[])

The receive exit method that your class must provide. This method will be
invoked whenever the MQSeries classes for Java receives some data from
the queue manager.

Parameters
channelExitParms
Contains information regarding the context in which the exit is
being invoked. The exitResponse member variable is an output
parameter that you use to tell the MQSeries classes for Java what
action to take next. See “MQChannelExit” on page 82 for further
details.
channelDefinition
Contains details of the channel through which all communications
with the queue manager take place.
agentBuffer
If the channelExitParms.exitReason is
MQChannelExit.MQXR_XMIT, agentBuffer contains the data
received from the queue manager; otherwise agentBuffer is null.

Chapter 9. The MQ base Java classes and interfaces 155

MQReceiveExit
Returns

If the exit response code (in channelExitParms) is set so that the MQSeries
classes for Java can now process the data (MQXCC_OK), your receive exit
method must return the data to be processed. The simplest receive exit,
therefore, consists of the single line ″return agentBuffer;″.

See also:
v “MQC” on page 152
v “MQChannelDefinition” on page 80

156 MQSeries Using Java

 MQSecurityExit

MQSecurityExit
public interface MQSecurityExit
extends Object

The security exit interface allows you to customize the security flows that occur
when an attempt is made to connect to a queue manager.

Note: This interface does not apply when connecting directly to MQSeries in
bindings mode.

To provide your own security exit, define a class that implements this interface.
Create a new instance of your class and assign the MQEnvironment.securityExit
variable to it before constructing your MQQueueManager object. For example:

// in MySecurityExit.java
class MySecurityExit implements MQSecurityExit {
// you must provide an implementation
// of the securityExit method
public byte[] securityExit(
MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte[] agentBuffer)
{
// your exit code goes here...
}
}
// in your main program...
MQEnvironment.securityExit = new MySecurityExit();
... // other initialization
MQQueueManager qMgr = new MQQueueManager("");

Methods
securityExit
public abstract byte[] securityExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte agentBuffer[])

The security exit method that your class must provide.

Parameters
channelExitParms
Contains information regarding the context in which the exit is
being invoked. The exitResponse member variable is an output
parameter that you use to tell the MQSeries Client for Java what
action to take next. See the “MQChannelExit” on page 82 for
further details.
channelDefinition
Contains details of the channel through which all communications
with the queue manager take place.
agentBuffer
If the channelExitParms.exitReason is
MQChannelExit.MQXR_SEC_MSG, agentBuffer contains the
security message received from the queue manager; otherwise
agentBuffer is null.

Chapter 9. The MQ base Java classes and interfaces 157

MQSecurityExit
Returns

If the exit response code (in channelExitParms) is set so that a message is

to be transmitted to the queue manager, your security exit method must
return the data to be transmitted.

See also:
v “MQC” on page 152
v “MQChannelDefinition” on page 80

158 MQSeries Using Java

 MQSendExit

MQSendExit
public interface MQSendExit
extends Object

The send exit interface allows you to examine and possibly alter the data sent to
the queue manager by the MQSeries Client for Java.

Note: This interface does not apply when connecting directly to MQSeries in
bindings mode.

To provide your own send exit, define a class that implements this interface. Create
a new instance of your class and assign the MQEnvironment.sendExit variable to it
before constructing your MQQueueManager object. For example:

// in MySendExit.java
class MySendExit implements MQSendExit {
// you must provide an implementation of the sendExit method
public byte[] sendExit(
MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte[] agentBuffer)
{
// your exit code goes here...
}
}
// in your main program...
MQEnvironment.sendExit = new MySendExit();
... // other initialization
MQQueueManager qMgr = new MQQueueManager("");

Methods
sendExit
public abstract byte[] sendExit(MQChannelExit channelExitParms,
MQChannelDefinition channelDefinition,
byte agentBuffer[])

The send exit method that your class must provide. This method is
invoked whenever the MQSeries classes for Java wishes to transmit some
data to the queue manager.

Parameters
channelExitParms
Contains information regarding the context in which the exit is
being invoked. The exitResponse member variable is an output
parameter that you use to tell the MQSeries classes for Java what
action to take next. See “MQChannelExit” on page 82 for further
details.
channelDefinition
Contains details of the channel through which all communications
with the queue manager take place.
agentBuffer
If the channelExitParms.exitReason is
MQChannelExit.MQXR_XMIT, agentBuffer contains the data to be
transmitted to the queue manager; otherwise agentBuffer is null.

Chapter 9. The MQ base Java classes and interfaces 159

MQSendExit
Returns

If the exit response code (in channelExitParms) is set so that a message is

to be transmitted to the queue manager (MQXCC_OK), your send exit
method must return the data to be transmitted. The simplest send exit,
therefore, consists of the single line ″return agentBuffer;″.

See also:
v “MQC” on page 152
v “MQChannelDefinition” on page 80

160 MQSeries Using Java

 ManagedConnection

ManagedConnection
public interface javax.resource.spi.ManagedConnection

Note: Normally, applications do not use this class; it is intended for use by
implementations of ConnectionManager.

MQSeries classes for Java provides an implementation of ManagedConnection that

is returned from ManagedConnectionFactory.createManagedConnection. This object
represents a connection to an MQSeries Queue Manager.

Methods
getConnection
public Object getConnection(javax.security.auth.Subject subject,
ConnectionRequestInfo cxRequestInfo)

Throws ResourceException.

Creates a new connection handle for the physical connection represented

by the ManagedConnection object. For MQSeries classes for Java, this
returns an MQQueueManager object. The ConnectionManager normally
returns this object from allocateConnection.

The subject parameter is ignored. If the cxRequestInfo parameter is not

suitable, a ResourceException is thrown. Multiple connection handles can
be used simultaneously for each single ManagedConnection.
destroy
public void destroy()

Throws ResourceException.

Destroys the physical connection to the MQSeries Queue Manager. Any

pending local transaction is committed. For more details, see
“getLocalTransaction” on page 162.
cleanup
public void cleanup()

Throws ResourceException.

Closes all open connection handles, and resets the physical connection to
an initial state ready to be pooled. Any pending local transaction is rolled
back. For more details, see “getLocalTransaction” on page 162.
associateConnection
public void associateConnection(Object connection)

Throws ResourceException.

MQSeries classes for Java does not currently support this method. A
javax.resource.NotSupportedException is thrown.

Chapter 9. The MQ base Java classes and interfaces 161

 ManagedConnection
addConnectionEventListener
public void addConnectionEventListener(ConnectionEventListener listener)

Adds a ConnectionEventListener to the ManagedConnection instance.

The listener is notified if a severe error occurs on the ManagedConnection,

or when MQQueueManager.disconnect() is called on a connection handle
that is associated with this ManagedConnection. The listener is not notified
about local transaction events (see “getLocalTransaction”).
removeConnectionEventListener
public void removeConnectionEventListener(ConnectionEventListener listener)

Removes a registered ConnectionEventListener.

getXAResource
public javax.transaction.xa.XAResource getXAResource()

Throws ResourceException.

MQSeries classes for Java does not currently support this method. A
javax.resource.NotSupportedException is thrown.
getLocalTransaction
public LocalTransaction getLocalTransaction()

| Throws ResourceException.

MQSeries classes for Java does not currently support this method. A
javax.resource.NotSupportedException is thrown.

Currently, a ConnectionManager cannot manage the MQSeries local

transaction, and registered ConnectionEventListeners are not informed
about events relating to the local transaction. When cleanup() occurs, any
ongoing unit of work is rolled back. When destroy() occurs, any ongoing
unit of work is committed.

Existing API behavior is that an ongoing unit of work is committed at

MQQueueManager.disconnect(). This existing behavior is preserved only
when an MQConnectionManager (rather than a ConnectionManager)
manages the connection.
getMetaData
public ManagedConnectionMetaData getMetaData()

Throws ResourceException.

Gets the meta data information for the underlying Queue Manager. See
“ManagedConnectionMetaData” on page 166.

162 MQSeries Using Java

 ManagedConnection
setLogWriter
public void setLogWriter(java.io.PrintWriter out)

Throws ResourceException.

Sets the log writer for this ManagedConnection. When a

ManagedConnection is created, it inherits the log writer from its
ManagedConnectionFactory.

MQSeries classes for Java does not currently use the log writer. See
“MQException.log” on page 93 for more information about logging.
getLogWriter
public java.io.PrintWriter getLogWriter()

Throws ResourceException.

Returns the log writer for this ManagedConnection.

MQSeries classes for Java does not currently use the log writer. See
“MQException.log” on page 93 for more information about logging.

Chapter 9. The MQ base Java classes and interfaces 163

ManagedConnectionFactory

ManagedConnectionFactory
public interface javax.resource.spi.ManagedConnectionFactory

Note: Normally, applications do not use this class.

MQSeries classes for Java provides an implementation of this interface to

ConnectionManagers. A ManagedConnectionFactory is used to construct
ManagedConnections, and to select suitable ManagedConnections from a set of
candidates. For more details about this interface, see the J2EE Connector
Architecture specification (refer to Sun’s Web site at http://java.sun.com).

Methods
createConnectionFactory
public Object createConnectionFactory()

Throws ResourceException.

MQSeries classes for Java does not currently support the

createConnectionFactory methods. This method throws a
javax.resource.NotSupportedException.
createConnectionFactory
public Object createConnectionFactory(ConnectionManager cxManager)

Throws ResourceException.

MQSeries classes for Java does not currently support the

createConnectionFactory methods. This method throws a
javax.resource.NotSupportedException.
createManagedConnection
public ManagedConnection createManagedConnection
(javax.security.auth.Subject subject,
ConnectionRequestInfo cxRequestInfo)

Throws ResourceException.

Creates a new physical connection to an MQSeries Queue Manager, and

returns a ManagedConnection object that represents this connection.
MQSeries ignores the subject parameter.
matchManagedConnection
public ManagedConnection matchManagedConnection
(java.util.Set connectionSet,
javax.security.auth.Subject subject,
ConnectionRequestInfo cxRequestInfo)

Throws ResourceException.

Searches the supplied set of candidate ManagedConnections for an

appropriate ManagedConnection. Returns either null, or a suitable
ManagedConnection from the set that meets the criteria for connection.

164 MQSeries Using Java

 ManagedConnectionFactory
setLogWriter
public void setLogWriter(java.io.PrintWriter out)

Throws ResourceException.

Sets the log writer for this ManagedConnectionFactory. When a

ManagedConnection is created, it inherits the log writer from its
ManagedConnectionFactory.

MQSeries classes for Java does not currently use the log writer. See
“MQException.log” on page 93 for more information about logging.
getLogWriter
public java.io.PrintWriter getLogWriter()

Throws ResourceException.

Returns the log writer for this ManagedConnectionFactory.

MQSeries classes for Java does not currently use the log writer. See
“MQException.log” on page 93 for more information about logging.
hashCode
public int hashCode()

Returns the hashCode for this ManagedConnectionFactory.

equals
public boolean equals(Object other)

Checks whether this ManagedConnectionFactory is equal to another

ManagedConnectionFactory. Returns true if both
ManagedConnectionFactories describe the same target Queue Manager.

Chapter 9. The MQ base Java classes and interfaces 165

ManagedConnectionMetaData

ManagedConnectionMetaData
public interface javax.resource.spi.ManagedConnectionMetaData

Note: Normally, applications do not use this class; it is intended for use by
implementations of ConnectionManager.

A ConnectionManager can use this class to retrieve meta data that is related to an
underlying physical connection to a Queue Manager. An implementation of this
class is returned from ManagedConnection.getMetaData().

Methods
getEISProductName
public String getEISProductName()

Throws ResourceException.

Returns “IBM MQSeries”.

getProductVersion
public String getProductVersion()

Throws ResourceException.

Returns a string that describes the command level of the MQSeries Queue
Manager to which the ManagedConnection is connected.
getMaxConnections
public int getMaxConnections()

Throws ResourceException.

Returns 0.
getUserName
public String getUserName()

Throws ResourceException.

If the ManagedConnection represents a Client connection to a Queue

Manager, this returns the user ID used for the connection. Otherwise, it
returns an empty string.

166 MQSeries Using Java

Part 3. Programming with MQ JMS
Chapter 10. Writing MQ JMS programs . . . . 169 Mapping JMS header fields at
The JMS model . . . . . . . . . . . . . 169 send()/publish() . . . . . . . . . . 201
Building a connection . . . . . . . . . . 170 Mapping JMS property fields . . . . . . 203
Retrieving the factory from JNDI . . . . . . 170 Mapping JMS provider-specific fields . . . 203
Using the factory to create a connection . . . 171 Mapping MQSeries fields onto JMS fields
Creating factories at runtime . . . . . . . 171 (incoming messages) . . . . . . . . . . 204
Starting the connection . . . . . . . . 171 Mapping JMS to a native MQSeries application 205
Choosing client or bindings transport . . . . 172 Message body . . . . . . . . . . . . 206
Obtaining a session . . . . . . . . . . . 172
Sending a message . . . . . . . . . . . 173 Chapter 13. MQ JMS Application Server
Setting properties with the ‘set’ method . . . 174 Facilities . . . . . . . . . . . . . . 209
Message types . . . . . . . . . . . . 175 ASF classes and functions . . . . . . . . . 209
Receiving a message . . . . . . . . . . . 175 ConnectionConsumer. . . . . . . . . . 209
Message selectors . . . . . . . . . . . 176 Planning an application . . . . . . . . . 210
Asynchronous delivery . . . . . . . . . 177 General principles for point-to-point
Closing down . . . . . . . . . . . . . 177 messaging . . . . . . . . . . . . 210
Java Virtual Machine hangs at shutdown . . . 177 General principles for publish/subscribe
Handling errors . . . . . . . . . . . . 177 messaging . . . . . . . . . . . . 211
Exception listener . . . . . . . . . . . 178 Handling poison messages . . . . . . . 212
Removing messages from the queue . . . . 213
Chapter 11. Programming Publish/Subscribe Error handling . . . . . . . . . . . . 214
applications . . . . . . . . . . . . . 179 Recovering from error conditions . . . . . 214
Writing a simple Publish/Subscribe application 179 Reason and feedback codes. . . . . . . 214
Import required packages . . . . . . . . 179 Application server sample code . . . . . . . 215
Obtain or create JMS objects . . . . . . . 179 MyServerSession.java. . . . . . . . . . 217
Publish messages . . . . . . . . . . . 181 MyServerSessionPool.java . . . . . . . . 217
Receive subscriptions . . . . . . . . . . 181 MessageListenerFactory.java . . . . . . . 218
Close down unwanted resources . . . . . . 181 Examples of ASF use . . . . . . . . . . . 219
Using topics . . . . . . . . . . . . . . 181 Load1.java . . . . . . . . . . . . . 219
Topic names . . . . . . . . . . . . . 181 CountingMessageListenerFactory.java . . . . 220
Creating topics at runtime . . . . . . . . 182 ASFClient1.java. . . . . . . . . . . . 220
Subscriber options . . . . . . . . . . . . 183 Load2.java . . . . . . . . . . . . . 222
Creating non-durable subscribers . . . . . . 184 LoggingMessageListenerFactory.java. . . . . 222
Creating durable subscribers . . . . . . . 184 ASFClient2.java. . . . . . . . . . . . 222
Using message selectors . . . . . . . . . 184 TopicLoad.java . . . . . . . . . . . . 223
Suppressing local publications . . . . . . . 184 ASFClient3.java. . . . . . . . . . . . 224
Combining the subscriber options . . . . . 185 ASFClient4.java. . . . . . . . . . . . 225
Configuring the base subscriber queue . . . . 185
Default configuration . . . . . . . . . 185 Chapter 14. JMS interfaces and classes . . . 227
Configuring non-durable subscribers . . . 186 Sun Java Message Service classes and interfaces 227
Configuring durable subscribers . . . . . 186 MQSeries JMS classes . . . . . . . . . . 230
Re-creation and migration issues for durable BytesMessage . . . . . . . . . . . . . 232
subscribers . . . . . . . . . . . . 187 Methods . . . . . . . . . . . . . . 232
Solving Publish/Subscribe problems. . . . . . 187 Connection . . . . . . . . . . . . . . 240
Incomplete Publish/Subscribe close down . . . 187 Methods . . . . . . . . . . . . . . 240
Subscriber cleanup utility . . . . . . . 188 ConnectionConsumer. . . . . . . . . . . 243
Handling broker reports . . . . . . . . . 188 Methods . . . . . . . . . . . . . . 243
ConnectionFactory. . . . . . . . . . . . 244
Chapter 12. JMS messages . . . . . . . . 191 MQSeries constructor. . . . . . . . . . 244
Message selectors . . . . . . . . . . . . 191 Methods . . . . . . . . . . . . . . 244
Mapping JMS messages onto MQSeries messages 195 ConnectionMetaData . . . . . . . . . . . 248
The MQRFH2 header. . . . . . . . . . 196 MQSeries constructor. . . . . . . . . . 248
JMS fields and properties with corresponding Methods . . . . . . . . . . . . . . 248
MQMD fields . . . . . . . . . . . . 199 DeliveryMode . . . . . . . . . . . . . 250
Mapping JMS fields onto MQSeries fields Fields . . . . . . . . . . . . . . . 250
(outgoing messages) . . . . . . . . . . 200 Destination . . . . . . . . . . . . . . 251

© Copyright IBM Corp. 1997, 2001 167

 MQSeries constructors . . . . . . . . . 251 TopicRequestor . . . . . . . . . . . . . 327
Methods . . . . . . . . . . . . . . 251 Constructors. . . . . . . . . . . . . 327
ExceptionListener . . . . . . . . . . . . 253 Methods . . . . . . . . . . . . . . 327
Methods . . . . . . . . . . . . . . 253 TopicSession. . . . . . . . . . . . . . 329
MapMessage . . . . . . . . . . . . . 254 MQSeries constructor. . . . . . . . . . 329
Methods . . . . . . . . . . . . . . 254 Methods . . . . . . . . . . . . . . 329
Message . . . . . . . . . . . . . . . 262 TopicSubscriber. . . . . . . . . . . . . 333
Fields . . . . . . . . . . . . . . . 262 Methods . . . . . . . . . . . . . . 333
Methods . . . . . . . . . . . . . . 262 XAConnection . . . . . . . . . . . . . 334
MessageConsumer . . . . . . . . . . . 275 XAConnectionFactory . . . . . . . . . . 335
Methods . . . . . . . . . . . . . . 275 XAQueueConnection . . . . . . . . . . . 336
MessageListener . . . . . . . . . . . . 277 Methods . . . . . . . . . . . . . . 336
Methods . . . . . . . . . . . . . . 277 XAQueueConnectionFactory . . . . . . . . 337
MessageProducer . . . . . . . . . . . . 278 Methods . . . . . . . . . . . . . . 337
MQSeries constructors . . . . . . . . . 278 XAQueueSession . . . . . . . . . . . . 339
Methods . . . . . . . . . . . . . . 278 Methods . . . . . . . . . . . . . . 339
MQQueueEnumeration * . . . . . . . . . 282 XASession . . . . . . . . . . . . . . 340
Methods . . . . . . . . . . . . . . 282 Methods . . . . . . . . . . . . . . 340
ObjectMessage . . . . . . . . . . . . . 283 XATopicConnection . . . . . . . . . . . 342
Methods . . . . . . . . . . . . . . 283 Methods . . . . . . . . . . . . . . 342
Queue . . . . . . . . . . . . . . . . 284 XATopicConnectionFactory . . . . . . . . . 344
MQSeries constructors . . . . . . . . . 284 Methods . . . . . . . . . . . . . . 344
Methods . . . . . . . . . . . . . . 284 XATopicSession. . . . . . . . . . . . . 346
QueueBrowser . . . . . . . . . . . . . 286 Methods . . . . . . . . . . . . . . 346
Methods . . . . . . . . . . . . . . 286
QueueConnection . . . . . . . . . . . . 288
Methods . . . . . . . . . . . . . . 288
QueueConnectionFactory . . . . . . . . . 290
MQSeries constructor. . . . . . . . . . 290
Methods . . . . . . . . . . . . . . 290
QueueReceiver . . . . . . . . . . . . . 292
Methods . . . . . . . . . . . . . . 292
QueueRequestor . . . . . . . . . . . . 293
Constructors. . . . . . . . . . . . . 293
Methods . . . . . . . . . . . . . . 293
QueueSender . . . . . . . . . . . . . 295
Methods . . . . . . . . . . . . . . 295
QueueSession . . . . . . . . . . . . . 298
Methods . . . . . . . . . . . . . . 298
Session . . . . . . . . . . . . . . . 301
Fields . . . . . . . . . . . . . . . 301
Methods . . . . . . . . . . . . . . 301
StreamMessage . . . . . . . . . . . . . 306
Methods . . . . . . . . . . . . . . 306
TemporaryQueue . . . . . . . . . . . . 314
Methods . . . . . . . . . . . . . . 314
TemporaryTopic . . . . . . . . . . . . 315
MQSeries constructor. . . . . . . . . . 315
Methods . . . . . . . . . . . . . . 315
TextMessage . . . . . . . . . . . . . . 316
Methods . . . . . . . . . . . . . . 316
Topic . . . . . . . . . . . . . . . . 317
MQSeries constructor. . . . . . . . . . 317
Methods . . . . . . . . . . . . . . 317
TopicConnection . . . . . . . . . . . . 319
Methods . . . . . . . . . . . . . . 319
TopicConnectionFactory . . . . . . . . . . 321
MQSeries constructor. . . . . . . . . . 321
Methods . . . . . . . . . . . . . . 321
TopicPublisher . . . . . . . . . . . . . 324
Methods . . . . . . . . . . . . . . 324

168 MQSeries Using Java

Chapter 10. Writing MQ JMS programs
This chapter provides information to assist with writing MQ JMS applications. It
provides a brief introduction to the JMS model, and detailed information on
programming some common tasks that application programs are likely to need to
perform.

The JMS model

JMS defines a generic view of a message passing service. It is important to
understand this view, and how it maps onto the underlying MQSeries transport.

The generic JMS model is based around the following interfaces that are defined in
Sun’s javax.jms package:
Connection
Provides access to the underlying transport, and is used to create Sessions.
Session
Provides a context for producing and consuming messages, including the
methods used to create MessageProducers and MessageConsumers.
MessageProducer
Used to send messages.
MessageConsumer
Used to receive messages.

Note that a Connection is thread safe, but Sessions, MessageProducers, and

MessageConsumers are not. The recommended strategy is to use one Session per
application thread.

In MQSeries terms:
Connection
Provides a scope for temporary queues. Also, it provides a place to hold
the parameters that control how to connect to MQSeries. Examples of these
parameters are the name of the queue manager, and the name of the
remote host if you use the MQSeries Java client connectivity.
Session
Contains an HCONN and therefore defines a transactional scope.
MessageProducer and MessageConsumer
Contain an HOBJ that defines a particular queue for writing to, or reading
from.

Note that normal MQSeries rules apply:

v Only a single operation can be in progress per HCONN at any given time.
Therefore, the MessageProducers or MessageConsumers associated with a
Session cannot be called concurrently. This is consistent with the JMS restriction
of a single thread per Session.
v PUTs can use remote queues, but GETs can only be applied to queues on the
local queue manager.

© Copyright IBM Corp. 1997, 2001 169

JMS model
The generic JMS interfaces are subclassed into more specific versions for
’Point-to-Point’ and ’Publish/Subscribe’ behavior.

The point-to-point versions are:

v QueueConnection
v QueueSession
v QueueSender
v QueueReceiver

A key idea in JMS is that it is possible, and strongly recommended, to write

application programs that use only references to the interfaces in javax.jms. All
vendor-specific information is encapsulated in implementations of:
v QueueConnectionFactory
v TopicConnectionFactory
v Queue
v Topic

These are known as “administered objects”, that is, objects that can be built using a
vendor-supplied administration tool and can be stored in a JNDI namespace. A
JMS application can retrieve these objects from the namespace and use them
without needing to know which vendor provided the implementation.

Building a connection
Connections are not created directly, but are built using a connection factory.
Factory objects can be stored in a JNDI namespace, thus insulating the JMS
application from provider-specific information. Details of how to create and store
factory objects are in “Chapter 5. Using the MQ JMS administration tool” on
page 31.

If you do not have a JNDI namespace available, see “Creating factories at runtime”
on page 171.

Retrieving the factory from JNDI

To retrieve an object from a JNDI namespace, an initial context must be set up, as
shown in this fragment taken from the IVTRun sample file:
import javax.jms.*;
import javax.naming.*;
import javax.naming.directory.*;
.
.
.
java.util.Hashtable environment = new java.util.Hashtable();
environment.put(Context.INITIAL_CONTEXT_FACTORY, icf);
environment.put(Context.PROVIDER_URL, url);
Context ctx = new InitialDirContext( environment );

where:
icf defines a factory class for the initial context
url defines a context specific URL

For more details about JNDI usage, see Sun’s JNDI documentation.

170 MQSeries Using Java

 Building a connection
Note: Some combinations of the JNDI packages and LDAP service providers can
result in an LDAP error 84. To resolve the problem, insert the following line
before the call to InitialDirContext.
environment.put(Context.REFERRAL, "throw");

Once an initial context is obtained, objects are retrieved from the namespace by
using the lookup() method. The following code retrieves a
QueueConnectionFactory named ivtQCF from an LDAP-based namespace:
QueueConnectionFactory factory;
factory = (QueueConnectionFactory)ctx.lookup("cn=ivtQCF");

Using the factory to create a connection

The createQueueConnection() method on the factory object is used to create a
’Connection’, as shown in the following code:
QueueConnection connection;
connection = factory.createQueueConnection();

Creating factories at runtime

If a JNDI namespace is not available, it is possible to create factory objects at
runtime. However, using this method reduces the portability of the JMS application
because it requires references to MQSeries specific classes.

The following code creates a QueueConnectionFactory with all default settings:

factory = new com.ibm.mq.jms.MQQueueConnectionFactory();

(You can omit the com.ibm.mq.jms. prefix if you import the com.ibm.mq.jms
package instead.)

A connection created from the above factory uses the Java bindings to connect to
the default queue manager on the local machine. The set methods shown in
Table 14 can be used to customize the factory with MQSeries specific information.

Starting the connection

The JMS specification defines that connections should be created in the ’stopped’
state. Until the connection starts, MessageConsumers that are associated with the
connection cannot receive any messages. To start the connection, issue the
following command:
connection.start();
Table 14. Set methods on MQQueueConnectionFactory
Method Description
setCCSID(int) Used to set the MQEnvironment.CCSID property
setChannel(String) The name of the channel for a client connection
setHostName(String) The name of the host for a client connection
setPort(int) The port for a client connection
setQueueManager(String) The name of the queue manager
setTemporaryModel(String) The name of a model queue used to generate a
temporary destination as a result of a call to
QueueSession.createTemporaryQueue(). We recommend
that this is the name of a temporary dynamic queue,
rather than a permanent dynamic queue.

Chapter 10. Writing MQ JMS programs 171

Building a connection
Table 14. Set methods on MQQueueConnectionFactory (continued)
Method Description
setTransportType(int) Specify how to connect to MQSeries. The options
currently available are:
v JMSC.MQJMS_TP_BINDINGS_MQ (the default)
v JMSC.MQJMS_TP_CLIENT_MQ_TCPIP.
JMSC is in the package com.ibm.mq.jms
setReceiveExit(String) These methods exist to allow the use of the send,
setSecurityExit(String) receive and security exits provided by the underlying
setSendExit(String) MQSeries Classes for Java. The set*Exit methods take
setReceiveExitInit(String) the name of a class that implements the relevant exit
setSecutityExitInit(String) methods. (See the MQSeries 5.1 product documentation
setSendExitInit(String) for details.)

Also, the class must implement a constructor with a

single String parameter. This string provides any
initialization data that may be required by the exit, and
is set to the value provided in the corresponding
set*ExitInit method.

Choosing client or bindings transport

MQ JMS can communicate with MQSeries using either the client or bindings
transports2. If you use the Java bindings, the JMS application and the MQSeries
queue manager must be located on the same machine. If you use the client, the
queue manager can be on a different machine to the application.

The contents of the connection factory object determine which transport to use.
“Chapter 5. Using the MQ JMS administration tool” on page 31 describes how to
define a factory object for use with client or bindings transport.

The following code fragment illustrates how you can define the transport within
an application:
String HOSTNAME = "machine1";
String QMGRNAME = "machine1.QM1";
String CHANNEL = "SYSTEM.DEF.SVRCONN";

factory = new MQQueueConnectionFactory();

factory.setTransportType(JMSC.MQJMS_TP_CLIENT_MQ_TCPIP);
factory.setQueueManager(QMGRNAME);
factory.setHostName(HOSTNAME);
factory.setChannel(CHANNEL);

Obtaining a session
Once a connection is made, use the createQueueSession method on the
QueueConnection to obtain a session.

The method takes two parameters:

1. A boolean that determines whether the session is ’transacted’ or
’non-transacted’.
2. A parameter that determines the ’acknowledge’ mode.

2. However, client transport is not supported on the z/OS & OS/390 platform.

172 MQSeries Using Java

 Obtaining a session
The simplest case is that of the ’non-transacted’ session with AUTO_ACKNOWLEDGE, as
shown in the following code fragment:
QueueSession session;

boolean transacted = false;

session = connection.createQueueSession(transacted,
Session.AUTO_ACKNOWLEDGE);

Note: A connection is thread safe, but sessions (and objects that are created from
them) are not. The recommended practice for multi-threaded applications is
to use a separate session for each thread.

Sending a message
Messages are sent using a MessageProducer. For point-to-point this is a
QueueSender that is created using the createSender method on QueueSession. A
QueueSender is normally created for a specific queue, so that all messages sent
using that sender are sent to the same destination. The destination is specified
using a Queue object. Queue objects can be either created at runtime, or built and
stored in a JNDI namespace.

Queue objects are retrieved from JNDI in the following way:

Queue ioQueue;
ioQueue = (Queue)ctx.lookup( qLookup );

MQ JMS provides an implementation of Queue in com.ibm.mq.jms.MQQueue. It

contains properties that control the details of MQSeries specific behavior, but in
many cases it is possible to use the default values. JMS defines a standard way to
specify the destination that minimizes the MQSeries specific code in the
application. This mechanism uses the QueueSession.createQueue method, which
takes a string parameter describing the destination. The string itself is still in a
vendor-specific format, but this is a more flexible approach than directly
referencing the vendor classes.

MQ JMS accepts two forms for the string parameter of createQueue().

v The first is the name of the MQSeries queue, as illustrated in the following
fragment taken from the IVTRun program in the samples directory:
public static final String QUEUE = "SYSTEM.DEFAULT.LOCAL.QUEUE" ;
.
.
.
ioQueue = session.createQueue( QUEUE );
v The second, and more powerful, form is based on “uniform resource identifiers”
(URI). This form allows you to specify remote queues (queues on a queue
manager other than the one to which you are connected). It also allows you to
set the other properties contained in a com.ibm.mq.jms.MQQueue object.
The URI for a queue begins with the sequence queue://, followed by the name
of the queue manager on which the queue resides. This is followed by a further
“/”, the name of the queue, and optionally, a list of name-value pairs that set
the remaining Queue properties. For example, the URI equivalent of the
previous example is:
ioQueue = session.createQueue("queue:///SYSTEM.DEFAULT.LOCAL.QUEUE");

Note that the name of the queue manager is omitted. This is interpreted as the
queue manager to which the owning QueueConnection is connected at the time
when the Queue object is used.

Chapter 10. Writing MQ JMS programs 173

Sending a message
The following example connects to queue Q1 on queue manager HOST1.QM1, and
causes all messages to be sent as non-persistent and priority 5:
ioQueue = session.createQueue("queue://HOST1.QM1/Q1?persistence=1&priority=5");

Table 15 lists the names that can be used in the name-value part of the URI. A
disadvantage of this format is that it does not support symbolic names for the
values, so where appropriate, the table also indicates ’special’ values. Note that
these special values may be subject to change. (See “Setting properties with the
‘set’ method” for an alternative method to set properties.)
Table 15. Property names for queue URIs
Property Description Values
expiry Lifetime of the message in 0 for unlimited, positive integers
milliseconds for timeout (ms)
priority Priority of the message 0 through 9, -1=QDEF, -2=APP
persistence Whether the message should be 1=non-persistent, 2=persistent,
’hardened’ to disk -1=QDEF, -2=APP
CCSID Character set of the destination integers - valid values listed in
base MQSeries documentation
targetClient Whether the receiving application 0=JMS, 1=MQ
is JMS compliant or not
encoding How to represent numeric fields An integer value as described in
the base MQSeries documentation

QDEF - a special value that means the property should be determined by the
configuration of the MQSeries queue.
APP - a special value that means the JMS application can control this property.

Once the Queue object is obtained (either using createQueue as above or from
JNDI), it must be passed into the createSender method to create a QueueSender:
QueueSender queueSender = session.createSender(ioQueue);

The resulting queueSender object is used to send messages by using the send
method:
queueSender.send(outMessage);

Setting properties with the ‘set’ method

You can set Queue properties by first creating an instance of
com.ibm.mq.jms.MQQueue using the default constructor. Then you can fill in the
required values by using public set methods. This method means that you can use
symbolic names for the property values. However, because these values are
vendor-specific, and are embedded in the code, the applications become less
portable.

The following code fragment shows the setting of a queue property with a set
method.
com.ibm.mq.jms.MQQueue q1 = new com.ibm.mq.jms.MQQueue();
q1.setBaseQueueManagerName("HOST1.QM1");
q1.setBaseQueueName("Q1");
q1.setPersistence(DeliveryMode.NON_PERSISTENT);
q1.setPriority(5);

174 MQSeries Using Java

 Sending a message
Table 16 shows the symbolic property values that are supplied with MQ JMS for
use with the set methods.
Table 16. Symbolic values for queue properties
Property Admin tool Values
keyword
expiry UNLIM JMSC.MQJMS_EXP_UNLIMITED
APP JMSC.MQJMS_EXP_APP
priority APP JMSC.MQJMS_PRI_APP
QDEF JMSC.MQJMS_PRI_QDEF
persistence APP JMSC.MQJMS_PER_APP
QDEF JMSC.MQJMS_PER_QDEF
PERS JMSC.MQJMS_PER_PER
NON JMSC.MQJMS_PER_NON
targetClient JMS JMSC.MQJMS_CLIENT_JMS_COMPLIANT
MQ JMSC.MQJMS_CLIENT_NONJMS_MQ
encoding Integer(N) JMSC.MQJMS_ENCODING_INTEGER_NORMAL
Integer(R) JMSC.MQJMS_ENCODING_INTEGER_REVERSED
Decimal(N) JMSC.MQJMS_ENCODING_DECIMAL_NORMAL
Decimal(R) JMSC.MQJMS_ENCODING_DECIMAL_REVERSED
Float(N) JMSC.MQJMS_ENCODING_FLOAT_IEEE_NORMAL
Float(R) JMSC.MQJMS_ENCODING_FLOAT_IEEE_REVERSED
Native JMSC.MQJMS_ENCODING_NATIVE

See “The ENCODING property” on page 42 for a discussion on encoding.

Message types
JMS provides several message types, each of which embodies some knowledge of
its content. To avoid referencing the vendor-specific class names for the message
types, methods are provided on the Session object for message creation.

In the sample program, a text message is created in the following manner:

System.out.println( "Creating a TextMessage" );
TextMessage outMessage = session.createTextMessage();
System.out.println("Adding Text");
outMessage.setText(outString);

The message types that can be used are:

v BytesMessage
v MapMessage
v ObjectMessage
v StreamMessage
v TextMessage

Details of these types are in “Chapter 14. JMS interfaces and classes” on page 227.

Receiving a message
Messages are received by using a QueueReceiver. This is created from a Session by
using the createReceiver() method. This method takes a Queue parameter that
defines where the messages are received from. See “Sending a message” on
page 173 for details of how to create a Queue object.

Chapter 10. Writing MQ JMS programs 175

Receiving a message
The sample program creates a receiver and reads back the test message with the
following code:
QueueReceiver queueReceiver = session.createReceiver(ioQueue);
Message inMessage = queueReceiver.receive(1000);

The parameter in the receive call is a timeout in milliseconds. This parameter

defines how long the method should wait if there is no message available
immediately. You can omit this parameter, in which case, the call blocks
indefinitely. If you do not want any delay, use the receiveNoWait() method.

The receive methods return a message of the appropriate type. For example, if a
TextMessage is put on a queue, when the message is received, the object that is
returned is an instance of TextMessage.

To extract the content from the body of the message, it is necessary to cast from
the generic Message class (which is the declared return type of the receive
methods) to the more specific subclass, such as TextMessage. If the received
message type is not known, you can use the “instanceof” operator to determine
which type it is. It is good practice always to test the message class before casting,
so that unexpected errors can be handled gracefully.

The following code illustrates the use of “instanceof”, and extraction of the content
from a TextMessage:
if (inMessage instanceof TextMessage) {
String replyString = ((TextMessage) inMessage).getText();
.
.
.
} else {
// Print error message if Message was not a TextMessage.
System.out.println("Reply message was not a TextMessage");
}

Message selectors
JMS provides a mechanism to select a subset of the messages on a queue so that
this subset is returned by a receive call. When creating a QueueReceiver, a string
can be provided that contains an SQL (Structured Query Language) expression to
determine which messages to retrieve. The selector can refer to fields in the JMS
message header as well as fields in the message properties (these are effectively
application-defined header fields). Details of the header field names, as well as the
syntax for the SQL selector, are in “Chapter 12. JMS messages” on page 191.

The following example shows how to select for a user-defined property named
myProp:
queueReceiver = session.createReceiver(ioQueue, "myProp = 'blue'");

Note: The JMS specification does not permit the selector associated with a receiver
to be changed. Once a receiver is created, the selector is fixed for the lifetime
of that receiver. This means that if you require different selectors, you must
create new receivers.

176 MQSeries Using Java

 Receiving a message
Asynchronous delivery
An alternative to making calls to QueueReceiver.receive() is to register a method
that is called automatically when a suitable message is available. The following
fragment illustrates the mechanism:
import javax.jms.*;

public class MyClass implements MessageListener

{
// The method that will be called by JMS when a message
// is available.
public void onMessage(Message message)
{
System.out.println("message is "+message);

// application specific processing here

.
.
.
}
}

.
.
.
// In Main program (possibly of some other class)
MyClass listener = new MyClass();
queueReceiver.setMessageListener(listener);

// main program can now continue with other application specific

// behavior.

Note: Use of asynchronous delivery with a QueueReceiver marks the entire

Session as asynchronous. It is an error to make an explicit call to the receive
methods of a QueueReceiver that is associated with a Session that is using
asynchronous delivery.

Closing down
Garbage collection alone cannot release all MQSeries resources in a timely manner.
This is especially true if the application needs to create many short-lived JMS
objects at the Session level or lower. It is therefore important to call the close()
methods of the various classes (QueueConnection, QueueSession, QueueSender,
and QueueReceiver) when the resources are no longer required.

Java Virtual Machine hangs at shutdown

If an MQ JMS application finishes without calling Connection.close(), some JVMs
will appear to hang. If this problem occurs, either edit the application to include a
call to Connection.close(), or terminate the JVM by using the Ctrl-C keys.

Handling errors
Any runtime errors in a JMS application are reported by exceptions. The majority
of methods in JMS throw JMSExceptions to indicate errors. It is good programming
practice to catch these exceptions and display them on a suitable output.

Unlike normal Java Exceptions, a JMSException may contain a further exception

embedded in it. For JMS, this can be a valuable way to pass important detail from

Chapter 10. Writing MQ JMS programs 177

Handling errors
the underlying transport. In the case of MQ JMS, when MQSeries raises an
MQException, this exception is usually included as the embedded exception in a
JMSException.

The implementation of JMSException does not include the embedded exception in

the output of its toString() method. Therefore, it is necessary to check explicitly
for an embedded exception and print it out, as shown in the following fragment:
try {
.
. code which may throw a JMSException
.
} catch (JMSException je) {
System.err.println("caught "+je);
Exception e = je.getLinkedException();
if (e != null) {
System.err.println("linked exception: "+e);
}
}

Exception listener
For asynchronous message delivery, the application code cannot catch exceptions
raised by failures to receive messages. This is because the application code does
not make explicit calls to receive() methods. To cope with this situation, it is
possible to register an ExceptionListener, which is an instance of a class that
implements the onException() method. When a serious error occurs, this method
is called with the JMSException passed as its only parameter. Further details are in
Sun’s JMS documentation.

178 MQSeries Using Java

Chapter 11. Programming Publish/Subscribe applications
This section introduces the programming model that is used to write
Publish/Subscribe applications that use the MQSeries Classes for Java Message
Service.

Writing a simple Publish/Subscribe application

This section provides a ‘walkthrough’ of a simple MQ JMS application.

Import required packages

An MQSeries classes for Java Message Service application starts with a number of
import statements which should include at least the following:
import javax.jms.*; // JMS interfaces
import javax.naming.*; // Used for JNDI lookup of
import javax.naming.directory.*; // administered objects

Obtain or create JMS objects

The next step is to obtain or create a number of JMS objects:
1. Obtain a TopicConnectionFactory
2. Create a TopicConnection
3. Create a TopicSession
4. Obtain a Topic from JNDI
5. Create TopicPublishers and TopicSubscribers

Many of these processes are similar to those that are used for point-to-point, as
shown in the following:
Obtain a TopicConnectionFactory
The preferred way to do this is to use JNDI lookup, so that portability of
the application code is maintained. The following code initializes a JNDI
context:
String CTX_FACTORY = "com.sun.jndi.ldap.LdapCtxFactory";
String INIT_URL = "ldap://server.company.com/o=company_us,c=us";

Java.util.Hashtable env = new java.util.Hashtable();

env.put( Context.INITIAL_CONTEXT_FACTORY, CTX_FACTORY );
env.put( Context.PROVIDER_URL, INIT_URL );
env.put( Context.REFERRAL, "throw" );

Context ctx = null;

try {
ctx = new InitialDirContext( env );
} catch( NamingException nx ) {
// Add code to handle inability to connect to JNDI context
}

Note: The CTX_FACTORY and INIT_URL variables need customizing to suit

your installation and your JNDI service provider.

© Copyright IBM Corp. 1997, 2001 179

Writing Publish/Subscribe applications
The properties required by JNDI initialization are in a hashtable, which is
passed to the InitialDirContext constructor. If this connection fails, an
exception is thrown to indicate that the administered objects required later
in the application are not available.

Now obtain a TopicConnectionFactory by using a lookup key that the

administrator has defined:
TopicConnectionFactory factory;
factory = (TopicConnectionFactory)lookup("cn=sample.tcf");

If a JNDI namespace is not available, you can create a

TopicConnectionFactory at runtime. You create a new
com.ibm.mq.jms.MQTopicConnectionFactory in a similar way to the
method described for a QueueConnectionFactory in “Creating factories at
runtime” on page 171.
Create a TopicConnection
This is created from the TopicConnectionFactory object. Connections are
always initialized in a stop state and must be started with the following
code:
TopicConnection conn;
conn = factory.createTopicConnection();
conn.start();
Create a TopicSession
This is created by using the TopicConnection. This method takes two
parameters; one to signify whether the session is transacted, and one to
specify the acknowledgement mode:
TopicSession session = conn.createTopicSession( false,
Session.AUTO_ACKNOWLEDGE );
Obtain a Topic
This object can be obtained from JNDI, for use with TopicPublishers and
TopicSubscribers that are created later. The following code retrieves a
Topic:
Topic topic = null;
try {
topic = (Topic)ctx.lookup( "cn=sample.topic" );
} catch( NamingException nx ) {
// Add code to handle inability to retrieve Topic from JNDI
}

If a JNDI namespace is not available, you can create a Topic at runtime, as

described in “Creating topics at runtime” on page 182.
Create consumers and producers of publications
Depending on the nature of the JMS client application that you write, a
subscriber, a publisher, or both must be created. Use the createPublisher
and createSubscriber methods as follows:
// Create a publisher, publishing on the given topic
TopicPublisher pub = session.createPublisher( topic );
// Create a subscriber, subscribing on the given topic
TopicSubscriber sub = session.createSubscriber( topic );

180 MQSeries Using Java

 Writing Publish/Subscribe applications
Publish messages
The TopicPublisher object, pub, is used to publish messages, rather like a
QueueSender is used in the point-to-point domain. The following fragment creates
a TextMessage by using the session, and then publishes the message:
// Create the TextMessage and place some data into it
TextMessage outMsg = session.createTextMessage();
outMsg.setText( "This is a short test string!" );

// Use the publisher to publish the message

pub.publish( outMsg );

Receive subscriptions
Subscribers must be able to read the subscriptions that are delivered to them, as in
the following code:
// Retrieve the next waiting subscription
TextMessage inMsg = (TextMessage)sub.receive();

// Obtain the contents of the message

String payload = inMsg.getText();

This fragment of code performs a ’get-with-wait’, which means that the receive call
will block until a message is available. Alternative versions of the receive call are
available (such as ’receiveNoWait’). For details, see “TopicSubscriber” on page 333.

Close down unwanted resources

It is important to free up all the resources used by the Publish/Subscribe
application when it terminates. Use the close() method on objects that can be
closed (publishers, subscribers, sessions, and connections):
// Close publishers and subscribers
pub.close();
sub.close();

// Close sessions and connections

session.close();
conn.close();

Using topics
This section discusses the use of JMS Topic objects in MQSeries classes for Java
Message Service applications.

Topic names
This section describes the use of topic names within MQSeries classes for Java
Message Service.

Note: The JMS specification does not specify exact details about the use and
maintenance of topic hierarchies. Therefore, this area may well vary from
one provider to the next.

Topic names in MQ JMS are arranged in a tree-like hierarchy, an example of which

is shown in Figure 3 on page 182.

Chapter 11. Programming Publish/Subscribe applications 181

 Using topics

Sport

Rugby Football Tennis

Spurs Arsenal

Results Signings Results

Figure 3. MQSeries classes for Java Message Service topic name hierarchy

In a topic name, levels in the tree are separated by the “/” character. This means
| that the “Signings” node in Figure 3 is identified by the topic name:
Sport/Football/Spurs/Signings

A powerful feature of the topic system in MQSeries classes for Java Message
Service is the use of wildcards. These allow subscribers to subscribe to more than
one topic at a time. The “*” wildcard matches zero or more characters, while the
“?” wildcard matches a single character.

If a subscriber subscribes to the Topic represented by the following topic name:

Sport/Football/*/Results

it receives publications on topics including:

v Sport/Football/Spurs/Results
v Sport/Football/Arsenal/Results

If the subscription topic is:

Sport/Football/Spurs/*

it receives publications on topics including:

v Sport/Football/Spurs/Results
v Sport/Football/Spurs/Signings

There is no need to administer the topic hierarchies that you use on the broker-side
of your system explicitly. When the first publisher or subscriber on a given topic
comes into existence, the broker automatically creates the state of the topics
currently being published on, and subscribed to.

Note: A publisher cannot publish on a topic whose name contains wildcards.

Creating topics at runtime

There are four ways to create Topic objects at runtime:
1. Construct a topic by using the one-argument MQTopic constructor
2. Construct a topic by using the default MQTopic constructor, and then call the
setBaseTopicName(..) method
3. Use the session’s createTopic(..) method

182 MQSeries Using Java

 Using topics
4. Use the session’s createTemporaryTopic() method
Method 1: Using MQTopic(..)
This method requires a reference to the MQSeries implementation of the
JMS Topic interface, and therefore renders the code non-portable.
The constructor takes one argument, which should be a uniform resource
identifier (URI). For MQSeries classes for Java Message Service Topics, this
should be of the form:
topic://TopicName[?property=value[&property=value]*]

For further details on URIs and the permitted name-value pairs, see
“Sending a message” on page 173.

The following code creates a topic for non-persistent, priority 5 messages:

// Create a Topic using the one-argument MQTopic constructor
String tSpec = "Sport/Football/Spurs/Results?persistence=1&priority=5";
Topic rtTopic = new MQTopic( "topic://" + tSpec );
Method 2: Using MQTopic(), then setBaseTopicName(..)
This method uses the default MQTopic constructor, and therefore renders
the code non-portable.
After the object is created, set the baseTopicName property by using the
setBaseTopicName method, passing in the required topic name.

Note: The topic name used here is the non-URI form, and cannot include
name-value pairs. Set these by using the ’set’ methods, as described
in “Setting properties with the ‘set’ method” on page 174. The
following code uses this method to create a topic:
// Create a Topic using the default MQTopic constructor
Topic rtTopic = new MQTopic();

// Set the object properties using the setter methods

((MQTopic)rtTopic).setBaseTopicName( "Sport/Football/Spurs/Results" );
((MQTopic)rtTopic).setPersistence(1);
((MQTopic)rtTopic).setPriority(5);
Method 3: Using session.createTopic(..)
A Topic object may also be created by using the createTopic method of
TopicSession, which takes a topic URI as follows:
// Create a Topic using the session factory method
Topic rtTopic = session.createTopic( "topic://Sport/Football/Spurs/Results" );
Method 4: Using session.createTemporaryTopic()
A TemporaryTopic is a Topic that may be consumed only by subscribers
that are created by the same TopicConnection. A TemporaryTopic is created
as follows:
// Create a TemporaryTopic using the session factory method
Topic rtTopic = session.createTemporaryTopic();

Subscriber options
There are a number of different ways to use JMS subscribers. This section describes
some examples of their use.

JMS provides two types of subscribers:

Chapter 11. Programming Publish/Subscribe applications 183

Subscriber options
Non-durable subscribers
These subscribers receive messages on their chosen topic, only if the
messages are published while the subscriber is active.
Durable subscribers
These subscribers receive all the messages published on a topic, including
those that are published while the subscriber is inactive.

Creating non-durable subscribers

The subscriber created in “Create consumers and producers of publications” on
page 180 is non-durable and is created with the following code:
// Create a subscriber, subscribing on the given topic
TopicSubscriber sub = session.createSubscriber( topic );

Creating durable subscribers

Creating a durable subscriber is very similar to creating a non-durable subscriber,
but you must also provide a name that uniquely identifies the subscriber:
// Create a durable subscriber, supplying a uniquely-identifying name
TopicSubscriber sub = session.createDurableSubscriber( topic, "D_SUB_000001" );

Non-durable subscribers automatically deregister themselves when their close()

method is called (or when they fall out of scope). However, if you wish to
terminate a durable subscription, you must explicitly notify the system. To do this,
use the session’s unsubscribe() method and pass in the unique name that created
the subscriber:
// Unsubscribe the durable subscriber created above
session.unsubscribe( "D_SUB_000001" );

A durable subscriber is created at the queue manager specified in the

MQTopicConnectionFactory queue manager parameter. If there is a subsequent
attempt to create a durable subscriber with the same name at a different queue
manager, a new and completely independent durable subscriber is returned.

Using message selectors

You can use message selectors to filter out messages that do not satisfy given
criteria. For details about message selectors, see “Message selectors” on page 176.
Message selectors are associated with a subscriber as follows:
// Associate a message selector with a non-durable subscriber
String selector = "company = 'IBM'";
TopicSubscriber sub = session.createSubscriber( topic, selector, false );

Suppressing local publications

It is possible to create a subscriber that ignores publications that are published on
the subscriber’s own connection. Set the third parameter of the createSubscriber
call to true, as follows:
// Create a non-durable subscriber with the noLocal option set
TopicSubscriber sub = session.createSubscriber( topic, null, true );

184 MQSeries Using Java

 Subscriber options
Combining the subscriber options
You can combine the subscriber variations, so that you can create a durable
subscriber that applies a selector and ignores local publications, if you wish to. The
following code fragment shows the use of the combined options:
// Create a durable, noLocal subscriber with a selector applied
String selector = "company = 'IBM'";
TopicSubscriber sub = session.createDurableSubscriber( topic, "D_SUB_000001",
selector, true );

Configuring the base subscriber queue

With MQ JMS V5.2, there are two ways in which you can configure subscribers:
v Multiple queue approach
Each subscriber has an exclusive queue assigned to it, from which it retrieves all
its messages. JMS creates a new queue for each subscriber. This is the only
approach available with MQ JMS V1.1.
v Shared queue approach
A subscriber uses a shared queue, from which it, and other subscribers, retrieve
their messages. This approach requires only one queue to serve multiple
subscribers. This is the default approach used with MQ JMS V5.2.

In MQ JMS V5.2, you can choose which approach to use, and configure which
queues to use.

In general, the shared queue approach gives a modest performance advantage. For
systems with a high throughput, there are also large architectural and
administrative advantages, because of the significant reduction in the number of
queues required.

In some situations, there are still good reasons for using the multiple queue
approach:
v The theoretical physical capacity for message storage is greater.
An MQSeries queue cannot hold more than 640000 messages, and in the shared
queue approach, this must be divided between all the subscribers that share the
queue. This issue is more significant for durable subscribers, because the lifetime
of a durable subscriber is usually much longer than that of a non-durable
subscriber. Therefore, more messages might accumulate for a durable subscriber.
v External administration of subscription queues is easier.
For certain application types, administrators may wish to monitor the state and
depth of particular subscriber queues. This task is much simpler when there is
one to one mapping between a subscriber and a queue.

Default configuration
The default configuration uses the following shared subscription queues:
v SYSTEM.JMS.ND.SUBSCRIPTION.QUEUE for non-durable subscriptions
v SYSTEM.JMS.D.SUBSCRIPTION.QUEUE for durable subscriptions

These are created for you when you run the MQJMS_PSQ.MQSC script.

If required, you can specify alternative physical queues. You can also change the
configuration to use the multiple queue approach.

Chapter 11. Programming Publish/Subscribe applications 185

Subscriber options
Configuring non-durable subscribers
You can set the non-durable subscriber queue name property in either of the
following ways:
v Use the MQ JMS administration tool (for JNDI retrieved objects) to set the
BROKERSUBQ property
v Use the setBrokerSubQueue() method in your program

For non-durable subscriptions, the queue name you provide should start with the
following characters:
SYSTEM.JMS.ND.

To select a shared queue approach, specify an explicit queue name, where the
named queue is the one to use for the shared queue. The queue that you specify
must already physically exist before you create the subscription.

To select the multiple queue approach, specify a queue name that ends with the *
character. Subsequently, each subscriber that is created with this queue name
creates an appropriate dynamic queue, for exclusive use by that particular
subscriber. MQ JMS uses its own internal model queue to create such queues.
Therefore, with the multiple queue approach, all required queues are created
dynamically.

When you use the multiple queue approach, you cannot specify an explicit queue
name. However, you can specify the queue prefix. This enables you to create
different subscriber queue domains. For example, you could use:
SYSTEM.JMS.ND.MYDOMAIN.*

The characters that precede the * character are used as the prefix, so that all
dynamic queues that are associated with this subscription will have queue names
that start with SYSTEM.JMS.ND.MYDOMAIN.

Configuring durable subscribers

As discussed earlier, there may still be good reasons to use the multiple queue
approach for durable subscriptions. Durable subscriptions are likely to have a
longer life span, so it is possible that a large number of un-retrieved messages
could accumulate on the queue.

Therefore, the durable subscriber queue name property is set in the Topic object
(that is, at a more manageable level than TopicConnectionFactory). This enables
you to specify a number of different subscriber queue names, without needing to
re-create multiple objects starting from the TopicConnectionFactory.

You can set the durable subscriber queue name in either of the following ways:
v Use the MQ JMS administration tool (for JNDI retrieved objects) to set the
BROKERDURSUBQ property
v Use the setBrokerDurSubQueue() method in your program:
// Set the MQTopic durable subscriber queue name using
// the multi-queue approach
sportsTopic.setBrokerDurSubQueue("SYSTEM.JMS.D.FOOTBALL.*");

Once the Topic object is initialized, it is passed into the TopicSession

createDurableSubscriber() method to create the specified subscription:
// Create a durable subscriber using our earlier Topic
TopicSubscriber sub = new session.createDurableSubscriber
(sportsTopic, "D_SUB_SPORT_001");

186 MQSeries Using Java

 Subscriber options
For durable subscriptions, the queue name you provide should start with the
following characters:
SYSTEM.JMS.D.

To select a shared queue approach, specify an explicit queue name, where the
named queue is the one to use for the shared queue. The queue that you specify
must already physically exist before you create the subscription.

To select the multiple queue approach, specify a queue name that ends with the *
character. Subsequently, each subscriber that is created with this queue name
creates an appropriate dynamic queue, for exclusive use by that particular
subscriber. MQ JMS uses its own internal model queue to create such queues.
Therefore, with the multiple queue approach, all required queues are created
dynamically.

When you use the multiple queue approach, you cannot specify an explicit queue
name. However, you can specify the queue prefix. This enables you to create
different subscriber queue domains. For example, you could use:
SYSTEM.JMS.D.MYDOMAIN.*

The characters that precede the * character are used as the prefix, so that all
dynamic queues that are associated with this subscription will have queue names
that start with SYSTEM.JMS.D.MYDOMAIN.

Re-creation and migration issues for durable subscribers

For a durable subscriber, do not try to reconfigure the subscriber queue name until
the subscriber has been deleted. That is, perform an unsubscribe(), and then create
the queue again from new (remember that any old subscriber messages are
deleted).

However, if you created a subscriber using MQ JMS V1.1, that subscriber will be
recognized when you migrate to the current level. You do not need to delete the
subscription. The subscription continues to operate using a multiple queue
approach.

Solving Publish/Subscribe problems

This section describes some problems that can occur when you develop JMS client
applications that use the publish/subscribe domain. Note that this section
discusses problems that are specific to the publish/subscribe domain. Refer to
“Handling errors” on page 177 and “Solving problems” on page 29 for more
general troubleshooting guidance.

Incomplete Publish/Subscribe close down

It is important that JMS client applications surrender all external resources when
they terminate. To do this, call the close() method on all objects that can be closed
once they are no longer required. For the publish/subscribe domain, these objects
are:
v TopicConnection
v TopicSession
v TopicPublisher
v TopicSubscriber

The MQSeries classes for Java Message Service implementation eases this task
through the use of a “cascading close”. With this process, a call to “close” on a

Chapter 11. Programming Publish/Subscribe applications 187

Publish/Subscribe problems
TopicConnection results in calls to “close” on each of the TopicSessions it created.
This in turn results in calls to “close” on all TopicSubscribers and TopicPublishers
the sessions created.

Therefore, to ensure the proper release of external resources, it is important to call

connection.close() for each of the connections that an application creates.

There are some circumstances where this “close” procedure may not complete.
These include:
v Loss of an MQSeries client connection
v Unexpected application termination

In these circumstances, the close() is not called, and external resources remain
open on the terminated application’s behalf. The main consequences of this are:
Broker state inconsistency
The MQSeries Message Broker may well contain registration information
for subscribers and publishers that no longer exist. This means that the
broker may continue forwarding messages to subscribers that will never
receive them.
Subscriber messages and queues remain
Part of the subscriber deregistration procedure is the removal of subscriber
messages. If appropriate, the underlying MQSeries queue that was used to
receive subscriptions is also removed. If normal closure has not occurred,
these messages and queues remain. If there is broker state inconsistency,
the queues continue to fill up with messages that will never be read.

Subscriber cleanup utility

To avoid the problems that are associated with non-graceful closure of subscriber
objects, MQ JMS includes a subscriber cleanup utility. This utility runs on a queue
manager when the first TopicConnection to use that physical queue manager
initializes. If all the TopicConnections on a given queue manager become closed,
when the next TopicConnection initializes for that queue manager, the utility runs
again.

The cleanup utility attempts to detect any earlier MQ JMS publish/subscribe

problems that could have occurred from other applications. If it detects problems,
it cleans up associated resources by:
v de-registering against the MQSeries Message Broker
v cleaning up any un-retrieved messages and queues associated with the
subscription

The cleanup utility runs transparently in the background and only persists for a
short time. It should not affect other MQ JMS operations. If a large number of
problems are detected against a given queue manager, there might be a small delay
at initialization time while resources are cleaned up.

Note: We still strongly recommend that whenever possible, you close all subscriber
objects gracefully to avoid a build up of subscriber problems.

Handling broker reports

The MQ JMS implementation uses report messages from the broker to confirm
registration and deregistration commands. These reports are normally consumed
by the MQSeries classes for Java Message Service implementation, but under some

188 MQSeries Using Java

 Publish/Subscribe problems
error conditions, they may remain on the queue. These messages are sent to the
SYSTEM.JMS.REPORT.QUEUE queue on the local queue manager.

A Java application, PSReportDump, is supplied with MQSeries classes for Java

Message Service, which dumps the contents of this queue in plain text format. The
information can then be analyzed, either by the user, or by IBM support staff. You
can also use the application to clear the queue of messages after a problem is
diagnosed or fixed.

The compiled form of the tool is installed in the <MQ_JAVA_INSTALL_PATH>/bin

directory. To invoke the tool, change to this directory, then use the following
command:
java PSReportDump [-m queueManager] [-clear]

where:
-m queueManager
= specify the name of the queue manager to use
-clear = clear the queue of messages after dumping its contents

Output is sent to the screen, or you can redirect it to a file.

Chapter 11. Programming Publish/Subscribe applications 189

190 MQSeries Using Java
Chapter 12. JMS messages
JMS Messages are composed of the following parts:
Header All messages support the same set of header fields. Header fields
contain values that are used by both clients and providers to
identify and route messages.
Properties Each message contains a built-in facility to support
application-defined property values. Properties provide an efficient
mechanism to filter application-defined messages.
Body JMS defines several types of message body which cover the
majority of messaging styles currently in use.
JMS defines five types of message body:
Stream a stream of Java primitive values. It is filled and
read sequentially.
Map a set of name-value pairs, where names are Strings
and values are Java primitive types. The entries
can be accessed sequentially or randomly by name.
The order of the entries is undefined.
Text a message containing a java.util.String.
Object a message that contains a Serializable java object
Bytes a stream of uninterpreted bytes. This message type
is for literally encoding a body to match an
existing message format.

The JMSCorrelationID header field is used to link one message with another. It
typically links a reply message with its requesting message. JMSCorrelationID can
hold a provider-specific message ID, an application-specific String, or a
provider-native byte[] value.

Message selectors
A Message contains a built-in facility to support application-defined property
values. In effect, this provides a mechanism to add application-specific header
fields to a message. Properties allow an application, via message selectors, to have
a JMS provider select or filter messages on its behalf, using application-specific
criteria. Application-defined properties must obey the following rules:
v Property names must obey the rules for a message selector identifier.
v Property values can be boolean, byte, short, int, long, float, double, and string.
v The following name prefixes are reserved: JMSX, JMS_.

Property values are set before sending a message. When a client receives a
message, the message properties are read-only. If a client attempts to set properties
at this point, a MessageNotWriteableException is thrown. If clearProperties is
called, the properties can now be both read from, and written to.

A property value may duplicate a value in a message’s body, or it may not. JMS
does not define a policy for what should or should not be made into a property.

© Copyright IBM Corp. 1997, 2001 191

Message selectors
However, application developers should note that JMS providers will probably
handle data in a message’s body more efficiently than data in a message’s
properties. For best performance, applications should only use message properties
when they need to customize a message’s header. The primary reason for doing
this is to support customized message selection.

A JMS message selector allows a client to specify the messages that it is interested
in by using the message header. Only messages whose headers match the selector
are delivered.

Message selectors cannot reference message body values.

A message selector matches a message when the selector evaluates to true when
the message’s header field and property values are substituted for their
corresponding identifiers in the selector.

A message selector is a String, whose syntax is based on a subset of the SQL92

conditional expression syntax. The order in which a message selector is evaluated
is from left to right within a precedence level. You can use parentheses to change
this order. Predefined selector literals and operator names are written here in
upper case; however, they are not case-sensitive.

A selector can contain:

v Literals
– A string literal is enclosed in single quotes. A doubled single quote represents
a single quote. Examples are ’literal’ and ’literal’’s’. Like Java string literals,
these use the Unicode character encoding.
– An exact numeric literal is a numeric value without a decimal point, such as
57, -957, +62. Numbers in the range of Java long are supported.
– An approximate numeric literal is a numeric value in scientific notation, such
as 7E3 or -57.9E2, or a numeric value with a decimal, such as 7., -95.7, or +6.2.
Numbers in the range of Java double are supported.
– The boolean literals TRUE and FALSE.
v Identifiers:
– An identifier is an unlimited length sequence of Java letters and Java digits,
the first of which must be a Java letter. A letter is any character for which the
method Character.isJavaLetter returns true. This includes “_” and “$”. A letter
or digit is any character for which the method Character.isJavaLetterOrDigit
returns true.
– Identifiers cannot be the names NULL, TRUE, or FALSE.
– Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, and IS.
– Identifiers are either header field references or property references.
– Identifiers are case-sensitive.
– Message header field references are restricted to:
- JMSDeliveryMode
- JMSPriority
- JMSMessageID
- JMSTimestamp
- JMSCorrelationID
- JMSType

192 MQSeries Using Java

 Message selectors
JMSMessageID, JMSTimestamp, JMSCorrelationID, and JMSType values may
be null, and if so, are treated as a NULL value.
– Any name beginning with “JMSX” is a JMS-defined property name.
– Any name beginning with “JMS_” is a provider-specific property name.
– Any name that does not begin with “JMS” is an application-specific property
name. If there is a reference to a property that does not exist in a message, its
value is NULL. If it does exist, its value is the corresponding property value.
v White space is the same as it is defined for Java: space, horizontal tab, form
feed, and line terminator.
v Expressions:
– A selector is a conditional expression. A selector that evaluates to true does
match, and a selector that evaluates to false or unknown does not match.
– Arithmetic expressions are composed of themselves, arithmetic operations,
identifiers (whose value is treated as a numeric literal), and numeric literals.
– Conditional expressions are composed of themselves, comparison operations,
and logical operations.
v Standard bracketing (), to set the order in which expressions are evaluated, is
supported.
v Logical operators in precedence order: NOT, AND, OR.
v Comparison operators: =, >, >=, <, <=, <> (not equal).
– Only values of the same type can be compared. One exception is that it is
valid to compare exact numeric values and approximate numeric values. (The
type conversion required is defined by the rules of Java numeric promotion.)
If there is an attempt to compare different types, the selector is always false.
– String and boolean comparison is restricted to = and <>. Two strings are
equal if, and only if, they contain the same sequence of characters.
v Arithmetic operators in precedence order:
–+, - unary.
–*, /, multiplication, and division.
–+, -, addition, and subtraction.
–Arithmetic operations on a NULL value are not supported. If they are
attempted, the complete selector is always false.
– Arithmetic operations must use Java numeric promotion.
v arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 and arithmetic-expr3
comparison operator:
– age BETWEEN 15 and 19 is equivalent to age >= 15 AND age <= 19.
– age NOT BETWEEN 15 and 19 is equivalent to age < 15 OR age > 19.
– If any of the exprs of a BETWEEN operation are NULL, the value of the
operation is false. If any of the exprs of a NOT BETWEEN operation are
NULL, the value of the operation is true.
v identifier [NOT] IN (string-literal1, string-literal2,...) comparison operator where
identifier has a String or NULL value.
– Country IN (’ UK’, ’US’, ’France’) is true for ’UK’ and false for ’Peru’. It is
equivalent to the expression (Country = ’ UK’) OR (Country = ’ US’) OR
(Country = ’ France’).
– Country NOT IN (’ UK’, ’US’, ’France’) is false for ’UK’ and true for ’Peru’. It
is equivalent to the expression NOT ((Country = ’ UK’) OR (Country = ’ US’)
OR (Country = ’ France’)).

Chapter 12. JMS messages 193

Message selectors
– If the identifier of an IN or NOT IN operation is NULL, the value of the
operation is unknown.
v identifier [NOT] LIKE pattern-value [ESCAPE escape-character] comparison
operator, where identifier has a String value. pattern-value is a string literal,
where ’_’ stands for any single character and ’%’ stands for any sequence of
characters (including the empty sequence). All other characters stand for
themselves. The optional escape-character is a single character string literal,
whose character is used to escape the special meaning of the ’_’ and ’%’ in
pattern-value.
– phone LIKE ’12%3’ is true for ’123’ ’12993’ and false for ’1234’.
– word LIKE ’l_se’ is true for ’lose’ and false for ’loose’.
– underscored LIKE ’\_%’ ESCAPE ’\’ is true for ’_foo’ and false for ’bar’.
– phone NOT LIKE ’12%3’ is false for ’123’ ’12993’ and true for ’1234’.
– If the identifier of a LIKE or NOT LIKE operation is NULL, the value of the
operation is unknown.
v identifier IS NULL comparison operator tests for a null header field value, or a
missing property value.
– prop_name IS NULL.
v identifier IS NOT NULL comparison operator tests for the existence of a
non-null header field value or a property value.
– prop_name IS NOT NULL.

The following message selector selects messages with a message type of car, color
of blue, and weight greater than 2500 lbs:
"JMSType = 'car' AND color = 'blue' AND weight > 2500"

As noted above, property values may be NULL. The evaluation of selector

expressions that contain NULL values is defined by SQL 92 NULL semantics. The
following is a brief description of these semantics:
v SQL treats a NULL value as unknown.
v Comparison or arithmetic with an unknown value always yields an unknown
value.
v The IS NULL and IS NOT NULL operators convert an unknown value into the
respective TRUE and FALSE values.

Although SQL supports fixed decimal comparison and arithmetic, JMS message
selectors do not. This is why exact numeric literals are restricted to those without a
decimal. It is also why there are numerics with a decimal as an alternate
representation for an approximate numeric value.

SQL comments are not supported.

194 MQSeries Using Java

 Mapping JMS messages

Mapping JMS messages onto MQSeries messages

This section describes how the JMS message structure that is described in the first
part of this chapter is mapped onto an MQSeries message. It is of interest to
programmers who wish to transmit messages between JMS and traditional
MQSeries applications. It is also of interest to people who wish to manipulate
messages transmitted between two JMS applications - for example, in a message
broker implementation.

MQSeries messages are composed of three components:

v The MQSeries Message Descriptor (MQMD)
v An MQSeries MQRFH2 header
v The message body.

The MQRFH2 is optional, and its inclusion in an outgoing message is governed by

a flag in the JMS Destination class. You can set this flag using the MQSeries JMS
administration tool. Because the MQRFH2 carries JMS-specific information, always
include it in the message when the sender knows that the receiving destination is a
JMS application. Normally, omit the MQRFH2 when sending a message directly to
a non-JMS application (MQSeries Native application). This is because such an
| application does not expect an MQRFH2 in its MQSeries message. Figure 4 shows
| how the structure of a JMS message is transformed to an MQSeries message and
| back again:

MQSeries Message
JMS Client JMS Client
Mapping MQMD Mapping
JMS Message JMS Message
Data
Header Header
RFH2
Properties Properties

Data Other Data Data

Copying Copying

Figure 4. JMS to MQSeries mapping model

The structures are transformed in two ways:

Mapping
Where the MQMD includes a field that is equivalent to the JMS field, the
JMS field is mapped onto the MQMD field. Additional MQMD fields are
exposed as JMS properties, because a JMS application may need to get or
set these fields when communicating with a non-JMS application.
Copying
Where there is no MQMD equivalent, a JMS header field or property is
passed, possibly transformed, as a field inside the MQRFH2.

Chapter 12. JMS messages 195

Mapping JMS messages
The MQRFH2 header
This section describes the MQRFH Version 2 header, which carries JMS-specific
data that is associated with the message content. The MQRFH2 Version 2 is an
extensible header, and can also carry additional information that is not directly
associated with JMS. However, but this section covers only its use by JMS.

There are two parts of the header, a fixed portion, and a variable portion.
Fixed portion
The fixed portion is modelled on the “standard” MQSeries header pattern
and consists of the following fields:
StrucId (MQCHAR4)
Structure identifier.
Must be MQRFH_STRUC_ID (value: “RFH ”) (initial value).
MQRFH_STRUC_ID_ARRAY (value: “R”,“F”,“H”,“ ”) is also
defined in the usual way.
Version (MQLONG)
Structure version number.
Must be MQRFH_VERSION_2 (value: 2) (initial value).
StrucLength (MQLONG)
Total length of MQRFH2, including the NameValueData fields.
The value set into StrucLength must be a multiple of 4 (the data in
the NameValueData fields may be padded with space characters to
achieve this).
Encoding (MQLONG)
Data encoding.
Encoding of any numeric data in the portion of the message
following the MQRFH2 (the next header, or the message data
following this header).
CodedCharSetId (MQLONG)
Coded character set identifier.
Representation of any character data in the portion of the message
following the MQRFH2 (the next header, or the message data
following this header).
Format (MQCHAR8)
Format name.
Format name for the portion of the message following the
MQRFH2.
Flags (MQLONG)
Flags.
MQRFH_NO_FLAGS =0. No flags set.
NameValueCCSID (MQLONG)
The coded character set identifier (CCSID) for the NameValueData
character strings contained in this header. The NameValueData
may be coded in a character set that differs from the other
character strings that are contained in the header (StrucID and
Format).

196 MQSeries Using Java

 Mapping JMS messages
If the NameValueCCSID is a 2-byte Unicode CCSID (1200, 13488,
or 17584), the byte order of the Unicode is the same as the byte
ordering of the numeric fields in the MQRFH2. (For example,
Version, StrucLength, NameValueCCSID itself.)
The NameValueCCSID may take only values from the following
| table:
| Table 17. Possible values for NameValueCCSID field
| Value Meaning
1200 UCS2 open-ended
1208 UTF8
13488 UCS2 2.0 subset
17584 UCS2 2.1 subset (includes Euro symbol)

Variable Portion
The variable portion follows the fixed portion. The variable portion
contains a variable number of MQRFH2 Folders. Each folder contains a
variable number of elements or properties. Folders group together related
properties. The MQRFH2 headers created by JMS can contain up to three
folders:
The <mcd> folder
This contains properties that describe the “shape” or “format” of
the message. For example the Msd property identifies the message
as being Text, Bytes, Stream. Map, Object, or “Null”. This folder is
always present in a JMS MQRFH2.
The <jms> folder
This is used to transport JMS header fields, and JMSX properties
that cannot be fully expressed in the MQMD. This folder is always
present in a JMS MQRFH2.
The <usr> folder
This is used to transport any application-defined properties
associated with the message. This folder is only present if the
application has set some application-defined properties.

Table 18 shows a full list of property names.

Table 18. MQRFH2 folders and properties used by JMS
JMS Field Name Java type MQRFH2 Property name Type/values
Folder name
JMSDestination Destination jms Dst string
JMSExpiration long jms Exp i8
JMSPriority int jms Pri i4
JMSDeliveryMode int jms Dlv i4
JMSCorrelationID String jms Cid string
JMSReplyTo Destination jms Rto string
JMSType String mcd Type string
JMSXGroupID String jms Gid string
JMSXGroupSeq int jms Seq i4
xxx (User Defined) Any usr xxx any

Chapter 12. JMS messages 197

 Mapping JMS messages
Table 18. MQRFH2 folders and properties used by JMS (continued)
JMS Field Name Java type MQRFH2 Property name Type/values
Folder name
mcd Msd jms_none
jms_text
jms_bytes
jms_map
jms_stream
jms_object

The syntax used to express the properties in the variable portion is as

follows:
NameValueLength (MQLONG)
Length in bytes of the NameValueData string that immediately
follows this length field (it does not include its own length). The
value set into NameValueLength is always a multiple of 4 (the
NameValueData field is padded with space characters to achieve
this).
NameValueData (MQCHARn)
A single character string, whose length in bytes is given by the
preceding NameValueLength field. It contains a “folder” holding a
sequence of “properties”. Each property is a “name/type/value”
triplet, contained within an XML element whose name is the folder
name, as follows:
<foldername> triplet1 triplet2 ..... tripletn </foldername>

The closing </foldername> tag can be followed by spaces as

padding characters. Each triplet is encoded using an XML-like
syntax:
<name dt='datatype'>value</name>

The dt='datatype' element is optional and is omitted for many

properties, because their datatype is predefined. If it is included,
one or more space characters must be included before the dt= tag.
name is the name of the property - see Table 18 on page 197.
| datatype must match, after folding, one of the literal Datatype
| values in Table 19.
| value is a string representation of the value to be conveyed,
| using the Definitions inTable 19.

A null value is encoded using the following syntax:

<name/>

| Table 19. Property datatype values and definitions

| Datatype Definition
| value
string Any sequence of characters excluding < and &
boolean The character 0 or 1 (1 = ″true″)
bin.hex Hexadecimal digits representing octets
i1 A number, expressed using digits 0..9, with optional sign (no fractions or
| exponent). Must lie in the range -128 to 127 inclusive

198 MQSeries Using Java

 Mapping JMS messages
| Table 19. Property datatype values and definitions (continued)
| Datatype Definition
| value
i2 A number, expressed using digits 0..9, with optional sign (no fractions or
| exponent). Must lie in the range -32768 to 32767 inclusive
i4 A number, expressed using digits 0..9, with optional sign (no fractions or
| exponent). Must lie in the range -2147483648 to 2147483647 inclusive
i8 A number, expressed using digits 0..9, with optional sign (no fractions or
| exponent). Must lie in the range -9223372036854775808 to
92233720368547750807 inclusive
int A number, expressed using digits 0..9, with optional sign (no fractions or
| exponent). Must lie in the same range as ’i8’. This can be used in place of
one of the ’i*’ types if the sender does not wish to associate a particular
precision with the property
r4 Floating point number, magnitude <= 3.40282347E+38, >= 1.175E-37
expressed using digits 0..9, optional sign, optional fractional digits, optional
exponent
r8 Floating point number, magnitude <= 1.7976931348623E+308, >= 2.225E-307
expressed using digits 0..9, optional sign, optional fractional digits, optional
exponent

A string value may contain spaces. You must use the following
escape sequences in a string value:
&amp; for the & character
&lt; for the < character

You can use the following escape sequences, but they are not
required:
&gt; for the > character
&apos; for the ' character
&quot; for the " character

JMS fields and properties with corresponding MQMD fields

| Table 20 lists the JMS header fields and Table 21 on page 200 lists the JMS
| properties that are mapped directly to MQMD fields. Table 22 on page 200 lists the
| provider specific properties and the MQMD fields that they are mapped to.
| Table 20. JMS header fields mapping to MQMD fields
| JMS header field Java MQMD field C type
| type
| JMSDeliveryMode int Persistence MQLONG
| JMSExpiration long Expiry MQLONG
| JMSPriority int Priority MQLONG
| JMSMessageID String MessageID MQBYTE24
| JMSTimestamp long PutDate MQCHAR8
| PutTime MQCHAR8
| JMSCorrelationID String CorrelId MQBYTE24
|

Chapter 12. JMS messages 199

 Mapping JMS messages
| Table 21. JMS properties mapping to MQMD fields
| JMS property Java MQMD field C type
| type
| JMSXUserID String UserIdentifier MQCHAR12
| JMSXAppID String PutApplName MQCHAR28
| JMSXDeliveryCount int BackoutCount MQLONG
| JMSXGroupID String GroupId MQBYTE24
| JMSXGroupSeq int MsgSeqNumber MQLONG
|
| Table 22. JMS provider specific properties mapping to MQMD fields
| JMS provider specific property Java MQMD field C type
| type
| JMS_IBM_Report_Exception int Report MQLONG
| JMS_IBM_Report_Expiration int Report MQLONG
| JMS_IBM_Report_COA int Report MQLONG
| JMS_IBM_Report_COD int Report MQLONG
| JMS_IBM_Report_PAN int Report MQLONG
| JMS_IBM_Report_NAN int Report MQLONG
| JMS_IBM_Report_Pass_Msg_ID int Report MQLONG
| JMS_IBM_Report_Pass_Correl_ID int Report MQLONG
| JMS_IBM_Report_Discard_Msg int Report MQLONG
| JMS_IBM_MsgType int MsgType MQLONG
| JMS_IBM_Feedback int Feedback MQLONG
| JMS_IBM_Format String Format MQCHAR8
| JMS_IBM_PutApplType int PutApplType MQLONG
| JMS_IBM_Encoding int Encoding MQLONG
| JMS_IBM_Character_Set String CodedCharacterSetId MQLONG
|

Mapping JMS fields onto MQSeries fields (outgoing

messages)
Table 23 on page 201 shows how the JMS header fields are mapped into
MQMD/RFH2 fields at send() or publish() time. Table 24 on page 201 shows how
JMS properties and Table 25 on page 201 shows how JMS provider specific
properties are mapped to MQMD fields at send() or publish() time,

For fields marked ’Set by Message Object’, the value transmitted is the value held
in the JMS message immediately before the send/publish(). The value in the JMS
Message is left unchanged by the send/publish().

For fields marked ’Set by Send Method’, a value is assigned when the
send/publish() is executed (any value held in the JMS Message is ignored). The
value in the JMS message is updated to show the value used.

Fields marked as ’Receive-only’ are not transmitted and are left unchanged in the
message by send() or publish().

200 MQSeries Using Java

 Mapping JMS messages
| Table 23. Outgoing message field mapping
| JMS header field name MQMD field used for Header Set by
| transmission
| JMSDestination MQRFH2 Send Method
| JMSDeliveryMode Persistence MQRFH2 Send Method
| JMSExpiration Expiry MQRFH2 Send Method
| JMSPriority Priority MQRFH2 Send Method
| JMSMessageID MessageID Send Method
| JMSTimestamp PutDate/PutTime Send Method
| JMSCorrelationID CorrelId MQRFH2 Message Object
| JMSReplyTo ReplyToQ/ReplyToQMgr MQRFH2 Message Object
| JMSType MQRFH2 Message Object
| JMSRedelivered Receive-only
|
| Table 24. Outgoing message JMS property mapping
| JMS property name MQMD field used for Header Set by
| transmision
| JMSXUserID UserIdentifier Send Method
| JMSXAppID PutApplName Send Method
| JMSXDeliveryCount Receive-only
| JMSXGroupID GroupId MQRFH2 Message Object
| JMSXGroupSeq MsgSeqNumber MQRFH2 Message Object
|
| Table 25. Outgoing message JMS provider specific property mapping
| JMS provider specific property name MQMD field used for Header Set by
| transmission
| JMS_IBM_Report_Exception Report Message Object
| JMS_IBM_Report_Expiration Report Message Object
| JMS_IBM_Report_COA/COD Report Message Object
| JMS_IBM_Report_NAN/PAN Report Message Object
| JMS_IBM_Report_Pass_Msg_ID Report Message Object
| JMS_IBM_Report_Pass_Correl_ID Report Message Object
| JMS_IBM_Report_Discard_Msg Report Message Object
| JMS_IBM_MsgType MsgType Message Object
| JMS_IBM_Feedback Feedback Message Object
| JMS_IBM_Format Format Message Object
| JMS_IBM_PutApplType PutApplType Send Method
| JMS_IBM_Encoding Encoding Message Object
| JMS_IBM_Character_Set CodedCharacterSetId Message Object
|

Mapping JMS header fields at send()/publish()

The following notes relate to the mapping of JMS fields at send()/publish():
v JMS Destination to MQRFH2: This is stored as a string that serializes the
salient characteristics of the destination object, so that a receiving JMS can

Chapter 12. JMS messages 201

Mapping JMS messages
reconstitute an equivalent destination object. The MQRFH2 field is encoded as
URI (see “uniform resource identifiers” on page 173 for details of the URI
notation).
v JMSReplyTo to MQMD ReplyToQ, ReplyToQMgr, MQRFH2: The Queue and
QueueManager name are copied to the MQMD ReplyToQ and ReplyToQMgr
fields respectively. The destination extension information (other “useful” details
that are kept in the Destination Object) is copied into the MQRFH2 field. The
MQRFH2 field is encoded as URI (see “uniform resource identifiers” on page 173
for details of the URI notation).
v JMSDeliveryMode to MQMD Persistence: The JMSDeliveryMode value is set
by the send/publish() Method or MessageProducer, unless the Destination
Object overrides it. The JMSDeliveryMode value is mapped to the MQMD
Persistence field as follows:
– JMS value PERSISTENT is equivalent to MQPER_PERSISTENT
– JMS value NON_PERSISTENT is equivalent to MQPER_NOT_PERSISTENT
If JMSDeliveryMode is set to a non-default value, the delivery mode value is
also encoded in the MQRFH2.
v JMSExpiration to/from MQMD Expiry, MQRFH2: JMSExpiration stores the
time to expire (the sum of the current time and the time to live), whereas
MQMD stores the time to live. Also, JMSExpiration is in milliseconds, but
MQMD.expiry is in centiseconds.
– If the send() method sets an unlimited time to live, MQMD Expiry is set to
MQEI_UNLIMITED, and no JMSExpiration is encoded in the MQRFH2.
– If the send() method sets a time to live that is less than 214748364.7 seconds
(about 7 years), the time to live is stored in MQMD. Expiry and the expiration
time (in milliseconds) is encoded as an i8 value in the MQRFH2.
– If the send() method sets a time to live greater than 214748364.7 seconds,
MQMD.Expiry is set to MQEI_UNLIMITED. The true expiration time in
milliseconds is encoded as an i8 value in the MQRFH2.
v JMSPriority to MQMD Priority: Directly map JMSPriority value (0-9) onto
MQMD priority value (0-9). If JMSPriority is set to a non-default value, the
priority level is also encoded in the MQRFH2.
v JMSMessageID from MQMD MessageID: All messages sent from JMS have
unique message identifiers assigned by MQSeries. The value assigned is
returned in the MQMD messageId field after the MQPUT call, and is passed
back to the application in the JMSMessageID field. The MQSeries messageId is a
24-byte binary value, whereas the JMSMessageID is a String. The JMSMessageID
is composed of the binary messageId value converted to a sequence of 48
hexadecimal characters, prefixed with the characters “ID:”. JMS provides a hint
that can be set to disable the production of message identifiers. This hint is
ignored, and a unique identifier is assigned in all cases. Any value that is set
into the JMSMessageId field before a send() is overwritten.
v JMSTimestamp from MQMD PutDate, PutTime: After a send, the
JMSTimestamp field is set equal to the date/time value given by the MQMD
PutDate and PutTime fields. Any value that is set into the JMSMessageId field
before a send() is overwritten.
v JMSType to MQRFH2: This string is set into the MQRFH2.
v JMSCorrelationID to MQMD CorrelId, MQRFH2: The JMSCorrelationID can
hold one of the following:
– A provider specific message ID: This is a message identifier from a message
previously sent or received, and so should be a string of 48 hexadecimal
digits that are prefixed with “ID:”. The prefix is removed, the remaining

202 MQSeries Using Java

 Mapping JMS messages
characters are converted into binary, and then they are set into the MQMD
CorrelId field. No CorrelId value is encoded in the MQRFH2.
– A provider-native byte[] value: The value is copied into the MQMD CorrelId
field - padded with nulls, or truncated to 24 bytes if necessary. No CorrelId
value is encoded in the MQRFH2.
– An application-specific String: The value is copied into the MQRFH2. The
first 24 bytes of the string, in UTF8 format, are written into the MQMD
CorrelID.

Mapping JMS property fields

These notes refer to the mapping of JMS property fields in MQSeries messages:
v JMSXUserID from MQMD UserIdentifier: JMSXUserID is set on return from
send call.
v JMSXAppID from MQMD PutApplName: JSMXAppID is set on return from
send call.
v JMSXGroupID to MQRFH2 (point-to-point): For point-to-point messages, the
JMSXGroupID is copied into the MQMD GroupID field. If the JMSXGroupID
starts with the prefix “ID:”, it is converted into binary. Otherwise, it is encoded
as a UTF8 string. The value is padded or truncated if necessary to a length of 24
bytes. The MQF_MSG_IN_GROUP flag is set.
v JMSXGroupID to MQRFH2 (publish/subscribe): For publish/subscribe
messages, the JMSXGroupID is copied into the MQRFH2 as a string.
v JMSXGroupSeq MQMD MsgSeqNumber (point-to-point): For point-to-point
messages, the JMSXGroupSeq is copied into the MQMD MsgSeqNumber field.
The MQF_MSG_IN_GROUP flag is set.
v JMSXGroupSeq MQMD MsgSeqNumber (publish/subscribe): For
publish/subscribe messages, the JMSXGroupSeq is copied into the MQRFH2 as
an i4.

Mapping JMS provider-specific fields

The following notes refer to the mapping of JMS Provider specific fields into
MQSeries messages:
v JMS_IBM_Report_<name> to MQMD Report: A JMS application can set the
MQMD Report options, using the following JMS_IBM_Report_XXX properties.
The single MQMD is mapped to several JMS_IBM_Report_XXX properties. The
application should set the value of these properties to the standard MQSeries
MQRO_ constants (included in com.ibm.mq.MQC). So, for example, to request
COD with full Data, the application should set JMS_IBM_Report_COD to the
value MQC.MQRO_COD_WITH_FULL_DATA.
JMS_IBM_Report_Exception

MQRO_EXCEPTION or
MQRO_EXCEPTION_WITH_DATA or
MQRO_EXCEPTION_WITH_FULL_DATA
JMS_IBM_Report_Expiration

MQRO_EXPIRATION or
MQRO_EXPIRATION_WITH_DATA or
MQRO_EXPIRATION_WITH_FULL_DATA
JMS_IBM_Report_COA

Chapter 12. JMS messages 203

 Mapping JMS messages
MQRO_COA or
MQRO_COA_WITH_DATA or
MQRO_COA_WITH_FULL_DATA
JMS_IBM_Report_COD

MQRO_COD or
MQRO_COD_WITH_DATA or
MQRO_COD_WITH_FULL_DATA
JMS_IBM_Report_PAN
MQRO_PAN
JMS_IBM_Report_NAN
MQRO_NAN
JMS_IBM_Report_Pass_Msg_ID
MQRO_PASS_MSG_ID
JMS_IBM_Report_Pass_Correl_ID
MQRO_PASS_CORREL_ID
JMS_IBM_Report_Discard_Msg
MQRO_DISCARD_MSG
v JMS_IBM_MsgType to MQMD MsgType: Value maps directly onto MQMD
MsgType. If the application has not set an explicit value of JMS_IBM_MsgType,
then a default value is used. This default value is determined as follows:
– If JMSReplyTo is set to an MQSeries queue destination, MSGType is set to the
value MQMT_REQUEST
– If JMSReplyTo is not set, or is set to anything other than an MQSeries queue
destination, MsgType is set to the value MQMT_DATAGRAM
v JMS_IBM_Feedback to MQMD Feedback: Value maps directly onto MQMD
Feedback.
v JMS_IBM_Format to MQMD Format: Value maps directly onto MQMD Format.
v JMS_IBM_Encoding to MQMD Encoding: If set, this property overrides the
numeric encoding of the Destination Queue or Topic.
v JMS_IBM_Character_Set to MQMD CodedCharacterSetId: If set, this property
overrides the coded character set property of the Destination Queue or Topic.

Mapping MQSeries fields onto JMS fields (incoming

messages)
| Table 26 shows how JMS header fields and Table 27 on page 205 shows how JMS
| property fields are mapped into MQMD/MQRFH2 fields at send() or publish()
| time. Table 28 on page 205 shows how JMS provider specific properties are
| mapped.
| Table 26. Incoming message JMS header field mapping
| JMS header field name MQMD field retrieved from MQRFH2 field
| retrieved from
| JMSDestination jms.Dst
| JMSDeliveryMode Persistence
| JMSExpiration jms.Exp
| JMSPriority Priority
| JMSMessageID MessageID

204 MQSeries Using Java

 Mapping JMS messages
| Table 26. Incoming message JMS header field mapping (continued)
| JMS header field name MQMD field retrieved from MQRFH2 field
| retrieved from
| JMSTimestamp PutDate PutTime
| JMSCorrelationID CorrelId jms.Cid
| JMSReplyTo ReplyToQ ReplyToQMgr jms.Rto
| JMSType mcd.Type
| JMSRedelivered BackoutCount
|
| Table 27. Incoming message property mapping
| JMS property name MQMD field retrieved from MQRFH2 field
| retrieved from
| JMSXUserID UserIdentifier
| JMSXAppID PutApplName
| JMSXDeliveryCount BackoutCount
| JMSXGroupID GroupId jms.Gid
| JMSXGroupSeq MsgSeqNumber jms.Seq
|
| Table 28. Incoming message provider specific JMS property mapping
| JMS property name MQMD field retrieved from MQRFH2 field
| retrieved from
| JMS_IBM_Report_Exception Report
| JMS_IBM_Report_Expiration Report
| JMS_IBM_Report_COA Report
| JMS_IBM_Report_COD Report
| JMS_IBM_Report_PAN Report
| JMS_IBM_Report_NAN Report
| JMS_IBM_Report_ Pass_Msg_ID Report
| JMS_IBM_Report_Pass_Correl_ID Report
| JMS_IBM_Report_Discard_Msg Report
| JMS_IBM_MsgType MsgType
| JMS_IBM_Feedback Feedback
| JMS_IBM_Format Format
| JMS_IBM_PutApplType PutApplType
1
| JMS_IBM_Encoding Encoding
1
| JMS_IBM_Character_Set CodedCharacterSetId

| 1. Only set if the incoming message is a Bytes Message.

|

Mapping JMS to a native MQSeries application

This section describes what happens if we send a message from a JMS Client
application to a traditional MQSeries application which has no knowledge of
MQRFH2 headers. Figure 5 on page 206 is a diagram of the mapping.

Chapter 12. JMS messages 205

 Mapping JMS messages
The administrator indicates that the JMS Client is communicating with such an
application by setting the MQSeries Destination’s TargetClient value to
JMSC.MQJMS_CLIENT_NONJMS_MQ. This indicates that no MQRFH2 field is to
| be produced. Note that if this is not done, the receiving application must be able to
| handle the MQRFH2 field.

The mapping from JMS to MQMD targeted at a Native MQSeries application is the
same as mapping from JMS to MQMD targeted at a true JMS client. If JMS receives
an MQSeries message with the MQMD Format field set to other than
MQFMT_RFH2, we know that we are receiving data from a non-JMS application. If
the Format is MQFMT_STRING, the message is received as a JMS Text Message.
Otherwise, it is received as a JMS Bytes message. Because there is no MQRFH2,
only those JMS properties that are transmitted in the MQMD can be restored.

JMS Client JMS Client

MQSeries Message
JMS Message JMS Message
Mapping Mapping
Header Header
MQMD
Mapping Mapping
Properties Properties
Copying Copying
Data Data Data

Traditional MQSeries Application

Figure 5. JMS to MQSeries mapping model

Message body
This section discusses the encoding of the message body itself. The encoding
depends on the type of JMS message:
ObjectMessage
is an object serialized by the Java Runtime in the normal way.
TextMessage
is an encoded string. For an outgoing message, the string is encoded in the
character set given by the Destination object. This defaults to UTF8
encoding (the UTF8 encoding starts with the first character of the message
- there is no length field at the start). It is, however, possible to specify any
other character set supported by MQ Java. Such character sets are used
mainly when you send a message to a non-JMS application.
If the character set is a double-byte set (including UTF16), the Destination
object’s integer encoding specification determines the order of the bytes.
An incoming message is interpreted using the character set and encoding
that are specified in the message itself. These specifications are in the
rightmost MQSeries header (or MQMD if there are no headers). For JMS
messages, the rightmost header will usually be the MQRFH2.
BytesMessage
is, by default, a sequence of bytes as defined by the JMS 1.0.2 specification,
and associated Java documentation.
For an outgoing message that was assembled by the application itself, the
Destination object’s encoding property may be used to override the

206 MQSeries Using Java

 Mapping JMS messages
encodings of integer and floating point fields contained in the message. For
example, you can request that floating point values are stored in S/390
rather than IEEE format).
An incoming message is interpreted using the numeric encoding specified
in the message itself. This specification is in the rightmost MQSeries header
(or MQMD if there are no headers). For JMS messages, the rightmost
header will usually be the MQRFH2.
If a BytesMessage is received, and is resent without modification, its body
is transmitted byte for byte, as it was received. The Destination object’s
encoding property has no effect on the body. The only string-like entity
that can be sent explicitly in a BytesMessage is a UTF8 string. This is
encoded in Java UTF8 format, and starts with a 2-byte length field. The
Destination object’s character set property has no effect on the encoding of
an outgoing BytesMessage. The character set value in an incoming
MQSeries message has no effect on the interpretation of that message as a
JMS BytesMessage.
Non-Java applications are unlikely to recognize the Java UTF8 encoding.
Therefore, for a JMS application to send a BytesMessage that contains text
data, the application itself must convert its strings to byte arrays, and write
these byte arrays into the BytesMessage.
MapMessage
is a string containing a set of XML name/type/value triplets, encoded as:
<map><elementName1 dt='datatype'>value</elementName1>
<elementName2 dt='datatype'>value</elementName2>.....
</map>

where:
datatype can take one of the values described in Table 19 on page 198.
string is the default datatype, so dt='string' is omitted.

The character set used to encode or interpret the XML string that makes up
the MapMessage body is determined following the rules that apply to a
TextMessage.
StreamMessage
is like a map, but without element names:
<stream><elt dt='datatype'>value</elt>
<elt dt='datatype'>value</elt>.....</stream>

Every element is sent using the same tagname (elt). The default type is
string, so dt='string' is omitted for string elements.

The character set used to encode or interpret the XML string that makes up
the StreamMessage body is determined following the rules that apply to a
TextMessage.

The MQRFH2.format field is set as follows:

MQFMT_NONE
for ObjectMessage, BytesMessage, or messages with no body.
MQFMT_STRING
for TextMessage, StreamMessage, or MapMessage.

Chapter 12. JMS messages 207

Mapping JMS messages

208 MQSeries Using Java

Chapter 13. MQ JMS Application Server Facilities
MQ JMS V5.2 supports the Application Server Facilities (ASF) that are specified in
the Java Message Service 1.0.2 specification (see Sun’s Java Web site at
http://java.sun.com). This specification identifies three roles within this
programming model:
v The JMS provider supplies ConnectionConsumer and advanced Session
functionality.
v The application server supplies ServerSessionPool and ServerSession
functionality.
v The client application uses the functionality that the JMS provider and
application server supply.

The following sections contain details about how MQ JMS implements ASF:
v “ASF classes and functions” describes how MQ JMS implements the
ConnectionConsumer class and advanced functionality in the Session class.
v “Application server sample code” on page 215 describes the sample
ServerSessionPool and ServerSession code that is supplied with MQ JMS.
v “Examples of ASF use” on page 219 describes supplied ASF samples and
examples of ASF use from the perspective of a client application.

Note: The Java Message Service 1.0.2 specification for ASF also describes JMS
support for distributed transactions using the X/Open XA protocol. For
details of the XA support that MQ JMS provides, see “Appendix E. JMS
JTA/XA interface with WebSphere” on page 361.

ASF classes and functions

MQ JMS implements the ConnectionConsumer class and advanced functionality in
the Session class. For details, see:
v “MQPoolServices” on page 123
v “MQPoolServicesEvent” on page 124
v “MQPoolToken” on page 126
v “MQPoolServicesEventListener” on page 153
v “ConnectionConsumer” on page 243
v “QueueConnection” on page 288
v “Session” on page 301
v “TopicConnection” on page 319

ConnectionConsumer
The JMS specification enables an application server to integrate closely with a JMS
implementation by using the ConnectionConsumer interface. This feature provides
concurrent processing of messages. Typically, an application server creates a pool
of threads, and the JMS implementation makes messages available to these threads.
A JMS-aware application server can use this feature to provide high-level
messaging functionality, such as message processing beans.

Normal applications do not use the ConnectionConsumer, but expert JMS clients
might use it. For such clients, the ConnectionConsumer provides a

© Copyright IBM Corp. 1997, 2001 209

ASF classes and functions
high-performance method to deliver messages concurrently to a pool of threads.
When a message arrives on a queue or a topic, JMS selects a thread from the pool
and delivers a batch of messages to it. To do this, JMS runs an associated
MessageListener’s onMessage() method.

You can achieve the same effect by constructing multiple Session and
MessageConsumer objects, each with a registered MessageListener. However, the
ConnectionConsumer provides better performance, less use of resources, and
greater flexibility. In particular, fewer Session objects are required.

To help you develop applications that use ConnectionConsumers, MQ JMS

provides a fully-functioning example implementation of a pool. You can use this
implementation without any changes, or adapt it to suit the specific needs of the
application.

Planning an application
General principles for point-to-point messaging
When an application creates a ConnectionConsumer from a QueueConnection
object, it specifies a JMS Queue object and a selector string. The
ConnectionConsumer then begins to receive messages (or, more accurately, to
provide messages to Sessions in the associated ServerSessionPool). Messages arrive
on the queue, and if they match the selector, they are delivered to Sessions in the
associated ServerSessionPool.

In MQSeries terms, the Queue object refers to either a QLOCAL or a QALIAS on

the local Queue Manager. If it is a QALIAS, that QALIAS must refer to a
QLOCAL. The fully resolved MQSeries QLOCAL is known as the underlying
QLOCAL. A ConnectionConsumer is said to be active if it is not closed and its
parent QueueConnection is started.

It is possible for multiple ConnectionConsumers, each with different selectors, to

run against the same underlying QLOCAL. To maintain performance, unwanted
messages should not accumulate on the queue. Unwanted messages are those for
which no active ConnectionConsumer has a matching selector. You can set the
QueueConnectionFactory so that these unwanted messages are removed from the
queue (for details, see “Removing messages from the queue” on page 213). You can
set this behavior in one of two ways:
v Use the JMS Administration tool to set the QueueConnectionFactory to
MRET(NO).
v In your program, use:
MQQueueConnectionFactory.setMessageRetention(JMSC.MQJMS_MRET_NO)
If you do not change this setting, the default is to retain such unwanted messages
on the queue.

It is possible that ConnectionConsumers that target the same underlying QLOCAL

could be created from multiple QueueConnection objects. However, for
performance reasons, we recommend that multiple JVMs do not create
ConnectionConsumers against the same underlying QLOCAL.

When you set up the MQSeries Queue Manager, consider the following points:
v The underlying QLOCAL must be enabled for shared input. To do this, use the
following MQSC command:
ALTER QLOCAL(your.qlocal.name) SHARE GET(ENABLED)

210 MQSeries Using Java

 ASF classes and functions
v Your queue manager must have an enabled dead-letter queue. If a
ConnectionConsumer experiences a problem when it puts a message on the
dead-letter queue, message delivery from the underlying QLOCAL stops. To
define a dead-letter queue, use:
ALTER QMGR DEADQ(your.dead.letter.queue.name)
v The user that runs the ConnectionConsumer must have authority to perform
MQOPEN with MQOO_SAVE_ALL_CONTEXT and
MQOO_PASS_ALL_CONTEXT. For details, see the MQSeries documentation for
your specific platform.
v If unwanted messages are left on the queue, they degrade the system
performance. Therefore, plan your message selectors so that between them, the
ConnectionConsumers will remove all messages from the queue.
For details about MQSC commands, see MQSeries MQSC Command Reference.

General principles for publish/subscribe messaging

When an application creates a ConnectionConsumer from a TopicConnection
object, it specifies a Topic object and a selector string. The ConnectionConsumer
then begins to receive messages on that Topic that match the selector.

Alternatively, an application can create a durable ConnectionConsumer that is

associated with a specific name. This ConnectionConsumer receives messages that
have been published on the Topic since the durable ConnectionConsumer was last
active. It receives all such messages on the Topic that match the selector.

For non-durable subscriptions, a separate queue is used for ConnectionConsumer

subscriptions. The CCSUB configurable option on the TopicConnectionFactory
specifies the queue to use. Normally, the CCSUB should specify a single queue for
use by all ConnectionConsumers that use the same TopicConnectionFactory.
However, it is possible to make each ConnectionConsumer generate a temporary
queue by specifying a queue name prefix followed by a ‘*’.

For durable subscriptions, the CCDSUB property of the Topic specifies the queue
to use. Again, this may be a queue that already exists or a queue name prefix
followed by a ‘*’. If you specify a queue that already exists, all durable
ConnectionConsumers that subscribe to the Topic use this queue. If you specify a
queue name prefix followed by a ‘*’, a queue is generated the first time that a
durable ConnectionConsumer is created with a given name. This queue is reused
later when a durable ConnectionConsumer is created with the same name.

When you set up the MQSeries Queue Manager, consider the following points:
v Your queue manager must have an enabled dead-letter queue. If a
ConnectionConsumer experiences a problem when it puts a message on the
dead-letter queue, message delivery from the underlying QLOCAL stops. To
define a dead-letter queue, use:
ALTER QMGR DEADQ(your.dead.letter.queue.name)
v The user that runs the ConnectionConsumer must have authority to perform
MQOPEN with MQOO_SAVE_ALL_CONTEXT and
MQOO_PASS_ALL_CONTEXT. For details, see the MQSeries documentation for
your specific platform.
v You can optimize performance for an individual ConnectionConsumer by
creating a separate, dedicated, queue for it. This is at the cost of extra resource
usage.

Chapter 13. MQ JMS Application Server Facilities 211

ASF classes and functions
Handling poison messages
Sometimes, a badly-formatted message arrives on a queue. Such a message might
make the receiving application fail and back out the receipt of the message. In this
situation, such a message might be received, then returned to the queue,
repeatedly. These messages are known as poison messages. The
ConnectionConsumer must be able to detect poison messages and reroute them to
an alternative destination.

When an application uses ConnectionConsumers, the circumstances in which a

message is backed out depend on the Session that the application server provides:
v When the Session is non-transacted, with AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE, a message is backed out only after a system error,
or if the application terminates unexpectedly.
v When the Session is non-transacted with CLIENT_ACKNOWLEDGE,
unacknowledged messages can be backed out by the application server calling
Session.recover().
Typically, the client implementation of MessageListener or the application server
calls Message.acknowledge(). Message.acknowledge() acknowledges all messages
delivered on the session so far.
v When the Session is transacted, typically, the application server commits the
Session. If the application server detects an error, it may choose to back out one
or more messages.
v If the application server supplies an XASession, messages are committed or
backed out depending on a distributed transaction. The application server takes
responsibility for completing the transaction.

The MQSeries Queue Manager keeps a record of the number of times that each
message has been backed out. When this number reaches a configurable threshold,
the ConnectionConsumer requeues the message on a named Backout Queue. If this
requeue fails for any reason, the message is removed from the queue and either
requeued to the dead-letter queue, or discarded. See “Removing messages from the
queue” on page 213 for more details.

On most platforms, the threshold and requeue queue are properties of the
MQSeries QLOCAL. For point-to-point messaging, this should be the underlying
QLOCAL. For publish/subscribe messaging, this is the CCSUB queue defined on
the TopicConnectionFactory, or the CCDSUB queue defined on the Topic. To set the
threshold and requeue Queue properties, issue the following MQSC command:
ALTER QLOCAL(your.queue.name) BOTHRESH(threshold) BOQUEUE(your.requeue.queue.name)

For publish/subscribe messaging, if your system creates a dynamic queue for each
subscription, these settings are obtained from the MQ JMS model queue. To alter
these settings, you can use:
ALTER QMODEL(SYSTEM.JMS.MODEL.QUEUE) BOTHRESH(threshold) BOQUEUE(your.requeue.queue.name)

If the threshold is zero, poison message handling is disabled, and poison messages
will remain on the input queue. Otherwise, when the backout count reaches the
threshold, the message is sent to the named requeue queue. If the backout count
reaches the threshold, but the message cannot go to the requeue queue, the
message is sent to the dead-letter queue or discarded. This situation occurs if the
requeue queue is not defined, or if the ConnectionConsumer cannot send the
message to the requeue queue. On some platforms, you cannot specify the
threshold and requeue queue properties. On these platforms, messages are sent to

212 MQSeries Using Java

 ASF classes and functions
the dead-letter queue, or discarded, when the backout count reaches 20.
See“Removing messages from the queue” for further details.

Removing messages from the queue

When an application uses ConnectionConsumers, JMS might need to remove
messages from the queue in a number of situations:
Badly formatted message
A message may arrive that JMS cannot parse.
Poison message
A message may reach the backout threshold, but the ConnectionConsumer
fails to requeue it on the backout queue.
No interested ConnectionConsumer
For point-to-point messaging, when the QueueConnectionFactory is set so
that it does not retain unwanted messages, a message arrives that is
unwanted by any of the ConnectionConsumers.

In these situations, the ConnectionConsumer attempts to remove the message from

the queue. The disposition options in the report field of the message’s MQMD set
the exact behavior. These options are:
MQRO_DEAD_LETTER_Q
The message is requeued to the queue manager’s dead-letter queue. This is
the default.
MQRO_DISCARD_MSG
The message is discarded.

The ConnectionConsumer also generates a report message, and this also depends
on the report field of the message’s MQMD. This message is sent to the message’s
ReplyToQ on the ReplyToQmgr. If there is an error while the report message is
being sent, the message is sent to the dead-letter queue instead. The exception
report options in the report field of the message’s MQMD set details of the report
message. These options are:
MQRO_EXCEPTION
A report message is generated that contains the MQMD of the original
message. It does not contain any message body data.
MQRO_EXCEPTION_WITH_DATA
A report message is generated that contains the MQMD, any MQ headers,
and 100 bytes of body data.
MQRO_EXCEPTION_WITH_FULL_DATA
A report message is generated that contains all data from the original
message.
default
No report message is generated.

When report messages are generated, the following options are honoured:
v MQRO_NEW_MSG_ID
v MQRO_PASS_MSG_ID
v MQRO_COPY_MSG_ID_TO_CORREL_ID
v MQRO_PASS_CORREL_ID

If a ConnectionConsumer cannot follow the disposition options, or the exception

report options, in the message’s MQMD, its action depends on the persistence of

Chapter 13. MQ JMS Application Server Facilities 213

ASF classes and functions
the message. If the message is non-persistent, the message is discarded, and no
report message is generated. If the message is persistent, delivery of all messages
from the QLOCAL stops.

Therefore, it is important to define a dead-letter queue, and to check it regularly to

ensure that no problems occur. Particularly, ensure that the dead-letter queue does
not reach its maximum depth, and that its maximum message size is large enough
for all messages.

When a message is requeued to the dead-letter queue, it is preceded by an

MQSeries dead-letter header (MQDLH). See MQSeries Application Programming
Reference for details about the format of the MQDLH. You can identify messages
that a ConnectionConsumer has placed on the dead-letter queue, or report
messages that a ConnectionConsumer has generated, by the following fields:
v PutApplType is MQAT_JAVA (0x1C)
v PutApplName is “MQ JMS ConnectionConsumer”

These fields are in the MQDLH of messages on the dead-letter queue, and the
MQMD of report messages. The feedback field of the MQMD, and the Reason field
of the MQDLH, contain a code describing the error. For details about these codes,
see “Error handling”. Other fields are as described in the MQSeries Application
Programming Reference.

Error handling
Recovering from error conditions
If a ConnectionConsumer experiences a serious error, message delivery to all
ConnectionConsumers with an interest in the same QLOCAL stops. Typically, this
occurs if the ConnectionConsumer cannot requeue a message to the dead-letter
queue, or it experiences an error when reading messages from the QLOCAL.

When this occurs, the application and application server are notified in the
following way:
v Any ExceptionListener that is registered with the affected Connection is notified.

You can use these to identify the cause of the problem. In some cases, the system
administrator must intervene to resolve the problem.

There are two ways in which an application can recover from these error
conditions:
v Call close() on all affected ConnectionConsumers. The application can create
new ConnectionConsumers only after all affected ConnectionConsumers are
closed and any system problems are resolved.
v Call stop() on all affected Connections. Once all Connections are stopped and
any system problems are resolved, the application should be able to start() all
Connections successfully.

Reason and feedback codes

To determine the cause of an error, you can use:
v The feedback code in any report messages
v The reason code in the MQDLH of any messages in the dead-letter queue

214 MQSeries Using Java

 ASF classes and functions
ConnectionConsumers generate the following reason codes.
MQRC_BACKOUT_THRESHOLD_REACHED (0x93A; 2362)
Cause The message reaches the Backout Threshold defined on the
QLOCAL, but no Backout Queue is defined.
On platforms where you cannot define the Backout Queue,
the message reaches the JMS-defined backout threshold of
20.
Action To avoid this situation, ensure that ConnectionConsumers
using the queue provide a set of selectors that deal with all
messages, or set the QueueConnectionFactory to retain
messages.
Alternatively, investigate the source of the message.
MQRC_MSG_NOT_MATCHED (0x93B; 2363)
Cause In point-to-point messaging, there is a message that does
not match any of the selectors for the
ConnectionConsumers monitoring the queue. To maintain
performance, the message is requeued to the dead-letter
queue.
Action To avoid this situation, ensure that ConnectionConsumers
using the queue provide a set of selectors that deal with all
messages, or set the QueueConnectionFactory to retain
messages.
Alternatively, investigate the source of the message.
MQRC_JMS_FORMAT_ERROR (0x93C; 2364)
Cause JMS cannot interpret the message on the queue.
Action Investigate the origin of the message. JMS usually delivers
messages of an unexpected format as a BytesMessage or
TextMessage. Occasionally, this fails if the message is very
badly formatted.

Other codes that appear in these fields are caused by a failed attempt to requeue
the message to a Backout Queue. In this situation, the code describes the reason
that the requeue failed. To diagnose the cause of these errors, refer to the MQSeries
Application Programming Reference.

If the report message cannot be put on the ReplyToQ, it is put on the dead-letter
queue. In this situation, the feedback field of the MQMD is filled in as described
above. The reason field in the MQDLH explains why the report message could not
be placed on the ReplyToQ.

Application server sample code

Figure 6 on page 216 summarizes the principles of ServerSessionPool and
ServerSession functionality.

Chapter 13. MQ JMS Application Server Facilities 215

Application server sample code

2
ConnectionConsumer

ConnectionConsumer

A B C D E
ConnectionConsumer

A B C D E
3
A B C D E

4
6

JMS Session 5

8
ServerSessionPool
A B SSt
1

JMS Session 5 SSa

8
C D E SSu

Server sessions

A B C D E F G

Message queue

Figure 6. ServerSessionPool and ServerSession functionality

1. The ConnectionConsumers get message references from the queue.

2. Each ConnectionConsumer selects specific message references.
3. The ConnectionConsumer buffer holds the selected message references.
4. The ConnectionConsumer requests one or more ServerSessions from the
ServerSessionPool.
5. ServerSessions are allocated from the ServerSessionPool.
6. The ConnectionConsumer assigns message references to the ServerSessions and
starts the ServerSession threads running.
7. Each ServerSession retrieves its referenced messages from the queue. It passes
them to the onMessage method from the MessageListener that is associated with
the JMS Session.
8. After it completes its processing, the ServerSession is returned to the pool.

216 MQSeries Using Java

 Application server sample code
Normally, the application server supplies ServerSessionPool and ServerSession
functionality. However, MQ JMS is supplied with a simple implementation of these
interfaces, with program source. These samples are in the following directory,
where <install_dir> is the installation directory for MQ JMS:
<install_dir>/samples/jms/asf

These samples enable you to use the MQ JMS ASF in a standalone environment
(that is, you do not need a suitable application server). Also, they provide
examples of how to implement these interfaces and take advantage of the MQ JMS
ASF. These examples are intended to aid both MQ JMS users, and vendors of other
application servers.

MyServerSession.java
This class implements the javax.jms.ServerSession interface. Its basic function is
to associate a thread with a JMS Session. Instances of this class are pooled by a
ServerSessionPool (see “MyServerSessionPool.java”). As a ServerSession, it must
implement the following two methods:
v getSession(), which returns the JMS Session this associated with this
ServerSession
v start(), which starts this ServerSession’s thread and results in the JMS Session’s
run() method being invoked

MyServerSession also implements the Runnable interface. Therefore, the creation of

the ServerSession’s thread can be based on this class, and does not need a separate
class.

The class uses a wait()-notify() mechanism that is based on the values of two
boolean flags, ready and quit. This mechanism means that the ServerSession
creates and starts its associated thread during its construction. However, it does
not automatically execute the body of the run() method. The body of the run()
method is executed only when the ready flag is set to true by the start() method.
The ASF calls the start() method when it is necessary to deliver messages to the
associated JMS Session.

For delivery, the run() method of the JMS Session is called. The MQ JMS ASF will
have already loaded the run() method with messages.

After delivery completes, the ready flag is reset to false, and the owning
ServerSessionPool is notified that delivery is complete. The ServerSession then
remains in a wait state until either the start() method is called again, or the
close() method is invoked and ends this ServerSession’s thread.

MyServerSessionPool.java
This class implements the javax.jms.ServerSessionPool interface, and exists to
create and control access to a pool of ServerSessions.

In this simple implementation, the pool consists of a static array of ServerSession

objects that are created during the construction of the pool. The following four
parameters are passed into the constructor:
v javax.jms.Connection connection
The connection used to create JMS Sessions.
v int capacity
The size of the array of MyServerSession objects.

Chapter 13. MQ JMS Application Server Facilities 217

Application server sample code
v int ackMode
The required acknowledge mode of the JMS Sessions.
v MessageListenerFactory mlf
The MesssageListenerFactory that creates the message listener that is supplied to
the JMS Sessions. See “MessageListenerFactory.java”.

The pool’s constructor uses these parameters to create an array of MyServerSession

objects. The supplied connection is used to create JMS Sessions of the given
acknowledge mode and correct domain (QueueSessions for point-to-point and
TopicSessions for publish/subscribe). The Sessions are supplied with a message
listener. Finally, the ServerSession objects, based on the JMS Sessions, are created.

This sample implementation is a static model. That is, all the ServerSessions in the
pool are created when the pool is created, and after this, the pool cannot grow or
shrink. This approach is just for simplicity. It is possible for a ServerSessionPool to
use a sophisticated algorithm to create ServerSessions dynamically, as needed.

MyServerSessionPool keeps a record of which ServerSessions are currently in use

by maintaining an array of boolean values called inUse. These booleans are all
initialized to false. When the getServerSession method is invoked and requests a
ServerSession from the pool, the inUse array is searched for the first false value.
When one is found, the boolean is set to true and the corresponding ServerSession
is returned. If there are no false values in the inUse array, the getServerSession
method must wait() until notification occurs.

Notification occurs in either of the following circumstances:

v The pool’s close() method is called, indicating that the pool should be shut
down.
v A ServerSession that is currently in use completes its workload and calls the
serverSessionFinished method. The serverSessionFinished method returns the
ServerSession to the pool, and sets the corresponding inUse flag to false. The
ServerSession then becomes eligible for re-use.

MessageListenerFactory.java
In this sample, a message listener factory object is associated with each
ServerSessionPool instance. The MessageListenerFactory class represents a very
simple interface that is used to obtain an instance of a class that implements the
javax.jms.MessageListener interface. The class contains a single method:
javax.jms.MessageListener createMessageListener();

An implementation of this interface is supplied when the ServerSessionPool is

constructed. This object is used to create message listeners for the individual JMS
Sessions that back up the ServerSessions in the pool. This architecture means that
each separate implementation of the MessageListenerFactory interface must have
its own ServerSessionPool.

MQ JMS includes a sample MessageListenerFactory implementation, which is

discussed in “CountingMessageListenerFactory.java” on page 220.

218 MQSeries Using Java

 Examples of ASF use

Examples of ASF use

There is a set of classes, with their source, in the directory
<install_dir>/samples/jms/asf (where <install_dir> is the installation directory
for MQ JMS). These classes use the MQ JMS application server facilities that are
described in “ASF classes and functions” on page 209, within the sample
standalone application server environment that is described in “Application server
sample code” on page 215.

These samples provide three examples of ASF use from the perspective of a client
application:
v A simple point-to-point example uses:
– ASFClient1.java
– Load1.java
– CountingMessageListenerFactory.java
v A more complex point-to-point example uses:
– ASFClient2.java
– Load2.java
– CountingMessageListenerFactory.java
– LoggingMessageListenerFactory.java
v A simple publish/subscribe example uses:
– ASFClient3.java
– TopicLoad.java
– CountingMessageListenerFactory.java
v A more complex publish/subscribe example uses:
– ASFClient4.java
– TopicLoad.java
– CountingMessageListenerFactory.java
– LoggingMessageListenerFactory.java

The following sections describe each class in turn.

Load1.java
This class is a simple generic JMS application that loads a given queue with a
number of messages, then terminates. It can either retrieve the required
administered objects from a JNDI namespace, or create them explicitly, using the
MQ JMS classes that implement these interfaces. The administered objects that are
required are a QueueConnectionFactory and a Queue. You can use the command
line options to set the number of messages with which to load the queue, and the
sleep time between individual message puts.

This application has two versions of the command line syntax.

For use with JNDI, the syntax is:

java Load1 [-icf jndiICF] [-url jndiURL] [-qcfLookup qcfLookup]
[-qLookup qLookup] [-sleep sleepTime] [-msgs numMsgs]

For use without JNDI, the syntax is:

java Load1 -nojndi [-qm qMgrName] [-q qName]
[-sleep sleepTime] [-msgs numMsgs]

Chapter 13. MQ JMS Application Server Facilities 219

Examples of ASF use
Table 29 describes the parameters and gives their defaults.
Table 29. Load1 parameters and defaults
Parameter Meaning Default
jndiICF Initial context factory class used com.sun.jndi.ldap.LdapCtxFactory
for JNDI
jndiURL Provider URL used for JNDI ldap://localhost/o=ibm,c=us
qcfLookup JNDI lookup key used for cn=qcf
QueueConnectionFactory
qLookup JNDI lookup key used for Queue cn=q
qMgrName Name of queue manager to ″″ (use the default queue manager)
connect to
qName Name of queue to load SYSTEM.DEFAULT.LOCAL.QUEUE
sleepTime Time (in milliseconds) to pause 0 (no pause)
between message puts
numMsgs Number of messages to put 1000

If there are any errors, an error message is displayed, and the application
terminates.

You can use this application to simulate message load on an MQSeries queue. In
turn, this message load could trigger the ASF-enabled applications described in the
following sections. The messages put to the queue are simple JMS TextMessage
objects. These objects do not contain user-defined message properties, which could
be useful to make use of different message listeners. The source code is supplied so
that you can modify this load application if necessary.

CountingMessageListenerFactory.java
This file contains definitions for two classes:
v CountingMessageListener
v CountingMessageListenerFactory

CountingMessageListener is a very simple implementation of the

javax.jms.MessageListener interface. It keeps a record of the number of times its
onMessage method has been invoked, but does nothing with the messages it is
passed.

CountingMessageListenerFactory is the factory class for CountingMessageListener.

It is an implementation of the MessageListenerFactory interface described in
“MessageListenerFactory.java” on page 218. This factory keeps a record of all the
message listeners that it produces. It also includes a method, printStats(), which
displays usage statistics for each of these listeners.

ASFClient1.java
This application acts as a client of the MQ JMS ASF. It sets up a single
ConnectionConsumer to consume the messages in a single MQSeries queue. It
displays throughput statistics for each message listener that is used, and terminates
after one minute.

220 MQSeries Using Java

 Examples of ASF use
The application can either retrieve the required administered objects from a JNDI
namespace, or create them explicitly, using the MQ JMS classes that implement
these interfaces. The administered objects that are required are a
QueueConnectionFactory and a Queue.

This application has two versions of the command line syntax:

For use with JNDI, the syntax is:

java ASFClient1 [-icf jndiICF] [-url jndiURL] [-qcfLookup qcfLookup]
[-qLookup qLookup] [-poolSize poolSize] [-batchSize batchSize]

For use without JNDI, the syntax is:

java ASFClient1 -nojndi [-qm qMgrName] [-q qName]
[-poolSize poolSize] [-batchSize batchSize]

Table 30 describes the parameters and gives their defaults.

Table 30. ASFClient1 parameters and defaults
Parameter Meaning Default
jndiICF Initial context factory class used com.sun.jndi.ldap.LdapCtxFactory
for JNDI
jndiURL Provider URL used for JNDI ldap://localhost/o=ibm,c=us
qcfLookup JNDI lookup key used for cn=qcf
QueueConnectionFactory
qLookup JNDI lookup key used for Queue cn=q
qMgrName Name of queue manager to ″″ (use the default queue manager)
connect to
qName Name of queue to consume from SYSTEM.DEFAULT.LOCAL.QUEUE
poolSize The number of ServerSessions 5
created in the ServerSessionPool
being used
batchSize The maximum number of message 10
that can be assigned to a
ServerSession at a time

The application obtains a QueueConnection from the QueueConnectionFactory.

A ServerSessionPool, in the form of a MyServerSessionPool, is constructed using:

v the QueueConnection that was created previously
v the required poolSize
v an acknowledge mode, AUTO_ACKNOWLEDGE
v an instance of a CountingMessageListenerFactory, as described in
“CountingMessageListenerFactory.java” on page 220

Chapter 13. MQ JMS Application Server Facilities 221

Examples of ASF use
Then, the connection’s createConnectionConsumer method is invoked, passing in:
v the Queue that was obtained earlier
v a null message selector (indicating that all messages should be accepted)
v the ServerSessionPool that was just created
v the batchSize that is required

The consumption of messages is then started through invocation of the

connection’s start() method.

The client application displays throughput statistics for each message listener that
is used, displaying statistics every 10 seconds. After one minute, the connection is
closed, the server session pool is stopped, and the application terminates.

Load2.java
This class is a JMS application that loads a given queue with a number of
messages, then terminates, in a similar way to Load1.java. The command line
syntax is also similar to that for Load1.java (substitute Load2 for Load1 in the
syntax). For details, see “Load1.java” on page 219.

The difference is that each message contains a user property called value, which
takes a randomly selected integer value between 0 and 100. This property means
that you can apply message selectors to the messages. Consequently, the messages
can be shared between the two consumers that are created in the client application
described in “ASFClient2.java”.

LoggingMessageListenerFactory.java
This file contains definitions for two classes:
v LoggingMessageListener
v LoggingMessageListenerFactory

LoggingMessageListener is an implementation of the javax.jms.MessageListener

interface. It takes the messages that are passed to it and writes an entry to the log
file. The default log file is ./ASFClient2.log. You can inspect this file and check
the messages that are sent to the connection consumer that is using this message
listener.

LoggingMessageListenerFactory is the factory class for LoggingMessageListener. It

is an implementation of the MessageListenerFactory interface described in
“MessageListenerFactory.java” on page 218.

ASFClient2.java
ASFClient2.java is a slightly more complicated client application than
ASFClient1.java. It creates two ConnectionConsumers that feed off the same queue,
but that apply different message selectors. The application uses a
CountingMessageListenerFactory for one consumer, and a
LoggingMessageListenerFactory for the other. Use of two different message listener
factories means that each consumer must have its own server session pool.

The application displays statistics that relate to one ConnectionConsumer on

screen, and writes statistics that relate to the other ConnectionConsumer to a log
file.

222 MQSeries Using Java

 Examples of ASF use
The command line syntax is similar to that for “ASFClient1.java” on page 220
(substitute ASFClient2 for ASFClient1 in the syntax). Each of the two server session
pools contains the number of ServerSessions set by the poolSize parameter.

There should be an uneven distribution of messages. The messages loaded onto the
source queue by Load2 contain a user property, where the value should be
between 0 and 100, evenly and randomly distributed. The message selector
value>75 is applied to highConnectionConsumer, and the message selector
value≤75 is applied to normalConnectionConsumer. The
highConnectionConsumer’s messages (approximately 25% of the total load) are
sent to a LoggingMessageListener. The normalConnectionConsumer’s messages
(approximately 75% of the total load) are sent to a CountingMessageListener.

When the client application runs, statistics that relate to the

normalConnectionConsumer, and its associated CountingMessageListenerFactories,
are printed to screen every 10 seconds. Statistics that relate to the
highConnectionConsumer, and its associated LoggingMessageListenerFactories, are
written to the log file.

You can inspect the screen and the log file to see the real destination of the
messages. Add the totals for each of the CountingMessageListeners. As long as the
client application does not terminate before all the messages are consumed, this
should account for approximately 75% of the load. The number of log file entries
should account for the remainder of the load. (If the client application terminates
before all the messages are consumed, you can increase the application timeout.)

TopicLoad.java
This class is a JMS application that is a publish/subscribe version of the Load2
queue loader described in “Load2.java” on page 222. It publishes the required
number of messages under the given topic, then it terminates. Each message
contains a user property called value, which takes a randomly selected integer
value between 0 and 100.

To use this application, ensure that the broker is running and that the required
setup is complete. For details, see “Additional setup for Publish/Subscribe mode”
on page 20.

This application has two versions of the command line syntax.

For use with JNDI, the syntax is:

java TopicLoad [-icf jndiICF] [-url jndiURL] [-tcfLookup tcfLookup]
[-tLookup tLookup] [-sleep sleepTime] [-msgs numMsgs]

For use without JNDI, the syntax is:

java TopicLoad -nojndi [-qm qMgrName] [-t tName]
[-sleep sleepTime] [-msgs numMsgs]

Table 31 describes the parameters and gives their defaults.

Table 31. TopicLoad parameters and defaults
Parameter Meaning Default
jndiICF Initial context factory class used com.sun.jndi.ldap.LdapCtxFactory
for JNDI
jndiURL Provider URL used for JNDI ldap://localhost/o=ibm,c=us

Chapter 13. MQ JMS Application Server Facilities 223

Examples of ASF use
Table 31. TopicLoad parameters and defaults (continued)
Parameter Meaning Default
tcfLookup JNDI lookup key used for cn=tcf
TopicConnectionFactory
tLookup JNDI lookup key used for Topic cn=t
qMgrName Name of queue manager to ″″ (use the default queue manager)
connect to, and broker queue
manager to publish messages to
tName Name of topic to publish to MQJMS/ASF/TopicLoad
sleepTime Time (in milliseconds) to pause 0 (no pause)
between message puts
numMsgs Number of messages to put 200

If there are any errors, an error message is displayed, and the application
terminates.

ASFClient3.java
ASFClient3.java is a client application that is a publish/subscribe version of
“ASFClient1.java” on page 220. It sets up a single ConnectionConsumer to consume
the messages published on a single Topic. It displays throughput statistics for each
message listener that is used, and terminates after one minute.

This application has two versions of the command line syntax.

For use with JNDI, the syntax is:

java ASFClient3 [-icf jndiICF] [-url jndiURL] [-tcfLookup tcfLookup]
[-tLookup tLookup] [-poolsize poolSize] [-batchsize batchSize]

For use without JNDI, the syntax is:

java ASFClient3 -nojndi [-qm qMgrName] [-t tName]
[-poolsize poolSize] [-batchsize batchSize]

Table 32 describes the parameters and gives their defaults.

Table 32. ASFClient3 parameters and defaults
Parameter Meaning Default
jndiICF Initial context factory class used com.sun.jndi.ldap.LdapCtxFactory
for JNDI
jndiURL Provider URL used for JNDI ldap://localhost/o=ibm,c=us
tcfLookup JNDI lookup key used for cn=tcf
TopicConnectionFactory
tLookup JNDI lookup key used for Topic cn=t
qMgrName Name of queue manager to ″″ (use the default queue manager)
connect to, and broker queue
manager to publish messages to
tName Name of topic to consume from MQJMS/ASF/TopicLoad
poolSize The number of ServerSessions 5
created in the ServerSessionPool
being used

224 MQSeries Using Java

 Examples of ASF use
Table 32. ASFClient3 parameters and defaults (continued)
Parameter Meaning Default
batchSize The maximum number of message 10
that can be assigned to a
ServerSession at a time

Like ASFClient1, the client application displays throughput statistics for each
message listener that is used, displaying statistics every 10 seconds. After one
minute, the connection is closed, the server session pool is stopped, and the
application terminates.

ASFClient4.java
ASFClient4.java is a more complex publish/subscribe client application. It creates
three ConnectionConsumers that all feed off the same topic, but each one applies
different message selectors.

The first two consumers use ‘high’ and ‘normal’ message selectors, in the same
way as the application “ASFClient2.java” on page 222. The third consumer does
not use any message selector. The application uses two
CountingMessageListenerFactories for the two selector-based consumers, and a
LoggingMessageListenerFactory for the third consumer. Because the application
uses different message listener factories, each consumer must have its own server
session pool.

The application displays statistics that relate to the two selector-based consumers
on screen. It writes statistics that relate to the third ConnectionConsumer to a log
file.

The command line syntax is similar to that for “ASFClient3.java” on page 224
(substitute ASFClient4 for ASFClient3 in the syntax). Each of the three server
session pools contains the number of ServerSessions set by the poolSize parameter.

When the client application runs, statistics that relate to the

normalConnectionConsumer and the highConnectionConsumer, and their
associated CountingMessageListenerFactories, are printed to screen every 10
seconds. Statistics that relate to the third ConnectionConsumer, and its associated
LoggingMessageListenerFactories, are written to the log file.

You can inspect the screen and the log file to see the real destination of the
messages. Add the totals for each of the CountingMessageListeners and inspect the
number of log file entries.

The distribution of messages should be different from the distribution obtained by

a point-to-point version of the same application (ASFClient2.java). This is because,
in the publish/subscribe domain, each consumer of a topic obtains its own copy of
each message published on that topic. In this application, for a given topic load,
the ‘high’ and ‘normal’ consumers will receive approximately 25% and 75% of the
load, respectively. The third consumer will still receive 100% of the load. Therefore,
the total number of messages received is greater than 100% of the load originally
published on the topic.

Chapter 13. MQ JMS Application Server Facilities 225

226 MQSeries Using Java
Chapter 14. JMS interfaces and classes
MQSeries classes for Java Message Service consists of a number of Java classes and
interfaces that are based on the Sun javax.jms package of interfaces and classes.
Clients should be written using the Sun interfaces and classes that are listed below,
and that are described in detail in the following sections. The names of the
MQSeries objects that implement the Sun interfaces and classes have a prefix of
“MQ” (unless stated otherwise in the object description). The descriptions include
details about any deviations of the MQSeries objects from the standard JMS
definitions. These deviations are marked with ‘*’.

Sun Java Message Service classes and interfaces

The following tables list the JMS objects contained in the package javax.jms.
Interfaces marked with ‘*’ are implemented by applications. Interfaces marked
with ‘**’ are implemented by application servers.
Table 33. Interface Summary
Interface Description
BytesMessage A BytesMessage is used to send a message containing a
stream of uninterpreted bytes.
Connection A JMS Connection is a client’s active connection to its
JMS provider.
ConnectionConsumer For application servers, Connections provide a special
facility for creating a ConnectionConsumer.
ConnectionFactory A ConnectionFactory encapsulates a set of connection
configuration parameters that an administrator has
defined.
ConnectionMetaData ConnectionMetaData provides information that
describes the Connection.
DeliveryMode Delivery modes supported by JMS.
Destination The parent interface for Queue and Topic.
ExceptionListener* An exception listener is used to receive exceptions
thrown by Connections asynchronous delivery threads.
MapMessage A MapMessage is used to send a set of name-value
pairs where names are Strings and values are Java
primitive types.
Message The Message interface is the root interface of all JMS
messages.
MessageConsumer The parent interface for all message consumers.
MessageListener* A MessageListener is used to receive asynchronously
delivered messages.
MessageProducer A client uses a MessageProducer to send messages to a
Destination.
ObjectMessage An ObjectMessage is used to send a message that
contains a serializable Java object.
Queue A Queue object encapsulates a provider-specific queue
name.

© Copyright IBM Corp. 1997, 2001 227

javax.jms
Table 33. Interface Summary (continued)
Interface Description
QueueBrowser A client uses a QueueBrowser to look at messages on a
queue without removing them.
QueueConnection A QueueConnection is an active connection to a JMS
point-to-point provider.
QueueConnectionFactory A client uses a QueueConnectionFactory to create
QueueConnections with a JMS point-to-point provider.
QueueReceiver A client uses a QueueReceiver to receive messages that
have been delivered to a queue.
QueueSender A client uses a QueueSender to send messages to a
queue.
QueueSession A QueueSession provides methods to create
QueueReceivers, QueueSenders, QueueBrowsers and
TemporaryQueues.
ServerSession ** A ServerSession is an object implemented by an
application server.
ServerSessionPool ** A ServerSessionPool is an object implemented by an
application server to provide a pool of ServerSessions
for processing the messages of a ConnectionConsumer.
Session A JMS Session is a single threaded context for
producing and consuming messages.
StreamMessage A StreamMessage is used to send a stream of Java
primitives.
TemporaryQueue A TemporaryQueue is a unique Queue object created
for the duration of a QueueConnection.
TemporaryTopic A TemporaryTopic is a unique Topic object created for
the duration of a TopicConnection.
TextMessage A TextMessage is used to send a message containing a
java.lang.String.
Topic A Topic object encapsulates a provider-specific topic
name.
TopicConnection A TopicConnection is an active connection to a JMS
Pub/Sub provider.
TopicConnectionFactory A client uses a TopicConnectionFactory to create
TopicConnections with a JMS Publish/Subscribe
provider.
TopicPublisher A client uses a TopicPublisher for publishing messages
on a topic.
TopicSession A TopicSession provides methods to create
TopicPublishers, TopicSubscribers and TemporaryTopics.
TopicSubscriber A client uses a TopicSubscriber to receive messages that
have been published to a topic.
XAConnection XAConnection extends the capability of Connection by
providing an XASession.
XAConnectionFactory Some application servers provide support for grouping
Java Transaction Service (JTS)-capable resource use into
a distributed transaction.
XAQueueConnection XAQueueConnection provides the same create options
as QueueConnection.

228 MQSeries Using Java

 javax.jms
Table 33. Interface Summary (continued)
Interface Description
XAQueueConnectionFactory An XAQueueConnectionFactory provides the same
create options as a QueueConnectionFactory.
XAQueueSession An XAQueueSession provides a regular QueueSession
which can be used to create QueueReceivers,
QueueSenders and QueueBrowsers.
XASession XASession extends the capability of Session by adding
access to a JMS provider’s support for the Java
Transaction API (JTA).
XATopicConnection An XATopicConnection provides the same create
options as TopicConnection.
XATopicConnectionFactory An XATopicConnectionFactory provides the same create
options as TopicConnectionFactory.
XATopicSession An XATopicSession provides a regular TopicSession
which can be used to create TopicSubscribers and
TopicPublishers.

Table 34. Class Summary

Class Description
QueueRequestor JMS provides a QueueRequestor helper class to simplify making
service requests.
TopicRequestor JMS provides a TopicRequestor helper class to simplify making
service requests.

Chapter 14. JMS interfaces and classes 229

 MQSeries JMS classes

MQSeries JMS classes

| Two packages contain the MQSeries classes for Java Message Service that
| implement the Sun interfaces. Table 35 lists the com.ibm.mq.jms package and
| Table 36 on page 231 lists the com.ibm.jms package.
Table 35. Package ’com.ibm.mq.jms’ class Summary
Class Implements
MQConnection Connection
MQConnectionConsumer ConnectionConsumer
MQConnectionFactory ConnectionFactory
MQConnectionMetaData ConnectionMetaData
MQDestination Destination
MQMessageConsumer MessageConsumer
MQMessageProducer MessageProducer
MQQueue Queue
MQQueueBrowser QueueBrowser
MQQueueConnection QueueConnection
MQQueueConnectionFactory QueueConnectionFactory
MQQueueEnumeration java.util.Enumeration from QueueBrowser
MQQueueReceiver QueueReceiver
MQQueueSender QueueSender
MQQueueSession QueueSession
MQSession Session
MQTemporaryQueue TemporaryQueue
MQTemporaryTopic TemporaryTopic
MQTopic Topic
MQTopicConnection TopicConnection
MQTopicConnectionFactory TopicConnectionFactory
MQTopicPublisher TopicPublisher
MQTopicSession TopicSession
MQTopicSubscriber TopicSubscriber
1
| MQXAConnection XAConnection
1
| MQXAConnectionFactory XAConnectionFactory
1
| MQXAQueueConnection XAQueueConnection
1
| MQXAQueueConnectionFactory XAQueueConnectionFactory
1
| MQXAQueueSession XAQueueSession
1
| MQXASession XASession
1
| MQXATopicConnection XATopicConnection
1
| MQXATopicConnectionFactory XATopicConnectionFactory
1
| MQXATopicSession XATopicSession

| Notes:
| 1. These classes implementing the XA function are not supported with MQ Java for iSeries
| & AS/400

230 MQSeries Using Java

 MQSeries JMS classes

Table 36. Package ’com.ibm.jms’ class summary

Class Implements
JMSBytesMessage BytesMessage
JMSMapMessage MapMessage
JMSMessage Message
JMSObjectMessage ObjectMessage
JMSStreamMessage StreamMessage
JMSTextMessage TextMessage

A sample implementation of the following JMS interfaces is supplied in this release

of MQSeries classes for Java Message Service.
v ServerSession
v ServerSessionPool
See “Application server sample code” on page 215.

Chapter 14. JMS interfaces and classes 231

BytesMessage

BytesMessage
public interface BytesMessage
extends Message

MQSeries class: JMSBytesMessage

java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSBytesMessage

A BytesMessage is used to send a message containing a stream of uninterpreted

bytes. It inherits Message and adds a bytes message body. The receiver of the
message supplies the interpretation of the bytes.

Note: This message type is for client encoding of existing message formats. If
possible, one of the other self-defining message types should be used
instead.

See also: MapMessage, Message, ObjectMessage, StreamMessage, and

TextMessage.

Methods
readBoolean
public boolean readBoolean() throws JMSException

Read a boolean from the bytes message.

Returns:
the boolean value read.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if it is the end of the message bytes.
readByte
public byte readByte() throws JMSException

Read a signed 8-bit value from the bytes message.

Returns:
the next byte from the bytes message as a signed 8-bit byte.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.

232 MQSeries Using Java

 BytesMessage
readUnsignedByte
public int readUnsignedByte() throws JMSException

Read an unsigned 8-bit number from the bytes message.

Returns:
the next byte from the bytes message, interpreted as an unsigned
8-bit number.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readShort
public short readShort() throws JMSException

Read a signed 16-bit number from the bytes message.

Returns:
the next two bytes from the bytes message, interpreted as a signed
16-bit number.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readUnsignedShort
public int readUnsignedShort() throws JMSException

Read an unsigned 16-bit number from the bytes message.

Returns:
the next two bytes from the bytes message, interpreted as an
unsigned 16-bit integer.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readChar
public char readChar() throws JMSException

Read a Unicode character value from the bytes message.

Returns:
the next two bytes from the bytes message as a Unicode character.

Chapter 14. JMS interfaces and classes 233

BytesMessage
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readInt
public int readInt() throws JMSException

Read a signed 32-bit integer from the bytes message.

Returns:
the next four bytes from the bytes message, interpreted as an int.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readLong
public long readLong() throws JMSException

Read a signed 64-bit integer from the bytes message.

Returns:
the next eight bytes from the bytes message, interpreted as a long.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readFloat
public float readFloat() throws JMSException

Read a float from the bytes message.

Returns:
the next four bytes from the bytes message, interpreted as a float.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.

234 MQSeries Using Java

 BytesMessage
readDouble
public double readDouble() throws JMSException

Read a double from the bytes message.

Returns:
the next eight bytes from the bytes message, interpreted as a
double.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readUTF
public java.lang.String readUTF() throws JMSException

Read in a string that has been encoded using a modified UTF-8 format
from the bytes message. The first two bytes are interpreted as a 2-byte
length field.
Returns:
a Unicode string from the bytes message.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v MessageEOFException - if it is the end of the message bytes.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readBytes
public int readBytes(byte[] value) throws JMSException

Read a byte array from the bytes message. If there are sufficient bytes
remaining in the stream the entire buffer is filled, if not, the buffer is
partially filled.
Parameters:
value - the buffer into which the data is read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no
more data because the end of the bytes has been reached.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v JMSException - if JMS fails to read the message because of an
internal JMS error.
readBytes
public int readBytes(byte[] value, int length)
throws JMSException

Read a portion of the bytes message.

Chapter 14. JMS interfaces and classes 235

BytesMessage
Parameters:
v value - the buffer into which the data is read.
v length - the number of bytes to read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no
more data because the end of the bytes has been reached.
Throws:
v MessageNotReadableException - if the message is in write-only
mode.
v IndexOutOfBoundsException - if length is negative, or is less
than the length of the array value
v JMSException - if JMS fails to read the message because of an
internal JMS error.
writeBoolean
public void writeBoolean(boolean value) throws JMSException

Write a boolean to the bytes message as a 1-byte value. The value true is
written out as the value (byte)1; the value false is written out as the
value (byte)0.
Parameters:
value - the boolean value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeByte
public void writeByte(byte value) throws JMSException

Write out a byte to the bytes message as a 1-byte value.

Parameters:
value - the byte value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeShort
public void writeShort(short value) throws JMSException

Write a short to the bytes message as two bytes.

Parameters:
value - the short to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.

236 MQSeries Using Java

 BytesMessage
writeChar
public void writeChar(char value) throws JMSException

Write a char to the bytes message as a 2-byte value, high byte first.
Parameters:
value - the char value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeInt
public void writeInt(int value) throws JMSException

Write an int to the bytes message as four bytes.

Parameters:
value - the int to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeLong
public void writeLong(long value) throws JMSException

Write a long to the bytes message as eight bytes,

Parameters:
value - the long to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeFloat
public void writeFloat(float value) throws JMSException

Convert the float argument to an int using floatToIntBits method in

class Float, and then write that int value to the bytes message as a 4-byte
quantity.
Parameters:
value - the float value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.

Chapter 14. JMS interfaces and classes 237

BytesMessage
writeDouble
public void writeDouble(double value) throws JMSException

Convert the double argument to a long using doubleToLongBits method in

class Double, and then write that long value to the bytes message as an
8-byte quantity.
Parameters:
value - the double value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeUTF
public void writeUTF(java.lang.String value)
throws JMSException

Write a string to the bytes message using UTF-8 encoding in a

machine-independent manner. The UTF-8 string written to the buffer starts
with a 2-byte length field.
Parameters:
value - the String value to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeBytes
public void writeBytes(byte[] value) throws JMSException

Write a byte array to the bytes message.

Parameters:
value - the byte array to be written.
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeBytes
public void writeBytes(byte[] value,
int length) throws JMSException

Write a portion of a byte array to the bytes message.

Parameters:
v value - the byte array value to be written.
v offset - the initial offset within the byte array.
v length - the number of bytes to use.

238 MQSeries Using Java

 BytesMessage
Throws:
v MessageNotWriteableException - if message in read-only mode.
v JMSException - if JMS fails to write the message because of an
internal JMS error.
writeObject
public void writeObject(java.lang.Object value)
throws JMSException

Write a Java object to the bytes message.

Note: This method only works for the primitive object types (such as
Integer, Double, and Long), Strings, and byte arrays.
Parameters:
value - the Java object to be written.
Throws:
v MessageNotWriteableException - if message in read-only
mode.
v MessageFormatException - if object is invalid type.
v JMSException - if JMS fails to write the message because
of an internal JMS error.
reset
public void reset() throws JMSException

Put the message body in read-only mode, and reposition the bytes of bytes
to the beginning.
Throws:
v JMSException - if JMS fails to reset the message because of an
internal JMS error.
v MessageFormatException - if message has an invalid format

Chapter 14. JMS interfaces and classes 239

Connection

Connection
public interface Connection
Subinterfaces: QueueConnection, TopicConnection, XAQueueConnection, and
XATopicConnection

MQSeries class: MQConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQConnection

A JMS Connection is a client’s active connection to its JMS provider.

See also: QueueConnection, TopicConnection, XAQueueConnection, and

XATopicConnection

Methods
getClientID
public java.lang.String getClientID()
throws JMSException

Get the client identifier for this connection. The client identifier can either
be preconfigured by the administrator in a ConnectionFactory, or assigned
by calling setClientId.
Returns:
the unique client identifier.
Throws:
JMSException - if the JMS implementation fails to return the client
ID for this Connection because of an internal error.
setClientID
public void setClientID(java.lang.String clientID)
throws JMSException

Set the client identifier for this connection.

Note: The client identifier is ignored for point-to-point connections.

Parameters:
clientID - the unique client identifier.
Throws:
v JMSException - if the JMS implementation fails to set the
client ID for this Connection because of an internal error.
v InvalidClientIDException - if the JMS client specifies an
invalid or duplicate client id.
v IllegalStateException - if attempting to set a connection’s
client identifier at the wrong time, or if it has been
configured administratively.
getMetaData
public ConnectionMetaData getMetaData() throws JMSException

Get the metadata for this connection.

240 MQSeries Using Java

 Connection
Returns:
the connection metadata.
Throws:
JMSException - general exception if the JMS implementation fails
to get the Connection metadata for this Connection.
See also:
ConnectionMetaData
getExceptionListener
public ExceptionListener getExceptionListener()
throws JMSException

Get the ExceptionListener for this Connection.

Returns:
The ExceptionListener for this Connection
Throws:
JMSException - general exception if the JMS implementation fails
to get the Exception listener for this Connection.
setExceptionListener
public void setExceptionListener(ExceptionListener listener)
throws JMSException

Set an exception listener for this connection.

Parameters:
handler - the exception listener.
Throws:
JMSException - general exception if the JMS implementation fails
to set the Exception listener for this Connection.
start
public void start() throws JMSException

Start (or restart) a Connection’s delivery of incoming messages. Starting a

started session is ignored.
Throws:
JMSException - if the JMS implementation fails to start the message
delivery because of an internal error.
See also:
stop
stop
public void stop() throws JMSException

Used to stop a Connection’s delivery of incoming messages temporarily. It

can be restarted using its start method. When stopped, delivery to all the
Connection’s message consumers is inhibited. Synchronous receives are
blocked, and messages are not delivered to message listeners.

Stopping a session has no affect on its ability to send messages. Stopping a

stopped session is ignored.

Chapter 14. JMS interfaces and classes 241

Connection
Throws:
JMSException - if the JMS implementation fails to stop the message
delivery because of an internal error.
See also:
start
close
public void close() throws JMSException

Because a provider may allocate some resources outside the JVM on behalf
of a Connection, clients should close them when they are not needed. You
cannot rely on garbage collection to reclaim these resources eventually,
because this may not occur soon enough. There is no need to close the
sessions, producers, and consumers of a closed connection.

Closing a connection causes any of its sessions’ in-process transactions to

be rolled back. In the case where a session’s work is coordinated by an
external transaction manager, when using XASession, a session’s commit
and rollback methods are not used and the result of a closed session’s
work is determined later by a transaction manager. Closing a connection
does NOT force an acknowledge of client acknowledged sessions.

MQ JMS keeps a pool of MQSeries hConns available for use by Sessions.

Under some circumstances, Connection.close() clears this pool. If an
application uses multiple Connections sequentially, it is possible to force
the pool to remain active between JMS Connections. To do this, register an
MQPoolToken with com.ibm.mq.MQEnvironment for the lifetime of your
JMS application. For details, see “Connection pooling” on page 64 and
“MQEnvironment” on page 88.
Throws:
JMSException - if the JMS implementation fails to close the
connection because of an internal error. Examples are a failure to
release resources or to close a socket connection.

242 MQSeries Using Java

 ConnectionConsumer

ConnectionConsumer
public interface ConnectionConsumer

MQSeries class: MQConnectionConsumer

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionConsumer

For application servers, Connections provide a special facility to create a

ConnectionConsumer. A Destination and a Property Selector specify the messages
that it is to consume. Also, a ConnectionConsumer must be given a
ServerSessionPool to use to process its messages.

See also: QueueConnection, and TopicConnection.

Methods
close()
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a ConnectionConsumer, clients should close them when they are
not needed. You cannot rely on garbage collection to reclaim these
resources eventually, because this may not occur soon enough.
Throws:
JMSException - if a JMS implementation fails to release resources
on behalf of ConnectionConsumer, or if it fails to close the
connection consumer.
getServerSessionPool()
public ServerSessionPool getServerSessionPool()
throws JMSException

Get the server session associated with this connection consumer.

Returns:
the server session pool used by this connection consumer.
Throws:
JMSException - if a JMS implementation fails to get the server
session pool associated with this connection consumer because of
an internal error.

Chapter 14. JMS interfaces and classes 243

ConnectionFactory

ConnectionFactory
public interface ConnectionFactory
Subinterfaces: QueueConnectionFactory, TopicConnectionFactory,
XAQueueConnectionFactory, and XATopicConnectionFactory

MQSeries class: MQConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionFactory

A ConnectionFactory encapsulates a set of connection configuration parameters

that has been defined by an administrator. A client uses it to create a Connection
with a JMS provider.

See also: QueueConnectionFactory, TopicConnectionFactory,

XAQueueConnectionFactory, and XATopicConnectionFactory

MQSeries constructor
MQConnectionFactory
public MQConnectionFactory()

Methods
setDescription *
public void setDescription(String x)

A short description of the object.

getDescription *
public String getDescription()

Retrieve the object description.

setTransportType *
public void setTransportType(int x) throws JMSException

Set the transport type to use. It can be either

JMSC.MQJMS_TP_BINDINGS_MQ, or
JMSC.MQJMS_TP_CLIENT_MQ_TCPIP.
getTransportType *
public int getTransportType()

Retrieve the transport type.

setClientId *
public void setClientId(String x)

Sets the client Identifier to be used for all connections created using this
Connection.

244 MQSeries Using Java

 ConnectionFactory
getClientId *
public String getClientId()

Get the client Identifier that is used for all connections that are created
using this ConnectionFactory.
setQueueManager *
public void setQueueManager(String x) throws JMSException

Set the name of the queue manager to connect to.

getQueueManager *
public String getQueueManager()

Get the name of the queue manager.

setHostName *
public void setHostName(String hostname)

For client only, the name of the host to connect to.

getHostName *
public String getHostName()

Retrieve the name of the host.

setPort *
public void setPort(int port) throws JMSException

Set the port for a client connection.

Parameters:
port - the new value to use.
Throws:
JMSException if the port is negative.
getPort *
public int getPort()

For client connections only, get the port number.

setChannel *
public void setChannel(String x) throws JMSException

For client only, set the channel to use.

getChannel *
public String getChannel()

For client only, get the channel that was used.

setCCSID *
public void setCCSID(int x) throws JMSException

Set the character set to be used when connecting to the queue manager. See
Table 13 on page 105 for a list of allowed values. We recommend that you
use the default value (819) for most situations.

Chapter 14. JMS interfaces and classes 245

ConnectionFactory
getCCSID *
public int getCCSID()

Get the character set of the queue manager.

setReceiveExit *
public void setReceiveExit(String receiveExit)

The name of a class that implements a receive exit.

getReceiveExit *
public String getReceiveExit()

Get the name of the receive exit class.

setReceiveExitInit *
public void setReceiveExitInit(String x)

Initialization string that is passed to the constructor of the receive exit

class.
getReceiveExitInit *
public String getReceiveExitInit()

Get the initialization string that was passed to the receive exit class.
setSecurityExit *
public void setSecurityExit(String securityExit)

The name of a class that implements a security exit.

getSecurityExit *
public String getSecurityExit()

Get the name of the security exit class.

setSecurityExitInit *
public void setSecurityExitInit(String x)

Initialization string that is passed to the security exit constructor.

getSecurityExitInit *
public String getSecurityExitInit()

Get the security exit inittialization string.

setSendExit *
public void setSendExit(String sendExit)

The name of a class that implements a send exit.

getSendExit *
public String getSendExit()

Get the name of the send exit class.

246 MQSeries Using Java

 ConnectionFactory
setSendExitInit *
public void setSendExitInit(String x)

Initialization string that is passed to the constructor of send exit.

getSendExitInit *
public String getSendExitInit()

Get the send exit initialization string.

Chapter 14. JMS interfaces and classes 247

ConnectionMetaData

ConnectionMetaData
public interface ConnectionMetaData

MQSeries class: MQConnectionMetaData

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionMetaData

ConnectionMetaData provides information that describes the connection.

MQSeries constructor
MQConnectionMetaData
public MQConnectionMetaData()

Methods
getJMSVersion
public java.lang.String getJMSVersion() throws JMSException

Get the JMS version.

Returns:
the JMS version.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getJMSMajorVersion
public int getJMSMajorVersion() throws JMSException

Get the JMS major version number.

Returns:
the JMS major version number.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getJMSMinorVersion
public int getJMSMinorVersion() throws JMSException

Get the JMS minor version number.

Returns:
the JMS minor version number.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getJMSXPropertyNames
public java.util.Enumeration getJMSXPropertyNames()
throws JMSException

Get an enumeration of the names of the JMSX Properties supported by this

connection.

248 MQSeries Using Java

 ConnectionMetaData
Returns:
an Enumeration of JMSX PropertyNames.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the property names retrieval.
getJMSProviderName
public java.lang.String getJMSProviderName()
throws JMSException

Get the JMS provider name.

Returns:
the JMS provider name.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getProviderVersion
public java.lang.String getProviderVersion()
throws JMSException

Get the JMS provider version.

Returns:
the JMS provider version.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getProviderMajorVersion
public int getProviderMajorVersion() throws JMSException

Get the JMS provider major version number.

Returns:
the JMS provider major version number.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
getProviderMinorVersion
public int getProviderMinorVersion() throws JMSException

Get the JMS provider minor version number.

Returns:
the JMS provider minor version number.
Throws:
JMSException - if an internal error occurs in JMS implementation
during the metadata retrieval.
toString *
public String toString()
Overrides:
toString in class Object.

Chapter 14. JMS interfaces and classes 249

DeliveryMode

DeliveryMode
public interface DeliveryMode

Delivery modes supported by JMS.

Fields
NON_PERSISTENT
public static final int NON_PERSISTENT

This is the lowest overhead delivery mode because it does not require that
the message be logged to stable storage.
PERSISTENT
public static final int PERSISTENT

This mode instructs the JMS provider to log the message to stable storage
as part of the client’s send operation.

250 MQSeries Using Java

 Destination

Destination
public interface Destination
Subinterfaces: Queue, TemporaryQueue, TemporaryTopic, and Topic

MQSeries class: MQDestination

java.lang.Object
|
+----com.ibm.mq.jms.MQDestination

The Destination object encapsulates provider-specific addresses.

See also: Queue, TemporaryQueue, TemporaryTopic, and Topic

MQSeries constructors
MQDestination
public MQDestination()

Methods
setDescription *
public void setDescription(String x)

A short description of the object.

getDescription *
public String getDescription()

Get the description of the object.

setPriority *
public void setPriority(int priority) throws JMSException

Used to override the priority of all messages sent to this destination.

getPriority *
public int getPriority()

Get the override priority value.

setExpiry *
public void setExpiry(int expiry) throws JMSException

Used to override the expiry of all messages sent to this destination.

getExpiry *
public int getExpiry()

Get the value of the expiry for this destination.

setPersistence *
public void setPersistence(int persistence)
throws JMSException

Used to override the persistence of all messages sent to this destination.

getPersistence *

Chapter 14. JMS interfaces and classes 251

Destination
public int getPersistence()

Get the value of the persistence for this destination.

setTargetClient *
public void setTargetClient(int targetClient)
throws JMSException

Flag to indicate whether or not the remote application is JMS compliant.

getTargetClient *
public int getTargetClient()

Get JMS compliance indicator flag.

setCCSID *
public void setCCSID(int x) throws JMSException

Character set to be used to encode text strings in messages sent to this

destination. See Table 13 on page 105 for a list of allowed values. The
default value is 1208 (UTF8).
getCCSID *
public int getCCSID()

Get the name of the character set that is used by this destination.
setEncoding *
public void setEncoding(int x) throws JMSException

Specifies the encoding to be used for numeric fields in messages sent to

this destination. See Table 13 on page 105 for a list of allowed values.
getEncoding *
public int getEncoding()

Get the encoding that is used for this destination.

252 MQSeries Using Java

 ExceptionListener

ExceptionListener
public interface ExceptionListener

If a JMS provider detects a serious problem with a Connection, it will inform the
Connection’s ExceptionListener if one has been registered. It does this by calling
the listener’s onException() method, passing it a JMSException that describes the
problem.

This allows a client to be asynchronously notified of a problem. Some Connections

only consume messages so they would have no other way to learn their
Connection has failed.

Exceptions are delivered when:

v There is a failure in receiving an asynchronous message
v A message throws a runtime exception

Methods
onException
public void onException(JMSException exception)

Notify user of a JMS exception.

Parameters:
exception - the JMS exception. These are exceptions that result
from asynchronous message delivery. Typically, they indicate a
problem with receiving a message from the queue manager, or
possibly an internal error in the JMS implementation.

Chapter 14. JMS interfaces and classes 253

MapMessage

MapMessage
public interface MapMessage
extends Message

MQSeries class: JMSMapMessage

java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSMapMessage

A MapMessage is used to send a set of name-value pairs where names are Strings
and values are Java primitive types. The entries can be accessed sequentially or
randomly by name. The order of the entries is undefined.

See also: BytesMessage, Message, ObjectMessage, StreamMessage, and

TextMessage

Methods
getBoolean
public boolean getBoolean(java.lang.String name)
throws JMSException

Return the boolean value with the given name.

Parameters:
name - the name of the boolean
Returns:
the boolean value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getByte
public byte getByte(java.lang.String name)
throws JMSException

Return the byte value with the given name.

Parameters:
name - the name of the byte.
Returns:
the byte value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.

254 MQSeries Using Java

 MapMessage
getShort
public short getShort(java.lang.String name) throws JMSException

Return the short value with the given name.

Parameters:
name - the name of the short.
Returns:
the short value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getChar
public char getChar(java.lang.String name)
throws JMSException

Return the Unicode character value with the given name.

Parameters:
name - the name of the Unicode character.
Returns:
the Unicode character value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getInt
public int getInt(java.lang.String name)
throws JMSException

Return the integer value with the given name.

Parameters:
name - the name of the integer.
Returns:
the integer value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getLong
public long getLong(java.lang.String name)
throws JMSException

Return the long value with the given name.

Parameters:
name - the name of the long.
Returns:
the long value with the given name.

Chapter 14. JMS interfaces and classes 255

MapMessage
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getFloat
public float getFloat(java.lang.String name) throws JMSException

Return the float value with the given name.

Parameters:
name - the name of the float.
Returns:
the float value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getDouble
public double getDouble(java.lang.String name) throws JMSException

Return the double value with the given name.

Parameters:
name - the name of the double.
Returns:
the double value with the given name.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getString
public java.lang.String getString(java.lang.String name)
throws JMSException

Return the String value with the given name.

Parameters:
name - the name of the String.
Returns:
the String value with the given name. If there is no item by this
name, a null value is returned.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getBytes
public byte[] getBytes(java.lang.String name) throws JMSException

Return the byte array value with the given name.

256 MQSeries Using Java

 MapMessage
Parameters:
name - the name of the byte array.
Returns:
a copy of the byte array value with the given name. If there is no
item by this name, a null value is returned.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getObject
public java.lang.Object getObject(java.lang.String name)
throws JMSException

Return the Java object value with the given name. This method returns in
object format, a value that has been stored in the Map either using the
setObject method call, or the equivalent primitive set method.
Parameters:
name - the name of the Java object.
Returns:
a copy of the Java object value with the given name, in object
format (if it is set as an int, then a Integer is returned). If there is
no item by this name, a null value is returned.
Throws:
JMSException - if JMS fails to read the message because of an
internal JMS error.
getMapNames
public java.util.Enumeration getMapNames() throws JMSException

Return an Enumeration of all the Map message’s names.

Returns:
an enumeration of all the names in this Map message.
Throws:
JMSException - if JMS fails to read the message because of an
internal JMS error.
setBoolean
public void setBoolean(java.lang.String name,
boolean value) throws JMSException

Set a boolean value with the given name into the Map.
Parameters:
v name - the name of the boolean.
v value - the boolean value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

Chapter 14. JMS interfaces and classes 257

MapMessage
setByte
public void setByte(java.lang.String name,
byte value) throws JMSException

Set a byte value with the given name into the Map.
Parameters:
v name - the name of the byte.
v value - the byte value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error
v MessageNotWriteableException - if the message is in read-only
mode.
setShort
public void setShort(java.lang.String name,
short value) throws JMSException

Set a short value with the given name into the Map.
Parameters:
v name - the name of the short.
v value - the short value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setChar
public void setChar(java.lang.String name,
char value) throws JMSException

Set a Unicode character value with the given name into the Map.
Parameters:
v name - the name of the Unicode character.
v value - the Unicode character value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setInt
public void setInt(java.lang.String name,
int value) throws JMSException

Set an integer value with the given name into the Map.
Parameters:
v name - the name of the integer.
v value - the integer value to set in the Map.

258 MQSeries Using Java

 MapMessage
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setLong
public void setLong(java.lang.String name,
long value) throws JMSException

Set a long value with the given name into the Map.
Parameters:
v name - the name of the long.
v value - the long value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setFloat
public void setFloat(java.lang.String name,
float value) throws JMSException

Set a float value with the given name into the Map.
Parameters:
v name - the name of the float.
v value - the float value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setDouble
public void setDouble(java.lang.String name,
double value) throws JMSException

Set a double value with the given name into the Map.
Parameters:
v name - the name of the double.
v value - the double value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

Chapter 14. JMS interfaces and classes 259

MapMessage
setString
public void setString(java.lang.String name,
java.lang.String value) throws JMSException

Set a String value with the given name into the Map.
Parameters:
v name - the name of the String.
v value - the String value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setBytes
public void setBytes(java.lang.String name,
byte[] value) throws JMSException

Set a byte array value with the given name into the Map.
Parameters:
v name - the name of the byte array.
v value - the byte array value to set in the Map.
The array is copied, so the value in the map is not altered by
subsequent modifications to the array.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
setBytes
public void setBytes(java.lang.String name,
byte[] value,
int offset,
int length) throws JMSException

Set a portion of the byte array value with the given name into the Map.

The array is copied, so the value in the map is not altered by subsequent
modifications to the array.
Parameters:
v name - the name of the byte array.
v value - the byte array value to set in the Map.
v offset - the initial offset within the byte array.
v length - the number of bytes to be copied.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

260 MQSeries Using Java

 MapMessage
setObject
public void setObject(java.lang.String name,
java.lang.Object value) throws JMSException

Set a Java object value with the given name into the Map. This method
only works for object primitive types (Integer, Double, Long, for example),
Strings and byte arrays.
Parameters:
v name - the name of the Java object.
v value - the Java object value to set in the Map.
Throws:
v JMSException - if JMS fails to write message due to some
internal JMS error.
v MessageFormatException - if object is invalid.
v MessageNotWriteableException - if the message is in read-only
mode.
itemExists
public boolean itemExists(java.lang.String name)
throws JMSException

Check if an item exists in this MapMessage.

Parameters:
name - the name of the item to test.
Returns:
true if the item does exist.
Throws:
JMSException - if a JMS error occurs.

Chapter 14. JMS interfaces and classes 261

Message

Message
public interface Message
Subinterfaces: BytesMessage, MapMessage, ObjectMessage,
StreamMessage, and TextMessage

MQSeries class: JMSMessage

java.lang.Object
|
+----com.ibm.jms.MQJMSMessage

The Message interface is the root interface of all JMS messages. It defines the JMS
header and the acknowledge method used for all messages.

Fields
DEFAULT_DELIVERY_MODE
public static final int DEFAULT_DELIVERY_MODE

The default delivery mode value.

DEFAULT_PRIORITY
public static final int DEFAULT_PRIORITY

The default priority value.

DEFAULT_TIME_TO_LIVE
public static final long DEFAULT_TIME_TO_LIVE

The default time to live value.

Methods
getJMSMessageID
public java.lang.String getJMSMessageID()
throws JMSException

Get the message ID.

Returns:
the message ID.
Throws:
JMSException - if JMS fails to get the message ID because of an
internal JMS error.
See also:
setJMSMessageID()
setJMSMessageID
public void setJMSMessageID(java.lang.String id)
throws JMSException

Set the message ID.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.

262 MQSeries Using Java

 Message
Parameters:
id - the ID of the message.
Throws:
JMSException - if JMS fails to set the message ID because of an
internal JMS error.
See also:
getJMSMessageID()
getJMSTimestamp
public long getJMSTimestamp() throws JMSException

Get the message timestamp.

Returns:
the message timestamp.
Throws:
JMSException - if JMS fails to get the Timestamp because of an
internal JMS error.
See also:
setJMSTimestamp()
setJMSTimestamp
public void setJMSTimestamp(long timestamp)
throws JMSException

Set the message timestamp.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.
Parameters:
timestamp - the timestamp for this message.
Throws:
JMSException - if JMS fails to set the timestamp because of an
internal JMS error.
See also:
getJMSTimestamp()
getJMSCorrelationIDAsBytes
public byte[] getJMSCorrelationIDAsBytes()
throws JMSException

Get the correlation ID as an array of bytes for the message.

Returns:
the correlation ID of a message as an array of bytes.
Throws:
JMSException - if JMS fails to get correlation ID because of an
internal JMS error.
See also:
setJMSCorrelationID(), getJMSCorrelationID(),
setJMSCorrelationIDAsBytes()

Chapter 14. JMS interfaces and classes 263

Message
setJMSCorrelationIDAsBytes
public void setJMSCorrelationIDAsBytes(byte[]
correlationID)
throws JMSException

Set the correlation ID as an array of bytes for the message. A client can use
this call to set the correlationID equal either to a messageID from a
previous message, or to an application-specific string. Application-specific
strings must not start with the characters ID:
Parameters:
correlationID - the correlation ID as a string, or the message ID of
a message being referred to.
Throws:
JMSException - if JMS fails to set the correlation ID because of an
internal JMS error.
See also:
setJMSCorrelationID(), getJMSCorrelationID(),
getJMSCorrelationIDAsBytes()
getJMSCorrelationID
public java.lang.String getJMSCorrelationID()
throws JMSException

Get the correlation ID for the message.

Returns:
the correlation ID of a message as a String.
Throws:
JMSException - if JMS fails to get the correlation ID because of an
internal JMS error.
See also:
setJMSCorrelationID(), getJMSCorrelationIDAsBytes(),
setJMSCorrelationIDAsBytes()
setJMSCorrelationID
public void setJMSCorrelationID
(java.lang.String correlationID)
throws JMSException

Set the correlation ID for the message.

A client can use the JMSCorrelationID header field to link one message
with another. A typical use is to link a response message with its request
message.

Note: The use of a byte[] value for JMSCorrelationID is non-portable.

Parameters:
correlationID - the message ID of a message being referred
to.
Throws:
JMSException - if JMS fails to set the correlation ID because
of an internal JMS error.

264 MQSeries Using Java

 Message
See also:
getJMSCorrelationID(), getJMSCorrelationIDAsBytes(),
setJMSCorrelationIDAsBytes()
getJMSReplyTo
public Destination getJMSReplyTo() throws JMSException

Get where a reply to this message should be sent.

Returns:
where to send a response to this message
Throws:
JMSException - if JMS fails to get ReplyTo Destination because of
an internal JMS error.
See also:
setJMSReplyTo()
setJMSReplyTo
public void setJMSReplyTo(Destination replyTo)
throws JMSException

Set where a reply to this message should be sent.

Parameters:
replyTo - where to send a response to this message. A null value
indicates that no reply is expected.
Throws:
JMSException - if JMS fails to set ReplyTo Destination because of
an internal JMS error.
See also:
getJMSReplyTo()
getJMSDestination
public Destination getJMSDestination() throws JMSException

Get the destination for this message.

Returns:
the destination of this message.
Throws:
JMSException - if JMS fails to get JMS Destination because of an
internal JMS error.
See also:
setJMSDestination()
setJMSDestination
public void setJMSDestination(Destination destination)
throws JMSexception

Set the destination for this message.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.
Parameters:
destination - the destination for this message.

Chapter 14. JMS interfaces and classes 265

Message
Throws:
JMSException - if JMS fails to set JMS Destination because of an
internal JMS error.
See also:
getJMSDestination()
getJMSDeliveryMode
public int getJMSDeliveryMode() throws JMSException

Get the delivery mode for this message.

Returns:
the delivery mode of this message.
Throws:
JMSException - if JMS fails to get JMS DeliveryMode because of an
internal JMS error.
See also:
setJMSDeliveryMode(), DeliveryMode
setJMSDeliveryMode
public void setJMSDeliveryMode(int deliveryMode)
throws JMSException

Set the delivery mode for this message.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.

To alter the delivery mode when a message is sent, use the

setDeliveryMode method on the QueueSender or TopicPublisher (this
method is inherited from MessageProducer).
Parameters:
deliveryMode - the delivery mode for this message.
Throws:
JMSException - if JMS fails to set JMS DeliveryMode because of an
internal JMS error.
See also:
getJMSDeliveryMode(), DeliveryMode
getJMSRedelivered
public boolean getJMSRedelivered() throws JMSException

Get an indication of whether this message is being redelivered.

If a client receives a message with the redelivered indicator set, it is likely,

but not guaranteed, that this message was delivered to the client earlier
but the client did not acknowledge its receipt at that earlier time.
Returns:
set to true if this message is being redelivered.
Throws:
JMSException - if JMS fails to get JMS Redelivered flag because of
an internal JMS error.

266 MQSeries Using Java

 Message
See also:
setJMSRedelivered()
setJMSRedelivered
public void setJMSRedelivered(boolean redelivered)
throws JMSException

Set to indicate whether this message is being redelivered.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.
Parameters:
redelivered - an indication of whether this message is being
redelivered.
Throws:
JMSException - if JMS fails to set JMSRedelivered flag because of
an internal JMS error.
See also:
getJMSRedelivered()
getJMSType
public java.lang.String getJMSType() throws JMSException

Get the message type.

Returns:
the message type.
Throws:
JMSException - if JMS fails to get JMS message type because of an
internal JMS error.
See also:
setJMSType()
setJMSType
public void setJMSType(java.lang.String type)
throws JMSException

Set the message type.

JMS clients should assign a value to type whether the application makes
use of it or not. This ensures that it is properly set for those providers that
require it.
Parameters:
type - the class of message.
Throws:
JMSException - if JMS fails to set JMS message type because of an
internal JMS error.
See also:
getJMSType()
getJMSExpiration
public long getJMSExpiration() throws JMSException

Get the message’s expiration value.

Chapter 14. JMS interfaces and classes 267

Message
Returns:
the time the message expires. It is the sum of the time-to-live value
specified by the client, and the GMT at the time of the send.
Throws:
JMSException - if JMS fails to get JMS message expiration because
of an internal JMS error.
See also:
setJMSExpiration()
setJMSExpiration
public void setJMSExpiration(long expiration)
throws JMSException

Set the message’s expiration value.

Any value set using this method is ignored when the message is sent, but
this method can be used to change the value in a received message.
Parameters:
expiration - the message’s expiration time.
Throws:
JMSException - if JMS fails to set JMS message expiration because
of an internal JMS error.
See also:
getJMSExpiration()
getJMSPriority
public int getJMSPriority() throws JMSException

Get the message priority.

Returns:
the message priority.
Throws:
JMSException - if JMS fails to get JMS message priority because of
an internal JMS error.
See also:
setJMSPriority() for priority levels
setJMSPriority
public void setJMSPriority(int priority)
throws JMSException

Set the priority for this message.

JMS defines a ten level priority value, with 0 as the lowest priority, and 9
as the highest. In addition, clients should consider priorities 0-4 as
gradations of normal priority, and priorities 5-9 as gradations of expedited
priority.
Parameters:
priority - the priority of this message.
Throws:
JMSException - if JMS fails to set JMS message priority because of
an internal JMS error.

268 MQSeries Using Java

 Message
See also:
getJMSPriority()
clearProperties
public void clearProperties() throws JMSException

Clear a message’s properties. The header fields and message body are not
cleared.
Throws:
JMSException - if JMS fails to clear JMS message properties
because of an internal JMS error.
propertyExists
public boolean propertyExists(java.lang.String name)
throws JMSException

Check if a property value exists.

Parameters:
name - the name of the property to test.
Returns:
true if the property does exist.
Throws:
JMSException - if JMS fails to check whether a property exists
because of an internal JMS error.
getBooleanProperty
public boolean getBooleanProperty(java.lang.String name)
throws JMSException

Return the boolean property value with the given name.

Parameters:
name - the name of the boolean property.
Returns:
the boolean property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid
getByteProperty
public byte getByteProperty(java.lang.String name)
throws JMSException

Return the byte property value with the given name.

Parameters:
name - the name of the byte property.
Returns:
the byte property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.

Chapter 14. JMS interfaces and classes 269

Message
getShortProperty
public short getShortProperty(java.lang.String name)
throws JMSException

Return the short property value with the given name.

Parameters:
name - the name of the short property.
Returns:
the short property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getIntProperty
public int getIntProperty(java.lang.String name)
throws JMSException

Return the integer property value with the given name.

Parameters:
name - the name of the integer property.
Returns:
the integer property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getLongProperty
public long getLongProperty(java.lang.String name)
throws JMSException

Return the long property value with the given name.

Parameters:
name - the name of the long property.
Returns:
the long property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getFloatProperty
public float getFloatProperty(java.lang.String name)
throws JMSException

Return the float property value with the given name.

Parameters:
name - the name of the float property.

270 MQSeries Using Java

 Message
Returns:
the float property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getDoubleProperty
public double getDoubleProperty(java.lang.String name)
throws JMSException

Return the double property value with the given name.

Parameters:
name - the name of the double property.
Returns:
the double property value with the given name.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getStringProperty
public java.lang.String getStringProperty (java.lang.String name)
throws JMSException

Return the String property value with the given name.

Parameters:
name - the name of the String property
Returns:
the String property value with the given name. If there is no
property by this name, a null value is returned.
Throws:
v JMSException - if JMS fails to get the property because of an
internal JMS error.
v MessageFormatException - if this type conversion is invalid.
getObjectProperty
public java.lang.Object getObjectProperty (java.lang.String name)
throws JMSException

Return the Java object property value with the given name.
Parameters:
name - the name of the Java object property.
Returns:
the Java object property value with the given name, in object
format (for example, if it set as an int, an Integer is returned). If
there is no property by this name, a null value is returned.
Throws:
JMSException - if JMS fails to get the property because of an
internal JMS error.

Chapter 14. JMS interfaces and classes 271

Message
getPropertyNames
public java.util.Enumeration getPropertyNames()
throws JMSException

Return an Enumeration of all the property names.

Returns:
an enumeration of all the names of property values.
Throws:
JMSException - if JMS fails to get the property names because of
an internal JMS error.
setBooleanProperty
public void setBooleanProperty(java.lang.String name,
boolean value) throws JMSException

Set a boolean property value with the given name into the Message.
Parameters:
v name - the name of the boolean property.
v value - the boolean property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageNotWriteableException - if the properties are read-only.
setByteProperty
public void setByteProperty(java.lang.String name,
byte value) throws JMSException

Set a byte property value with the given name into the Message.
Parameters:
v name - the name of the byte property.
v value - the byte property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageNotWriteableException - if the properties are read-only.
setShortProperty
public void setShortProperty(java.lang.String name,
short value) throws JMSException

Set a short property value with the given name into the Message.
Parameters:
v name - the name of the short property.
v value - the short property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageNotWriteableException - if the properties are read-only.

272 MQSeries Using Java

 Message
setIntProperty
public void setIntProperty(java.lang.String name,
int value) throws JMSException

Set an integer property value with the given name into the Message.
Parameters:
v name - the name of the integer property.
v value - the integer property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageNotWriteableException - if the properties are read-only.
setLongProperty
public void setLongProperty(java.lang.String name,
long value) throws JMSException

Set a long property value with the given name into the Message.
Parameters:
v name - the name of the long property.
v value - the long property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageNotWriteableException - if the properties are read-only.
setFloatProperty
public void setFloatProperty(java.lang.String name,
float value) throws JMSException

Set a float property value with the given name into the Message.
Parameters:
v name - the name of the float property.
v value - the float property value to set in the Message.
Throws:
v JMSException - if JMS fails to set the property because of an
internal JMS error.
v MessageNotWriteableException - if the properties are read-only.
setDoubleProperty
public void setDoubleProperty(java.lang.String name,
double value) throws JMSException

Set a double property value with the given name into the Message.
Parameters:
v name - the name of the double property.
v value - the double property value to set in the Message.

Chapter 14. JMS interfaces and classes 273

Message
Throws:
v JMSException - if JMS fails to set the property because of an
internal JMS error.
v MessageNotWriteableException - if the properties are read-only.
setStringProperty
public void setStringProperty(java.lang.String name,
java.lang.String value) throws JMSException

Set a String property value with the given name into the Message.
Parameters:
v name - the name of the String property.
v value - the String property value to set in the Message.
Throws:
v JMSException - if JMS fails to set the property because of an
internal JMS error.
v MessageNotWriteableException - if the properties are read-only.
setObjectProperty
public void setObjectProperty(java.lang.String name,
java.lang.Object value) throws JMSException

Set a property value with the given name into the Message.
Parameters:
v name - the name of the Java object property.
v value - the Java object property value to set in the Message.
Throws:
v JMSException - if JMS fails to set Property because of an internal
JMS error.
v MessageFormatException - if the object is invalid.
v MessageNotWriteableException - if the properties are read-only.
acknowledge
public void acknowledge() throws JMSException

Acknowledge this and all previous messages received by the session.

Throws:
JMSException - if JMS fails to acknowledge because of an internal
JMS error.
clearBody
public void clearBody() throws JMSException

Clear out the message body. All other parts of the message are left
untouched.
Throws:
JMSException - if JMS fails to because of an internal JMS error.

274 MQSeries Using Java

 MessageConsumer

MessageConsumer
public interface MessageConsumer
Subinterfaces: QueueReceiver and TopicSubscriber

MQSeries class: MQMessageConsumer

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageConsumer

The parent interface for all message consumers. A client uses a message consumer
to receive messages from a Destination.

Methods
getMessageSelector
public java.lang.String getMessageSelector()
throws JMSException

Get this message consumer’s message selector expression.

Returns:
this message consumer’s message selector.
Throws:
JMSException - if JMS fails to get the message selector because of a
JMS error.
getMessageListener
public MessageListener getMessageListener()
throws JMSException

Get the message consumer’s MessageListener.

Returns:
the listener for the message consumer, or null if a listener is not
set.
Throws:
JMSException - if JMS fails to get the message listener because of a
JMS error.
See also:
setMessageListener
setMessageListener
public void setMessageListener(MessageListener listener)
throws JMSException

Set the message consumer’s MessageListener.

Parameters:
messageListener - the messages are delivered to this listener.
Throws:
JMSException - if JMS fails to set message listener because of a JMS
error.
See also:
getMessageListener

Chapter 14. JMS interfaces and classes 275

MessageConsumer
receive
public Message receive() throws JMSException

Receive the next message produced for this message consumer.

Returns:
the next message produced for this message consumer.
Throws:
JMSException - if JMS fails to receive the next message because of
an error.
receive
public Message receive(long timeOut) throws JMSException

Receive the next message that arrives within the specified timeout interval.
A timeout value of zero causes the call to wait indefinitely until a message
arrives.
Parameters:
timeout - the timeout value (in milliseconds).
Returns:
the next message produced for this message consumer, or null if
one is not available.
Throws:
JMSException - if JMS fails to receive the next message because of
an error.
receiveNoWait
public Message receiveNoWait() throws JMSException

Receive the next message if one is immediately available.

Returns:
the next message produced for this message consumer, or null if
one is not available.
Throws:
JMSException - if JMS fails to receive the next message because of
an error.
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a MessageConsumer, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.

This call blocks until a receive or message listener in progress has

completed.
Throws:
JMSException - if JMS fails to close the consumer because of an
error.

276 MQSeries Using Java

 MessageListener

MessageListener
public interface MessageListener

A MessageListener is used to receive asynchronously delivered messages.

Methods
onMessage
public void onMessage(Message message)

Pass a message to the Listener.

Parameters:
message - the message passed to the listener.
See also
Session.setMessageListener

Chapter 14. JMS interfaces and classes 277

MessageProducer

MessageProducer
public interface MessageProducer
Subinterfaces: QueueSender and TopicPublisher

MQSeries class: MQMessageProducer

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageProducer

A client uses a message producer to send messages to a Destination.

MQSeries constructors
MQMessageProducer
public MQMessageProducer()

Methods
setDisableMessageID
public void setDisableMessageID(boolean value)
throws JMSException

Set whether message IDs are disabled.

Message IDs are enabled by default.

Note: This method is ignored in the MQSeries classes for Java Message
Service implementation.
Parameters:
value - indicates whether message IDs are disabled.
Throws:
JMSException - if JMS fails to set the disabled message ID
because of an internal error.
getDisableMessageID
public boolean getDisableMessageID() throws JMSException

Get an indication of whether message IDs are disabled.

Returns:
an indication of whether message IDs are disabled.
Throws:
JMSException - if JMS fails to get the disabled message ID because
of an internal error.
setDisableMessageTimestamp
public void setDisableMessageTimestamp(boolean value)
throws JMSException

Set whether message timestamps are disabled.

Message timestamps are enabled by default.

278 MQSeries Using Java

 MessageProducer
Note: This method is ignored in the MQSeries classes for Java Message
Service implementation.
Parameters:
value - indicates whether message timestamps are disabled.
Throws:
JMSException - if JMS fails to set the disabled message
timestamp because of an internal error.
getDisableMessageTimestamp
public boolean getDisableMessageTimestamp()
throws JMSException

Get an indication of whether message timestamps are disabled.

Returns:
an indication of whether message IDs are disabled.
Throws:
JMSException - if JMS fails to get the disabled message timestamp
because of an internal error.
setDeliveryMode
public void setDeliveryMode(int deliveryMode)
throws JMSException

Set the producer’s default delivery mode.

| Delivery mode is set to DeliveryMode.PERSISTENT by default.

Parameters:
deliveryMode - the message delivery mode for this message
producer.
Throws:
JMSException - if JMS fails to set the delivery mode because of an
internal error.
See also:
| getDeliveryMode, DeliveryMode.NON_PERSISTENT,
| DeliveryMode.PERSISTENT
getDeliveryMode
public int getDeliveryMode() throws JMSException

Get the producer’s default delivery mode.

Returns:
the message delivery mode for this message producer.
Throws:
JMSException - if JMS fails to get the delivery mode because of an
internal error.
See also:
setDeliveryMode
setPriority
public void setPriority(int priority) throws JMSException

Set the producer’s default priority.

Chapter 14. JMS interfaces and classes 279

MessageProducer
Priority is set to 4, by default.
Parameters:
priority - the message priority for this message producer.
Throws:
JMSException - if JMS fails to set the priority because of an internal
error.
See also:
getPriority
getPriority
public int getPriority() throws JMSException

Get the producer’s default priority.

Returns:
the message priority for this message producer.
Throws:
JMSException - if JMS fails to get the priority because of an
internal error.
See also:
setPriority
setTimeToLive
public void setTimeToLive(long timeToLive)
throws JMSException

Set the default length of time, in milliseconds from its dispatch time, that a
produced message should be retained by the message system.

Time to live is set to zero by default.

Parameters:
timeToLive - the message time to live in milliseconds; zero is
unlimited.
Throws:
JMSException - if JMS fails to set the Time to Live because of an
internal error.
See also:
getTimeToLive
getTimeToLive
public long getTimeToLive() throws JMSException

Get the default length of time in milliseconds from its dispatch time that a
produced message should be retained by the message system.
Returns:
the message time to live in milliseconds; zero is unlimited.
Throws:
JMSException - if JMS fails to get the Time to Live because of an
internal error.
See also:
setTimeToLive

280 MQSeries Using Java

 MessageProducer
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a MessageProducer, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.
Throws:
JMSException - if JMS fails to close the producer because of an
error.

Chapter 14. JMS interfaces and classes 281

MQQueueEnumeration

MQQueueEnumeration *
public class MQQueueEnumeration
extends Object
implements Enumeration

java.lang.Object
|
+----com.ibm.mq.jms.MQQueueEnumeration

Enumeration of messages on a queue. This class is not defined in the JMS

specification, it is created by calling the getEnumeration method of
MQQueueBrowser. The class contains a base MQQueue instance to hold the
browse cursor. The queue is closed once the cursor has moved off the end of the
queue.

There is no way to reset an instance of this class - it acts as a ’one-shot’

mechanism.

See also: MQQueueBrowser

Methods
hasMoreElements
public boolean hasMoreElements()

Indicate whether another message can be returned.

nextElement
public Object nextElement() throws NoSuchElementException

Return the current message.

If hasMoreElements() returns ’true’, nextElement() always returns a

message. It is possible for the returned message to pass its expiry date
between the hasMoreElements() and the nextElement calls.

282 MQSeries Using Java

 ObjectMessage

ObjectMessage
public interface ObjectMessage
extends Message

MQSeries class: JMSObjectMessage

java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSObjectMessage

An ObjectMessage is used to send a message that contains a serializable Java

object. It inherits from Message and adds a body containing a single Java reference.
Only Serializable Java objects can be used.

See also: BytesMessage, MapMessage, Message, StreamMessage and TextMessage

Methods
setObject
public void setObject(java.io.Serializable object)
throws JMSException

Set the serializable object containing this message’s data. The

ObjectMessage contains a snapshot of the object at the time setObject() is
called. Subsequent modifications of the object have no effect on the
ObjectMessage body.
Parameters:
object - the message’s data.
Throws:
v JMSException - if JMS fails to set the object because of an
internal JMS error.
v MessageFormatException - if object serialization fails.
v MessageNotWriteableException - if the message is in read-only
mode.
getObject
public java.io.Serializable getObject()
throws JMSException

Get the serializable object containing this message’s data. The default value
is null.
Returns:
the serializable object containing this message’s data.
Throws:
v JMSException - if JMS fails to get the object because of an
internal JMS error.
v MessageFormatException - if object deserialization fails.

Chapter 14. JMS interfaces and classes 283

Queue

Queue
public interface Queue
extends Destination
Subinterfaces: TemporaryQueue

MQSeries class: MQQueue

java.lang.Object
|
+----com.ibm.mq.jms.MQDestination
|
+----com.ibm.mq.jms.MQQueue

A Queue object encapsulates a provider-specific queue name. It is the way a client

specifies the identity of a queue to JMS methods.

MQSeries constructors
MQQueue *
public MQQueue()

Default constructor for use by the administration tool.

MQQueue *
public MQQueue(String URIqueue)

Create a new MQQueue instance. The string takes a URI format, as

described on page 173.
MQQueue *
public MQQueue(String queueManagerName,
String queueName)

Methods
getQueueName
public java.lang.String getQueueName()
throws JMSException

Get the name of this queue.

Clients that depend upon the name are not portable.

Returns:
the queue name
Throws:
JMSException - if JMS implementation for Queue fails to return the
queue name because of an internal error.
toString
public java.lang.String toString()

Return a pretty printed version of the queue name.

Returns:
the provider-specific identity values for this queue.

284 MQSeries Using Java

 Queue
Overrides:
toString in class java.lang.Object
getReference *
public Reference getReference() throws NamingException

Create a reference for this queue.

Returns:
a reference for this object
Throws:
NamingException
setBaseQueueName *
public void setBaseQueueName(String x) throws JMSException

Set the value of the MQSeries queue name.

Note: This method should only be used by the administration tool. It

makes no attempt to decode queue:qmgr:queue format strings.
getBaseQueueName *
public String getBaseQueueName()
Returns:
the value of the MQSeries Queue name.
setBaseQueueManagerName *
public void setBaseQueueManagerName(String x) throws JMSException

Set the value of the MQSeries queue manager name.

Note: This method should only be used by the administration tool.

getBaseQueueManagerName *
public String getBaseQueueManagerName()
Returns:
the value of the MQSeries Queue manager name.

Chapter 14. JMS interfaces and classes 285

QueueBrowser

QueueBrowser
public interface QueueBrowser

MQSeries class: MQQueueBrowser

java.lang.Object
|
+----com.ibm.mq.jms.MQQueueBrowser

A client uses a QueueBrowser to look at messages on a queue without removing

them.

Note: The MQSeries class MQQueueEnumeration is used to hold the browse

cursor.

See also: QueueReceiver

Methods
getQueue
public Queue getQueue() throws JMSException

Get the queue associated with this queue browser.

Returns:
the queue.
Throws:
JMSException - if JMS fails to get the queue associated with this
Browser because of a JMS error.
getMessageSelector
public java.lang.String getMessageSelector() throws JMSException

Get this queue browser’s message selector expression.

Returns:
this queue browser’s message selector.
Throws:
JMSException - if JMS fails to get the message selector for this
browser because of a JMS error.
getEnumeration
public java.util.Enumeration getEnumeration() throws JMSException

Get an enumeration for browsing the current queue messages in the order
that they would be received.
Returns:
an enumeration for browsing the messages.
Throws:
JMSException - if JMS fails to get the enumeration for this browser
because of a JMS error.

Note: If the browser is created for a nonexistent queue, this is not

detected until the first call to getEnumeration.

286 MQSeries Using Java

 QueueBrowser
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a QueueBrowser, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.
Throws:
JMSException - if a JMS fails to close this Browser because of a
JMS error.

Chapter 14. JMS interfaces and classes 287

QueueConnection

QueueConnection
public interface QueueConnection
extends Connection
Subinterfaces: XAQueueConnection

MQSeries class: MQQueueConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQConnection
|
+----com.ibm.mq.jms.MQQueueConnection

A QueueConnection is an active connection to a JMS point-to-point provider. A

client uses a QueueConnection to create one or more QueueSessions for producing
and consuming messages.

See also: Connection, QueueConnectionFactory, and XAQueueConnection

Methods
createQueueSession
public QueueSession createQueueSession(boolean transacted,
int acknowledgeMode)
throws JMSException

Create a QueueSession.
Parameters:
v transacted - if true, the session is transacted.
v acknowledgeMode - indicates whether the consumer or the
client will acknowledge any messages it receives. Possible values
are:
Session.AUTO_ACKNOWLEDGE
Session.CLIENT_ACKNOWLEDGE
Session.DUPS_OK_ACKNOWLEDGE
This parameter is ignored if the session is transacted.
Returns:
a newly created queue session.
Throws:
JMSException - if JMS Connection fails to create a session because
of an internal error, or lack of support for specific transaction and
acknowledgement mode.
createConnectionConsumer
public ConnectionConsumer createConnectionConsumer
(Queue queue,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
throws JMSException

Create a connection consumer for this connection. This is an expert facility

that is not used by regular JMS clients.

288 MQSeries Using Java

 QueueConnection
Parameters:
v queue - the queue to access.
v messageSelector - only messages with properties that match the
message selector expression are delivered.
v sessionPool - the server session pool to associate with this
connection consumer.
v maxMessages - the maximum number of messages that can be
assigned to a server session at one time.
Returns:
the connection consumer.
Throws:
v JMSException - if the JMS Connection fails to create a connection
consumer because of an internal error, or invalid arguments for
sessionPool and messageSelector.
v InvalidSelectorException - if the message selector is invalid.
See Also:
ConnectionConsumer
close *
public void close() throws JMSException
Overrides:
close in class MQConnection.

Chapter 14. JMS interfaces and classes 289

QueueConnectionFactory

QueueConnectionFactory
public interface QueueConnectionFactory
extends ConnectionFactory
Subinterfaces: XAQueueConnectionFactory

MQSeries class: MQQueueConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionFactory
|
+----com.ibm.mq.jms.MQQueueConnectionFactory

A client uses a QueueConnectionFactory to create QueueConnections with a JMS

point-to-point provider.

See also: ConnectionFactory and XAQueueConnectionFactory

MQSeries constructor
MQQueueConnectionFactory
public MQQueueConnectionFactory()

Methods
createQueueConnection
public QueueConnection createQueueConnection()
throws JMSException

Create a queue connection with default user identity. The connection is

created in stopped mode. No messages will be delivered until
Connection.start method is explicitly called.
Returns:
a newly created queue connection.
Throws:
v JMSException - if JMS Provider fails to create Queue Connection
because of an internal error.
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.
createQueueConnection
public QueueConnection createQueueConnection
(java.lang.String userName,
java.lang.String password)
throws JMSException

Create a queue connection with specified user identity.

Note: This method can be used only with transport type

JMSC.MQJMS_TP_CLIENT_MQ_TCPIP (see ConnectionFactory). The
connection is created in stopped mode. No messages will be
delivered until Connection.start method is explicitly called.

290 MQSeries Using Java

 QueueConnectionFactory
Parameters:
v userName - the caller’s user name.
v password - the caller’s password.
Returns:
a newly created queue connection.
Throws:
v JMSException - if JMS Provider fails to create Queue
Connection because of an internal error.
v JMSSecurityException - if client authentication fails
because of an invalid user name or password.
setTemporaryModel *
public void setTemporaryModel(String x) throws JMSException
getTemporaryModel *
public String getTemporaryModel()
getReference *
public Reference getReference() throws NamingException

Create a reference for this queue connection factory .

Returns:
a reference for this object.
Throws:
NamingException.
| setMessageRetention*
public void setMessageRetention(int x) throws JMSException

Set method for messageRetention attribute.

Parameters:
Valid values are:
v JMSC.MQJMS_MRET_YES - unwanted messages remain on the
input queue.
v JMSC.MQJMS_MRET_NO - uwanted messages are dealt with
according to their disposition options.
| getMessageRetention*
| public int getMessageRetention()

Get method for messageRetention attribute.

Returns:
v JMSC.MQJMS_MRET_YES - unwanted messages remain on the
input queue.
v JMSC.MQJMS_MRET_NO - uwanted messages are dealt with
according to their disposition options.

Chapter 14. JMS interfaces and classes 291

QueueReceiver

QueueReceiver
public interface QueueReceiver
extends MessageConsumer

MQSeries class: MQQueueReceiver

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageConsumer
|
+----com.ibm.mq.jms.MQQueueReceiver

A client uses a QueueReceiver for receiving messages that have been delivered to a
queue.

See also: MessageConsumer

This class inherits the following methods from MQMessageConsumer.

v receive
v receiveNoWait
v close
v getMessageListener
v setMessageListener

Methods
getQueue
public Queue getQueue() throws JMSException

Get the queue associated with this queue receiver.

Returns:
the queue.
Throws:
JMSException - if JMS fails to get queue for this queue receiver
because of an internal error.

292 MQSeries Using Java

 QueueRequestor

QueueRequestor
public class QueueRequestor
extends java.lang.Object

java.lang.Object
|
+----javax.jms.QueueRequestor

JMS provides this QueueRequestor helper class to simplify making service

requests. The QueueRequestor constructor is given a non-transacted QueueSession
and a destination Queue. It creates a TemporaryQueue for the responses, and
provides a request() method that sends the request message and waits for its reply.
Users are free to create more sophisticated versions.

See also: TopicRequestor

Constructors
QueueRequestor
public QueueRequestor(QueueSession session,
Queue queue)
throws JMSException

This implementation assumes that the session parameter is non-transacted

and either AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE.
Parameters:
v session - the queue session the queue belongs to.
v queue - the queue to perform the request/reply call on.
Throws:
JMSException - if a JMS error occurs.

Methods
request
public Message request(Message message)
throws JMSException

Send a request and wait for a reply. The temporary queue is used for
replyTo, and only one reply per request is expected.
Parameters:
message - the message to send.
Returns:
the reply message.
Throws:
JMSException - if a JMS error occurs.

Chapter 14. JMS interfaces and classes 293

QueueRequestor
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a QueueRequestor, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.

Note: This method closes the Session object passed to the QueueRequestor
constructor.
Throws:
JMSException - if a JMS error occurs.

294 MQSeries Using Java

 QueueSender

QueueSender
public interface QueueSender
extends MessageProducer

MQSeries class: MQQueueSender

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageProducer
|
+----com.ibm.mq.jms.MQQueueSender

A client uses a QueueSender to send messages to a queue.

A QueueSender is normally associated with a particular Queue. However, it is

possible to create an unidentified QueueSender that is not associated with any
given Queue.

See also: MessageProducer

Methods
getQueue
public Queue getQueue() throws JMSException

Get the queue associated with this queue sender.

Returns:
the queue.
Throws:
JMSException - if JMS fails to get the queue for this queue sender
because of an internal error.
send
public void send(Message message) throws JMSException

Send a message to the queue. Use the QueueSender’s default delivery

mode, time to live, and priority.
Parameters:
message - the message to be sent.
Throws:
v JMSException - if JMS fails to send the message because of an
error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with a
Queue sender with an invalid queue.
send
public void send(Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException

Send a message specifying delivery mode, priority, and time to live to the
queue.

Chapter 14. JMS interfaces and classes 295

QueueSender
Parameters:
v message - the message to be sent.
v deliveryMode - the delivery mode to use.
v priority - the priority for this message.
v timeToLive - the message’s lifetime (in milliseconds).
Throws:
v JMSException - if JMS fails to send the message because of an
internal error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with a
Queue sender with an invalid queue.
send
public void send(Queue queue,
Message message) throws JMSException

Send a message to the specified queue with the QueueSender’s default

delivery mode, time to live, and priority.

Note: This method can only be used with unidentified QueueSenders.

Parameters:
v queue - the queue that this message should be sent to.
v message - the message to be sent.
Throws:
v JMSException - if JMS fails to send the message because
of an internal error.
v MessageFormatException - if an invalid message is
specified.
v InvalidDestinationException - if a client uses this method
with an invalid queue.
send
public void send(Queue queue,
Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException

Send a message to the specified queue with delivery mode, priority, and
time to live.

Note: This method can only be used with unidentified QueueSenders.

Parameters:
v queue - the queue that this message should be sent to.
v message - the message to be sent.
v deliveryMode - the delivery mode to use.
v priority - the priority for this message.
v timeToLive - the message’s lifetime (in milliseconds).

296 MQSeries Using Java

 QueueSender
Throws:
v JMSException - if JMS fails to send the message because
of an internal error.
v MessageFormatException - if an invalid message is
specified.
v InvalidDestinationException - if a client uses this method
with an invalid queue.
close *
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a QueueSender, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.
Throws:
JMSException if JMS fails to close the producer due to some error.
Overrides:
close in class MQMessageProducer.

Chapter 14. JMS interfaces and classes 297

QueueSession

QueueSession
public interface QueueSession
extends Session

MQSeries class: MQQueueSession

java.lang.Object
|
+----com.ibm.mq.jms.MQSession
|
+----com.ibm.mq.jms.MQQueueSession

A QueueSession provides methods to create QueueReceivers, QueueSenders,

QueueBrowsers and TemporaryQueues.

See also: Session

The following methods are inherited from MQSession:

v close
v commit
v rollback
v recover

Methods
createQueue
public Queue createQueue(java.lang.String queueName)
throws JMSException

Create a Queue given a Queue name. This allows the creation of a queue
with a provider specific name. The string takes a URI format, as described
on page 173.

Note: Clients that depend on this ability are not portable.

Parameters:
queueName - the name of this queue.
Returns:
a Queue with the given name.
Throws:
JMSException - if a session fails to create a queue because of a JMS
error.
createReceiver
public QueueReceiver createReceiver(Queue queue)
throws JMSException

Create a QueueReceiver to receive messages from the specified queue.

Parameters:
queue - the queue to access.
Throws:
v JMSException - if a session fails to create a receiver because of a
JMS error.
v InvalidDestinationException - if an invalid Queue is specified.

298 MQSeries Using Java

 QueueSession
createReceiver
public QueueReceiver createReceiver(Queue queue,
java.lang.String messageSelector)
throws JMSException

Create a QueueReceiver to receive messages from the specified queue.

Parameters:
v queue - the queue to access.
v messageSelector - only messages with properties that match the
message selector expression are delivered.
Throws:
v JMSException - if a session fails to create a receiver because of a
JMS error.
v InvalidDestinationException - if an invalid Queue is specified.
v InvalidSelectorException - if the message selector is invalid.
createSender
public QueueSender createSender(Queue queue)
throws JMSException

Create a QueueSender to send messages to the specified queue.

Parameters:
queue - the queue to access, or null if this is to be an unidentified
producer.
Throws:
v JMSException - if a session fails to create a sender because of a
JMS error.
v InvalidDestinationException - if an invalid Queue is specified.
createBrowser
public QueueBrowser createBrowser(Queue queue)
throws JMSException

Create a QueueBrowser to peek at the messages on the specified queue.

Parameters:
queue - the queue to access.
Throws:
v JMSException - if a session fails to create a browser because of a
JMS error.
v InvalidDestinationException - if an invalid Queue is specified.
createBrowser
public QueueBrowser createBrowser(Queue queue,
java.lang.String messageSelector)
throws JMSException

Create a QueueBrowser to peek at the messages on the specified queue.

Parameters:
v queue - the queue to access.
v messageSelector - only messages with properties that match the
message selector expression are delivered.

Chapter 14. JMS interfaces and classes 299

QueueSession
Throws:
v JMSException - if a session fails to create a browser because of a
JMS error.
v InvalidDestinationException - if an invalid Queue is specified.
v InvalidSelectorException - if the message selector is invalid.
createTemporaryQueue
public TemporaryQueue createTemporaryQueue()
throws JMSException

Create a temporary queue. Its lifetime will be that of the QueueConnection

unless deleted earlier.
Returns:
a temporary queue.
Throws:
JMSException - if a session fails to create a Temporary Queue
because of a JMS error.

300 MQSeries Using Java

 Session

Session
public interface Session
extends java.lang.Runnable
Subinterfaces: QueueSession, TopicSession, XAQueueSession, XASession, and
XATopicSession

MQSeries class: MQSession

java.lang.Object
|
+----com.ibm.mq.jms.MQSession

A JMS Session is a single threaded context for producing and consuming messages.

See also: QueueSession, TopicSession, XAQueueSession, XASession, and

XATopicSession

Fields
AUTO_ACKNOWLEDGE
public static final int AUTO_ACKNOWLEDGE

With this acknowledgement mode, the session automatically acknowledges

a message when it has either successfully returned from a call to receive,
or the message listener it has called to process the message successfully
returns.
CLIENT_ACKNOWLEDGE
public static final int CLIENT_ACKNOWLEDGE

With this acknowledgement mode, the client acknowledges a message by

calling a message’s acknowledge method.
DUPS_OK_ACKNOWLEDGE
public static final int DUPS_OK_ACKNOWLEDGE

This acknowledgement mode instructs the session to lazily acknowledge

the delivery of messages.

Methods
createBytesMessage
public BytesMessage createBytesMessage()
throws JMSException

Create a BytesMessage. A BytesMessage is used to send a message

containing a stream of uninterpreted bytes.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.

Chapter 14. JMS interfaces and classes 301

Session
createMapMessage
public MapMessage createMapMessage() throws JMSException

Create a MapMessage. A MapMessage is used to send a self-defining set of

name-value pairs, where names are Strings, and values are Java primitive
types.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
createMessage
public Message createMessage() throws JMSException

Create a Message. The Message interface is the root interface of all JMS
messages. It holds all the standard message header information. It can be
sent when a message containing only header information is sufficient.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
createObjectMessage
public ObjectMessage createObjectMessage()
throws JMSException

Create an ObjectMessage. An ObjectMessage is used to send a message

that contains a serializable Java object.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
createObjectMessage
public ObjectMessage createObjectMessage
(java.io.Serializable object)
throws JMSException

Create an initialized ObjectMessage. An ObjectMessage is used to send a

message that contains a serializable Java object.
Parameters:
object - the object to use to initialize this message.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
createStreamMessage
public StreamMessage createStreamMessage()
throws JMSException

Create a StreamMessage. A StreamMessage is used to send a self-defining

stream of Java primitives.
Throws:
JMSException if JMS fails to create this message because of an
internal error.

302 MQSeries Using Java

 Session
createTextMessage
public TextMessage createTextMessage() throws JMSException

Create a TextMessage. A TextMessage is used to send a message containing

a String.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
createTextMessage
public TextMessage createTextMessage
(java.lang.String string)
throws JMSException

Create an initialized TextMessage. A TextMessage is used to send a

message containing a String.
Parameters:
string - the string used to initialize this message.
Throws:
JMSException - if JMS fails to create this message because of an
internal error.
getTransacted
public boolean getTransacted() throws JMSException

Is the session in transacted mode?

Returns:
true if the session is in transacted mode.
Throws:
JMSException - if JMS fails to return the transaction mode because
of an internal error in JMS Provider.
commit
public void commit() throws JMSException

Commit all messages done in this transaction and release any locks
currently held.
Throws:
v JMSException - if JMS implementation fails to commit the
transaction because of an internal error.
v TransactionRolledBackException - if the transaction gets rolled
back because of an internal error during commit.
rollback
public void rollback() throws JMSException

Roll back any messages done in this transaction and release any locks
currently held.
Throws:
JMSException - if the JMS implementation fails to roll back the
transaction because of an internal error.

Chapter 14. JMS interfaces and classes 303

Session
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a Session, clients should close them when they are not needed.
You cannot rely on garbage collection to reclaim these resources eventually,
because this may not occur soon enough.

Closing a transacted session rolls back any in-progress transaction. Closing

a session automatically closes its message producers and consumer, so
there is no need to close them individually.
Throws:
JMSException - if the JMS implementation fails to close a Session
because of an internal error.
recover
public void recover() throws JMSException

Stop message delivery in this session, and restart sending messages with
the oldest unacknowledged message.
Throws:
JMSException - if the JMS implementation fails to stop message
delivery and restart message send because of an internal error.
getMessageListener
public MessageListener getMessageListener()
throws JMSException

Return the session’s distinguished message listener.

Returns:
the message listener associated with this session.
Throws:
JMSException - if JMS fails to get the message listener because of
an internal error in the JMS Provider.
See also:
setMessageListener
setMessageListener
public void setMessageListener(MessageListener listener)
throws JMSException

Set the session’s distinguished message listener. When it is set, no other

form of message receipt in the session can be used. However, all forms of
sending messages are still supported.

This is an expert facility that is not used by regular JMS clients.

Parameters:
listener - the message listener to associate with this session.
Throws:
JMSException - if JMS fails to set the message listener because of
an internal error in the JMS Provider.
See also:
getMessageListener, ServerSessionPool, ServerSession

304 MQSeries Using Java

 Session
run
public void run()

This method is intended for use only by application servers.

Specified by:
run in the interface java.lang.Runnable
See also:
ServerSession

Chapter 14. JMS interfaces and classes 305

StreamMessage

StreamMessage
public interface StreamMessage
extends Message

MQSeries class: JMSStreamMessage

java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSStreamMessage

A StreamMessage is used to send a stream of Java primitives.

See also: BytesMessage, MapMessage, Message, ObjectMessage and TextMessage

Methods
readBoolean
public boolean readBoolean() throws JMSException

Read a boolean from the stream message.

Returns:
the boolean value read.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.
readByte
public byte readByte() throws JMSException

Read a byte value from the stream message.

Returns:
the next byte from the stream message as an 8-bit byte.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.

306 MQSeries Using Java

 StreamMessage
readShort
public short readShort() throws JMSException

Read a 16-bit number from the stream message.

Returns:
a 16-bit number from the stream message.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.
readChar
public char readChar() throws JMSException

Read a Unicode character value from the stream message.

Returns:
a Unicode character from the stream message.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException if this type conversion is invalid.
v MessageNotReadableException if the message is in write-only
mode.
readInt
public int readInt() throws JMSException

Read a 32-bit integer from the stream message.

Returns:
a 32-bit integer value from the stream message, interpreted as an
int.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException if this type conversion is invalid.
v MessageNotReadableException if the message is in write-only
mode.
readLong
public long readLong() throws JMSException

Read a 64-bit integer from the stream message.

Returns:
a 64-bit integer value from the stream message, interpreted as a
long.

Chapter 14. JMS interfaces and classes 307

StreamMessage
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream
v MessageFormatException if this type conversion is invalid.
v MessageNotReadableException if the message is in write-only
mode.
readFloat
public float readFloat() throws JMSException

Read a float from the stream message.

Returns:
a float value from the stream message.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream
v MessageFormatException if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.
readDouble
public double readDouble() throws JMSException

Read a double from the stream message.

Returns:
a double value from the stream message.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.
readString
public java.lang.String readString() throws JMSException

Read in a string from the stream message.

Returns:
a Unicode string from the stream message.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode

308 MQSeries Using Java

 StreamMessage
readBytes
public int readBytes(byte[] value)
throws JMSExceptioneam message.

Read a byte array field from the stream message into the specified byte[]
object (the read buffer). If the buffer size is less than, or equal to, the size
of the data in the message field, an application must make further calls to
this method to retrieve the remainder of the data. Once the first readBytes
call on a byte[] field value has been done, the full value of the field must
be read before it is valid to read the next field. An attempt to read the next
field before that has been done will throw a MessageFormatException.
Parameters:
value - the buffer into which the data is read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no
more data because the end of the byte field has been reached.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v MessageFormatException - if this type conversion is invalid.
v MessageNotReadableException - if the message is in write-only
mode.
readObject
public java.lang.Object readObject() throws JMSException

Read a Java object from the stream message.

Returns:
a Java object from the stream message in object format (for
example, if it was set as an int, an Integer is returned).
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageEOFException - if an end of message stream is received.
v NotReadableException - if the message is in write-only mode.
writeBoolean
public void writeBoolean(boolean value) throws JMSException

Write a boolean to the stream message.

Parameters:
value - the boolean value to be written.
Throws:
v JMSException - if JMS fails to read the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

Chapter 14. JMS interfaces and classes 309

StreamMessage
writeByte
public void writeByte(byte value) throws JMSException

Write out a byte to the stream message.

Parameters:
value - the byte value to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeShort
public void writeShort(short value) throws JMSException

Write a short to the stream message.

Parameters:
value - the short to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeChar
public void writeChar(char value) throws JMSException

Write a char to the stream message.

Parameters:
value - the char value to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeInt
public void writeInt(int value) throws JMSException

Write an int to the stream message.

Parameters:
value - the int to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

310 MQSeries Using Java

 StreamMessage
writeLong
public void writeLong(long value) throws JMSException

Write a long to the stream message.

Parameters:
value - the long to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeFloat
public void writeFloat(float value) throws JMSException

Write a float to the stream message.

Parameters:
value - the float value to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeDouble
public void writeDouble(double value) throws JMSException

Write a double to the stream message.

Parameters:
value - the double value to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeString
public void writeString(java.lang.String value)
throws JMSException

Write a string to the stream message.

Parameters:
value - the String value to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.

Chapter 14. JMS interfaces and classes 311

StreamMessage
writeBytes
public void writeBytes(byte[] value) throws JMSException

Write a byte array to the stream message.

Parameters:
value - the byte array to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeBytes
public void writeBytes(byte[] value,
int offset,
int length) throws JMSException

Write a portion of a byte array to the stream message.

Parameters:
v value - the byte array value to be written.
v offset - the initial offset within the byte array.
v length - the number of bytes to use.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
writeObject
public void writeObject(java.lang.Object value)
throws JMSException

Write a Java object to the stream message. This method only works for
object primitive types (Integer, Double, Long, for example), Strings, and
byte arrays.
Parameters:
value - the Java object to be written.
Throws:
v JMSException - if JMS fails to write the message because of an
internal JMS error.
v MessageNotWriteableException - if the message is in read-only
mode.
v MessageFormatException - if the object is invalid.

312 MQSeries Using Java

 StreamMessage
reset
public void reset() throws JMSException

Put the message in read-only mode, and reposition the stream to the
beginning.
Throws:
v JMSException - if JMS fails to reset the message because of an
internal JMS error.
v MessageFormatException - if the message has an invalid format.

Chapter 14. JMS interfaces and classes 313

TemporaryQueue

TemporaryQueue
public interface TemporaryQueue
extends Queue

MQSeries class: MQTemporaryQueue

java.lang.Object
|
+----com.ibm.mq.jms.MQDestination
|
+----com.ibm.mq.jms.MQQueue
|
+----com.ibm.mq.jms.MQTemporaryQueue

A TemporaryQueue is a unique Queue object that is created for the duration of a

QueueConnection.

Methods
delete
public void delete() throws JMSException

Delete this temporary queue. If there are still existing senders or receivers
using it, a JMSException will be thrown.
Throws:
JMSException - if JMS implementation fails to delete a
TemporaryQueue because of an internal error.

314 MQSeries Using Java

 TemporaryTopic

TemporaryTopic
public interface TemporaryTopic
extends Topic

MQSeries class: MQTemporaryTopic

java.lang.Object
|
+----com.ibm.mq.jms.MQDestination
|
+----com.ibm.mq.jms.MQTopic
|
+----com.ibm.mq.jms.MQTemporaryTopic

A TemporaryTopic is a unique Topic object created for the duration of a

TopicConnection and can only be consumed by consumers of that connection.

MQSeries constructor
MQTemporaryTopic
MQTemporaryTopic() throws JMSException

Methods
delete
public void delete() throws JMSException

Delete this temporary topic. If there are still existing publishers or

subscribers still using it, a JMSException will be thrown.
Throws:
JMSException - if JMS implementation fails to delete a
TemporaryTopic because of an internal error.

Chapter 14. JMS interfaces and classes 315

TextMessage

TextMessage
public interface TextMessage
extends Message

MQSeries class: JMSTextMessage

java.lang.Object
|
+----com.ibm.jms.JMSMessage
|
+----com.ibm.jms.JMSTextMessage

TextMessage is used to send a message containing a java.lang.String. It inherits

from Message and adds a text message body.

See also: BytesMessage, MapMessage, Message, ObjectMessage and

StreamMessage

Methods
setText
public void setText(java.lang.String string)
throws JMSException

Set the string containing this message’s data.

Parameters:
string - the String containing the message’s data.
Throws:
v JMSException - if JMS fails to set text because of an internal JMS
error.
v MessageNotWriteableException - if the message is in read-only
mode.
getText
public java.lang.String getText() throws JMSException

Get the string containing this message’s data. The default value is null.
Returns:
the String containing the message’s data.
Throws:
JMSException - if JMS fails to get the text because of an internal
JMS error.

316 MQSeries Using Java

 Topic

Topic
public interface Topic
extends Destination
Subinterfaces: TemporaryTopic

MQSeries class: MQTopic

java.lang.Object
|
+----com.ibm.mq.jms.MQDestination
|
+----com.ibm.mq.jms.MQTopic

A Topic object encapsulates a provider-specific topic name. It is the way a client

specifies the identity of a topic to JMS methods.

See also: Destination

MQSeries constructor
MQTopic
public MQTopic()
public MQTopic(string URItopic)

See TopicSession.createTopic.

Methods
getTopicName
public java.lang.String getTopicName() throws JMSException

Get the name of this topic in URI format. (URI format is described in
“Creating topics at runtime” on page 182.)

Note: Clients that depend upon the name are not portable.
Returns:
the topic name.
Throws:
JMSException - if JMS implementation for Topic fails to
return the topic name because of an internal error.
toString
public String toString()

Return a pretty printed version of the Topic name.

Returns:
the provider specific identity values for this Topic.
Overrides:
toString in class Object.
getReference *
public Reference getReference()

Create a reference for this topic.

Chapter 14. JMS interfaces and classes 317

Topic
Returns:
a reference for this object.
Throws:
NamingException.
setBaseTopicName *
public void setBaseTopicName(String x)

set method for the underlying MQSeries topic name.

getBaseTopicName *
public String getBaseTopicName()

get method for the underlying MQSeries topic name.

setBrokerDurSubQueue *
public void setBrokerDurSubQueue(String x) throws JMSException

Set method for brokerDurSubQueue attribute.

Parameters:
brokerDurSubQueue - the name of the durable subscription queue
to use.
getBrokerDurSubQueue *
public String getBrokerDurSubQueue()

Get method for brokerDurSubQueue attribute.

Returns:
the name of the durable subscription queue (the
brokerDurSubQueue) to use.
setBrokerCCDurSubQueue *
public void setBrokerCCDurSubQueue(String x) throws JMSException

Set method for brokerCCDurSubQueue attribute.

Parameters:
brokerCCDurSubQueue - the name of the durable subscription
queue to use for a ConnectionConsumer.
getBrokerCCDurSubQueue *
public String getBrokerCCDurSubQueue()

Get method for brokerCCDurSubQueue attribute.

Returns:
the name of the durable subscription queue (the
brokerCCDurSubQueue) to use for a ConnectionConsumer.

318 MQSeries Using Java

 TopicConnection

TopicConnection
public interface TopicConnection
extends Connection
Subinterfaces: XATopicConnection

MQSeries class: MQTopicConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQConnection
|
+----com.ibm.mq.jms.MQTopicConnection

A TopicConnection is an active connection to a JMS Publish/Subscribe provider.

See also: Connection, TopicConnectionFactory, and XATopicConnection

Methods
createTopicSession
public TopicSession createTopicSession(boolean transacted,
int acknowledgeMode)
throws JMSException

Create a TopicSession.
Parameters:
v transacted - if true, the session is transacted.
v acknowledgeMode - one of:
Session.AUTO_ACKNOWLEDGE
Session.CLIENT_ACKNOWLEDGE
Session.DUPS_OK_ACKNOWLEDGE

Indicates whether the consumer or the client will acknowledge

any messages it receives. This parameter will be ignored if the
session is transacted.
Returns:
a newly created topic session.
Throws:
JMSException - if JMS Connection fails to create a session because
of an internal error, or a lack of support for the specific transaction
and acknowledgement mode.
createConnectionConsumer
public ConnectionConsumer createConnectionConsumer
(Topic topic,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
throws JMSException

Create a connection consumer for this connection. This is an expert facility

that is not used by regular JMS clients.

Chapter 14. JMS interfaces and classes 319

TopicConnection
Parameters:
v topic - the topic to access.
v messageSelector - only messages with properties that match the
message selector expression are delivered.
v sessionPool - the server session pool to associate with this
connection consumer.
v maxMessages - the maximum number of messages that can be
assigned to a server session at one time.
Returns:
the connection consumer.
Throws:
v JMSException - if the JMS Connection fails to create a connection
consumer because of an internal error, or because of invalid
arguments for sessionPool.
v InvalidSelectorException - if the message selector is invalid.
See also:
ConnectionConsumer
createDurableConnectionConsumer
public ConnectionConsumer createDurableConnectionConsumer
(Topic topic,
java.lang.String subscriptionName
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
throws JMSException

Create a durable connection consumer for this connection. This is an expert

facility that is not used by regular JMS clients.
Parameters:
v topic - the topic to access.
v subscriptionName - name of the durable subscription.
v messageSelector - only messages with properties that match the
message selector expression are delivered.
v sessionPool - the server session pool to associate with this
durable connection consumer.
v maxMessages - the maximum number of messages that can be
assigned to a server session at one time.
Returns:
the durable connection consumer.
Throws:
v JMSException - if the JMS Connection fails to create a connection
consumer because of an internal error, or because of invalid
arguments for sessionPool and messageSelector.
v InvalidSelectorException - if the message selector is invalid.
See also:
ConnectionConsumer

320 MQSeries Using Java

 TopicConnectionFactory

TopicConnectionFactory
public interface TopicConnectionFactory
extends ConnectionFactory
Subinterfaces: XATopicConnectionFactory

MQSeries class: MQTopicConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionFactory
|
+----com.ibm.mq.jms.MQTopicConnectionFactory

A client uses a TopicConnectionFactory to create TopicConnections with a JMS

Publish/Subscribe provider.

See also: ConnectionFactory and XATopicConnectionFactory

MQSeries constructor
MQTopicConnectionFactory
public MQTopicConnectionFactory()

Methods
createTopicConnection
public TopicConnection createTopicConnection()
throws JMSException

Create a topic connection with default user identity. The connection is

created in stopped mode. No messages will be delivered until
Connection.start method is explicitly called.
Returns:
a newly created topic connection.
Throws:
v JMSException - if JMS Provider fails to create a Topic Connection
because of an internal error.
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.
createTopicConnection
public TopicConnection createTopicConnection
(java.lang.String userName,
java.lang.String password)
throws JMSException

Create a topic connection with specified user identity. The connection is

created in stopped mode. No messages will be delivered until
Connection.start method is explicitly called.

Note: This method is valid only for transport type

IBM_JMS_TP_CLIENT_MQ_TCPIP. See ConnectionFactory.

Chapter 14. JMS interfaces and classes 321

TopicConnectionFactory
Parameters:
v userName - the caller’s user name.
v password - the caller’s password.
Returns:
a newly created topic connection.
Throws:
v JMSException - if JMS Provider fails to create a Topic
Connection because of an internal error.
v JMSSecurityException - if client authentication fails
because of an invalid user name or password.
setBrokerControlQueue *
public void setBrokerControlQueue(String x) throws JMSException

Set method for brokerControlQueue attribute.

Parameters:
brokerControlQueue - the name of the broker control queue.
getBrokerControlQueue *
public String getBrokerControlQueue()

Get method for brokerControlQueue attribute.

Returns:
the broker’s control queue name
setBrokerQueueManager *
public void setBrokerQueueManager(String x) throws JMSException

Set method for brokerQueueManager attribute.

Parameters:
brokerQueueManager - the name of the broker’s Queue Manager.
getBrokerQueueManager *
public String getBrokerQueueManager()

Get method for brokerQueueManager attribute.

Returns:
the broker’s queue manager name.
setBrokerPubQueue *
public void setBrokerPubQueue(String x) throws JMSException

Set method for brokerPubQueue attribute.

Parameters:
brokerPubQueue - the name of the broker publish queue.
getBrokerPubQueue *
public String getBrokerPubQueue()

Get method for brokerPubQueue attribute.

Returns:
the broker’s publish queue name.

322 MQSeries Using Java

 TopicConnectionFactory
setBrokerSubQueue *
public void setBrokerSubQueue(String x) throws JMSException

Set method for brokerSubQueue attribute.

Parameters:
brokerSubQueue - the name of the non-durable subscription queue
to use.
getBrokerSubQueue *
public String getBrokerSubQueue()

Get method for brokerSubQueue attribute.

Returns:
the name of the non-durable subscription queue to use.
setBrokerCCSubQueue *
public void setBrokerCCSubQueue(String x) throws JMSException

Set method for brokerCCSubQueue attribute.

Parameters:
brokerSubQueue - the name of the non-durable subscription queue
to use for a ConnectionConsumer.
getBrokerCCSubQueue *
public String getBrokerCCSubQueue()

Get method for brokerCCSubQueue attribute.

Returns:
the name of the non-durable subscription queue to use for a
ConnectionConsumer.
setBrokerVersion *
public void setBrokerVersion(int x) throws JMSException

Set method for brokerVersion attribute.

Parameters:
brokerVersion - the broker’s version number.
getBrokerVersion *
public int getBrokerVersion()

Get method for brokerVersion attribute.

Returns:
the broker’s version number.
getReference *
public Reference getReference()

Return a reference for this topic connection factory.

Returns:
a reference for this topic connection factory.
Throws:
NamingException.

Chapter 14. JMS interfaces and classes 323

TopicPublisher

TopicPublisher
public interface TopicPublisher
extends MessageProducer

MQSeries class: MQTopicPublisher

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageProducer
|
+----com.ibm.mq.jms.MQTopicPublisher

A client uses a TopicPublisher for publishing messages on a topic. TopicPublisher

is the Pub/Sub variant of a JMS message producer.

Methods
getTopic
public Topic getTopic() throws JMSException

Get the topic associated with this publisher.

Returns:
this publisher’s topic
Throws:
JMSException - if JMS fails to get the topic for this topic publisher
because of an internal error.
publish
public void publish(Message message) throws JMSException

Publish a Message to the topic Use the topic’s default delivery mode, time
to live, and priority.
Parameters:
message - the message to publish
Throws:
v JMSException - if JMS fails to publish the message because of an
internal error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with a
Topic Publisher with an invalid topic.
publish
public void publish(Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException

Publish a Message to the topic specifying delivery mode, priority, and time
to live to the topic.

324 MQSeries Using Java

 TopicPublisher
Parameters:
v message - the message to publish.
v deliveryMode - the delivery mode to use.
v priority - the priority for this message.
v timeToLive - the message’s lifetime (in milliseconds).
Throws:
v JMSException - if JMS fails to publish the message because of an
internal error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with a
Topic Publisher with an invalid topic.
publish
public void publish(Topic topic,
Message message) throws JMSException

Publish a Message to a topic for an unidentified message producer. Use the

topic’s default delivery mode, time to live, and priority.
Parameters:
v topic - the topic to publish this message to.
v message - the message to send.
Throws:
v JMSException - if JMS fails to publish the message because of an
internal error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with
an invalid topic.
publish
public void publish(Topic topic,
Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException

Publish a Message to a topic for an unidentified message producer,

specifying delivery mode, priority, and time to live.
Parameters:
v topic - the topic to publish this message to.
v message - the message to send.
v deliveryMode - the delivery mode to use.
v priority - the priority for this message.
v timeToLive - the message’s lifetime (in milliseconds).

Chapter 14. JMS interfaces and classes 325

TopicPublisher
Throws:
v JMSException - if JMS fails to publish the message because of an
internal error.
v MessageFormatException - if an invalid message is specified.
v InvalidDestinationException - if a client uses this method with
an invalid topic.
close *
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a TopicPublisher, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.
Throws:
JMSException if JMS fails to close the producer because of an error.
Overrides:
close in class MQMessageProducer.

326 MQSeries Using Java

 TopicRequestor

TopicRequestor
public class TopicRequestor
extends java.lang.Object

java.lang.Object
|
+----javax.jms.TopicRequestor

JMS provides this TopicRequestor class to assist with making service requests.

The TopicRequestor constructor is given a non-transacted TopicSession and a

destination Topic. It creates a TemporaryTopic for the responses, and provides a
request() method that sends the request message and waits for its reply. Users are
free to create more sophisticated versions.

Constructors
TopicRequestor
public TopicRequestor(TopicSession session,
Topic topic) throws JMSException

Constructor for the TopicRequestor class. This implementation assumes

that the session parameter is non-transacted, and either
AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE.
Parameters:
v session - the topic session the topic belongs to.
v topic - the topic to perform the request/reply call on.
Throws:
JMSException - if a JMS error occurs.

Methods
request
public Message request(Message message) throws JMSException

Send a request and wait for a reply.

Parameters:
message - the message to send.
Returns:
the reply message.
Throws:
JMSException - if a JMS error occurs.
close
public void close() throws JMSException

Because a provider may allocate some resources outside of the JVM on

behalf of a TopicRequestor, clients should close them when they are not
needed. You cannot rely on garbage collection to reclaim these resources
eventually, because this may not occur soon enough.

Chapter 14. JMS interfaces and classes 327

TopicRequestor
Note: This method closes the Session object passed to the TopicRequestor
constructor.
Throws:
JMSException - if a JMS error occurs.

328 MQSeries Using Java

 TopicSession

TopicSession
public interface TopicSession
extends Session

MQSeries class: MQTopicSession

java.lang.Object
|
+----com.ibm.mq.jms.MQSession
|
+----com.ibm.mq.jms.MQTopicSession

A TopicSession provides methods for creating TopicPublishers, TopicSubscribers

and TemporaryTopics.

See also: Session

MQSeries constructor
MQTopicSession
public MQTopicSession(boolean transacted,
int acknowledgeMode) throws JMSException

See TopicConnection.createTopicSession.

Methods
createTopic
public Topic createTopic(java.lang.String topicName)
throws JMSException

Create a Topic given a URI format Topic name. (URI format is described in
“Creating topics at runtime” on page 182.) This allows the creation of a
topic with a provider specific name.

Note: Clients that depend on this ability are not portable.

Parameters:
topicName - the name of this topic.
Returns:
a Topic with the given name.
Throws:
JMSException - if a session fails to create a topic because of
a JMS error.
createSubscriber
public TopicSubscriber createSubscriber(Topic topic)
throws JMSException

Create a non-durable Subscriber to the specified topic.

Parameters:
topic - the topic to subscribe to

Chapter 14. JMS interfaces and classes 329

TopicSession
Throws:
v JMSException - if a session fails to create a subscriber because of
a JMS error.
v InvalidDestinationException - if an invalid Topic is specified.
createSubscriber
public TopicSubscriber createSubscriber
(Topic topic,
java.lang.String messageSelector,
boolean noLocal) throws JMSException

Create a non-durable Subscriber to the specified topic.

Parameters:
v topic - the topic to subscribe to.
v messageSelector - only messages with properties that match the
message selector expression are delivered. This value may be
null.
v noLocal - if set, inhibits the delivery of messages published by
its own connection.
Throws:
v JMSException - if a session fails to create a subscriber because of
a JMS error or invalid selector.
v InvalidDestinationException - if an invalid Topic is specified.
v InvalidSelectorException - if the message selector is invalid.
createDurableSubscriber
public TopicSubscriber createDurableSubscriber
(Topic topic,
java.lang.String name) throws JMSException

Create a durable Subscriber to the specified topic. A client can change an

existing durable subscription by creating a Durable Subscriber with the
same name and a new topic and/or message selector.
Parameters:
v topic - the topic to subscribe to.
v name - the name used to identify this subscription.
Throws:
v JMSException - if a session fails to create a subscriber because of
a JMS error.
v InvalidDestinationException - if an invalid Topic is specified.

See TopicSession.unsubscribe
createDurableSubscriber
public TopicSubscriber createDurableSubscriber
(Topic topic,
java.lang.String name,
java.lang.String messageSelector,
boolean noLocal) throws JMSException

Create a durable Subscriber to the specified topic.

330 MQSeries Using Java

 TopicSession
Parameters:
v topic - the topic to subscribe to.
v name - the name used to identify this subscription.
v messageSelector - only messages with properties that match the
message selector expression are delivered. This value may be
null.
v noLocal - if set, inhibits the delivery of messages published by
its own connection.
Throws:
v JMSException - if a session fails to create a subscriber because of
a JMS error or invalid selector.
v InvalidDestinationException - if an invalid Topic is specified.
v InvalidSelectorException - if the message selector is invalid.
createPublisher
public TopicPublisher createPublisher(Topic topic)
throws JMSException

Create a Publisher for the specified topic.

Parameters:
topic - the topic to publish to, or null if this is an unidentified
producer.
Throws:
v JMSException - if a session fails to create a publisher because of
a JMS error.
v InvalidDestinationException - if an invalid Topic is specified.
createTemporaryTopic
public TemporaryTopic createTemporaryTopic()
throws JMSException

Create a temporary topic. Its lifetime will be that of the TopicConnection

unless deleted earlier.
Returns:
a temporary topic.
Throws:
JMSException - if a session fails to create a temporary topic
because of a JMS error.
unsubscribe
public void unsubscribe(java.lang.String name)
throws JMSException

Unsubscribe a durable subscription that has been created by a client.

Note: Do not use this method while an active subscription exists. You
must close() your subscriber first.
Parameters:
name - the name used to identify this subscription.

Chapter 14. JMS interfaces and classes 331

TopicSession
Throws:
v JMSException - if JMS fails to unsubscribe the durable
subscription because of a JMS error.
v InvalidDestinationException - if an invalid Topic is specified.

332 MQSeries Using Java

 TopicSubscriber

TopicSubscriber
public interface TopicSubscriber
extends MessageConsumer

MQSeries class: MQTopicSubscriber

java.lang.Object
|
+----com.ibm.mq.jms.MQMessageConsumer
|
+----com.ibm.mq.jms.MQTopicSubscriber

A client uses a TopicSubscriber for receiving messages that have been published to
a topic. TopicSubscriber is the Pub/Sub variant of a JMS message consumer.

See also: MessageConsumer and TopicSession.createSubscriber

MQTopicSubscriber inherits the following methods from MQMessageConsumer:

close
getMessageListener
receive
receiveNoWait
setMessageListener

Methods
getTopic
public Topic getTopic() throws JMSException

Get the topic associated with this subscriber.

Returns:
this subscriber’s topic.
Throws:
JMSException - if JMS fails to get topic for this topic subscriber
because of an internal error.
getNoLocal
public boolean getNoLocal() throws JMSException

Get the NoLocal attribute for this TopicSubscriber. The default value for
this attribute is false.
Returns:
set to true if locally published messages are being inhibited.
Throws:
JMSException - if JMS fails to get NoLocal attribute for this topic
subscriber because of an internal error.

Chapter 14. JMS interfaces and classes 333

XAConnection

XAConnection
public interface XAConnection
Subinterfaces: XAQueueConnection and XATopicConnection

MQSeries class: MQXAConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQXAConnection

XAConnection extends the capability of Connection by providing an XASession.

Refer to “Appendix E. JMS JTA/XA interface with WebSphere” on page 361 for
details about how MQ JMS uses XA classes.

See also: XAQueueConnection and XATopicConnection

334 MQSeries Using Java

 XAConnectionFactory

XAConnectionFactory
public interface XAConnectionFactory
Subinterfaces: XAQueueConnectionFactory and XATopicConnectionFactory

MQSeries class: MQXAConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQXAConnectionFactory

Some application servers provide support to group JTS-capable resource use into a
distributed transaction. To include JMS transactions in a JTS transaction, an
application server requires a JTS-aware JMS provider. A JMS provider exposes its
JTS support by using a JMS XAConnectionFactory, which an application server
uses to create XASessions. XAConnectionFactories are JMS-administered objects
just like ConnectionFactories. It is expected that application servers use JNDI to
find them.

Refer to “Appendix E. JMS JTA/XA interface with WebSphere” on page 361 for
details about how MQ JMS uses XA classes.

See also: XAQueueConnectionFactory and XATopicConnectionFactory

Chapter 14. JMS interfaces and classes 335

XAQueueConnection

XAQueueConnection
public interface XAQueueConnection
extends QueueConnection and XAConnection

MQSeries class: MQXAQueueConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQConnection
|
+----com.ibm.mq.jms.MQQueueConnection
|
+----com.ibm.mq.jms.MQXAQueueConnection

XAQueueConnection provides the same create options as QueueConnection. The

only difference is that, by definition, an XAConnection is transacted. Refer to
“Appendix E. JMS JTA/XA interface with WebSphere” on page 361 for details
about how MQ JMS uses XA classes.

See also: XAConnection and QueueConnection

Methods
createXAQueueSession
public XAQueueSession createXAQueueSession()

Create an XAQueueSession.
Throws:
JMSException - if JMS Connection fails to create an XA queue
session because of an internal error.
createQueueSession
public QueueSession createQueueSession(boolean transacted,
int acknowledgeMode)
throws JMSException

Create a QueueSession.
Parameters:
v transacted - if true, the session is transacted.
v acknowledgeMode - indicates whether the consumer or the
client will acknowledge any messages it receives. Possible values
are:
Session.AUTO_ACKNOWLEDGE
Session.CLIENT_ACKNOWLEDGE
Session.DUPS_OK_ACKNOWLEDGE
This parameter is ignored if the session is transacted.
Returns:
a newly created queue session (note that this is not an XA queue
session).
Throws:
JMSException - if JMS Connection fails to create a queue session
because of an internal error.

336 MQSeries Using Java

 XAQueueConnectionFactory

XAQueueConnectionFactory
public interface XAQueueConnectionFactory
extends QueueConnectionFactory and XAConnectionFactory

MQSeries class: MQXAQueueConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionFactory
|
+----com.ibm.mq.jms.MQQueueConnectionFactory
|
+----com.ibm.mq.jms.MQXAQueueConnectionFactory

An XAQueueConnectionFactory provides the same create options as a

QueueConnectionFactory. Refer to “Appendix E. JMS JTA/XA interface with
WebSphere” on page 361 for details about how MQ JMS uses XA classes.

See also: QueueConnectionFactory and XAConnectionFactory

Methods
createXAQueueConnection
public XAQueueConnection createXAQueueConnection()
throws JMSException

Create an XAQueueConnection using the default user identity. The

connection is created in stopped mode. No messages are delivered until
the Connection.start method is called explicitly.
Returns:
a newly created XA queue connection.
Throws:
v JMSException - if the JMS Provider fails to create an XA queue
connection because of an internal error.
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.
createXAQueueConnection
public XAQueueConnection createXAQueueConnection
(java.lang.String userName,
java.lang.String password)
throws JMSException

Create an XA queue connection using a specific user identity. The

connection is created in stopped mode. No messages are delivered until
the Connection.start method is called explicitly.
Parameters:
v userName - the user name of the caller.
v password - the password for the caller.
Returns:
a newly created XA queue connection.

Chapter 14. JMS interfaces and classes 337

XAQueueConnectionFactory
Throws:
v JMSException - if the JMS Provider fails to create an XA queue
connection because of an internal error.
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.

338 MQSeries Using Java

 XAQueueSession

XAQueueSession
public interface XAQueueSession
extends XASession

MQSeries class: MQXAQueueSession

java.lang.Object
|
+----com.ibm.mq.jms.MQXASession
|
+----com.ibm.mq.jms.MQXAQueueSession

An XAQueueSession provides a regular QueueSession that can be used to create

QueueReceivers, QueueSenders and QueueBrowsers. Refer to “Appendix E. JMS
JTA/XA interface with WebSphere” on page 361 for details about how MQ JMS
uses XA classes.

The XAResource that corresponds to the QueueSession can be obtained by calling

the getXAResource method, which is is inherited from XASession.

See also: XASession

Methods
getQueueSession
public QueueSession getQueueSession()
throws JMSException

Get the queue session associated with this XAQueueSession.

Returns:
the queue session object.
Throws:
JMSException - if a JMS error occurs.

Chapter 14. JMS interfaces and classes 339

XASession

XASession
public interface XASession
extends Session
Subinterfaces: XAQueueSession and XATopicSession

MQSeries class: MQXASession

java.lang.Object
|
+----com.ibm.mq.jms.MQXASession

XASession extends the capability of Session by adding access to a JMS provider’s

support for JTA. This support takes the form of a javax.transaction.xa.XAResource
object. The functionality of this object closely resembles that defined by the
standard X/Open XA Resource interface.

An application server controls the transactional assignment of an XASession by

obtaining its XAResource. It uses the XAResource to assign the session to a
transaction, prepare and commit work on the transaction, and so on.

An XAResource provides some fairly sophisticated facilities such as interleaving

work on multiple transactions and recovering a list of transactions in progress.

A JTA-aware JMS provider must fully implement this functionality. To do this, a

JMS provider could either use the services of a database that supports XA, or
implement this functionality from scratch.

A client of the application server is given what appears to be a regular JMS

Session. Behind the scenes, the application server controls the transaction
management of the underlying XASession.

Refer to “Appendix E. JMS JTA/XA interface with WebSphere” on page 361 for
details about how MQ JMS uses XA classes.

See also: XAQueueSession and XATopicSession

Methods
getXAResource
public javax.transaction.xa.XAResource getXAResource()

Return an XA resource to the caller.

Returns:
an XA resource to the caller.
getTransacted
public boolean getTransacted()
throws JMSException

Always returns true.

Specified by:
getTransacted in the Session interface.
Returns:
true - if the session is in transacted mode.

340 MQSeries Using Java

 XASession
Throws:
JMSException - if JMS fails to return the transaction mode because
of an internal error in the JMS Provider.
commit
public void commit()
throws JMSException

This method should not be called for an XASession object. If it is called, it

throws a TransactionInProgressException.
Specified by:
commit in the Session interface.
Throws:
TransactionInProgressException - if this method is called on an
XASession.
rollback
public void rollback()
throws JMSException

This method should not be called for an XASession object. If it is called, it

throws a TransactionInProgressException.
Specified by:
rollback in the Session interface.
Throws:
TransactionInProgressException - if this method is called on an
XASession.

Chapter 14. JMS interfaces and classes 341

XATopicConnection

XATopicConnection
public interface XATopicConnection
extends TopicConnection and XAConnection

MQSeries class: MQXATopicConnection

java.lang.Object
|
+----com.ibm.mq.jms.MQConnection
|
+----com.ibm.mq.jms.MQTopicConnection
|
+----com.ibm.mq.jms.MQXATopicConnection

An XATopicConnection provides the same create options as TopicConnection. The

only difference is that, by definition, an XAConnection is transacted. Refer to
“Appendix E. JMS JTA/XA interface with WebSphere” on page 361 for details
about how MQ JMS uses XA classes.

See also: TopicConnection and XAConnection

Methods
createXATopicSession
public XATopicSession createXATopicSession()
throws JMSException

Create an XATopicSession.
Throws:
JMSException - if the JMS Connection fails to create an XA topic
session because of an internal error.
createTopicSession
public TopicSession createTopicSession(boolean transacted,
int acknowledgeMode)
throws JMSException

Create a TopicSession.
Specified by:
createTopicSession in interface TopicConnection.
Parameters:
v transacted - if true, the session is transacted.
v acknowledgeMode - one of:
Session.AUTO_ACKNOWLEDGE
Session.CLIENT_ACKNOWLEDGE
Session.DUPS_OK_ACKNOWLEDGE

Indicates whether the consumer or the client will acknowledge

any messages it receives. This parameter will be ignored if the
session is transacted.
Returns:
a newly created topic session (note that this is not an XA topic
session).

342 MQSeries Using Java

 XATopicConnection
Throws:
JMSException - if JMS Connection fails to create a topic session
because of an internal error.

Chapter 14. JMS interfaces and classes 343

XATopicConnectionFactory

XATopicConnectionFactory
public interface XATopicConnectionFactory
extends TopicConnectionFactory and XAConnectionFactory

MQSeries class: MQXATopicConnectionFactory

java.lang.Object
|
+----com.ibm.mq.jms.MQConnectionFactory
|
+----com.ibm.mq.jms.MQTopicConnectionFactory
|
+----com.ibm.mq.jms.MQXATopicConnectionFactory

An XATopicConnectionFactory provides the same create options as

TopicConnectionFactory. Refer to “Appendix E. JMS JTA/XA interface with
WebSphere” on page 361 for details about how MQ JMS uses XA classes.

See also: TopicConnectionFactory and XAConnectionFactory

Methods
createXATopicConnection
public XATopicConnection createXATopicConnection()
throws JMSException

Create an XA topic connection using the default user identity. The

connection is created in stopped mode. No messages are delivered until
the Connection.start method is called explicitly.
Returns:
a newly created XA topic connection.
Throws:
v JMSException - if the JMS Provider fails to create an XA topic
connection because of an internal error.
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.
createXATopicConnection
public XATopicConnection createXATopicConnection(java.lang.String userName,
java.lang.String password)
throws JMSException

Create an XA topic connection using the specified user identity. The

connection is created in stopped mode. No messages are delivered until
the Connection.start method is called explicitly.
Parameters:
v userName - the user name of the caller
v password - the password of the caller
Returns:
a newly created XA topic connection.
Throws:
v JMSException - if the JMS Provider fails to create an XA topic
connection because of an internal error.

344 MQSeries Using Java

 XATopicConnectionFactory
v JMSSecurityException - if client authentication fails because of an
invalid user name or password.

Chapter 14. JMS interfaces and classes 345

XATopicSession

XATopicSession
public interface XATopicSession
extends XASession

MQSeries class: MQXATopicSession

java.lang.Object
|
+----com.ibm.mq.jms.MQXASession
|
+----com.ibm.mq.jms.MQXATopicSession

An XATopicSession provides a TopicSession, which can be used to create

TopicSubscribers and TopicPublishers. Refer to “Appendix E. JMS JTA/XA interface
with WebSphere” on page 361 for details about how MQ JMS uses XA classes.

The XAResource that corresponds to the TopicSession can be obtained by calling

the getXAResource method, which is is inherited from XASession.

See also: TopicSession and XASession

Methods
getTopicSession
public TopicSession getTopicSession()
throws JMSException

Get the topic session associated with this XATopicSession.

Returns:
the topic session object.
Throws:
v JMSException - if a JMS error occurs.

346 MQSeries Using Java

Part 4. Appendixes

© Copyright IBM Corp. 1997, 2001 347

348 MQSeries Using Java
Appendix A. Mapping between Administration tool properties
and programmable properties
MQSeries Classes for Java Message Service provides facilities to set and query the
properties of administered objects either using the MQ JMS administration tool, or
in an application program. Table 37 shows the mapping between each property
name used with the administration tool and the corresponding member variable it
refers to. It also shows the mapping between symbolic property values used in the
tool and their programmable equivalents.
Table 37. Comparison of representations of property values within the administration tool and within programs.
Property Member variable name Tool property Program property values
values
DESCRIPTION description
TRANSPORT transportType v BIND JMSC.MQJMS_TP_BINDINGS_MQ
v CLIENT JMSC.MQJMS_TP_CLIENT_MQ_TCPIP
CLIENTID clientId
QMANAGER queueManager*
HOSTNAME hostName
PORT port
CHANNEL channel
CCSID CCSID
RECEXIT receiveExit
RECEXITINIT receiveExitInit
SECEXIT securityExit
SECEXITINIT securityExitInit
SENDEXIT sendExit
SENDEXITINIT sendExitInit
TEMPMODEL temporaryModel
MSGRETENTION messageRetention v YES JMSC.MQJMS_MRET_YES
v NO
JMSC.MQJMS_MRET_NO
BROKERVER brokerVersion v V1 JMSC.MQJMS_BROKER_V1
BROKERPUBQ brokerPubQueue
BROKERSUBQ brokerSubQueue
BROKERDURSUBQ brokerDurSubQueue
BROKERCCSUBQ brokerCCSubQueue
BROKERCCDSUBQ brokerCCDurSubQueue
BROKERQMGR brokerQueueManager
BROKERCONQ brokerControlQueue
EXPIRY expiry v APP JMSC.MQJMS_EXP_APP
v UNLIM JMSC.MQJMS_EXP_UNLIMITED
PRIORITY priority v APP JMSC.MQJMS_PRI_APP
v QDEF JMSC.MQJMS_PRI_QDEF

© Copyright IBM Corp. 1997, 2001 349

Properties
Table 37. Comparison of representations of property values within the administration tool and within
programs. (continued)
Property Member variable name Tool property Program property values
values
PERSISTENCE persistence v APP JMSC.MQJMS_PER_APP
v QDEF JMSC.MQJMS_PER_QDEF
v PERS JMSC.MQJMS_PER_PER
v NON JMSC.MQJMS_PER_NON
TARGCLIENT targetClient v JMS JMSC.MQJMS_CLIENT_JMS_COMPLIANT
v MQ JMSC.MQJMS_CLIENT_NONJMS_MQ
ENCODING encoding
QUEUE baseQueueName
TOPIC baseTopicName
Note: * for an MQQueue object, the member variable name is baseQueueManagerName

350 MQSeries Using Java

Appendix B. Scripts provided with MQSeries classes for Java
Message Service
The following files are provided in the bin directory of your MQ JMS installation.
These scripts are provided to assist with common tasks that need to be performed
while installing or using MQ JMS. Table 38 lists the scripts and their uses.
Table 38. Utilities supplied with MQSeries classes for Java Message Service
Utility Use
IVTRun.bat Used to run the point-to-point installation verification test
IVTTidy.bat program, described in “Running the point-to-point IVT” on
IVTSetup.bat page 22.
PSIVTRun.bat Used to run the Pub/Sub installation verification test program
described in “The Publish/Subscribe Installation Verification
Test” on page 25.
formatLog.bat Used to convert binary log files to plain text, described in
“Logging” on page 29.
JMSAdmin.bat Used to run the administration tool, described in “Chapter 5.
Using the MQ JMS administration tool” on page 31.
JMSAdmin.config Configuration file for the administration tool, described in
“Configuration” on page 32.
runjms.bat A utility script to assist with the running of JMS applications,
described in “Running your own MQ JMS programs” on
page 28.
PSReportDump.class Used to view broker report messages, described in “Handling
broker reports” on page 188.
Note: On UNIX systems, the extension “.bat” is omitted from the filenames.

© Copyright IBM Corp. 1997, 2001 351

Scripts

352 MQSeries Using Java

 Appendix C. LDAP schema definition for storing Java objects
| This appendix gives details of the schema definitions (objectClass and attribute
| definitions) needed in an LDAP directory in order for it to store Java objects. Its
| intended audience is users wishing to use an LDAP server as their JNDI service
| provider in which to store MQ JMS administered objects. You should ensure that
| your LDAP server schema contains the following definitions; the exact procedure
| to achieve this will vary from server to server. How to make the changes to some
| specific LDAP servers is covered later in this section.

| Much of the data contained in this appendix has been taken from RFC 2713 Schema
| for Representing Java Objects in an LDAP Directory, which can be found at
| http://www.faqs.org/rfcs/rfc2713.html. LDAP server-specific information has been
| taken from Sun Microsystems’ JNDI 1.2.1 LDAP service provider, available at
| http://java.sun.com/products/jndi.

Checking your LDAP server configuration

| To check whether the LDAP server is already configured to accept Java objects, run
| the MQ JMS Administration Tool JMSAdmin against your LDAP server (see
| “Invoking the Administration tool” on page 31).

Attempt to create and display a test object using the following commands:
DEFINE QCF(ldapTest)
DISPLAY QCF(ldapTest)

| If no errors occur, your server is properly configured to store Java objects and you
| can proceed to store JMS objects. However, if your LDAP server contains older
| schema definitions (for example, from an earlier draft of RFC 2713 such as the
| now-obsolete “draft-ryan-java-schema-00” and “draft-ryan-java-schema-01”
| specifications), you should update them with those presented here.

| If a SchemaViolationException occurs, or if the message “Unable to bind to object”

| is returned, your server is not properly configured. Either your server is not
| configured to store Java objects, or permissions on the objects are not correct, or
| the provided suffix or context has not been set up. The following information
| should help you with the schema configuration part of your server setup.

© Copyright IBM Corp. 1997, 2001 353

 Attribute definitions

| Attribute definitions
| Table 39. Attribute settings for javaCodebase
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.7
| Syntax IA5 String (1.3.6.1.4.1.1466.115.121.1.26)
| Maximum length 2048
| Single/multi-valued Multi-valued
| User modifiable? Yes
| Matching rules caseExactIA5Match
| Access class normal
| Usage userApplications
| Description URL(s) specifying the location of class definition
|
| Table 40. Attribute settings for javaClassName
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.6
| Syntax Directory String (1.3.6.1.4.1.1466.115.121.1.15)
| Maximum length 2048
| Single/multi-valued Single-valued
| User modifiable? Yes
| Matching rules caseExactMatch
| Access class normal
| Usage userApplications
| Description Fully qualified name of distinguished Java class or interface
|
| Table 41. Attribute settings for javaClassNames
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.13
| Syntax Directory String (1.3.6.1.4.1.1466.115.121.1.15)
| Maximum length 2048
| Single/multi-valued Multi-valued
| User modifiable? Yes
| Matching rules caseExactMatch
| Access class normal
| Usage userApplications
| Description Fully qualified Java class or interface name
|

354 MQSeries Using Java

 Attribute definitions
| Table 42. Attribute settings for javaFactory
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.10
| Syntax Directory String (1.3.6.1.4.1.1466.115.121.1.15)
| Maximum length 2048
| Single/multi-valued Single-valued
| User modifiable? Yes
| Matching rules caseExactMatch
| Access class normal
| Usage userApplications
| Description Fully qualified Java class name of a JNDI object factory
|
| Table 43. Attribute settings for javaReferenceAddress
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.11
| Syntax Directory String (1.3.6.1.4.1.1466.115.121.1.15)
| Maximum length 2048
| Single/multi-valued Multi-valued
| User modifiable? Yes
| Matching rules caseExactMatch
| Access class normal
| Usage userApplications
| Description Addresses associated with a JNDI Reference
|
| Table 44. Attribute settings for javaSerializedData
| Attribute Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.1.8
| Syntax Octet String (1.3.6.1.4.1.1466.115.121.1.40)
| Single/multi-valued Single-valued
| User modifiable? Yes
| Access class normal
| Usage userApplications
| Description Serialized form of a Java object
|

| objectClass definitions
| Table 45. objectClass definition for javaSerializedObject
| Definition Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.2.5
| Extends/superior javaObject
| Type AUXILIARY
| Required (must) attrs javaSerializedData
|

Appendix C. LDAP schema definition for storing Java objects 355

 objectClass definitions
| Table 46. objectClass definition for javaObject
| Definition Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.2.4
| Extends/superior top
| Type ABSTRACT
| Required (must) attrs javaClassName
| Optional (may) attrs javaClassNames javaCodebase javaDoc description
|
| Table 47. objectClass definition for javaContainer
| Definition Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.2.1
| Extends/superior top
| Type STRUCTURAL
| Required (must) attrs cn
|
| Table 48. objectClass definition for javaNamingReference
| Definition Value
| OID (Object Identifier) 1.3.6.1.4.1.42.2.27.4.2.7
| Extends/superior javaObject
| Type AUXILIARY
| Optional (may) attrs javaReferenceAddress javaFactory
|

| Server-specific configuration details

| Netscape Directory (4.1 and earlier)

| This level of Netscape Directory does not support the Octet String syntax, so
| Binary syntax (1.3.6.1.4.1.1466.115.121.1.5) should be used in its place. Netscape
| Directory 4.1 also has problems parsing an object class definition which contains a
| MUST clause without parentheses. The workaround is to add a superfluous value
| (objectClass) to each MUST clause.

| Alternatively, you may wish to use the Sun-supplied schema modification

| applications described in “Sun Microsystems’ Schema Modification Applications”
| on page 357.

| Microsoft® Active Directory

| Within Active Directory, only the names of structural classes (not auxiliary classes)
| may appear in the object class attribute of an entry. Therefore, the abstract and
| auxiliary classes in the Java schema definition should be re-defined as structural.
| This has the following effects:
| v the javaObject class should now inherit from javaContainer
| v the javaNamingReference and javaSerializedObject classes should now inherit
| from javaObject

| Instead of making these changes manually, you may wish to use the Sun-supplied
| schema modification applications described in “Sun Microsystems’ Schema
| Modification Applications” on page 357.

356 MQSeries Using Java

 Sun Microsystems’ Schema Modification Applications
| Sun Microsystems’ Schema Modification Applications
| You can use your LDAP server’s administration tool (for example, the Directory
| Management Tool for IBM’s SecureWay® Directory) to verify or add the definitions
| described above. Alternatively, Sun Microsystems’ JNDI 1.2.1 LDAP service
| provider (available at http://java.sun.com/products/jndi) contains Java
| applications (CreateJavaSchema.java and UpdateJavaSchema.java) which will add
| or update the required schema definitions automatically. These applications contain
| workarounds for schema bugs and server-specific behavior in both Netscape
| Directory Server (pre-4.1 and 4.1) and Microsoft Windows 2000 Active Directory.

| These applications are not packaged with MQSeries classes for Java Message
| Service. Details on running them can be found in both the README and the
| application source contained in the Sun JNDI 1.2.1 LDAP service provider
| download.

| iSeries OS/400 V4R5 Schema Modification

| You can use your LDAP server’s administration tool (the Directory Management
| Tool for IBM’s SecureWay Directory) to verify or add the definitions described
| above.

| OS/400 V4R5 LDAP Server is shipped with an out of date version of RFC 2713
| schema for java objects. This schema must be updated to the schema as described
| above for correct operation with JMSAdmin. Modifying the schema requires the
| out of data definitions and any uses of those definitions to be deleted before the
| correct definitions can be added.

| OS/400 V5R1 is shipped with the current version of RFC 2713 and does not
| require these changes.

Appendix C. LDAP schema definition for storing Java objects 357

358 MQSeries Using Java
Appendix D. Connecting to MQSeries Integrator V2
You can use MQSeries Integrator V2:
v as the publish/subscribe broker for MQ JMS
v to route or transform messages that are created by a JMS client application, and
to send or publish messages to a JMS client

Publish/subscribe
You can use MQSeries Integrator V2 as the publish/subscribe broker for MQ JMS.
This requires the following setup activities:
v Base MQSeries
First, you must create a broker publication queue. This is an MQSeries queue on
the broker queue manager; it is used to submit publications to the broker. You
can choose your own name for this queue but it must match the queue name in
your TopicConnectionFactory’s BROKERPUBQ property. By default, a
TopicConnectionFactory’s BROKERPUBQ property is set to the value
SYSTEM.BROKER.DEFAULT.STREAM so, unless you want to configure a
different name in the TopicConnectionFactory, you should name the queue
SYSTEM.BROKER.DEFAULT.STREAM.
v MQSeries Integrator V2
The next step is to set up a message flow within an execution group for the
broker. The purpose of this message flow is to read messages from the broker
publication queue. (If you want, you can set up multiple publication queues;
each will need its own TopicConnectionFactory and message flow.)
The basic message flow consists of an MQInput node (configured to read from
the SYSTEM.BROKER.DEFAULT.STREAM queue) whose output is connected to
the input of a Publication (or MQOutput) node.
The message flow diagram would therefore look similar to the following:

Figure 7. MQSeries Integrator message flow

When this message flow is deployed and the broker is started, from the JMS
application’s perspective the MQSeries Integrator V2 broker behaves like an
MQSeries Publish/Subscribe broker. The current subscription state can be
viewed using the MQSeries Integrator Control Center.
Notes:
1. No modifications are required to MQSeries classes for Java Message Service.
2. MQSeries Publish/Subscribe and MQSeries Integrator V2 brokers cannot
coexist on the same queue manager.
3. Details of the MQSeries Integrator V2 installation and setup procedure are
described in the MQSeries Integrator for Windows NT Version 2.0 Installation
Guide.

© Copyright IBM Corp. 1997, 2001 359

 Connecting to MQSeries Integrator V2

Transformation and routing

You can use MQSeries Integrator V2 to route or transform messages that are
created by a JMS client application, and to send or publish messages to a JMS
client.

The MQSeries JMS implementation uses the mcd folder of the MQRFH2 to carry
information about the message, as described in “The MQRFH2 header” on
page 196. By default, the Message Domain (Msd) property is used to identify
| whether the message is a text, bytes, stream, map, or object message. This value is
| set depending on the type of the JMS message.

| If the application calls setJMSType it can set the mcd type field to a value of its
| choosing. This type field can be read by the MQSeries Integrator message flow,
| and a receiving JMS application can use the getJMSType method to retrieve its
| value. This applies to all kinds of JMS message.

| When a JMS application creates a text or bytes message, the application can set
| mcd folder fields explicitly by calling the setJMSType method and passing in a
| string argument in a special URI format as follows:
mcd://domain/[set]/[type][?format=fmt]

| This URI form allows an application to set the mcd to a domain that is not one of
| the standard “jms_xxxx” values; for example, to domain “mrm”. It also allows the
| application to set any or all of the mcd set, type and format fields if desired.

| The string argument to setJMSType is interpreted as follows:

| 1. If the string does not appear to be in the special URI format (i.e. it does not
| start with “mcd://”) then the string is added to the mcd folder as the type
| field.
| 2. If the string does start with “mcd://” and conforms to the URI format and the
| message is a Text or Bytes message, then the URI string is split into its
| constituent parts. The domain part overrides the jms_text or jms_bytes value
| that would otherwise have been generated, and the remaining parts (if present)
| are used to set the set, type and format fields in the mcd. Note that set, type
| and format are all optional.
| 3. If the string starts with “mcd://” and the message is a Map, Stream or Object
| message then the setJMSType call throws an exception. So you cannot override
| the domain, or provide a set or format for these classes of message, but you
| can provide a type if you wish.

| When an MQ message is received with an Msd domain other than one of the
| standard “jms_xxxx” values, it is instantiated as a JMS text or bytes message and a
| URI-style JMSType is assigned to it. The receiving application can read this using
| the getJMSType method.

360 MQSeries Using Java

 Appendix E. JMS JTA/XA interface with WebSphere
MQSeries classes for Java Message Service includes the JMS XA interfaces. These
allow MQ JMS to participate in a two-phase commit that is coordinated by a
transaction manager that complies with the Java Transaction API (JTA).

This section describes how to use these features with the WebSphere Application
Server, Advanced Edition, so that WebSphere can coordinate JMS send and receive
operations, and database updates, in a global transaction.
Notes:
1. Before you use MQ JMS and the XA classes with WebSphere, there might be
additional installation or configuration steps. Refer to the Readme.txt file on the
MQSeries Using Java SupportPac Web page for the latest information
(www.ibm.com/software/ts/mqseries/txppacs/ma88.html).
| 2. The functions described here are not supported in MQ Java for iSeries &
| AS/400.

Using the JMS interface with WebSphere

This section provides guidance on using the JMS interface with the WebSphere
Application Server, Advanced Edition.

You must already understand the basics of JMS programs, MQSeries, and EJB
beans. These details are in the JMS specification, the EJB V2 specification (both
available from Sun), this manual, the samples provided with MQ JMS, and other
manuals for MQSeries and WebSphere.

Administered objects
JMS uses administered objects to encapsulate vendor-specific information. This
minimizes the impact of vendor-specific details on end-user applications.
Administered objects are stored in a JNDI namespace, and can be retrieved and
used in a portable manner without knowledge of the vendor-specific contents.

For standalone use, MQ JMS provides the following classes:

v MQQueueConnectionFactory
v MQQueue
v MQTopicConnectionFactory
v MQTopic

WebSphere provides an additional pair of administered objects so that MQ JMS can

integrate with WebSphere:
v JMSWrapXAQueueConnectionFactory
v JMSWrapXATopicConnectionFactory

You use these objects in exactly the same way as the MQQueueConnectionFactory
and MQTopicConnectionFactory. However, behind the scenes they use the XA
versions of the JMS classes, and enlist the MQ XAResource in the WebSphere
transaction.

© Copyright IBM Corp. 1997, 2001 361

JMS JTA/XA interface with WebSphere
Container-managed versus bean-managed transactions
Container-managed transactions are transactions in EJB beans that are demarcated
automatically by the EJB container. Bean-managed transactions are transactions in
EJB beans that are demarcated by the program (via the UserTransaction interface).

Two-phase commit versus one-phase optimization

The WebSphere coordinator only invokes a true two-phase commit if more than
one XAResource is used in a particular transaction. Transactions that involve a
single resource are committed using a one-phase optimization. This largely
removes the need to use different ConnectionFactories for distributed and
non-distributed transactions.

Defining administered objects

You can use the MQ JMS administration tool to define the WebSphere-specific
connection factories and store them in a JNDI namespace. The admin.config file in
MQ_install_dir/bin should contain the following lines:
INITIAL_CONTEXT_FACTORY=com.ibm.ejs.ns.jndi.CNInitialContextFactory
PROVIDER_URL=iiop://hostname/

MQ_install_dir is the installation directory for MQ JMS, and hostname is the name
or IP address of the machine that is running WebSphere.

To access the com.ibm.ejs.ns.jndi.CNInitialContextFactory, you must add the file

ejs.jar from the WebSphere lib directory to the CLASSPATH.

To create the new factories, use the define verb with the following two new types:
def WSQCF(name) [properties]
def WSTCF(name) [properties]

These new types use the same properties as the equivalent QCF or TCF types,
except that only the BIND transport type is allowed (and therefore, client
properties cannot be configured). For details, see “Administering JMS objects” on
page 35.

Retrieving administration objects

In an EJB bean, you retrieve the JMS-administered objects using the
InitialContext.lookup() method, for example:
InitialContext ic = new InitialContext();
TopicConnectionFactory tcf = (TopicConnectionFactory) ic.lookup("jms/Samples/TCF1");

The objects can be cast to, and used as, the generic JMS interfaces. Normally, there
is no need to program to the MQSeries specific classes in the application code.

Samples
There are three samples that illustrate the basics of using MQ JMS with WebSphere
Application Server Advanced Edition. These are in subdirectories of
MQ_install_dir/samples/ws, where MQ_install_dir is the installation directory for
MQ JMS.
v Sample1 demonstrates a simple put and get for a message in a queue by using
container-managed transactions.
v Sample2 demonstrates a simple put and get for a message in a queue by using
bean-managed transactions.

362 MQSeries Using Java

 JMS JTA/XA interface with WebSphere
v Sample3 illustrates the use of the publish/subscribe API.

For details about how to build and deploy the EJB beans, please refer to the
WebSphere Application Server documentation.

The readme.txt files in each sample directory include example output from each
EJB bean. The scripts provided assume that a default queue manager is available
on the local machine. If your installation varies from the default, you can edit these
scripts as required.

Sample1
Sample1EJB.java, in the sample1 directory, defines two methods that use JMS:
v putMessage() sends a TextMessage to a queue, and returns the MessageID of the
sent message
v getMessage() reads the message with the specified MessageID back from the
queue

Before you run the sample, you must store two administered objects in the
WebSphere JNDI namespace:
QCF1 a WebSphere-specific queue connection factory
Q1 a queue

Both objects must be bound in the jms/Samples sub-context.

To set up the administered objects, you can either use the MQ JMS administration
tool and set them up manually, or you can use the script provided.

The MQ JMS administration tool must be configured to access the WebSphere

namespace. For details about how to configure the administration tool, refer to
“Configuring for WebSphere” on page 33.

To set up the administered objects with typical default settings, you can enter the
following command to run the script admin.scp:
JMSAdmin < admin.scp

The bean must be deployed with the getMessage and putMessage methods marked
as TX_REQUIRED. This ensures that the container starts a transaction before
entering each method, and commits the transaction when the method completes.
Within the methods, you do not need any application code that relates to the
transactional state. However, remember that the message sent from putMessage
occurs under syncpoint, and will not become available until the transaction is
committed.

In the sample1 directory, there is a simple client program, Sample1Client.java, to

call the EJB bean. There is also a script, runClient, to simplify running this
program.

The client program (or script) takes a single parameter, which is used as the body
of a TextMessage that will be sent by the EJB bean putMessage method. Then, the
getMessage is called to read the message back off the queue and return the body to
the client for display. The EJB bean sends progress messages to the standard
output (stdout) of the application server, so you might wish to monitor that output
during the run.

Appendix E. JMS JTA/XA interface with WebSphere 363

JMS JTA/XA interface with WebSphere
If the application server is on a machine that is remote from the client, you might
need to edit Sample1Client.java. If you do not use the defaults, you may need to
edit the runClient script to match the local installation path and name of the
deployed jar file.

Sample2
Sample2EJB.java, in the sample2 directory, performs the same task as sample1, and
requires the same administered objects. Unlike sample1, sample2 uses
bean-managed transactions to control the transactional boundaries.

If you have not already run sample1, ensure that you set up the administered
objects QCF1 and Q1, as described in “Sample1” on page 363.

The putMessage methods and getMessage methods start by obtaining an instance

of UserTransaction. They use this instance to create a transaction via the
UserTransaction.begin() method. After that, the main body of the code is the same
as sample1 until the end of each method. At the end of each method, the
transaction is completed by the UserTransaction.commit() call.

In the sample2 directory, there is a simple client program, Sample2Client.java, to

call the EJB bean. There is also a script, runClient, to simplify running this
program. You can use these in the same way as described for “Sample1” on
page 363.

Sample3
Sample3EJB.java, in the sample3 directory, demonstrates the use of the
publish/subscribe API with WebSphere. Publishing a message is very similar to the
point to point case. However, there are differences when receiving messages via a
TopicSubscriber.

Publish/subscribe programs commonly use nondurable subscribers. These

nondurable subscribers exist only for the lifetime of their owning sessions (or less
if the subscriber is closed explicitly). Also, they can receive messages from the
broker only during that lifetime.

To convert sample1 to publish/subscribe, you might replace the QueueSender in

putMessage with a TopicPublisher, and the QueueReceiver in getMessage with a
nondurable TopicSubscriber. However, this would fail, because when the message
is sent, the broker would not know of any subscribers to the topic. Therefore, the
message would be discarded.

The solution is to create a durable subscriber before the message is published.

Durable subscribers persist as a deliverable end-point beyond the lifetime of the
session. Therefore, the message is available for retrieval during the call to
getMessage().

The EJB bean includes two additional methods:

v createSubscription creates a durable subscription
v destroySubscription deletes a durable subscription
These methods (along with putMessage and getMessage) must be deployed with
the TX_REQUIRED attribute.

364 MQSeries Using Java

 JMS JTA/XA interface with WebSphere
Before you run sample3, you must store two administered objects in the
WebSphere JNDI namespace:
TCF1
T1

Both objects must be bound in the jms/Samples sub-context.

To set up the administered objects, you can either use the MQ JMS administration
tool and set them up manually, or you can use a script. The script admin.scp is
provided in the sample3 directory.

The MQ JMS administration tool must be configured to access the WebSphere

namespace. For details about how to configure the administration tool, refer to
“Configuring for WebSphere” on page 33.

To set up the administered objects with typical default settings, you can enter the
following command to run the script admin.scp:
JMSAdmin < admin.scp

If you have already run admin.scp to set up objects for sample1 or sample2, there
will be error messages when you run admin.scp for sample3. (These occur when
you attempt to create the jms and Samples sub-contexts.) You can safely ignore
these error messages.

Also, before you run sample3, ensure that the MQSeries publish/subscribe broker
(SupportPac MA0C) is installed and running.

In the sample3 directory, there is a simple client program, Sample3Client.java, to

call the EJB bean. There is also a script, runClient, to simplify running this
program. You can use these in the same way as described for “Sample1” on
| page 363.

Appendix E. JMS JTA/XA interface with WebSphere 365

366 MQSeries Using Java
|

| Appendix F. Using MQ Java in applets with Java 1.2 or later

| You may need to perform additional tasks to run an applet using MQ Java classes
| in a Java virtual machine (JVM) at Java 1.2 level or greater. This is because the
| default security rules for applets with JVMs at these levels were changed to reduce
| the risk of damage by malevolent or misbehaving classes.

| There are two different approaches that you can take:

| 1. Change the security settings on the browser and JVM to allow the use of MQ
| Java packages.
| 2. Copy the MQ Java classes to the same location as the applet you wish to run.
|
| Changing browser security settings
| Different errors can result from trying to run the same applet in different
| environments; for example, in IBM VisualAge for Java, in appletviewer (supplied
| with most Java Development Kits) or in a web browser such as Internet Explorer.
| The differences are to do with different security settings in each environment. You
| can change the behavior of the environments to allow an applet access to the
| classes it needs that are stored in package files.

| In the following instructions, examples assume use of the Windows platform. On

| other platforms, the instructions will need slight modification.
| For IBM VisualAge for Java:
| You must change the java.policy file found in
| <vaj_install_dir>\ide\program\lib\security, where “<vaj_install_dir>”
| is the directory in which you installed IBM VisualAge for Java.
| Make the following changes to the permissions:
| 1. Comment out the line
| permission java.net.SocketPermission "localhost:1024-", "listen";

| and replace it with the following line:

| permission java.net.SocketPermission "*", "accept, connect, listen, resolve";
| 2. Add the following lines:
| permission java.util.PropertyPermission "MQJMS_LOG_DIR", "read";
| permission java.util.PropertyPermission "MQJMS_TRACE_DIR", "read";
| permission java.util.PropertyPermission "MQJMS_TRACE_LEVEL", "read";
| permission java.lang.RuntimePermission "loadLibrary.*";
| Notes:
| 1. You may need to restart VisualAge for Java if you get the error message
| “Unknown Java Error” after repeated tests.
| 2. Make sure that <ma88_install_dir>\java\lib is in the workspace
| classpath.
| For appletviewer:
| Find the policy file for your JDK and make the same changes as for IBM
| VisualAge for Java. For example, in the IBM Developer Kit for Windows,
| Java Technology Edition, Version 1.3, the java.policy file is found in the

© Copyright IBM Corp. 1997, 2001 367

 Changing browser security
| directory <jdk_install_dir>\jre\lib\security, where
| “<jdk_install_dir>” is the directory where the Developer Kit was
| installed.
| For a web browser:
| To achieve consistent behavior for applets within different web browsers
| use the Sun Java plug-in.
| 1. Install the Sun Java plug-in 1.3.01 or later.
| From this level, Netscape 6 is also supported.
| 2. Make the same changes to the java.policy file as listed above.
| The policy file is found in <java_plugin_install_dir>\lib\security.
| 3. Make sure that your HTML applet tags are changed to run with the
| plug-in.
| Download and run the Sun HTML Converter v1.3 to make the
| necessary changes.
|
| Copying package class files
| When a Java program is executed in the context of an applet (which is what is
| done when appletviewer is executed or a web browser is used), by default the Java
| program has significant security restrictions applied to it. One of these restrictions
| is that all environment variables in effect when the applet is launched are ignored.
| This includes CLASSPATH.

| As a result, unless you make the changes described in “Changing browser security
| settings” on page 367, when an applet is executed, each and every class that it
| needs must also be available for download from the same location as the applet
| code itself.

| To achieve this on a Windows system, perform the following steps (non-Windows

| users will need to perform similar tasks):
| 1. Download and install WINZIP (http://www.winzip.com) or equivalent file
| unzipping utility
| 2. Find the files containing the MQ Java, or other package, classes that your
| applet needs.
| For example, MQ base Java classes are in a file called com.ibm.mq.jar usually
| found in the C:\Program Files\IBM\MQSeries\Java\lib folder.
| 3. Using the unzipping utility you installed in step 1, extract all the files in the .jar
| file into the folder that contains your applet.
| For the samples supplied with MQ Java, the folder to use is C:\Program
| Files\IBM\MQSeries\Java\samples\base
| This will result in a sub-folder structure com\ibm being created.
| 4. Run your applet.

368 MQSeries Using Java

|

| Appendix G. Information for SupportPac MA1G

| This appendix contains information that is relevant to users of SupportPac MA1G
| “MQSeries for MVS/ESA – MQSeries classes for Java”. MA1G provides support for
| MQSeries classes for Java from versions of OS/390 not supported by MA88. It also
| provides support for CICS and High Performance Java (HPJ).

| Users intending to use the MQ base Java with CICS Transaction Server for OS/390
| should be familiar with:
| v Customer Information Control System (CICS) concepts
| v Using the CICS Java Application Programming Interface (API)
| v Running Java programs from within CICS

| Users intending to use VisualAge for Java to develop OS/390 UNIX System
| Services High Performance Java (HPJ) applications should be familiar with the
| Enterprise Toolkit for OS/390 (supplied with VisualAge for Java Enterprise Edition
| for OS/390, Version 2).
|
| Environments supported by SupportPac MA1G
| SupportPac MA1G provides support for MQ base Java from the following
| environments:
| v OS/390 V2R6 or higher
| v Java for OS/390, V1.1.8 or higher
| v IBM MQSeries for MVS/ESA, Version 1.2 or higher
| v High Performance Java (HPJ)

| SupportPac MA1G also provides support for CICS TS1.3 or higher. Support for
| HPJ in this environment requires OS/390 V2R9 or higher.

| SupportPac MA1G does not provide support for JMS.

|
| Obtaining and installing SupportPac MA1G
| SupportPac MA1G should be obtained from the MQSeries web site
| http://www.ibm.com/software/mqseries. Follow links to “Download” and then
| “SupportPacs” to find the MQ Java code.

| The following procedure installs the MQSeries classes for Java. The directory used
| for the installation needs at least 2MB of free storage. In the following, replace
| “/u/joe/mqm” with the path name of the directory you choose:
| 1. Remove any previous installation of this product using the following
| commands in the OpenEdition shell:
| cd /u/joe
| chmod -fR 700 mqm
| rm -rf mqm
| mkdir mqm
| 2. Using FTP binary mode, upload the file ma1g.tar.Z from your workstation to
| the HFS directory /u/joe/mqm.

© Copyright IBM Corp. 1997, 2001 369

 Obtaining and installing
| 3. While in the OpenEdition shell, change to the installation directory
| /u/joe/mqm.
| 4. Uncompress and untar the file with the command
| tar -xpozf ma1g.tar.Z
| 5. Set up your CLASSPATH and LIBPATH as described in “Environment
| variables” on page 11.

| Verifying installation using the sample program

| To verify installation of MA1G from Unix System Services (USS), follow the
| instructions in “Verifying with the sample application” on page 16.

| To verify installation of MA1G from CICS Transaction Server:

| 1. Define the sample application program (MQIVP) to CICS.
| 2. Define a transaction to run the sample application.
| 3. Put the queue manager name into the file used for standard input.
| 4. Run the transaction.

| The program output is placed in the files used for standard and error output.

| Refer to CICS documentation for more information on running Java programs and
| setting the input and output files.
|
| Features not provided by SupportPac MA1G
| SupportPac MA1G provides a subset of features available to other MQ base Java
| applications. In particular, it does not support the ConnectionPooling feature
| described in “Chapter 7. Writing MQ base Java programs” on page 51. The
| following classes and methods are not supported:
| v Classes and Interfaces
| – MQPoolServices
| – MQPoolServicesEvent
| – MQPoolToken
| – MQSimpleConnectionManager
| – MQPoolServicesEventListener
| – MQConnectionManager
| – ManagedConnection
| – ManagedConnectionFactory
| – ManagedConnectionMetaData
| v Methods
| – MQEnvironment.getDefaultConnectionManager()
| – MQEnvironment.setDefaultConnectionManager()
| – MQEnvironment.addConnectionPoolToken()
| – MQEnvironment.removeConnectionPoolToken()
| – The six MQQueueManager constructors which allow a ConnectionManager or
| MQConnectionManager to be specified.
| Attempting to use these classes, interfaces or methods will result in compile-time
| errors or run-time exceptions.

370 MQSeries Using Java

 Running MQ base Java applications under CICS
|
| Running MQ base Java applications under CICS Transaction Server for
| OS/390
| To run a Java application as a transaction under CICS, you must:
| 1. Define the application and transaction to CICS by using the supplied CEDA
| transaction.
| 2. Ensure that the MQSeries CICS adapter is installed in your CICS system. (See
| MQSeries for OS/390 System Management Guide for details.)
| 3. Ensure that the JVM environment specified in the DHFJVM parameter of your
| CICS startup JCL (Job Control Language) includes appropriate CLASSPATH
| and LIBPATH entries.
| 4. Initiate the transaction by using any of your normal processes.

| For more information on running CICS Java transactions, refer to your CICS
| system documentation.
|
| Restrictions under CICS Transaction Server
| In the CICS Transaction Server for OS/390 environment, only the main (first)
| thread is allowed to issue CICS or MQSeries calls. It is therefore not possible to
| share MQQueueManager or MQQueue objects between threads in this
| environment, or to create a new MQQueueManager on a child thread.

| Table 12 on page 74 lists the restrictions and variations which apply to the
| MQSeries classes for Java when running against an OS/390 MQSeries queue
| manager. Additionally, when running under CICS, the transaction control methods
| on MQQueueManager are not supported. Instead of issuing
| MQQueueManager.commit() or MQQueueManager.backout(), applications should
| use the JCICS task synchronization methods, Task.commit() and Task.rollback().
| The Task class is supplied by JCICS in the com.ibm.cics.server package.

Appendix G. Information for SupportPac MA1G 371

372 MQSeries Using Java
Appendix H. Notices
This information was developed for products and services offered in the United
States. IBM may not offer the products, services, or features discussed in this
information in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply
that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user’s responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this information. The furnishing of this information does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 1997, 2001 373

Notices
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM United Kingdom Laboratories,
Mail Point 151,
Hursley Park,
Winchester,
Hampshire,
England
SO21 2JN.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Programming License Agreement, or any equivalent agreement
between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:

AIX AS/400 BookManager

CICS IBM IBMLink
Language Environment MQSeries MVS/ESA
OS/2 OS/390 OS/400
SecureWay SupportPac System/390
S/390 VisualAge VSE/ESA
WebSphere

Java, HotJava, JDK, and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the United States, other
countries, or both.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in

the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other company, product, and service names may be trademarks or service marks
of others.

374 MQSeries Using Java

Glossary of terms and abbreviations
This glossary describes terms used in this book HTML. Hypertext Markup Language
and words used with other than their everyday
Hypertext Markup Language (HTML). A language
meaning. In some cases, a definition may not be
used to define information that is to be displayed on
the only one applicable to a term, but it gives the
the World Wide Web.
particular sense in which the word is used in this
book. IEEE. Institute of Electrical and Electronics Engineers.

If you do not find the term you are looking for, IIOP. Internet Inter-ORB Protocol.
see the index or the IBM Dictionary of Computing,
Internet Inter-ORB Protocol (IIOP). A standard for
New York: McGraw-Hill, 1994. TCP/IP communications between ORBs from different
vendors.
Abstract Window Toolkit for Java (AWT). A
collection of Graphical User Interface (GUI) instance. An instance is an object. When a class is
components that are implemented using instantiated to produce an object, we say that the object
native-platform versions of the components. is an instance of the class.
applet. A Java program which is designed to run only interface. An interface is a class that contains only
on a Web page. abstract methods and no instance variables. An
interface provides a common set of methods that can
API. Application Programming Interface.
be implemented by subclasses of a number of different
Application Programming Interface (API). An classes.
Application Programming Interface consists of the
Internet. The Internet is a cooperative public network
functions and variables that programmers are allowed
of shared information. Physically, the Internet uses a
to use in their applications.
subset of the total resources of all the currently existing
AWT. Abstract Window Toolkit for Java. public telecommunication networks. Technically, what
distinguishes the Internet as a cooperative public
casting. A term used in Java to describe the explicit network is its use of a set of protocols called TCP/IP
conversion of the value of an object or primitive type (Transmission Control Protocol/Internet Protocol).
into another type.
JAAS. Java Authentication and Authorization Service.
channel. See MQI channel.
Java Authentication and Authorization Service
class. A class is an encapsulated collection of data and (JAAS). A Java service that provides entity
methods to operate on the data. A class may be authentication and access control.
instantiated to produce an object that is an instance of
the class. | Java Development Kit (JDK). A package of software
| distributed for Java developers, by Sun Microsystems
client. In MQSeries, a client is a runtime component | or others. It includes the Java interpreter, Java classes
that provides access to queuing services on a server for | and Java development tools: compiler, debugger,
local user applications. | disassembler, appletviewer, stub file generator, and
| documentation generator.
EJB. Enterprise JavaBeans.
Java Naming and Directory Service (JNDI). An API
encapsulation. Encapsulation is an object-oriented specified in the Java programming language. It
programming technique that makes an object’s data provides naming and directory functions to
private or protected and allows programmers to access applications written in the Java programming language.
and manipulate the data only through method calls.
Java Message Service (JMS). Sun Microsystem’s API
Enterprise JavaBeans (EJB). A server-side component for accessing enterprise messaging systems from Java
architecture, distributed by Sun Microsystems, for programs.
writing reusable business logic and portable enterprise
applications. Enterprise JavaBean components are Java Runtime Environment (JRE). A subset of the
written entirely in Java and run on any EJB compliant Java Development Kit (JDK) that contains the core
server. executables and files that constitute the standard Java

© Copyright IBM Corp. 1997, 2001 375

Glossary
platform. The JRE includes the Java Virtual Machine, MQSeries. MQSeries is a family of IBM licensed
core classes, and supporting files. programs that provide message queuing services.

Java Transaction API (JTA). An API that allows MQSeries commands (MQSC). Human-readable
applications and J2EE servers to access transactions. commands, uniform across all platforms, that are used
to manipulate MQSeries objects.
Java Transaction Service (JTS). A transaction manager
that supports JTA and implements the Java mapping of MQSeries Message Descriptor (MQMD). Control
the OMG Object Transaction Service 1.1 specification information that describes the message format and
below the level of the API. properties, that is carried as part of an MQSeries
message.
Java Virtual Machine (JVM). A software
implementation of a central processing unit (CPU) that object. (1) In Java, an object is an instance of a class. A
runs compiled Java code (applets and applications). class models a group of things; an object models a
particular member of that group. (2) In MQSeries, an
Java 2 Platform, Enterprise Edition (J2EE). A set of object is a queue manager, a queue, or a channel.
services, APIs, and protocols that provide the
functionality to develop multi-tiered, Web-based Object Request Broker (ORB). An application
applications. framework that provides interoperability between
objects, built in different languages, running on
JDK. Java Development Kit. different machines, in heterogeneous distributed
environments.
JNDI. Java Naming and Directory Service.
Object Management Group (OMG). A consortium
JMS. Java Message Service. that sets standards in object-oriented programming.
JRE. Java Runtime Environment. OMG. Object Management Group.
JTA. Java Transaction API. ORB. Object Request Broker.
JTS. Java Transaction Service. overloading. The situation where one identifier refers
to multiple items in the same scope. In Java, methods
JVM. Java Virtual Machine.
can be overloaded, but not variables or operators.
J2EE. Java 2 Platform, Enterprise Edition.
package. A package in Java is a way of giving a piece
LDAP. Lightweight Directory Access Protocol. of Java code access to a specific set of classes. Java code
that is part of a particular package has access to all the
Lightweight Directory Access Protocol (LDAP). A classes in the package and to all non-private methods
client-server protocol for accessing a directory service. and fields in the classes.

message. In message queuing applications, a message private. A private field is not visible outside its own
is a communication sent between programs. class.

message queue. See queue. protected. A protected field is visible only within its
own class, within a subclass, or within packages of
message queuing. A programming technique in which which the class is a part
each program within an application communicates with
the other programs by putting messages on queues. public. A public class or interface is visible
everywhere. A public method or variable is visible
method. Method is the object-oriented programming everywhere that its class is visible
term for a function or procedure.
queue. A queue is an MQSeries object. Message
MQDLH. MQSeries dead letter header. See MQSeries queueing applications can put messages on, and get
Application Programming Reference. messages from, a queue

MQI channel. An MQI channel connects an MQSeries queue manager. a queue manager is a system
client to a queue manager on a server system and program the provides message queuing services to
transfers MQI calls and responses in a bidirectional applications.
manner.
Red Hat Package Manager (RPM). A software
MQMD. MQSeries Message Descriptor. packaging system for use on Red Hat Linux platforms,
and other Linux and UNIX platforms.
MQSC. MQSeries commands.

376 MQSeries Using Java

 Glossary
| RFC. (Request For Comment) A document defining a
| standard that is part of the TCP/IP suite of protocols.
| An RFC starts out as a proposal and not all RFCs are
| adopted and implemented.

RPM. Red Hat Package Manager.

server. (1) An MQSeries a server is a queue manager

that provides message queuing services to client
applications running on a remote workstation. (2) More
generally, a server is a program that responds to
requests for information in the particular two-program
information flow model of client/server. (3) The
computer on which a server program runs.

servlet. A Java program which is designed to run only

on a Web server.

subclass. A subclass is a class that extends another.

The subclass inherits the public and protected methods
and variables of its superclass.

superclass. A superclass is a class that is extended by

some other class. The superclass’s public and protected
methods and variables are available to the subclass.

TCP/IP. Transmission Control Protocol/Internet

Protocol.

Transmission Control Protocol/Internet Protocol

(TCP/IP). A set of communication protocols that
support peer-to-peer connectivity functions for both
local and wide area networks.

Uniform Resource Locator (URL). A sequence of

characters that represent information resources on a
computer or in a network such as the Internet.

URL. Uniform Resource Locator.

VisiBroker for Java. An Object Request Broker (ORB)

written in Java.

Web. See World Wide Web.

Web browser. A program that formats and displays

information that is distributed on the World Wide Web.

World Wide Web (Web). The World Wide Web is an

Internet service, based on a common set of protocols,
which allows a particularly configured server computer
to distribute documents across the Internet in a
standard way.

Glossary of terms and abbreviations 377

Glossary

378 MQSeries Using Java

Bibliography
This section describes the documentation v MQSeries Application Programming Reference,
available for all current MQSeries products. SC33-1673
v MQSeries Programming Interfaces Reference
MQSeries cross-platform Summary, SX33-6095
publications v MQSeries Using C++, SC33-1877
v MQSeries Using Java, SC34-5456
Most of these publications, which are sometimes
v MQSeries Application Messaging Interface,
referred to as the MQSeries “family” books, apply
SC34-5604
to all MQSeries Level 2 products. The latest
MQSeries Level 2 products are:
v MQSeries for AIX, V5.2 MQSeries platform-specific
v MQSeries for AS/400, V5.2 publications
v MQSeries for AT&T GIS UNIX, V2.2
v MQSeries for Compaq (DIGITAL) OpenVMS, Each MQSeries product is documented in at least
V2.2.1.1 one platform-specific publication, in addition to
v MQSeries for Compaq Tru64 UNIX, V5.1 the MQSeries family books.
v MQSeries for HP-UX, V5.2
MQSeries for AIX, V5.2
v MQSeries for Linux, V5.2
v MQSeries for OS/2 Warp, V5.1 MQSeries for AIX Quick Beginnings,
v MQSeries for OS/390, V5.2 GC33-1867
v MQSeries for SINIX and DC/OSx, V2.2 MQSeries for AS/400, V5.2
v MQSeries for Sun Solaris, V5.2
MQSeries for AS/400 Quick Beginnings,
v MQSeries for Sun Solaris, Intel Platform
GC34-5557
Edition, V5.1
v MQSeries for Tandem NonStop Kernel, V2.2.0.1 MQSeries for AS/400 System
v MQSeries for VSE/ESA, V2.1.1 Administration, SC34-5558
v MQSeries for Windows, V2.0 MQSeries for AS/400 Application
v MQSeries for Windows, V2.1 Programming Reference (ILE RPG),
v MQSeries for Windows NT and Windows 2000, SC34-5559
V5.2
MQSeries for AT&T GIS UNIX, V2.2
The MQSeries cross-platform publications are: MQSeries for AT&T GIS UNIX System
Management Guide, SC33-1642
v MQSeries Brochure, G511-1908
v An Introduction to Messaging and Queuing, MQSeries for Compaq (DIGITAL) OpenVMS,
GC33-0805 V2.2.1.1
v MQSeries Intercommunication, SC33-1872 MQSeries for Compaq (DIGITAL)
OpenVMS System Management Guide,
v MQSeries Queue Manager Clusters, SC34-5349
GC33-1791
v MQSeries Clients, GC33-1632
MQSeries for Compaq Tru64 UNIX, V5.1
v MQSeries System Administration, SC33-1873
MQSeries for Compaq Tru64 UNIX Quick
v MQSeries MQSC Command Reference, SC33-1369
Beginnings, GC34-5684
v MQSeries Event Monitoring, SC34-5760
MQSeries for HP-UX, V5.2
v MQSeries Programmable System Management,
SC33-1482 MQSeries for HP-UX Quick Beginnings,
GC33-1869
v MQSeries Administration Interface Programming
Guide and Reference, SC34-5390 MQSeries for Linux, V5.2
v MQSeries Messages, GC33-1876 MQSeries for Linux Quick Beginnings,
v MQSeries Application Programming Guide, GC34-5691
SC33-0807

© Copyright IBM Corp. 1997, 2001 379

Bibliography
MQSeries for OS/2 Warp, V5.1 MQSeries for Windows NT and Windows
MQSeries for OS/2 Warp Quick 2000 Quick Beginnings, GC34-5389
Beginnings, GC33-1868 MQSeries for Windows NT Using the
Component Object Model Interface,
MQSeries for OS/390, V5.2
SC34-5387
MQSeries for OS/390 Concepts and
MQSeries LotusScript Extension,
Planning Guide, GC34-5650
SC34-5404
MQSeries for OS/390 System Setup
Guide, SC34-5651
MQSeries for OS/390 System
Softcopy books
Administration Guide, SC34-5652 Most of the MQSeries books are supplied in both
MQSeries for OS/390 Problem hardcopy and softcopy formats.
Determination Guide, GC34-5892
MQSeries for OS/390 Messages and HTML format
Codes, GC34-5891 Relevant MQSeries documentation is provided in
MQSeries for OS/390 Licensed Program HTML format with these MQSeries products:
Specifications, GC34-5893 v MQSeries for AIX, V5.2
v MQSeries for AS/400, V5.2
MQSeries for OS/390 Program Directory
v MQSeries for Compaq Tru64 UNIX, V5.1
MQSeries link for R/3, Version 1.2 v MQSeries for HP-UX, V5.2
MQSeries link for R/3 User’s Guide, v MQSeries for Linux, V5.2
GC33-1934 v MQSeries for OS/2 Warp, V5.1
v MQSeries for OS/390, V5.2
MQSeries for SINIX and DC/OSx, V2.2 v MQSeries for Sun Solaris, V5.2
MQSeries for SINIX and DC/OSx System v MQSeries for Sun Solaris, Intel Platform
Management Guide, GC33-1768 Edition, V5.1
v MQSeries for Windows NT and Windows 2000,
MQSeries for Sun Solaris, V5.2
V5.2 (compiled HTML)
MQSeries for Sun Solaris Quick v MQSeries link for R/3, V1.2
Beginnings, GC33-1870
The MQSeries books are also available in HTML
MQSeries for Sun Solaris, Intel Platform format from the MQSeries product family Web
Edition, V5.1 site at:
MQSeries for Sun Solaris, Intel Platform http://www.ibm.com/software/mqseries/
Edition Quick Beginnings, GC34-5851
MQSeries for Tandem NonStop Kernel, V2.2.0.1 Portable Document Format (PDF)
MQSeries for Tandem NonStop Kernel PDF files can be viewed and printed using the
System Management Guide, GC33-1893 Adobe Acrobat Reader.
MQSeries for VSE/ESA, V2.1.1
If you need to obtain the Adobe Acrobat Reader,
MQSeries for VSE/ESA™ Licensed or would like up-to-date information about the
Program Specifications, GC34-5365 platforms on which the Acrobat Reader is
MQSeries for VSE/ESA System supported, visit the Adobe Systems Inc. Web site
Management Guide, GC34-5364 at:
MQSeries for Windows, V2.0 http://www.adobe.com/

MQSeries for Windows User’s Guide, PDF versions of relevant MQSeries books are
GC33-1822 supplied with these MQSeries products:
MQSeries for Windows, V2.1 v MQSeries for AIX, V5.2
MQSeries for Windows User’s Guide, v MQSeries for AS/400, V5.2
GC33-1965 v MQSeries for Compaq Tru64 UNIX, V5.1
v MQSeries for HP-UX, V5.2
MQSeries for Windows NT and Windows 2000, v MQSeries for Linux, V5.2
V5.2 v MQSeries for OS/2 Warp, V5.1
v MQSeries for OS/390, V5.2

380 MQSeries Using Java

 Bibliography
v MQSeries for Sun Solaris, V5.2
v MQSeries for Sun Solaris, Intel Platform
Edition, V5.1
v MQSeries for Windows NT and Windows 2000,
V5.2
v MQSeries link for R/3, V1.2

PDF versions of all current MQSeries books are

also available from the MQSeries product family
Web site at:
http://www.ibm.com/software/mqseries/

BookManager® format
The MQSeries library is supplied in IBM
BookManager format on a variety of online
library collection kits, including the Transaction
Processing and Data collection kit, SK2T-0730. You
can view the softcopy books in IBM BookManager
format using the following IBM licensed
programs:
BookManager READ/2
BookManager READ/6000
BookManager READ/DOS
BookManager READ/MVS
BookManager READ/VM
BookManager READ for Windows

PostScript format
The MQSeries library is provided in PostScript
(.PS) format with many MQSeries Version 2
products. Books in PostScript format can be
printed on a PostScript printer or viewed with a
suitable viewer.

Windows Help format

The MQSeries for Windows User’s Guide is
provided in Windows Help format with MQSeries
for Windows, Version 2.0 and MQSeries for
Windows, Version 2.1.

MQSeries information available

on the Internet
The MQSeries product family Web site is at:
http://www.ibm.com/software/mqseries/

By following links from this Web site you can:

v Obtain latest information about the MQSeries
product family.
v Access the MQSeries books in HTML and PDF
formats.
v Download an MQSeries SupportPac.

Bibliography 381
MQSeries on the Internet

382 MQSeries Using Java

Index
A broker reports 189
BROKERCCDSUBQ object property 39,
classpath
configuring 19
accessing queues and processes 59 211, 351 settings 11
administered objects 36, 170 BROKERCCSUBQ object property 39, client properties 41
with WebSphere 361 211, 351 client transport, choosing 172
administering JMS objects 35 BROKERCONQ object property 39, 351 CLIENTID object property 39, 351
administration BROKERDURSUBQ object property 39, clients
commands 34 351 configuring queue manager 13
verbs 34 BROKERPUBQ object property 39, 351 connection 5
administration tool BROKERQMGR object property 39, 351 programming 51
configuration file 32 BROKERSUBQ object property 39, 351 verifying 16
configuring 32 BROKERVER object property 39, 351 closing
overview 31 building a connection 170 applications 177
property mapping 349 bytes message 191 JMS resources in Publish/Subscribe
starting 31 BytesMessage mode 181
advantages of Java interface 47 interface 232 resources 177
AIX, installing MQ Java 8 type 175 code examples 52
applets com.ibm.jms package 231
example code 52 com.ibm.mq.iiop.jar 7
running 70
security settings for 367 C com.ibm.mq.jar 7
com.ibm.mq.jms package 230
using MQ Java in 367 CCSID object property 39, 351
com.ibm.mqbind.jar 7
versus applications 51 CHANGE (administration verb) 34
com.ibm.mqjms.jar 7
appletviewer CHANNEL object property 39, 351
combinations, valid, of objects and
using 5, 13 choosing transport 172
properties 41
with sample applet 15 CICS Transaction Server
commands, administration 34
application example 56 running applications 371
compiling MQSeries classes for Java
Application Server Facilities 209 class library 49
programs 69
classes and functions 209 classes, Application Server Facilities 209
configuration file, for administration
sample client applications 219 classes, core 73
tool 32
sample code 215 extensions for V5 75
configuring
applications restrictions and variations 74, 371
environment variables 19
closing 177 classes, JMS 227
for Publish/Subscribe 20
Publish/Subscribe, writing 179 classes, MQSeries classes for Java 79
for WebSphere 33
running 70 ManagedConnection 161
LDAP server 353
unexpected termination 188 ManagedConnectionFactory 164
queue manager for clients 13
versus applets 51 ManagedConnectionMetaData 166
the administration tool 32
AS/400, installing MQ Java 9 MQC 152
to run applets 367
ASF (Application Server Facilities) 209 MQChannelDefinition 80
Web server 12
ASFClient1.java 220 MQChannelExit 82
your classpath 19
ASFClient2.java 222 MQConnectionManager 154
your installation 19
ASFClient3.java 224 MQDistributionList 85
confirm on arrival report options,
ASFClient4.java 225 MQDistributionListItem 87
message 103
asynchronous message delivery 177 MQEnvironment 88
confirm on delivery report options,
MQException 93
message 103
MQGetMessageOptions 95
connecting to a queue manager 58
B MQManagedObject 99
MQMessage 102
connecting to MQSeries Integrator
bean-managed transactions 362 V2 359
MQMessageTracker 121
sample application 364 connection
MQPoolServices 123
behavior in different environments 73, building 170
MQPoolServicesEvent 124
371 creating 171
MQPoolServicesEventListener 153
benefits of JMS 3 interface 169
MQPoolToken 126
bibliography 379 MQSeries, losing 188
MQProcess 127
bindings options 4
MQPutMessageOptions 129
connection 6 starting 171
MQQueue 132
connection, programming 52 Connection interface 240
MQQueueManager 140
example application 56 connection pooling 64
MQReceiveExit 155
verifying 16 example 64
MQSecurityExit 157
bindings transport, choosing 172 connection type, defining 52
MQSendExit 159
body, message 191 ConnectionConsumer class 209
MQSimpleConnectionManager 150
BookManager 381 ConnectionConsumer interface 243

© Copyright IBM Corp. 1997, 2001 383

ConnectionFactory interface 244 exceptions interface, programming 48
ConnectionMetaData interface 248 JMS 177 interfaces
connector.jar 7 MQSeries 177 JMS 169, 227
container-managed transactions 362 exit string properties 42 MQSeries 169
sample application 363 expiration report options, message 103 introduction
converting the log file 31 EXPIRY object property 39, 351 for programmers 47
COPY (administration verb) 34 extensions to core classes for V5 75 MQSeries classes for Java 3
core classes 73 extra function provided over MQ Java 3 MQSeries classes for Java Message
extensions for V5 75 Service 3
restrictions and variations 74, 371 iSeries 400, installing MQ Java 9
CountingMessageListenerFactory.java 220
createQueueSession method 172
F IVT (Installation Verification Test
program) 22
factories, creating at runtime 171
createReceiver method 175 IVTrun utility 351
formatLog utility 31, 351
createSender method 173 IVTRun utility 22, 24
fscontext.jar 7
creating IVTSetup utility 23, 351
function, extra provided over MQ
a connection 171 IVTTidy utility 25, 351
Java 3
factories at runtime 171
functions, Application Server
JMS objects 37
Facilities 209
Topics at runtime 182
customizing the sample applet 15
J
J2EE connector architecture 64
G JAAS (Java Authentication and
Authorization Service) 64, 154
D getting started 3
glossary 375
jar files 7
default connection pool 64 Java 2 Platform Enterprise Edition
multiple components 66 (J2EE) 64
default trace and log output locations 28 Java Authentication and Authorization
DEFINE (administration verb) 34 H Service (JAAS) 64, 154
defining connection type 52 handling Java classes 49, 79
defining transport 172 errors 61 Java Development Kit (JDK) 48
definition, LDAP schema 353 JMS runtime errors 177 Java interface, advantages 47
DELETE (administration verb) 34 messages 60 Java Transaction API (JTA) 340, 361
DeliveryMode interface 250 headers, message 191 javaClassName
dependencies, property 41 HOSTNAME object property 39, 351 LDAP attribute setting 354
DESCRIPTION object property 39, 351 HP-UX, installing MQ Java 8 javaClassNames
Destination interface 251 HTML (Hypertext Markup LDAP attribute setting 354
differences between applets and Language) 380 javaCodebase
applications 51 Hypertext Markup Language LDAP attribute setting 354
differences due to environment 73, 371 (HTML) 380 javaContainer
directories, installation 10 LDAP objectClass definition 356
disconnecting from a queue manager 58 javaFactory
DISPLAY (administration verb) 34
disposition options, message 103, 213
I LDAP attribute setting 355
javaNamingReference
IIOP connection, programming 51
durable subscribers 184 LDAP objectClass definition 356
import statements 179
javaObject
INITIAL_CONTEXT_FACTORY
LDAP objectClass definition 356
parameter 32
E inquire and set 62
javaReferenceAddress
LDAP attribute setting 355
ENCODING object property 42 installation
javaSerializedData
END (administration verb) 34 directories 10
LDAP attribute setting 355
environment differences 73, 371 Installation Verification Test program
javaSerializedObject
environment variables 11 for Publish/Subscribe (PSIVT) 25
LDAP objectClass definition 355
configuring 19 IVT error recovery 25
javax.jms package 227
error PSIVT error recovery 28
JDK (Java Development Kit) 48
conditions for object creation 43 setup 19
JMS
handling 61 verifying 19
administered objects 170
logging 29 Installation Verification Test program
benefits 3
recovery, IVT 25 (IVT) 22
classes 227
recovery, PSIVT 28 installing
exception listener 178
runtime, handling 177 MQ base Java on OS/390 9
exceptions 177
error messages 18 MQ base Java on z/OS 9
interfaces 169, 227
LDAP server 353 MQ Java on iSeries & AS/400 9
introduction 3
example code 52 MQ Java on Linux 9
mapping of fields at
exception listener 178 MQ Java on UNIX 8
send/publish 201
exception report options, message 103, MQ Java on Windows 10
mapping with MQMD 199
213 MQSeries classes for Java 7
message types 175
ExceptionListener interface 253 MQSeries classes for Java Message
messages 191
Service 7
model 169

384 MQSeries Using Java

JMS (continued)
objects, administering 35
M mqjavac (continued)
using to verify 13
objects, creating 37 MA1G, SupportPac MQManagedObject 99
objects, properties 38 special considerations for 369 MQMD (MQSeries Message
objects for Publish/Subscribe 179 ManagedConnection 161 Descriptor) 195
programs, writing 169 ManagedConnectionFactory 164 MQMessage 60, 102
resources, closing in ManagedConnectionMetaData 166 MQMessageConsumer class 275
Publish/Subscribe mode 181 manipulating subcontexts 35 MQMessageProducer interface 278
jms.jar 7 map message 191 MQMessageTracker 121
JMS JTA/XA Interface 361 MapMessage MQObjectMessage class 283
JMSAdmin.config utility 351 interface 254 MQPoolServices 123
JMSAdmin utility 351 type 175 MQPoolServicesEvent 124
JMSBytesMessage class 232 mapping properties between admin. tool MQPoolServicesEventListener 153
JMSCorrelationID header field 191 and programs 349 MQPoolToken 126
JMSMapMessage class 254 mcd folder 360 MQProcess 127
JMSMessage class 262 message MQPutMessageOptions 129
JMSStreamMessage class 306 body 191 MQQueue 60, 132
JMSTextMessage class 316 delivery, asynchronous 177 (JMS object) 36
JNDI error 18 class 284
retrieving 170 handling 60 for verification 23
security considerations 33 headers 191 MQQueueBrowser class 286
jndi.jar 7 message body 206 MQQueueConnection class 288
JTA (Java Transaction API) 340, 361 properties 191 MQQueueConnectionFactory
selectors 176, 191 (JMS object) 36
selectors and SQL 192 class 290
selectors in Publish/Subscribe
L mode 184
for verification 23
interface 290
ldap.jar 7 sending 173 object 170
LDAP naming considerations 37 types 175, 191 set methods 172
LDAP schema definition 353 Message interface 262 MQQueueEnumeration class 282
LDAP server 23 MessageConsumer interface 169, 275 MQQueueManager 59, 140
attribute settings MessageListener interface 277 MQQueueReceiver class 292
javaClassName 354 MessageListenerFactory.java 218 MQQueueSender interface 295
javaClassNames 354 MessageProducer interface 169, 278 MQQueueSession class 298
javaCodebase 354 MessageProducer object 173 MQReceiveExit 155
javaFactory 355 messages MQRFH2 header 196
javaReferenceAddress 355 JMS 191 mcd folder of the 360
javaSerializedData 355 mapping between JMS and MQSecurityExit 157
configuration 353 MQSeries 195 MQSendExit 159
error messages 353 poison 212 MQSeries
iSeries OS/400 V4R5 Schema publishing 181 connection, losing 188
Modification 357 receiving 175 exceptions 177
Microsoft Active Directory 356 receiving in Publish/Subscribe interfaces 169
Netscape Directory 356 mode 181 messages 195
objectClass definitions selecting 176, 191 MQSeries classes for Java classes 79
javaContainer 356 model, JMS 169 MQSeries Integrator V2, connecting to
javaNamingReference 356 MOVE (administration verb) 34 MQ JMS 359
javaObject 356 MQC 152 MQSeries Message Descriptor
javaSerializedObject 355 MQChannelDefinition 80 (MQMD) 195
schema 353 MQChannelExit 82 mapping with JMS 199
Sun Microsystems’ Schema MQConnection class 240 MQSeries publications 379
Modification Applications 357 MQConnectionConsumer class 209, 243 MQSeries supported verbs 48
library, Java classes 49 MQConnectionFactory class 244 MQSeriesV5 extensions 75
Linux, installing MQ Java 9 MQConnectionManager 154 MQSession class 209, 301
listener, JMS exception 178 MQConnectionMetaData class 248 MQSimpleConnectionManager 150
Load1.java 219 MQDeliveryMode class 250 MQTemporaryQueue class 314
Load2.java 222 MQDestination class 251 MQTemporaryTopic class 315
local publications, suppressing 184 MQDistributionList 85 MQTopic
log file MQDistributionListItem 87 (JMS object) 36
converting 31 MQEnvironment 52, 58, 88 class 317
default output location 28 MQException 93 MQTopicConnection class 319
logging errors 29 MQGetMessageOptions 95 MQTopicConnectionFactory
LoggingMessageListenerFactory.java 222 MQIVP (JMS object) 36
listing 16 class 321
sample application 16 object 170
tracing 17 MQTopicPublisher class 324
mqjavac MQTopicSession class 329
tracing 17

Index 385
MQTopicSubscriber class 333 PostScript format 381 QueueRequestor class 293
MQXAConnection class 334 prerequisite software 6 queues, accessing 59
MQXAConnectionFactory class 335 PRIORITY object property 39, 351 QueueSender interface 295
MQXAQueueConnection class 336 problems, solving 17, 29 QueueSession interface 298
MQXAQueueConnectionFactory problems, solving in Publish/Subscribe
class 337 mode 187
MQXAQueueSession class 339
MQXASession class 340
processes, accessing 59
programmers, introduction 47
R
reading strings 61
MQXATopicConnection class 342 programming
receiving
MQXATopicConnectionFactory class 344 bindings connection 52
messages 175
MQXATopicSession class 346 client connections 51
messages in Publish/Subscribe
MSGRETENTION object property 39, compiling 69
mode 181
351 connections 51
RECEXIT object property 39, 351
multithreaded programs 62 multithreaded 62
RECEXITINIT object property 39, 351
MyServerSession.java 217 tracing 70
report options, message 102, 213
MyServerSessionPool.java 217 writing 51
reports, broker 189
programming interface 48
resources, closing 177
programs
restrictions and variations
N JMS, writing 169
Publish/Subscribe, writing 179
to core classes 74, 371
names, of Topics 181 retrieving objects from JNDI 170
running 28, 70
naming considerations, LDAP 37 runjms utility 28, 351
tracing 29
Netscape Navigator, using 6 running
properties
non-durable subscribers 184 applets 70
client 41
applications under CICS Transaction
dependencies 41
Server 371
mapping between admin. tool and
O programs 349
in a Web browser 5
MQSeries classes for Java
object creation, error conditions 43 message 191
programs 70
ObjectMessage of exit strings 42
programs 28
interface 283 of JMS objects 38
standalone program 5
type 175 queue, setting 173
the IVT 22
objects properties and objects, valid
the PSIVT 25
administered 170 combinations 41
with appletviewer 5
JMS, administering 35 PROVIDER_URL parameter 32
your own programs 17
JMS, creating 37 providerutil.jar 7
runtime
JMS, properties 38 PSIVT (Installation Verification Test
creating factories 171
message 191 program) 25
creating Topics 182
retrieving from JNDI 170 PSIVTRun utility 26, 351
errors, handling 177
objects and properties, valid PSReportDump application 189
combinations 41 publications
obtaining MQSeries 379
MQSeries classes for Java 7 publications (Publish/Subscribe), local S
MQSeries classes for Java Message suppressing 184 sample applet
Service 7 publish/subscribe, sample customizing 15
obtaining a session 172 application 364 tracing 17
one-phase optimization, with Publish/Subscribe Installation Verification using to verify 13
WebSphere 362 Test program (PSIVT) 25 with appletviewer 15
operations on queue managers 58 publishing messages 181 sample application
options bean-managed transactions 364
connection 4 bindings mode 56
subscribers 183
OS/390, installing MQ base Java 9
Q container-managed transactions 363
MQ JMS with WebSphere 362
QMANAGER object property 39, 351
overview 3 publish/subscribe 179, 364
Queue
tracing 17
interface 284
using Application Server
object 170
P queue manager
Facilities 219
using to verify 16
package configuring for clients 13
sample classpath settings 11
com.ibm.jms 231 connecting to 58
sample code
com.mq.ibm.jms 230 disconnecting from 58
applet 52
javax.jms 227 operations on 58
ServerSession 215
PDF (Portable Document Format) 380 QUEUE object property 39, 351
ServerSessionPool 215
PERSISTENCE object property 39, 351 queue properties
Sample1EJB.java 363
platform differences 73, 371 setting 173
Sample2EJB.java 364
point-to-point installation verification 22 setting with set methods 174
Sample3EJB.java 364
poison messages 212 QueueBrowser interface 286
schema, LDAP server 353
PORT object property 39, 351 QueueConnection interface 288
schema definition, LDAP 353
Portable Document Format (PDF) 380 QueueReceiver interface 292

386 MQSeries Using Java

scripts provided with MQSeries classes TemporaryQueue interface 314 verification
for Java Message Service 351 TemporaryTopic interface 315 with JNDI (point-to-point) 23
SECEXIT object property 39, 351 termination, unexpected 188 with JNDI (Publish/Subscribe) 27
SECEXITINIT object property 39, 351 testing MQSeries classes for Java without JNDI (point-to-point) 22
SECURITY_AUTHENTICATION programs 70 without JNDI (Publish/Subscribe) 26
parameter 32 text message 191 verifying
security considerations, JNDI 33 TextMessage client mode installation 13
selecting a subset of messages 176, 191 interface 316 TCP/IP clients 16
selectors type 175 with the sample applet 13
message 176, 191 tokens, connection pooling 64 with the sample application 16
message, and SQL 192 Topic your installation 19
message in Publish/Subscribe interface 179, 317 versions of software required 6
mode 184 names 181 VisiBroker
SENDEXIT object property 39, 351 names, wildcards 182 configuring the queue manager 14
SENDEXITINIT object property 39, 351 object 170 connection 4, 52, 55
sending a message 173 TOPIC object property 39, 351 using 4, 6, 17
ServerSession sample code 215 TopicConnection 179
ServerSessionPool sample code 215 interface 319
session, obtaining 172
Session class 209
TopicConnectionFactory 179
interface 321
W
Web browser
Session interface 169, 301 TopicLoad.java 223
using 5
set and inquire 62 TopicPublisher 180
Web server, configuring 12
set methods interface 324
WebSphere
on MQQueueConnectionFactory 172 TopicRequestor class 327
configuration 33
using to set queue properties 174 TopicSession 179
CosNaming namespace 32
setJMSType method 360 interface 329
CosNaming repository 32
setting TopicSubscriber 180
WebSphere Application Server 215, 361
queue properties 173 interface 333
using with JMS 361
queue properties with set trace, default output location 28
widcards in topic names 182
methods 174 tracing
Windows
shutting down applications 177 MQSeries for Java Message
installing MQ Java 10
softcopy books 380 Service 29
Windows Help 381
software, prerequisites 6 programs 70
writing
Solaris sample applet 17
JMS programs 169
installing MQ Java 8 the sample application 17
programs 51
solving problems 17 transactions
Publish/Subscribe applications 179
general 29 bean-managed 362
strings 61
in Publish/Subscribe mode 187 container-managed 362
user exits 63
SQL for message selectors 192 sample application 363, 364
standalone program, running 5 transport, choosing 172
starting a connection 171 TRANSPORT object property 39, 351
starting the administration tool 31 two-phase commit, with WebSphere 362 X
stream message 191 types of JMS message 175, 191 XAConnection interface 334
StreamMessage XAConnectionFactory interface 335
interface 306 XAQueueConnection interface 288, 336
type 175
strings, reading and writing 61
U XAQueueConnectionFactory
interface 290, 337
unexpected application termination 188
subcontexts, manipulating 35 XAQueueSession interface 339
uniform resource identifier (URI) for
subscriber options 183 XAResource 340
queue properties 173
subscriptions, receiving 181 XASession interface 340
UNIX, installing MQ Java 8
subset of messages, selecting 176, 191 XATopicConnection interface 342
URI for queue properties 173
Sun JMS interfaces and classes 227 XATopicConnectionFactory interface 344
user exits, writing 63
Sun Solaris XATopicSession interface 346
uses for MQSeries 3
installing MQ Java 8
using
Sun Web site 3
appletviewer 13
SupportPac 381
SupportPac MA1G
MQ base Java 13 Z
utilities provided with MQSeries classes z/OS, installing MQ base Java 9
special considerations for 369
for Java Message Service 351
suppressing local publications 184

T V
V5 extensions 75
TARGCLIENT object property 39, 351
valid combinations of objects and
TCP/IP
properties 41
client verifying 16
verbs, MQSeries supported 48
connection, programming 51
TEMPMODEL object property 39, 351

Index 387
388 MQSeries Using Java
Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the
methods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in which
the information is presented.

To make comments about the functions of IBM products or systems, talk to your
IBM representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.

You can send your comments to IBM in any of the following ways:
v By mail, to this address:
User Technologies Department (MP095)
IBM United Kingdom Laboratories
Hursley Park
WINCHESTER,
Hampshire
SO21 2JN
United Kingdom
v By fax:
– From outside the U.K., after your international access code use
44–1962–842327
– From within the U.K., use 01962–842327
v Electronically, use the appropriate network ID:
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL
– IBMLink™: HURSLEY(IDRCF)
– Internet: [email protected]

Whichever method you use, ensure that you include:

v The publication title and order number
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.

© Copyright IBM Corp. 1997, 2001 389

390 MQSeries Using Java



Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.

SC34-5456-07
Spine information:

 MQSeries® MQSeries Using Java