Websphere MQ Everyplace

com.ibm.mqe
Class MQeQueueManager

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeQueueManager
All Implemented Interfaces:
MQeExceptionCodes
Direct Known Subclasses:
MQeQueueManagerConfigure

public class MQeQueueManager
extends MQe

Instances of this class provide an entry point to the messaging API for an installed MQe System. A queue manager needs to be defined, created and activated before it can be used.

A queue manager is defined by the creation of a registry on permanent storage (disk). This can be done by using an instance of MQeQueueManagerConfigure .

Creation and activation of the queue manager can be done either in one step (call the two argument constructor), or in two steps (call the zero argument constructor and one of the activate methods). For the simplest case the one step process is probably sufficient. In more complex cases (for example when using secure registries) you will need to pass more parameters to the queue manager during activation, and the two step method is required.

Once the queue manager instance has been created and activated it can be used as the entry point for the messaging operations - for example putMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeMsgObject, com.ibm.mqe.MQeAttribute, long), getMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long) Examples given in the Javadoc for methods are not intended to represent good Object-Oriented code, but to illustrate the usage of the methods. Better programming examples are provided in the examples suite.

See Also:
examples.install, examples.queuemanager, examples.application

Field Summary
static java.lang.String Name
          The name of the field passed to the activate call.
static java.lang.String QueueManager
          The name of the field passed to the activate call.
static java.lang.String Registry
          The name of the field passed to the activate call.
 
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
MQeQueueManager()
          Queue Manager constructor.
MQeQueueManager(java.lang.String queueManagerName, java.lang.String registryLocation)
          Queue Manager constructor.
 
Method Summary
 void activate(MQeFields startupParams)
          Activates a queue manager.
protected  void activate(java.lang.String activateName)
          Activates a queue manager.
 void activate(java.lang.String queueManagerName, java.lang.String registryLocation)
          Activates a queue manager.
 void addMessageListener(MQeMessageListenerInterface objref, java.lang.String queueName, MQeFields filter)
          Adds a non-durable subscription to receive filtered MQe Message Events as they occur on a specific queue.
 MQeEnumeration browseMessages(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, boolean justUID)
          This method returns an enumeration of the messages available on a specified queue.
 long browseMessages(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, long confirmId, boolean justUID, java.util.Vector results)
          Browse messages on a queue, and place the results into a Vector.
 MQeEnumeration browseMessagesAndLock(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, long confirmId, boolean justUID)
          This method returns an enumeration of the messages available on a specified queue.
 boolean checkActive()
          Deprecated. Use isQueueManagerActive() method as a direct replacement
 void close()
          Closes Queue Manager.
 void closeImmediate()
          Closes Queue Manager immediately.
 void closeQuiesce(long quiesceDuration)
          Closes Queue Manager specifying a delay to allow existing internal processes to finish normally.
 void confirmGetMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter)
          Confirms the successful receipt of a message that was retrieved from a queue by a previous getMessage operation.
 void confirmPutMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter)
          Confirms a put operation.
 void deleteMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter)
          Deletes a message from a queue.
static MQeQueueManager getDefaultQueueManager()
          Gets a reference to the default queue manager being used in this JVM.
 MQeMsgObject getMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, long confirmId)
          Gets a message from a queue.
 java.lang.String getName()
          Gets (unique) Queue Manager name.
static MQeQueueManager getReference(java.lang.String queueManagerName)
          Deprecated. Since there can only be one queue manager per jvm it is more efficient to use the method getDefaultQueueManager which returns a reference or null.
 boolean isQueueManagerActive()
          Reply true if the receiver is active, false otherwise.
 void putMessage(java.lang.String qmgrName, java.lang.String queueName, MQeMsgObject msgObj, MQeAttribute attr, long confirmId)
          Puts a message to a queue.
 void removeMessageListener(MQeMessageListenerInterface listener, java.lang.String queueName, MQeFields filter)
          Removes an objects subscription to WebSphere MQ Everyplace message events generated when messages arrive on a specified queue.
 void triggerTransmission()
           This method triggers an attempt to transmit any pending messages.
 void undo(java.lang.String queueManagerName, java.lang.String queueName, long confirmId)
          This method is intended to be used in the event of an error during a put, get,or browseAndLock command.
 void unlockMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter)
          Unlocks a message that has been previously locked.
 MQeMsgObject waitForMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, long confirmId, int waitForTime)
          Waits for a message to arrive, then gets it.
 MQeMsgObject waitForMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter, MQeAttribute attr, long confirmId, int waitForTime, int pollInterval)
          Waits for a message to arrive, then gets it.
 
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, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QueueManager

public static final java.lang.String QueueManager
The name of the field passed to the activate call.

See Also:
activate(MQeFields), Constant Field Values

Registry

public static final java.lang.String Registry
The name of the field passed to the activate call.

See Also:
activate(MQeFields), Constant Field Values

Name

public static final java.lang.String Name
The name of the field passed to the activate call.

See Also:
activate(MQeFields), Constant Field Values
Constructor Detail

MQeQueueManager

public MQeQueueManager()

Queue Manager constructor.

The activate(java.lang.String, java.lang.String) method must be called to initialise and start the queue manager.

Example:
 import com.ibm.mqe.*;
 
 public static void main(String[] args) {
     MQeFields iniSections = new MQeFields();
 
     try {
         if (null == args || args.length < 1 || null == args[0]) {
             System.out.println("No ini file name supplied");
         } else {
             System.out.println("Reading ini file: " + args[0]);
             iniSections.restoreFromString(args[0], "\r\n", "(#0)#1=#2");
             MQeQueueManager queueManager = new MQeQueueManager();
 
             System.out.println("Activating queueManager");
             queueManager.activate(iniSections);
             System.out.println("Closing queueManager");
             queueManager.close();
             System.out.println("Closed queueManager");
         }
     } catch (Exception e) {
         System.out.println("Exception thrown: " + e.getMessage());
         e.printStackTrace();
     }
     }
 

The example code demonstrates a minimum fragment needed to start a queue manager from an ini file. The name of the ini file must be passed as the first parameter. The ini file must describe an existing QueueManager Registry.

Note that this code does not initialise any aliases.


MQeQueueManager

public MQeQueueManager(java.lang.String queueManagerName,
                       java.lang.String registryLocation)
                throws java.lang.Exception

Queue Manager constructor.

This constructor will create and activate a queue manager based upon a pre-existing registry.

Note that this code does not initialise any aliases.

Parameters:
queueManagerName - A String the name of the queue manager
registryLocation - A String the location of the base directory for the registry
Throws:
MQeException - Using codes:
MQeExceptionCodes.Except_QMgr_Activated
If the queue manager has already been started.
MQeExceptionCodes.Except_Active
When an attempt is made to activate an already active object.
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
If the registry specified is back-level. Please refer to the documentation for description of how to migrate the registry before using it with this level of code.
java.lang.Exception
Example:
 public static void simpleConstruct(String queueManagerName, String registryDirectory) throws Exception {
     System.out.println("Creating queueManager");
     MQeQueueManager queueManager = new MQeQueueManager(queueManagerName, registryDirectory);
 
     System.out.println("Closing queueManager");
     queueManager.close();
     System.out.println("Closed queueManager");
     }
 
Method Detail

activate

public void activate(java.lang.String queueManagerName,
                     java.lang.String registryLocation)
              throws java.lang.Exception

Activates a queue manager. After activation the queue manager functionality can be used.

The queue manager then initializes all its subcomponents and reads any information stored in its registry.

Note: Before starting a queue manager, all required WebSphere MQ Everyplace aliases must have already been added. Refer to the WebSphere MQ Everyplace Programmers Guide for details of how to do this. Note: Any class overriding this method must call super.activate(String, String) to ensure that the queue manager is initialised correctly.

Parameters:
queueManagerName - A String the name of the queue manager
registryLocation - A String the location of the base directory for the registry
Returns:
void
Throws:
MQeException - Using codes:
MQeExceptionCodes.Except_QMgr_Activated
If the queue manager has already been started.
MQeExceptionCodes.Except_Active
When an attempt is made to activate an already active object.
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
If the registry specified is back-level. Please refer to the documentation for description of how to migrate the registry before using it with this level of code.
java.lang.Exception
Example:
 public static void simpleActivate(String queueManagerName, String registryDirectory) throws Exception {
     System.out.println("Creating queueManager");
     MQeQueueManager queueManager = new MQeQueueManager();
 
     queueManager.activate(queueManagerName, registryDirectory);
     System.out.println("Closing queueManager");
     queueManager.close();
     System.out.println("Closed queueManager");
     }
 

activate

public void activate(MQeFields startupParams)
              throws java.lang.Exception

Activates a queue manager. After activation the queue manager functionality can be used.

The queue manager then initializes all its subcomponents and reads any information stored in its registry.

Note: Before starting a queue manager, all required WebSphere MQ Everyplace aliases must have already been added. Refer to the WebSphere MQ Everyplace Programmers Guide for details of how to do this. Note: Any class overriding this method must call super.activate(MQeFields) to ensure that the queue manager is initialised correctly.

Parameters:
startupParams - An MQeFields object containing startup parameters for the queue manager and components which the queue manager depends on.

The fields acceptable in this structure are:

Field name: QueueManager
This field is mandatory. A collection of parameters relating to the queue manager being activated. It is a field of type MQeFields containing other fields:
Field name: Name
The name of the queue manager. For example "ExampleQM". This field is mandatory. It is a field of type ascii.
Field name: Registry
A collection of parameters relating to teh queue manager registry, a component used by the queue manager to store and retrieve configuration information. This field is mandatory. The field is of type MQeFields containing other fields:
Field name: MQeRegistry.DirName
The fully qualified path name of a directory in which the queue manager stores configuration information. The path name normally ends with the string "Registry". No trailing file separator characters are supplied on the end of this string. We also recommend that forward-sloping slashes are used for this string. For example "C:/ExampleQM/Registry". This is a mandatory field. The field is of type ascii.
Throws:
MQeException - Using codes:
MQeExceptionCodes.Except_QMgr_Activated
If the queue manager has already been started.
MQeExceptionCodes.Except_Active
When an attempt is made to activate an already active object.
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
If the registry specified is back-level. Please refer to the documentation for description of how to migrate the registry before using it with this level of code.
java.lang.Exception
Example:
 
 // Create QueueManager parameters
 MQeFields QMgrParams = new MQeFields();
 
 QMgrParams.putAscii(MQeQueueManager.Name, "ExampleQM");
 
 // Create Registry parameters
 MQeFields RegParams = new MQeFields();
 
 RegParams.putAscii(MQeRegistry.DirName, "C:\\ExampleQM\\Registry");
 
 // Combine the two sets of parameters into a single Fields object
 MQeFields Params = new MQeFields();
 
 Params.putFields(MQeQueueManager.QueueManager, QMgrParams);
 Params.putFields(MQeQueueManager.Registry, RegParams);
 
 //Instantiate Queue Manager
 MQeQueueManager QMgr = new MQeQueueManager();
 
 //Activate QMgr using parameters
 QMgr.activate(Params);
 
 
 

activate

protected void activate(java.lang.String activateName)
                 throws java.lang.Exception
Activates a queue manager. After activation the queue manager functionality can be used.

Intended for use by QMgr subclasses which want to override the default activation procedure

Parameters:
activateName - java.lang.String the name of the queue manager.
Returns:
void
Throws:
java.lang.Exception

addMessageListener

public void addMessageListener(MQeMessageListenerInterface objref,
                               java.lang.String queueName,
                               MQeFields filter)
                        throws java.lang.Exception

Adds a non-durable subscription to receive filtered MQe Message Events as they occur on a specific queue.

This method registers an object as a listener to any MQeMessage events generated by the queue specified in the queueName parameter.

It is only possible to add listeners to local queues.

Note: The listening object must implement the MQeMessageListenerInterface interface.

Events are processed by the event handler methods specified in this interface.

A message filter consisting of message fields (for example MessageId or Priority) may be specified so that the listening object only receives events concerning messages that include the same fields as those specified. If no fields are specified, events are triggered for all messages on the queue.

Parameters:
queueName - A String containing the name of the queue from which the listener wishes to receive events
Returns:
void
Throws:
MQeException - Except_QMgr_NotActive
java.lang.Exception
Example:
 filter = new MQeFields();// search parameters
 MQeQueueManager MyQM = new MQeQueueManager();
 
 filter.putByte(MQe.Msg_Priority, (byte) 3);// only interested in  msgs of priority 3
 
 // add listener
 MyQM.addMessageListener(objref, "MyQueue", filter);
 
 
 

browseMessages

public MQeEnumeration browseMessages(java.lang.String queueManagerName,
                                     java.lang.String queueName,
                                     MQeFields filter,
                                     MQeAttribute attr,
                                     boolean justUID)
                              throws java.lang.Exception

This method returns an enumeration of the messages available on a specified queue. The messages are not deleted from the queue. The queue can belong to a local or remote queue manager.

A filter can be specified, consisting of message fields (for example message ID or priority). This causes only messages that have matching fields to be returned.

Returning an enumeration of messages in their entirety can be expensive in terms of system resources, so if the justUID parameter is set to true , just the unique ids of the messages that match the filter are returned.

The messages returned in the enumeration are still visible to other WebSphere MQ Everyplace applications. Therefore, when performing subsequent operations on the messages contained in the enumeration, the application should be aware that it is possible for another application to have processed these messages in the time since the enumeration was returned. To lock the messages contained in the enumeration, therefore preventing other applications from processing them, use the browseMessagesAndLock(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long, boolean) method.

Parameters:
queueManagerName - A string containing the name of the queue manager that holds the queue to be browsed. If a value of null is used it is assumed that the local queue manager is to be used.
queueName - A string containing the name of the queue that holds the queue.
filter - An MQeFields object containing the parameters with which to perform the browse.
attr - An MQeAttribute object used to provide message-level security.
justUID - A boolean value denoting whether to return all the fields in the messages, or just the UID values.
Returns:
An MQeEnumeration containing zero or more MQeMsgObject message objects. Depending on the value passed in justUID parameter, the return value can alternatively contain MQeFields objects containing justUID values.
Throws:
MQeException - Except_QMgr_InvalidQMgrName MQeException Except_QMgr_InvalidQName MQeException Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
See Also:
browseMessagesAndLock(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long, boolean)
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeEnumeration msgs = null;
 byte[]msgId = MQe.asciiToByte("240999");
 byte[]correlId = MQe.asciiToByte("240999/2");
 
 try {
     // setup parameters object for matching
     filter = new MQeFields();  //match against msgs
     filter.putArrayOfByte(MQe.Msg_MsgID, msgId);  //with this Msg Id
     filter.putArrayOfByte(MQe.Msg_CorrelID,  // &this Correl Id
         correlId);
     // look at available messages
     msgs = qmgr.browseMessages(null, "MyQueue", filter, null, false);
 
     // get this one and remove from queue
     MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue",
             (MQeFields) msgs.nextElement(), null, 0);
 } catch (MQeException e) {// Handle the error here
 }
 
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeEnumeration msgs = null;
 byte[]msgId = MQe.asciiToByte("240999");
 byte[]correlId = MQe.asciiToByte("240999/2");
 
 try {
     // setup parameters object for matching
     filter = new MQeFields();  //match against msgs
     filter.putArrayOfByte(MQe.Msg_MsgID, msgId);  //with this Msg Id
     filter.putArrayOfByte(MQe.Msg_CorrelID,  // &this Correl Id
         correlId);
 
     // look at available messages
     msgs = qmgr.browseMessagesAndLock(null, "MyQueue", filter, null, 0, false);
     long lockId = msgs.getLockId(); // get Lock Id
 
     filter.putLong(MQe.Msg_LockID, lockId); // Add lock Id
 
     // get the first locked message from queue
     MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue", filter, null, 0);
 } catch (MQeException e) {// Handle the error here
 }
 
 

browseMessagesAndLock

public MQeEnumeration browseMessagesAndLock(java.lang.String queueManagerName,
                                            java.lang.String queueName,
                                            MQeFields filter,
                                            MQeAttribute attr,
                                            long confirmId,
                                            boolean justUID)
                                     throws java.lang.Exception

This method returns an enumeration of the messages available on a specified queue. The messages are not deleted from the queue. The queue may belong to a local or remote queue manager.

A filter can be specified, which consists of message fields (message ID and priority for example), so that only messages that have matching fields are returned.

Any messages that are returned by this operation are also locked on the queue. This means that these messages still exist on the queue, but they will not be visible to any subsequent operations, until they are unlocked.

A lockID is returned as part of the browse enumeration. The lockID allows operations to be performed on locked messages so long as it is specified as part of the message filter that is passed into that operation. Each lockID is unique, so every browse and lock operation generates a different ID. The lockID applies to all the messages that are returned by the browse operation.

The operations that can be performed on a locked message are:

Note:waitForMessage() should not be used with locked messages as the outcome is unpredictable.

Returning an enumeration of messages in their entirety can be expensive in terms of system resources, so if the justUID parameter is set to true just the unique ids of the messages that match the filter are returned.

Specifying an MQeAttribute object allows browsing of messages that have message-level security defined with a matching attribute. Browsing queues containing messages with differing levels of message-level security may cause undefined results.

The confirmID is used in the event of an error whilst executing this command. The error could occur before the lock id is returned to the application and yet leave the messages in a locked state on the target queue. Passing the same confirmID used on this method to the undo() method restores the messages to their previous state. It is recommended that a unique value be used for each browse and lock operation. A unique value can be generated using the MQe.uniqueValue() method.

A confirmID parameter of 0 is a special value, indicating that any browsed messages matching the specified filter should not be locked. Consequently, in this case, the lockID returned in the MQeEnumeration object cannot be used to in conjunction with the unlockMessage() method. If a confirmID 0 is used, the caller should not expect messages to be locked for later use with deleteMessage(), getMessage(), confirmGetMessage(),or undo().

Parameters:
queueManagerName - A string containing the name of the queue manager that holds the queue to be browsed. If a value of null is used it is assumed that the local queue manager is to be used.
queueName - A string containing the name of the queue on which the messages are held.
filter - An MQeFields object containing the message fields with which to perform the browse.
attr - An MQeAttribute object used to provide message-level security.
confirmId - A long value that is used in the event of a queue manager failure. The application should store the value used, and use it to reset the messages should a failure occur.
justUID - A boolean value denoting whether to return the entire message, or just its UID.
Returns:
An MQeEnumeration containing zero or more MQeMsgObject message objects. The enumeration also contains the lock id, which can be accessed using the getLockID() method.objects. Depending on the value passed in justUID parameter, the return value can alternatively contain MQeFields objects containing justUID values.
Throws:
 - MQeException : Except_QMgr_InvalidQMgrName
  MQeException : Except_QMgr_InvalidQName
  MQeException : Except_QMgr_NotActive
 
MQeException - Except_S_NoPresetKeyAvailable
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
See Also:
getMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long), waitForMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long, int), browseMessages(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, boolean), unlockMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields), deleteMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields), undo(java.lang.String, java.lang.String, long)
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeEnumeration msgs = null;
 byte[]msgId = MQe.asciiToByte("240999");
 byte[]correlId = MQe.asciiToByte("240999/2");
 
 try {
     // setup parameters object for matching
     filter = new MQeFields();  //match against msgs
     filter.putArrayOfByte(MQe.Msg_MsgID, msgId);  //with this Msg Id
     filter.putArrayOfByte(MQe.Msg_CorrelID,  // &this Correl Id
         correlId);
 
     // look at available messages
     msgs = qmgr.browseMessagesAndLock(null, "MyQueue", filter, null, 0, false);
     long lockId = msgs.getLockId(); // get Lock Id
 
     filter.putLong(MQe.Msg_LockID, lockId); // Add lock Id
 
     // get the first locked message from queue
     MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue", filter, null, 0);
 } catch (MQeException e) {// Handle the error here
 }
 
 

checkActive

public final boolean checkActive()
Deprecated. Use isQueueManagerActive() method as a direct replacement

To check whether the queue manager is active or not.

Returns:
true if Queue Manager is active and false if Queue Manager not active.

close

public void close()
           throws java.lang.Exception

Closes Queue Manager.

This method closes down the queue manager. One of the close methods should be called by MQe applications when they have finished using the queue manager. This method has been replaced by the closeImmediate() method which most closely resembles the original functionality.

Returns:
void
Throws:
java.lang.Exception

closeImmediate

public void closeImmediate()
                    throws java.lang.Exception

Closes Queue Manager immediately.

This method closes down the queue manager. One of the close methods should be called by MQe applications when they have finished using the queue manager.

After this method has been called, no more event notifications will be dispatched to message listeners. It is conceivable that mesages may complete their arrival after this method has been called (and before it finishes). Such messages will not be notified. Application programmers should be aware of this, and not assume that every message arrival will generate a message event.

Returns:
void
Throws:
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject msgObj = null;
 
 try {
     qmgr.putMessage(null, "MyQueue", msgObj, null, 0);
 } catch (MQeException e) {// Handle the exception here
 }
 qmgr.closeImmediate();  // close QMgr
 
 

closeQuiesce

public void closeQuiesce(long quiesceDuration)
                  throws java.lang.Exception

Closes Queue Manager specifying a delay to allow existing internal processes to finish normally. Note that this delay is only implemented as a series of 100ms pause and retry cycles. Calling this method will prevent any new activity (such as transmitting a message) from being started, but will allow activities already in progress to complete. The delay is a suggestion only, and various JVM dependant thread scheduling factors could result in the delay being greater. If the activities currently in progress finish sooner, then the method will return before the expiry of the quiesce duration.

If at the expiry of this period the queue has not closed, it is forced to close.

This method closes down the queue manager. One of the close methods should be called by WMQe applications when they have finished using the queue manager.

After this method has been called, no more event notifications will be dispatched to message listeners. It is conceivable that mesages may complete their arrival after this method has been called (and before it finishes). Such messages will not be notified. Application programmers should be aware of this, and not assume that every message arrival will generate a message event.

Parameters:
quiesceDuration - A long integer value containing the quiesce duration.
Returns:
void
Throws:
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject msgObj = null;
 
 try {
     qmgr.putMessage(null, "MyQueue", msgObj, null, 0);
 } catch (MQeException e) {// Handle the exception here
 }
 qmgr.closeQuiesce(3000);  // close QMgr
 
 

confirmGetMessage

public void confirmGetMessage(java.lang.String queueManagerName,
                              java.lang.String queueName,
                              MQeFields filter)
                       throws java.lang.Exception

Confirms the successful receipt of a message that was retrieved from a queue by a previous getMessage operation.

The message remains locked on the target queue until the confirm flow is received.

Parameters:
queueManagerName - A string containing the name of the queue manager that holds the queue.
queueName - A string containing the name of the queue on which the message is held. If a value of null is used it is assumed that the local queue manager is to be used.
filter - An MQeFields object containing a message filter. The filter must contain the message’s unique id for the operation to be successful.
Returns:
void
Throws:
MQeException - Except_NotFound This exception is thrown when attempting to confirm a message that has already been confirmed. If an application has reissued a confirm get message request then this exception can be treated as a successful return code.
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 // generate a unique confirmId for this operation
 long confirmId = MQe.uniqueValue();
 
 // get next available msg -msg still locked on target queue
 MQeMsgObject msg = qmgr.getMessage("RemoteQMgr", "RemoteQueue", null, null, confirmId);
 
 // confirm the successful Get
 qmgr.confirmGetMessage("RemoteQMgr", "RemoteQueue",
     msg.getMsgUIDFields());
 
 

confirmPutMessage

public void confirmPutMessage(java.lang.String queueManagerName,
                              java.lang.String queueName,
                              MQeFields filter)
                       throws java.lang.Exception

Confirms a put operation.

Parameters:
queueManagerName - A string containing the name of the queue manager that holds the queue.
queueName - A string containing the name of the queue on which the message is held. If a value of null is used it is assumed that the local queue manager is to be used.
filter - An MQeFields object containing a message filter. The filter must contain the message’s unique id for the operation to be successful.
Returns:
void
Throws:
MQeException - Except_NotFound This exception is thrown when attempting * to confirm a message that has already been confirmed. If an application has reissued a confirm put message request then this exception can be treated as a successful return code.
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject msg = new MQeMsgObject();;
 // generate a unique confirmId for this operation
 long confirmId = MQe.uniqueValue();
 
 qmgr.putMessage("RemoteQMgr", "RemoteQueue", msg, null, confirmId);
 
 // confirm the put
 qmgr.confirmPutMessage("RemoteQMgr", "RemoteQueue",
     msg.getMsgUIDFields());
 
 

deleteMessage

public void deleteMessage(java.lang.String queueManagerName,
                          java.lang.String queueName,
                          MQeFields filter)
                   throws java.lang.Exception

Deletes a message from a queue.

It does not return the message to the application that called it. Only one message can be deleted per operation and the uniqueID (timestamp and origin queue manager name) of the message must always be supplied.

The queue may belong to a local or remote WebSphere MQ Everyplace queue manager. Messages that have been locked by a previous operation (browse for example) can be deleted by included a valid lock id in the message filter. If the message is not available, an exception is thrown.

Parameters:
queueManagerName - (java.lang.String) A String containing the name of the queue manager that holds the queue. If a value of null is used it is assumed that the queue manager is local.
queueName - (java.lang.String) A String containing the name of the queue on which the message is held.
filter - An MQeFields object containing a message filter. The filter must contain the unique id of the message for the operation to be successful.
Returns:
void
Throws:
 - MQeException : Except_QMgr_InvalidQName
 MQeException : Except_QMgr_NotActive
 MQeException : Except_QMgr_QDoesNotExist
 MQeException : Except_QMgr_WrongType
 MQeException : Except_NotFound
 MQeException : Except_NotAllowed
 
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeEnumeration msgEnum;
 
 filter = new MQeFields();
 MQeQueueManager qmgr = new MQeQueueManager();
 
 filter.putArrayOfByte(MQe.Msg_MsgID, new byte[] {1, 2, 3, 4 }
 );
 
 // return all messages with a Message Id of 1234
 msgEnum = qmgr.browseMessages(null, "MyQueue", filter, null, false);
 
 // delete all message with a Message Id of 1234
 while (msgEnum.hasMoreElements())
     qmgr.deleteMessage(null, "MyQueue", (MQeMsgObject) msgEnum.nextElement());
 
 

getDefaultQueueManager

public static final MQeQueueManager getDefaultQueueManager()
Gets a reference to the default queue manager being used in this JVM.

Currently, only a single queue manager is supported.

Returns:
A reference to an active queue manager, or null if there is no active queue manager currently in this JVM.

getMessage

public MQeMsgObject getMessage(java.lang.String queueManagerName,
                               java.lang.String queueName,
                               MQeFields filter,
                               MQeAttribute attr,
                               long confirmId)
                        throws java.lang.Exception

Gets a message from a queue.

This method returns an available message from the specified queue and the message is removed from the queue. The queue can belong to a local or a remote WebSphere MQ Everyplace queue manager.

If no message filter is specified, the first available message on the queue is returned. If a message filter is specified, the first available message that matches the filter is returned.

Messages that have been locked by a previous browse operation can be retrieved by including, in the message filter, the lock id that was used to lock the message.

If no message is available, an exception is thrown. The use of assured message delivery is dependent upon the value of the confirmId parameter. Passing a nonzero value returns the message as normal, but the message is locked and is not removed from the target queue until a subsequent confirm is received. A confirm can be issued using the confirmGetMessage() method. Passing a value of zero returns the message and removes it from the target queue, however, the message delivery is not assured. The confirmId parameter is also used in the event of an error when executing this command. A failure could occur before the message is returned to the application and yet leave the message in a locked state on the target queue. Passing the same confirm id used for the get operation to the undo method restores the message to its previous state. It is recommended that a unique value be used for each get operation. A unique value can be generated using the MQe.uniqueValue() method.

Parameters:
queueManagerName - A string containing the name of the queue manager that holds the queue. If a value of null is used it is assumed that the queue manager is local.
queueName - A string containing the name of the queue from which to obtain a message.
filter - null,or anMQeFields object containing a message filter.
confirmId - A long value denoting whether or not to use guaranteed message delivery. A nonzero value does not remove the message from the target queue, this occurs on a subsequent confirm flow. A value of zero will remove the message from the target queue.
Returns:
An MQeMsgObject containing the message obtained from the specified queue.
Throws:
MQeException - Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // This does a simple get, no filtering done.
 try {
     // get 1st available message on the queue
     MQeMsgObject myMsgObject = qmgr.getMessage(null, "MyQueue", null, null, 0);
 } catch (MQeException e) {// Handle the error here.
 }
 
 

Example2

,
 MQeQueueManager qmgr = new MQeQueueManager();
 // This method browses and gets.
 // Lock all msgs on this queue
 MQeEnumeration msgEnum = qmgr.browseMessagesAndLock(null, "MyQueue", null, null, 0, false);
 long lockId = msgEnum.getLockId();  // get the Lock Id
 
 filter = new MQeFields(); // create a msg filter
 filter.putLong(MQe.Msg_LockID, lockId); // add lock Id
 
 // get the 1st locked message on the queue
 MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue", filter, null, 0);
 
 

Example3

,
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // gets with assured message delivery
 
 // generate a unique confirmId for this operation
 confirmId = MQe.uniqueValue();
 
 // get next available msg -msg remains locked on the target queue
 MQeMsgObject msg = qmgr.getMessage("RemoteQMgr", "RemoteQueue", null, null, confirmId);
 
 // confirm the successful Get
 qmgr.confirmGetMessage("RemoteQMgr", "RemoteQueue", msg.getMsgUIDFields());
 
 

getName

public final java.lang.String getName()
                               throws MQeException

Gets (unique) Queue Manager name.

Returns:
A String containing the name of the QueueManager.
Throws:
MQeException -

Note: It is strongly recommended that all queue manager names are unique within an WebSphere MQ Everyplace network.

Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 String qmgrName = qmgr.getName();
 
 

getReference

public static final MQeQueueManager getReference(java.lang.String queueManagerName)
                                          throws MQeException
Deprecated. Since there can only be one queue manager per jvm it is more efficient to use the method getDefaultQueueManager which returns a reference or null.

Returns a object reference to a named Queue Manager.

If QueueManagerName paramameter is null, then the Default QMgr for this JVM is returned. Note that the One queue manager per JVM is enforced by the current code, so unless the supplied name is null, or matches the singleton, then no queue manager will be found. This results in an exception.

Parameters:
queueManagerName - java.lang.String
Returns:
an instance of MQeQueueManager.
Throws:
MQeException - Except_QMgr_UnknownQMgr
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject Msg = null;
 
 // Obtain a reference to "MyQMgr"Queue Manager
 qmgr = MQeQueueManager.getDefaultQueueManager();
 
 // Put a message
 qmgr.putMessage(null, "DestQ", Msg, null, 0);
 
 

isQueueManagerActive

public final boolean isQueueManagerActive()
Reply true if the receiver is active, false otherwise. This method is synchronized to hide transitional states (eg activating). If (when!) the method returns the result will be true if the queue manager can be used as normal, and false if it has been closed.

An active queue manager:

  -       allows queue/listener/connection administration
  -       allows message manipulation
  -       performs background message pushing
 

Returns:
a boolean. True, if the queue manager is active and False, otherwise.

Note : This method replaces checkActive() which is now deprecated.


putMessage

public void putMessage(java.lang.String qmgrName,
                       java.lang.String queueName,
                       MQeMsgObject msgObj,
                       MQeAttribute attr,
                       long confirmId)
                throws java.lang.Exception

Puts a message to a queue.

This method places the specified message onto the specified queue. This queue may belong to a local or a remote queue manager.

Puts to remote queues can occur immediately, or at some later time depending upon how the remote queue is defined on the local queue manager.

If a remote queue is defined as synchronous, the transmission of the message over the network occurs immediately.

If a remote queue is defined as asynchronous, the message is stored within the local queue manager. The message remains there until the queue manager rules decide that it is time to transmit any pending messages or the queue manager is triggered through the triggerTransmission() method. If the local queue manager does not hold a definition of the remote queue then it attempts to contact the queue synchronously.

The assured delivery of the message is dependent on the value of the confirmId parameter. Passing a nonzero value transmits the message as normal, but the message is locked on the target queue until a subsequent confirm is received. Passing a value of zero transmits the message without the need for a subsequent confirm, however the delivery of the message is not assured.

The confirmID is also used in the event of an error during the execution of this command. Passing the same confirm id used for the put operation to the undo method removes the unconfirmed message from the target queue. It is recommended that a unique value be used for each put operation. A unique value can be generated using the MQe.uniqueValue() method.

A message can be protected using message-level security (see WebSphere MQ Everyplace Programming Guide for information on WebSphere MQ Everyplace security). The security is defined by providing an MQeAttribute object, or one of its descendants. The attribute can be attached to the message prior to any put message request, or the attribute parameter can be used to specify the message-level security to be used.

If the attribute parameter is not null, the value overrides any attribute attached to the message prior to the put message request. If the attribute parameter is null, it has no effect on the sending of the message. Checks if message Origin QMgr field has been set.

Parameters:
qmgrName - A string containing the name of the remote queue manager to which the specified queue belongs. If a value of null is used it is assumed that the queue manager is local.
queueName - A string containing the name of the queue on which the message should be placed.
confirmId - A long value denoting whether or not to use assured message delivery. A nonzero value locks the message on the target queue, it is not made visible until a subsequent confirm flow. A value of zero transmits the message without the need for a subsequent confirm.
Returns:
void
Throws:
MQeException - Except_QMgr_InvalidQName
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 // Simple Put Operation
 MQeQueueManager qmgr = new MQeQueueManager();
 
 try {
     qmgr.putMessage(null, "MyQueue", msgObj, null, 0); // simple put
 
 } catch (MQeException e) {// Hanlde the error here.
 }
 
 

Example2

,
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject msg = null;
 
 // put with assured message delivery
 
 // generate a unique confirmId for this operation
 confirmId = MQe.uniqueValue();
 qmgr.putMessage("RemoteQMgr", "RemoteQueue", msg, null, confirmId);
 // confirm the put
 qmgr.confirmPutMessage("RemoteQMgr", "RemoteQueue", msg.getMsgUIDFields());
 
 

removeMessageListener

public void removeMessageListener(MQeMessageListenerInterface listener,
                                  java.lang.String queueName,
                                  MQeFields filter)
                           throws java.lang.Exception

Removes an objects subscription to WebSphere MQ Everyplace message events generated when messages arrive on a specified queue.

It is only possible to have listeners on local queues.

Note: The listening object must implement the MQeMessageListenerInterface. If an optional message filter is specified, the object’s subscription is only removed for events concerning messages that include the same fields as those specified in the filter. If the filter is null, the object’s subscription for events concerning all messages is removed.

Parameters:
listener - A reference to MQeMessageListenerInterface
queueName - (java.lang.String) A String containing the name of the queue for which the listener previously registered to receive events.
filter - null or a MQeFields object containing a message filter.
Returns:
void
Throws:
MQeException - Except_QMgr_NotActive
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // remove the 'all messages'listener for this queue
 qmgr.removeMessageListener(listener, "MY.QUEUE", null);
 
 

triggerTransmission

public void triggerTransmission()
                         throws java.lang.Exception

This method triggers an attempt to transmit any pending messages.

Pending messages are messages awaiting transmission to remote queue managers.Typically, the transmission of pending messages would be handled by the queue manager rules, but this method allows transmission of pending messages at a time convenient to the application. In addition, this method triggers any home server queues that are defined. These queues attempt to collect messages from their home servers.

Returns:
void

Transmission will not occur on the callers thread but will trigger transmission via a background thread.

Throws:
MQeException - Except_BadRequest
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue.This is usually a result of a failure in the underlying file system(eg out of disk space).The MessageStoreException contains the original exception thrown by the underlying system.The queue will not be usable until it has been reinitialized.The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 
 try {
     // application decides it's time to transmit
     //if (timeToTransmit())
     qmgr.triggerTransmission();
 } catch (MQeException e) {
 
     throw e;
 }
 
 

undo

public void undo(java.lang.String queueManagerName,
                 java.lang.String queueName,
                 long confirmId)
          throws java.lang.Exception

This method is intended to be used in the event of an error during a put, get,or browseAndLock command. It is possible that the error could leave messages in an unconfirmed or locked state on the target queue. This method resets the message to the state (either locked or unlocked) that it was in prior to the failed operation, or in the case of an unconfirmed put operation, the message is deleted.

To reset the message, it is necessary to supply the confirmId that was used in the failed operation. It is recommended that confirm ids are unique for each message. A unique value can be generated using the MQe.uniqueValue() method.

It should be noted that on return from this method an additional field will have been added to the message, com.ibm.mqe.MQe.Msg_BackoutCount. This field is required by JMS so may be removed if this API is not being used.

Parameters:
queueName - A string containing the name of the queue that holds the locked message.
confirmId - A long value that is the same as the confirm id used on the failed operation.
Returns:
void
Throws:
MQeException - Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeMsgObject msg = null;
 
 // generate a unique confirmId for this operation
 confirmId = MQe.uniqueValue();
 try {
     qmgr.putMessage("RemoteQMgr", "RemoteQueue", msg, null, confirmId);
     qmgr.confirmPutMessage("RemoteQMgr", "RemoteQueue",
         msg.getMsgUIDFields());
 } catch (Exception e) {
     // Give the remote Queue Manager time to recover from error
     Thread.sleep(30000);
     // Remote Queue Manager failure -undo the put message
     qmgr.undo("RemoteQMgr", "RemoteQueue", confirmId);
 }
 
 

unlockMessage

public void unlockMessage(java.lang.String queueManagerName,
                          java.lang.String queueName,
                          MQeFields filter)
                   throws java.lang.Exception

Unlocks a message that has been previously locked.

This makes it visible once again to all applications. Only one message can be unlocked at a time and both the unique id (timestamp and origin queue manager name), and lock id of the message must be supplied. The queue may belong to a local or remote queue manager.

If the message is not available, an exception is thrown. This method would typically be used in conjunction with the browseMessagesAndLock(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long, boolean) method.

Parameters:
queueName - A string containing the name of the queue that holds the locked message.
filter - An MQeFields object containing a message filter. This must contain both the message unique id and lock id for the operation to be successful.
Returns:
void
Throws:
MQeException - Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeEnumeration msgEnum;
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // lock all msgs on queue
 msgEnum = qmgr.browseMessagesAndLock(null, "MyQueue", null, null, 0, false);
 long lockID = msgEnum.getLockId(); // get lockID
 
 while (msgEnum.hasMoreElements()) {
     MQeFields msgFields = (MQeFields) msgEnum.nextElement();
     String msgID = MQe.byteToAscii(msgFields.getArrayOfByte(MQe.Msg_MsgID));
 
     // Unlock all messages with an ID of 1234
     if (msgID.equals("1234")) {
         msgFields.putLong(MQe.Msg_LockID, lockID);
         qmgr.unlockMessage(null, "MyQueue", msgFields);
     }
 }
 
 

waitForMessage

public MQeMsgObject waitForMessage(java.lang.String queueManagerName,
                                   java.lang.String queueName,
                                   MQeFields filter,
                                   MQeAttribute attr,
                                   long confirmId,
                                   int waitForTime)
                            throws java.lang.Exception

Waits for a message to arrive, then gets it.

This method works in an identical manner to getMessage. However, if no message is available, the method waits for the period of time specified by milliseconds. If no message is available at the end of this period, an Exception is thrown.

Parameters:
queueName - a string containing the name of the WebSphere MQ Everyplace queue from which to obtain a message.
filter - null,or anMQeFields object containing a message filter.
confirmId - A long value denoting whether or not to use assured message delivery. A nonzero value does not remove the message from the target queue, this occurs on a subsequent confirm flow. A value of zero removes the message from the target queue.
waitForTime - The period of time (specified in milliseconds) for which to wait for a message to become available.
Returns:
void
Throws:
MQeException - Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 String MsgId = "260399";
 String CorrelId = "260399/2";
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // set up a parameters object to match with only interested in msgs
 filter = new MQeFields();
 // with this message Id
 filter.putArrayOfByte(MQe.Msg_MsgID, qmgr.asciiToByte(MsgId));
 // &this correlation Id
 filter.putArrayOfByte(MQe.Msg_CorrelID, qmgr.asciiToByte(CorrelId));
 
 // wait 10 seconds for a msg to arrive
 MQeMsgObject msgObj = qmgr.waitForMessage(null, "MyQueue", filter, null, 0, 10000);
 
 

browseMessages

public long browseMessages(java.lang.String queueManagerName,
                           java.lang.String queueName,
                           MQeFields filter,
                           MQeAttribute attr,
                           long confirmId,
                           boolean justUID,
                           java.util.Vector results)
                    throws java.lang.Exception

Browse messages on a queue, and place the results into a Vector.

If non-zero confirm id then lock them to obtain exclusive access to the messages browsed.

Parameters:
queueName - A string containing the name of the queue on which the messages are held.
filter - An MQeFields object containing a message filter.
attr - An MQeAttribute object
confirmId - A long value.
justUID - A boolean value denoting the authenticity of the user.
results - java.util.Vector for the results. Results are added to the vector with the method addElement(), after any existing elements have been removed.
Returns:
A long value. If a non-zero confirmId was specified, then the lock id will be returned. If a zero confirm id was specified then the return value is meaningless.
Throws:
MQeException - Except_QMgr_InvalidQMgrName
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeEnumeration msgs = null;
 byte[]msgId = MQe.asciiToByte("240999");
 byte[]correlId = MQe.asciiToByte("240999/2");
 
 try {
     // setup parameters object for matching
     filter = new MQeFields();  //match against msgs
     filter.putArrayOfByte(MQe.Msg_MsgID, msgId);  //with this Msg Id
     filter.putArrayOfByte(MQe.Msg_CorrelID,  // &this Correl Id
         correlId);
     // look at available messages
     msgs = qmgr.browseMessages(null, "MyQueue", filter, null, false);
 
     // get this one and remove from queue
     MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue",
             (MQeFields) msgs.nextElement(), null, 0);
 } catch (MQeException e) {// Handle the error here
 }
 
 MQeQueueManager qmgr = new MQeQueueManager();
 MQeEnumeration msgs = null;
 byte[]msgId = MQe.asciiToByte("240999");
 byte[]correlId = MQe.asciiToByte("240999/2");
 
 try {
     // setup parameters object for matching
     filter = new MQeFields();  //match against msgs
     filter.putArrayOfByte(MQe.Msg_MsgID, msgId);  //with this Msg Id
     filter.putArrayOfByte(MQe.Msg_CorrelID,  // &this Correl Id
         correlId);
 
     // look at available messages
     msgs = qmgr.browseMessagesAndLock(null, "MyQueue", filter, null, 0, false);
     long lockId = msgs.getLockId(); // get Lock Id
 
     filter.putLong(MQe.Msg_LockID, lockId); // Add lock Id
 
     // get the first locked message from queue
     MQeMsgObject msgObj = qmgr.getMessage(null, "MyQueue", filter, null, 0);
 } catch (MQeException e) {// Handle the error here
 }
 
 

waitForMessage

public MQeMsgObject waitForMessage(java.lang.String queueManagerName,
                                   java.lang.String queueName,
                                   MQeFields filter,
                                   MQeAttribute attr,
                                   long confirmId,
                                   int waitForTime,
                                   int pollInterval)
                            throws java.lang.Exception

Waits for a message to arrive, then gets it.

This method works in an identical manner to getMessage. However, if no message is available, the method waits for the period of time specified by milliseconds. If no message is available at the end of this period, an Exception is thrown. All other exceptions (such as 'queue manager not known', 'no route to host', etc) will terminate wait with exception.

Parameters:
queueName - a string containing the name of the WebSphere MQ Everyplace queue from which to obtain a message.
filter - null,or anMQeFields object containing a message filter.
confirmId - A long value denoting whether or not to use assured message delivery. A nonzero value does not remove the message from the target queue, this occurs on a subsequent confirm flow. A value of zero removes the message from the target queue.
waitForTime - The period of time (specified in milliseconds) for which to wait for a message to become available.
pollInterval - The period of time (specified in milliseconds) to wait between checks for a message available.
Returns:
An MQeMsgObject.
Throws:
MQeException - Except_QMgr_NotActive
MQeMessageStoreException - This is thrown as a result of a low-level failure in the message store used by the queue. This is usually a result of a failure in the underlying file system (eg out of disk space). The MessageStoreException contains the original exception thrown by the underlying system. The queue will not be usable until it has been reinitialized. The only way the user can currently do this is to close and re-open the queue manager.
java.lang.Exception
Example:
 String MsgId = "260399";
 String CorrelId = "260399/2";
 MQeQueueManager qmgr = new MQeQueueManager();
 
 // set up a parameters object to match with only interested in msgs
 filter = new MQeFields();
 // with this message Id
 filter.putArrayOfByte(MQe.Msg_MsgID, qmgr.asciiToByte(MsgId));
 // &this correlation Id
 filter.putArrayOfByte(MQe.Msg_CorrelID, qmgr.asciiToByte(CorrelId));
 
 // wait 10 seconds for a msg to arrive
 MQeMsgObject msgObj = qmgr.waitForMessage(null, "MyQueue", filter, null, 0, 10000);
 
 

Websphere MQ Everyplace