Handling IBM MQ message headers with IBM MQ classes for Java
Java classes are provided representing different types of message header. Two helper classes are also provided.
The MQHeader interface
Header objects are described by the MQHeader interface, which provides general-purpose methods for accessing header fields and for reading and writing message content. Each header type has its own class that implements the MQHeader interface and adds getter and setter methods for individual fields. For example, the MQRFH2 header type is represented by the MQRFH2 class; the MQDLH header type by the MQDLH class, and so on. The header classes perform any necessary data conversion automatically, and can read or write data in any specified numeric encoding or character set (CCSID).
Important: The MQRFH2 headers classes treat the message as a random access file, which means that the cursor must be positioned at the start of the message. Before using an internal message header class like MQRFH, MQRFH2, MQCIH, MQDEAD, MQIIH or MQXMIT, make sure that you update the message's cursor position to the correct location before passing the message to the class.Helper classes
Two helper classes, MQHeaderIterator and MQHeaderList, assist with reading and decoding (parsing) the header content in messages:- The MQHeaderIterator class works like a java.util.Iterator. For as long as there are more headers in the message, the next() method returns true, and the nextHeader() or next() method returns the next header object.
- The MQHeaderList works like a java.util.List. Like the MQHeaderIterator, it parses header content, but it also allows you to search for particular headers, add new headers, remove existing headers, update header fields and then write the header content back to a message. Alternatively, we can create an empty MQHeaderList, then populate it with header instances and write it to a message once or repeatedly.
The MQHeaderIterator and MQHeaderList classes use the information in the MQHeaderRegistry to know which IBM MQ header classes are associated with particular message types and formats. The MQHeaderRegistry is configured with knowledge of all current IBM MQ formats and header types and their implementation classes, and we can also register your own header types. Support is provided for the following commonly used IBM MQ headers
- MQRFH - Rules and formatting header
- MQRFH2 - Like MQRFH, used to pass messages to and from a message broker belonging to IBM Integration Bus. Also used to contain message properties
- MQCIH - CICS Bridge
- MQDLH - Dead letter header
- MQIIH - IMS information header
- MQRMH - reference message header
- MQSAPH - SAP header
- MQWIH - Work information header
- MQXQH - Transmission Queue header
- MQDH - Distribution header
- MQEPH - Encapsulated PCF header
We can also define classes representing your own headers.
To use an MQHeaderIterator to get an RFH2 header, either set MQGMO_PROPERTIES_FORCE_MQRFH2 in the GetMessageOptions, or set the queue property PROPCTL to FORCE.
- Printing all the headers in a message using IBM MQ classes for Java
In this example, an instance of MQHeaderIterator parses the headers in an MQMessage that has been received from a queue. The MQHeader objects returned from the nextHeader() method display their structure and contents when their toString method is invoked. - Skipping over the headers in a message using IBM MQ classes for Java
In this example, the skipHeaders() method of MQHeaderIterator positions the message read cursor immediately after the last header. - Finding the reason code in a dead-letter message using IBM MQ classes for Java
In this example, the read method populates the MQDLH object by reading from the message. After the read operation, the message read cursor is positioned immediately after the MQDLH header content. - Reading and removing the header from a dead-letter message using IBM MQ classes for Java
In this example, MQDLH is used to remove the header from a dead-letter message. - Printing the content of a message using IBM MQ classes for Java
This example uses MQHeaderList to print out the content of a message, including its headers. - Finding a specific type of header in a message using IBM MQ classes for Java
This example uses the indexOf(String) method of MQHeaderList to find an MQRFH2 header in a message, if one is present. - Analyzing an MQRFH2 header using IBM MQ classes for Java
This example shows how to access a known field value in a named folder, using the MQRFH2 class. - Reading and writing byte streams other than MQMessage objects using IBM MQ classes for Java
These examples use the header classes to parse and manipulate IBM MQ header content when the data source is not an MQMessage object. - Create classes for new header types using IBM MQ classes for Java
We can create Java classes for header types not supplied with IBM MQ classes for Java.
Parent topic: Writing IBM MQ classes for Java applications