|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.mqe.MQe | +--com.ibm.mqe.MQeFields | +--com.ibm.mqe.MQeMsgObject | +--com.ibm.mqe.MQeMultiMsgObject
Represents a number of MQeMsgObjects wrapped into a single message.
This is a special type of MQeMsgObject that allows many MQeMsgObjects to be wrapped inside it.
Use this message type instead of the MQeMsgObject message type when you wish to convey many messages to the same target queue in an efficient manner. A single Multi message containing 100 inner messages will likely travel much faster over the MQe messaging fabric than 101 separate MQeMsgObject messages.
The term inner-message is used throughout this class description to refer to messages contained within the multi-message collection container.
Conceptually, a multi-message is created by an application, and messages destined for the same target queue
are added to it using the #putMessage
and #putMessages
methods.
The multi-message can then be put to the normal MQe queue manager methods such as MQeQueueManager.putMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeMsgObject, com.ibm.mqe.MQeAttribute, long)
at which point, all inner messages contained within the multi-message are atomically put to the queue manager.
Websphere MQ Everyplace will convey the multi-message through intermediate queues, and channels until it reaches a point in the network topology where un-packing the multi-message is required. At this "unpack-point", all inner messages are taken from the multi-message, and are posted onto the messaging fabric to travel individually. During this operation, the now-empty multi-message container is discarded by MQe, together with any field data it contains.
The multi-message will be un-packed at the first bridge queue it comes to. Any other queue will simply hold the packed version of the multi-message.
Certain properties of the MultiMessage apply to all the smaller messages contained within the MultiMessage. Setting these in the containing Multi message causes the same property to effectively be set for all the messages inside it.
The properties are :
Similarly, any fields with values put into the Multi message will be copied into the contained messages at the point where the multi-message is unpacked. Any duplicated fields in the inner messages will not be overwritten, except in the cases above. This feature can be extremely useful if many small messages need to contain some fields which have the same value. Instead of putting the data into the inner message, and packing all the inner messages together into a multi-message for posting, you can used the putInt, putAscii, putUnicode...etc. methods to populate the multi message with data fields containing the common values. When the multi-message is conveyed over the messaging fabric, only one copy of the data is conveyed. When the multi-message is unpacked, these common data fields are copied from the multi message into each and every inner message before the multi message is discarded. From the point messages are unpacked to when they are consumed, inner messages will have multiple copies of this common data.
This message may not have an attribute applied to it, though it can be put to a queue which has attributes set. Likewise, inner messages may not use attributes.
Putting an empty MQeMultiMsgObject will fail at the point the message is put.
This class is not thread safe, use only one thread when manipulating it. The state of messages being added, and the number of inner messages may be inconsistent if many threads are manipulating this object simultaneously.
Fields of MQeMultiMsgObject | |
---|---|
Field name | Description |
com.ibm.mqe.MQeMultiMsgObject#Msg_InnerMsgs |
An array of byte arrays. Each byte array is a representation of an inner message. |
com.ibm.mqe.MQeMultiMsgObject#Msg_InnerMsgIDs |
An array of long integers. Each long is the Msg_Time of the corresponding message in Msg_InnerMsgs. |
Field Summary |
Fields inherited from class com.ibm.mqe.MQeFields |
ArraySeparator, TypeArrayElements, TypeAscii, TypeBoolean, TypeByte, TypeDouble, TypeFields, TypeFloat, TypeInt, TypeLong, TypeShort, TypeUnicode, TypeUnTyped |
Constructor Summary | |
MQeMultiMsgObject()
Simple constructor. |
Method Summary | |
MQeMsgObject |
getInnerMessage(int messageNumber)
Retrieves the messages. |
int |
getInnerMessageCount()
Returns the number of messages contained by this message |
MQeFields |
getMsgUIDFields()
Extracts the unique identifier for the message. |
void |
putInnerMessage(MQeMsgObject message)
Adds a message to this collection of messages. |
void |
putInnerMessages(MQeMsgObject[] messages)
Fills an MQeMultiMsgObject with each of the MQeMsgObjects in the array passed in. |
void |
resetMsgUIDFields()
Resets the UID fields of the wrapping message and all of the messages inside it. |
Methods inherited from class com.ibm.mqe.MQeMsgObject |
getOriginQMgr, getTimeStamp, putOriginQMgr, unwrapMsgObject |
Methods inherited from class com.ibm.mqe.MQe |
abbreviate, alias, asciiToByte, byteToAscii, byteToHex, byteToHex, byteToInt, byteToLong, byteToShort, byteToUnicode, fileSeparator, getEventLogHandler, hexToAscii, hexToByte, intToByte, isCLDC, loadClass, loadObject, log, setEventLogHandler, setLoader, sliceByteArray, type, unicodeToByte, uniqueValue |
Methods inherited from class java.lang.Object |
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public MQeMultiMsgObject() throws java.lang.Exception
Simple constructor. Creates an empty container message to which other messages can be added.
Method Detail |
public final void putInnerMessages(MQeMsgObject[] messages) throws java.lang.Exception
Fills an MQeMultiMsgObject with each of the MQeMsgObjects in the array passed in.
If any of the messages have a priority set, then an exception will be thrown. This message cannot be got using getMessage, or browsed using browseMessage. It will be expanded when it gets to its destination. Listeners will fire on receipt of the contained messages, not on the container message.
messages
- An array of messages to be added to this MQeMultiMsgObject
MQeException
- An exception is thrown if any of these messages has a priority set,
or if one of the messages is a collection message itself
an exception is also thrown if this collection message has already been put.
java.lang.Exception
public final void putInnerMessage(MQeMsgObject message) throws java.lang.Exception
Adds a message to this collection of messages.
An exception is thrown if the added message has a priority set. Enclosed messages take the priority of the MQeMultiMsgObject in which they are wrapped.
Enclosed messages may not have attributes. It will not be possible to put a message that has been added to a MQeMultiMsgObject separately afterwards. Changes that occur to the message after the add has been called will not be reflected in the finally arriving message.
message
- A message to be added to this MQeMultiMsgObject
MQeException
- An exception is thrown if this message has a priority set, or if one of the messages
is a collection message itself.
an exception is also thrown if this collection message has already been put.
java.lang.Exception
public final int getInnerMessageCount() throws java.lang.Exception
Returns the number of messages contained by this message
This is an integer with a value of 0 or greater.
java.lang.Exception
public final MQeFields getMsgUIDFields() throws java.lang.Exception
Extracts the unique identifier for the message.
See MQeMsgObject
For an MQeMultiMsgObject all of the contained messages UID information is returned as well, so do not extract pieces of the returned UID fields information and confirm using that.
getMsgUIDFields
in class MQeMsgObject
java.lang.Exception
public final void resetMsgUIDFields() throws java.lang.Exception
Resets the UID fields of the wrapping message and all of the messages inside it.
resetMsgUIDFields
in class MQeMsgObject
java.lang.Exception
MQeMsgObject
public final MQeMsgObject getInnerMessage(int messageNumber) throws java.lang.Exception
Retrieves the messages.
The messagenumber (x) must be 0<=x<getInnerMessageCount() or an exception will be thrown. This method does not remove the inner message from the MQeMultiMsgObject
messageNumber
- The index of the message to be returned.
java.lang.Exception
|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |