|
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.MQeRule | +--com.ibm.mqe.MQeQueueRule
Queue rules control the behaviour of WebSphere MQ Everyplace queues. The queue rules are activated by the queue when it is itself activated. During the operation of the queue, the rules are called when certain events occur, for example, when a message is put, a message expires, or a duplicate message arrives. The rules then determine how the queue handles these events.
The base set of queue rules is defined in this class, which should be extended if a solution wishes to alter queue behaviour.
Note:Any unexpected exception thrown from a user's rule method (for instance, a null pointer exception) will result in the default behaviour being applied as though the rule invocation had never occurred.
Field Summary |
Constructor Summary | |
MQeQueueRule()
|
Method Summary | |
void |
addListener(MQeMessageListenerInterface listener,
MQeFields filter)
This rule is called when a message listener is attached to the queue. |
void |
attributeChange(MQeAttribute attribute)
This rule is called when an attempt is made to change the queue’s attribute. |
boolean |
browseMessage(MQeMsgObject msg,
long confirmID)
The rule decides whether to allow the message to be included in the set of messages returned to the application that issued the browse request. |
void |
deleteMessage(MQeFields filter)
This rule is called when a delete message operation takes place. |
void |
duplicateMessage(MQeMsgObject msg,
long confirmID)
This rule is called if a duplicate message is put onto the queue. |
boolean |
filterMessage(int what,
MQeFields filter)
This rule is called when a message filter is being applied during a getMessage(), browseMessage() or deleteMessage() method call. |
boolean |
getMessage(MQeMsgObject msg,
long confirmID)
This rule is called when a message is found that satisfies a get message request. |
void |
getPendingMessage(java.lang.String queueManagerName,
MQeFields filter,
long confirmID)
Deprecated. as of MQe version 2 this method is no longer invoked |
void |
indexEntry(MQeFields entry,
MQeMsgObject msg)
Deprecated. This is deprecated as this method is no longer used. |
boolean |
messageExpired(MQeFields entry,
MQeMsgObject msg)
This rule is called to notify when a message has exceeded either the queue’s expiry interval, or its own expiry interval. |
void |
messageMoved(MQeMsgObject msg,
java.lang.String queueManager,
java.lang.String queue)
This rule is called when a message has been moved form a Async Queue or a StoreForward Queue. |
void |
putMessage(MQeMsgObject msg,
long confirmID)
This rule is called when a put message request is made. |
void |
queueActivate()
This rule is called when the queue is activated. |
void |
queueClose()
This rule is called when the queue is closed. |
void |
removeListener(MQeMessageListenerInterface Listener,
MQeFields filter)
This rule is called when a message listener is removed from a queue. |
void |
resetMessageLock(MQeFields filter)
Deprecated. This is deprecated as this rule is no longer used. |
boolean |
transmitMessage(MQeMsgObject msg,
java.lang.String targetQMgr)
Called before a request is made to transmit a message from a remote queue or a store and forward queue If the method returns false then no attempt will be made to transmit the message to the target queue manager. |
boolean |
undo(MQeFields filter)
This rule is called when an undo operation occurs. |
void |
useCountChanged(int useCount)
Deprecated. This is deprecated as this method is no longer used. |
Methods inherited from class com.ibm.mqe.MQeRule |
activate, close, newRule |
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 |
Constructor Detail |
public MQeQueueRule()
Method Detail |
public void addListener(MQeMessageListenerInterface listener, MQeFields filter) throws java.lang.Exception
This rule is called when a message listener is attached to the queue.
By throwing an exception the rule is able to reject the add listener request.
listener
- A reference to the object that is subscribing to WebSphere MQ
Everyplace message events. The object must implement
MQeMessageListenerInterface.filter
- null or an MQeFields
object containing
message fields. A value of null means that the listener wishes to receive
events for all messages on the queue.
Specifying an MQeFields object containing message fields means that the listener is only interested in events concerning messages whose fields match those contained in the filter.
java.lang.Exception
// This rule logs the addition of a message listener public void addListener(MQeMessageListenerInterface listener, MQeFields filter) throws Exception { log(MQe_Log_Information, Event_Queue_AddMsgListener, "Added listener on queue " + ((MQeQueueProxy) owner).getQueueManagerName() + "+" + ((MQeQueueProxy) owner).getQueueName()); }
public void attributeChange(MQeAttribute attribute) throws java.lang.Exception
This rule is called when an attempt is made to change the queue’s attribute. The attribute defines the authenticator, cryptor and compressor used on the queue. Messages are stored using the attributes defined.
The messages held on the queue can be protected by an authenticator and cryptor. The messages can also be compressed by using a compressor. Together, the authenticator, cryptor, and compressor are known as the attributes of the queue, and they are defined by specifying an appropriate MQeAttribute object to be associated with the queue. This rule is called whenever an attempt is made to replace the queue’s attribute.
Note: Changing a queue’s attribute when it already holds messages stored using another attribute, may cause message loss, since the message may not be recoverable using the new attribute.
By throwing an exception the rule is able to reject the attribute change request.
attribute
- null , or an MQeAttribute
object that
defines the authenticator, cryptor and compressor that will be used on the
queue, if the change is allowed. null means that no attribute will be used
on the queue.
java.lang.Exception
// This rule only allows the queue's attribute to be changed if it was // not previously set // The MQeQueueProxy object is the owner of the rule public void attributeChange(MQeAttribute attribute)throws Exception { if (((MQeQueueProxy) owner).getQueueAttribute() != null) { throw new MQeException(Except_Rule, "Attribute already set"); } }
public boolean browseMessage(MQeMsgObject msg, long confirmID) throws java.lang.Exception
The rule decides whether to allow the message to be included in the set of messages returned to the application that issued the browse request.
A browse messages operation matches zero or more messages held on a queue. This method is called for every message matched. The rule decides whether to allow the message to be included in the set of messages returned to the application that issued the browse request.
If this rule throws an exception then the browse operation will be terminated.
msg
- An MQeMsgObject
containing the message being
browsed.confirmID
- A long value that is the confirmID used on this browse
operation. The confirmID is used to restore messages in the event of a
failure.
True - Allow the message to be included False - Do not allow the message to be included
java.lang.Exception
// This rule only allows messages of type 'OrderResponse' to be browsed public boolean browseMessage(MQeMsgObject msg, long confirmID) throws Exception { // get message type field String msgType = msg.getAscii("MsgType"); // what message type is it? if (msgType.equals("OrderResponse")) { return (true); // allow browse } else { return (false); // don't allow browse } }
public void deleteMessage(MQeFields filter) throws java.lang.Exception
This rule is called when a delete message operation takes place.
By throwing an exception the rule can reject the delete message request.
filter
- An MQeFields
object containing a message
filter. The filter must contain the message UID for the delete operation to
be successful.
java.lang.Exception
// This rule requires that the filter contain a password public void deleteMessage(MQeFields filter) throws Exception { if (filter != null && filter.contains("Password")) { String pswd = filter.getAscii("Password"); if (pswd.equals("12345678")) { // remove password from filter filter.delete("Password"); } else { throw new MQeException(Except_Rule, "Incorrect password"); } } else { throw new MQeException(Except_Rule, "No Password"); } }
public void duplicateMessage(MQeMsgObject msg, long confirmID) throws java.lang.Exception
This rule is called if a duplicate message is put onto the queue.
msg
- An MQeMsgObject
containing the duplicate
message.confirmID
- A long value that is the confirmID used on this put
operation. The confirmID is used to restore messages in the event of a
failure.
java.lang.Exception
- Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.
// This rule logs the duplicate message exception public void duplicateMessage(MQeMsgObject msg, long confirmID) throws Exception { // get message UID MQeFields msgUID = msg.getMsgUIDFields(); // log the duplicate message exception log(MQe_Log_Warning, Event_Queue_Duplicate, msgUID.getAscii(MQe.Msg_OriginQMgr) + "+" + msgUID.getLong(MQe.Msg_Time)); }
public boolean filterMessage(int what, MQeFields filter)
This rule is called when a message filter is being applied during a getMessage(), browseMessage() or deleteMessage() method call.
The queue rule checks to make sure certain fields exist in the filter, and that they contain certain values. The rule then uses this information to allow or reject the operation.
what
- An integer, indicating which operation is being performed:filter
- An MQeFields
object: null or the search
filter used to restrict the operation to a subset of messages on the queue.
true - Allow the requested operation to go ahead. false - Reject the requested operation.
none
getMessage(com.ibm.mqe.MQeMsgObject, long)
,
browseMessage(com.ibm.mqe.MQeMsgObject, long)
,
deleteMessage(com.ibm.mqe.MQeFields)
public boolean filterMessage(int what, MQeFields filter) { //Allow all operations by default,regardless of filter. return true; }
public boolean getMessage(MQeMsgObject msg, long confirmID) throws java.lang.Exception
This rule is called when a message is found that satisfies a get message request. The rule can decide whether the message should be allowed to satisfy the get message request.
If the rule does not allow the message to satisfy the get message request then the queue will search for another message that satisfies the request.
By throwing an exception the rule can terminate the get message request.
msg
- An MQeMsgObject
containing a message that
satisfies the get message request.confirmID
- A long value that is the confirmID used on this get request.
The confirmID is used to restore messages in the event of a failure.
true - Allow the requested operation to go ahead false - Reject the requested operation
java.lang.Exception
putMessage(com.ibm.mqe.MQeMsgObject, long)
// This rule disallows a get request on a message if the message states // that it can only be browsed public boolean getMessage(MQeMsgObject msg, long confirmId) throws Exception { boolean result = true; // does the message contain a field which states what operations are // allowed upon it if (msg.contains("AllowableOperations")) { String allowedOperations = msg.getAscii("AllowableOperations"); // if the message states that it can only be browsed disallow the get if (allowedOperations.equals("BrowseOnly")) { result = false; } } return (result); }
public final void getPendingMessage(java.lang.String queueManagerName, MQeFields filter, long confirmID) throws java.lang.Exception
This rule is called when a get pending message request is received.
An WebSphere MQ Everyplace queue manager is able to collect messages destined for itself from its home-server through a home-server queue. The home-server stores messages destined for its clients in one or more store-and-forward queues. The home-server queue contacts its home-server’s store-and-forward queues using the MQeStoreAndForwardQueue.getPendingMessage() method. Any pending messages for that WebSphere MQ Everyplace queue manager are then returned.
queueManagerName
- A String containing the name of the WebSphere MQ Everyplace
queue manager that initiated the get pending message request.filter
- null or an MQeFields
object containing a message
filter, used to match any pending messages. null means return the first available
message addressed to the queue manager specified in queueManagerName.confirmID
- A long value that is the confirmID for this operation.
The confirmID is used to restore messages in the event of a failure.
java.lang.Exception
public final void indexEntry(MQeFields entry, MQeMsgObject msg) throws java.lang.Exception
This rule is called whenever an index entry is created.
This occurs when a new message is put onto the queue.
The index entry contains state information about the message, along with certain index fields that are held to enable faster message searching.
entry
- An MQeFields object that is the index entry for a message.msg
- An MQeMsgObject
containing the message for
which an index entry is being created.
java.lang.Exception
public boolean messageExpired(MQeFields entry, MQeMsgObject msg) throws java.lang.Exception
This rule is called to notify when a message has exceeded either the queue’s expiry interval, or its own expiry interval.
If a message has remained on the queue for a length of time greater than the queue’s expiry interval, or if a message exceeds its own expiry interval then this the message will be expired as soon as this situation is detected. This rule is then called to notify the rule implementor of the expiry. The implementor may choose to take any action as a result of this notification, but typically might place the message on a ’dead letter queue’.
entry
- An MQeFields
null value maintained for backward
compatibility.msg
- An MQeMsgObject
containing the message that
has expired.
java.lang.Exception
- Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.
// This rule puts a copy of any expired messages to a Dead Letter Queue public boolean messageExpired(MQeFields entry, MQeMsgObject msg) throws Exception { // Get the reference to the Queue Manager MQeQueueManager qmgr = MQeQueueManager.getDefaultQueueManager(); // need to set re-send flag so that put of message to new queue isn't // rejected msg.putBoolean(MQe.Msg_Resend, true); // if the message contains an expiry interval field, remove it if (msg.contains(MQe.Msg_ExpireTime)) { msg.delete(MQe.Msg_ExpireTime); } // put message onto dead letter queue qmgr.putMessage(null, "DEAD.LETTER.QUEUE", msg, null, 0); // return true (the return code is ignored) return (true); }
public void putMessage(MQeMsgObject msg, long confirmID) throws java.lang.Exception
This rule is called when a put message request is made.
By throwing an exception the rule can prevent the message being put onto the queue.
msg
- An MQeMsgObject
containing the message to be
put onto the queue.confirmID
- A long value containing the confirmID for this
operation. The confirmID is used to restore locked messages in the
event of a failure.
java.lang.Exception
// This rule blocks a message Put if the message priority is less than 5 public void putMessage(MQeMsgObject msg, long confirmID) throws Exception { if ((msg.contains(MQe.Msg_Priority)) && (msg.getByte(MQe.Msg_Priority) < 5)) { throw new MQeException(Except_Rule, "Priority too low"); } }
public void queueActivate()
This rule is called when the queue is activated.
none
// This rule logs the activation of the queue public void queueActivate() { try { logFile = new LogToDiskFile("log.txt"); log(MQe_Log_Information, Event_Queue_Activate, "Queue " + ((MQeQueueProxy) owner).getQueueManagerName() + "+" + ((MQeQueueProxy) owner).getQueueName() + "active"); } catch (Exception e) { e.printStackTrace(System.err); } }
public void queueClose()
This rule is called when the queue is closed.
none
// This rule logs the closure of the queue public void queueClose() { try { log(MQe_Log_Information, Event_Queue_Closed, "Queue " + ((MQeQueueProxy) owner).getQueueManagerName() + "+" + ((MQeQueueProxy) owner).getQueueName() + "closed"); // close log file logFile.close(); } catch (Exception e) { e.printStackTrace(System.err); } }
public void removeListener(MQeMessageListenerInterface Listener, MQeFields filter) throws java.lang.Exception
This rule is called when a message listener is removed from a queue.
By throwing an exception the rule can prevent the listener from being removed.
Listener
- The object that is subscribing to WebSphere MQ Everyplace
message events. The object must implement
MQeMessageListenerInterface
.filter
- null or an MQeFields
object containing
a message filter. The filter must match the filter used in the add listener
command that created this listener.
java.lang.Exception
// This rule logs the removal of the message listener public void removeListener(MQeMessageListenerInterface listener, MQeFields filter) throws Exception { log(MQe_Log_Information, Event_Queue_RemoveMsgListener, "Removed listener on queue " + ((MQeQueueProxy) owner).getQueueManagerName() + "+" + ((MQeQueueProxy) owner).getQueueName()); }
public final void resetMessageLock(MQeFields filter) throws java.lang.Exception
This rule is called when a request is made to reset the lock state on a message. The message is reset to an unlocked state.
This function can only be performed by Websphere MQ administration. By throwing an exception the rule can prevent the reset from occurring.
filter
- An MQeFields
object containing a message
filter. This filter is used to match the message having its lock state reset.
java.lang.Exception
public boolean transmitMessage(MQeMsgObject msg, java.lang.String targetQMgr) throws java.lang.Exception
Called before a request is made to transmit a message from a remote queue or a store and forward queue If the method returns false then no attempt will be made to transmit the message to the target queue manager. This will also prevent any other messages destined for the target queue manager from being transmitted on the current transmit cycle.
msg
- A reference to the message that is pending transmission.targetQMgr
- Name of the queue manager the message is targetted at.
true - allow message to be transmitted false - prevent message from being transmitted
java.lang.Exception
// This rule only allows transmission of the given message if // its priority is greater than 4 public boolean transmitMessage(MQeMsgObject msg, String targetQMgr) throws Exception { boolean result = true; if (!msg.contains(MQe.Msg_Priority) || ((msg.contains(MQe.Msg_Priority)) && (msg.getByte(MQe.Msg_Priority) < 5))) { result = false; } else { result = true; } return result; }
Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.
public boolean undo(MQeFields filter) throws java.lang.Exception
This rule is called when an undo operation occurs. An undo message operation matches zero or more messages held on a queue. This rule is called for each message matched.
java.lang.Exception
- Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.
// This rule logs the message reset public boolean undo(MQeFields filter) throws Exception { // get message UID if (filter.contains(MQe.Msg_Time) && filter.contains(MQe.Msg_OriginQMgr)) { String originQMgr = filter.getAscii(MQe.Msg_OriginQMgr); long timeStamp = filter.getLong(MQe.Msg_Time); log(MQe_Log_Information, Event_Queue_ResetMessageLock, "Message " + originQMgr + ":" + timeStamp + "on queue " + ((MQeQueueProxy) owner).getQueueManagerName() + "+" + ((MQeQueueProxy) owner).getQueueName() + "has been reset"); } return (true); }
public final void useCountChanged(int useCount) throws java.lang.Exception
This rule is called every time the queue's use count is changed.
The use count is a measure of the number of users attached to the queue. The use count changes when the queue is activated or closed, and when remote queue managers connect to, or disconnect from, the queue using an MQeTransporter.
useCount
- The queue’s current use count.
java.lang.Exception
public void messageMoved(MQeMsgObject msg, java.lang.String queueManager, java.lang.String queue)
If the message has been moved from a Store/Forward Queue, and/or has been subject to security, this message will be wrapped. It will be necassary to "unwrap" the mesasge. For the case where security has been applied to a message on a Store/Forward Queue then issue 2 unwraps. The first for the Store/Forward Queue Wrapper (with no attribute) and then call unwrap again supplying the correct attribute.
msg
- The message that has just been movedqueueManager
- The QueueManager to which the message is destinedqueue
- The Queue to which the message is destined.MQeMsgObject.unwrapMsgObject(com.ibm.mqe.MQeAttribute)
|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |