|
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.MQeQueueManager
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.
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. |
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 |
public static final java.lang.String QueueManager
activate(MQeFields)
,
Constant Field Valuespublic static final java.lang.String Registry
activate(MQeFields)
,
Constant Field Valuespublic static final java.lang.String Name
activate(MQeFields)
,
Constant Field ValuesConstructor Detail |
public MQeQueueManager()
Queue Manager constructor.
The activate(java.lang.String, java.lang.String)
method must be called to
initialise and start the queue manager.
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.
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.
queueManagerName
- A String
the name of the queue managerregistryLocation
- A String
the location of the base
directory for the registry
MQeException
- Using codes:
MQeExceptionCodes.Except_QMgr_Activated
MQeExceptionCodes.Except_Active
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
java.lang.Exception
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 |
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.
queueManagerName
- A String
the name of the queue managerregistryLocation
- A String
the location of the base
directory for the registry
MQeException
- Using codes:
MQeExceptionCodes.Except_QMgr_Activated
MQeExceptionCodes.Except_Active
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
java.lang.Exception
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"); }
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.
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:
QueueManager
MQeFields
containing other fields:
Name
Registry
MQeFields
containing other fields:
MQeRegistry.DirName
MQeException
- Using codes:
MQeExceptionCodes.Except_QMgr_Activated
MQeExceptionCodes.Except_Active
MQeExceptionCodes.Except_QMgr_RegistryDataVersion
java.lang.Exception
// 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);
protected void activate(java.lang.String activateName) throws java.lang.Exception
Intended for use by QMgr subclasses which want to override the default activation procedure
activateName
- java.lang.String the name of the queue manager.
java.lang.Exception
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.
queueName
- A String containing the name of the queue from which the
listener wishes to receive events
MQeException
- Except_QMgr_NotActive
java.lang.Exception
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);
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.
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.
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.
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
browseMessagesAndLock(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long, boolean)
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 }
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().
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.
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.
- 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
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)
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 }
public final boolean checkActive()
To check whether the queue manager is active or not.
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.
java.lang.Exception
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.
java.lang.Exception
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
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.
quiesceDuration
- A long integer value containing the quiesce duration.
java.lang.Exception
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
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.
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.
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
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());
public void confirmPutMessage(java.lang.String queueManagerName, java.lang.String queueName, MQeFields filter) throws java.lang.Exception
Confirms a put operation.
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.
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
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());
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.
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.
- 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
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());
public static final MQeQueueManager getDefaultQueueManager()
Currently, only a single queue manager is supported.
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.
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.
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
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());
public final java.lang.String getName() throws MQeException
Gets (unique) Queue Manager name.
MQeException
- Note: It is strongly recommended that all queue manager names are unique within an WebSphere MQ Everyplace network.
MQeQueueManager qmgr = new MQeQueueManager(); String qmgrName = qmgr.getName();
public static final MQeQueueManager getReference(java.lang.String queueManagerName) throws MQeException
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.
queueManagerName
- java.lang.String
MQeException
- Except_QMgr_UnknownQMgrMQeQueueManager 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);
public final boolean isQueueManagerActive()
An active queue manager:
- allows queue/listener/connection administration - allows message manipulation - performs background message pushing
Note : This method replaces checkActive() which is now deprecated.
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.
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.
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
// 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());
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.
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.
MQeException
- Except_QMgr_NotActive
java.lang.Exception
MQeQueueManager qmgr = new MQeQueueManager(); // remove the 'all messages'listener for this queue qmgr.removeMessageListener(listener, "MY.QUEUE", null);
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.
Transmission will not occur on the callers thread but will trigger transmission via a background thread.
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
MQeQueueManager qmgr = new MQeQueueManager(); try { // application decides it's time to transmit //if (timeToTransmit()) qmgr.triggerTransmission(); } catch (MQeException e) { throw e; }
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.
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.
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
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); }
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.
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.
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
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); } }
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.
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.
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
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);
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.
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 objectconfirmId
- 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.
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
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 }
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.
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.
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
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 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |