Websphere MQ Everyplace

com.ibm.mqe
Class MQeMultiMsgObject

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeFields
              |
              +--com.ibm.mqe.MQeMsgObject
                    |
                    +--com.ibm.mqe.MQeMultiMsgObject
All Implemented Interfaces:
MQeExceptionCodes

public class MQeMultiMsgObject
extends MQeMsgObject

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
 
Fields inherited from class com.ibm.mqe.MQe
Admin_Queue_Name, Admin_Reply_Queue_Name, copyright, DeadLetter_Queue_Name, Event_Activate, Event_Attribute, Event_Authenticate, Event_Close, Event_Logoff, Event_Logon, Event_MiniCert_Validate, Event_Queue, Event_QueueManager, Event_UserBase, JMS_Version, MQ_Headers, MQe_Log_Audit_Failure, MQe_Log_Audit_Success, MQe_Log_Error, MQe_Log_Information, MQe_Log_Success, MQe_Log_Warning, Msg_BackoutCount, Msg_CorrelID, Msg_ExpireTime, Msg_LockID, Msg_MsgID, Msg_OriginQMgr, Msg_Priority, Msg_ReplyToQ, Msg_ReplyToQMgr, Msg_Resend, Msg_Style, Msg_Style_Datagram, Msg_Style_Reply, Msg_Style_Request, Msg_Time, Msg_WrapMsg, sccsid, System_Default_Queue_Name, version
 
Fields inherited from interface com.ibm.mqe.MQeExceptionCodes
Except_Active, Except_AdapterException, Except_AdapterMissingRemoteAddress, Except_Admin_ActionNotSupported, Except_Admin_InvalidField, Except_Admin_NotAdminMsg, Except_AdminAction, Except_Authenticate, Except_BadRequest, Except_BridgeListener, Except_Chnl_Attributes, Except_Chnl_ID, Except_Chnl_Limit, Except_Chnl_Overrun, Except_Closed, Except_Con_AdapterRequired, Except_Con_AliasAlreadyExists, Except_Con_AlreadyExists, Except_Con_InvalidName, Except_Connect_Failure, Except_ConnectonType, Except_Cryptor, Except_Data, Except_Duplicate, Except_JmxProperties, Except_Listener, Except_MessageStore, Except_MiniCertReg_ActivateFailed, Except_MiniCertReg_BadPIN, Except_MiniCertReg_NotOpen, Except_NotActive, Except_NotAllowed, Except_NotFound, Except_NotSupported, Except_PrivateReg_ActivateFailed, Except_PrivateReg_BadPIN, Except_PrivateReg_NotOpen, Except_PublicReg_ActivateFailed, Except_PublicReg_InvalidAddress, Except_PublicReg_InvalidRequest, Except_Q_Full, Except_Q_InvalidName, Except_Q_InvalidPriority, Except_Q_MsgTooLarge, Except_Q_NoMatchingMsg, Except_Q_TargetRegistryRequired, Except_QMgr_Activated, Except_QMgr_AlreadyExists, Except_QMgr_InvalidQMgrName, Except_QMgr_InvalidQName, Except_QMgr_NotActive, Except_QMgr_NotBridgeEnabled, Except_QMgr_NotConfigured, Except_QMgr_QDoesNotExist, Except_QMgr_QExists, Except_QMgr_QNotEmpty, Except_QMgr_RegistryDataVersion, Except_QMgr_UnknownQMgr, Except_QMgr_WrongQType, Except_Reg_AddFailed, Except_Reg_AlreadyExists, Except_Reg_AlreadyOpen, Except_Reg_CRTKeyDecFailed, Except_Reg_CRTKeySignFailed, Except_Reg_DeleteFailed, Except_Reg_DeleteRegistryFailed, Except_Reg_DoesNotExist, Except_Reg_InvalidSession, Except_Reg_ListFailed, Except_Reg_NotDefined, Except_Reg_NotSecure, Except_Reg_NullName, Except_Reg_OpenFailed, Except_Reg_ReadFailed, Except_Reg_RenameFailed, Except_Reg_ResetPINFailed, Except_Reg_SearchFailed, Except_Reg_UpdateFailed, Except_RemoteException, Except_Rule, Except_S_BadIntegrity, Except_S_BadSubject, Except_S_CertificateExpired, Except_S_Cipher, Except_S_InvalidAttribute, Except_S_InvalidSignature, Except_S_MiniCertNotAvailable, Except_S_MissingSection, Except_S_NoPresetKeyAvailable, Except_S_RegistryNotAvailable, Except_Stopped, Except_Syntax, Except_TimeOut, Except_Transporter, Except_TriggerTransmission, Except_Trnsport_QMgr, Except_Trnsport_Request, Except_Type, Except_UdpipAdapterStateException, Except_UdpipAdapterTimeOut, Except_UdpipAdapterUnableToConfirmSuccess, Except_UnCoded, Except_Uncontactable_DontTransmit
 
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.MQeFields
contains, copy, copy, dataType, deepCopy, delete, dump, dumpedType, dumpToString, equals, fields, getArrayLength, getArrayOfByte, getArrayOfDoubleAsLong, getArrayOfFloatAsInt, getArrayOfInt, getArrayOfLong, getArrayOfShort, getAscii, getAsciiArray, getAttribute, getBoolean, getByte, getDoubleAsLong, getFields, getFieldsArray, getFloatAsInt, getInt, getIntArray, getLong, getLongArray, getObject, getShort, getShortArray, getUnicode, getUnicodeArray, includes, isEqualTo, putArrayLength, putArrayOfByte, putArrayOfDoubleAsLong, putArrayOfFloatAsInt, putArrayOfInt, putArrayOfLong, putArrayOfShort, putAscii, putAsciiArray, putBoolean, putByte, putByteArray, putDoubleAsLong, putFields, putFieldsArray, putFloatAsInt, putInt, putIntArray, putLong, putLongArray, putObject, putShort, putShortArray, putUnicode, putUnicodeArray, rename, restore, restoreFromString, restoreFromString, restoreFromString, setAttribute, updateValue
 
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

MQeMultiMsgObject

public MQeMultiMsgObject()
                  throws java.lang.Exception

Simple constructor. Creates an empty container message to which other messages can be added.

Method Detail

putInnerMessages

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.

Parameters:
messages - An array of messages to be added to this MQeMultiMsgObject
Throws:
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

putInnerMessage

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.

Parameters:
message - A message to be added to this MQeMultiMsgObject
Throws:
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

getInnerMessageCount

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

getMsgUIDFields

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.

Overrides:
getMsgUIDFields in class MQeMsgObject
Returns:
Throws:
java.lang.Exception

resetMsgUIDFields

public final void resetMsgUIDFields()
                             throws java.lang.Exception

Resets the UID fields of the wrapping message and all of the messages inside it.

Overrides:
resetMsgUIDFields in class MQeMsgObject
Returns:
void
java.lang.Exception
See Also:
MQeMsgObject

getInnerMessage

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

Parameters:
messageNumber - The index of the message to be returned.
Throws:
java.lang.Exception

Websphere MQ Everyplace