Websphere MQ Everyplace

com.ibm.mqe
Class MQeQueueManagerRule

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeRule
              |
              +--com.ibm.mqe.MQeQueueManagerRule
All Implemented Interfaces:
MQeExceptionCodes
Direct Known Subclasses:
ExampleQueueManagerRules, QueueManagerRules

public class MQeQueueManagerRule
extends MQeRule

This class contains methods that are invoked when the queue manager performs certain operations. The rules can affect the outcome of these operations. This class contains the default queue manager rules. Typically, these default rules would be overridden to provide appropriate behavior for a given WebSphere MQ Everyplace solution.

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
 
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
MQeQueueManagerRule()
           
 
Method Summary
 boolean activateQueues()
          This rule decides whether to activate certain queues at queue manager startup time.
 boolean addQueue(MQeQueueProxy Queue)
          This rule is called when a new queue is added to the queue manager.
 void deleteMessage(java.lang.String destQMgr, java.lang.String destQ, MQeFields filter)
          This rule is called when a delete message operation occurs.
 void getMessage(java.lang.String destQMgr, java.lang.String destQ, MQeFields filter, MQeAttribute attribute, long confirmID)
          This rule is called when a get message operation occurs.
 int getRetryCount()
          Deprecated. This method is no longer used.
 void peerConnection(java.lang.String qmgrName)
          Deprecated. This method is no longer called, as peer channels are not supported in version 2 of MQe
 void putMessage(java.lang.String destQMgr, java.lang.String destQ, MQeMsgObject msg, MQeAttribute attribute, long confirmID)
          This rule is called when a put message operation occurs.
 void queueManagerActivate()
          This rule is called when the queue manager is activated.
 void queueManagerClose()
          This rule is called when the queue manager is closed.
 void removeQueue(MQeQueueProxy Queue)
          This rule is called when a queue is to be removed from the queue manager.
 boolean transmit(MQeQueueProxy queue)
          This rule is called for each remote asynchronous queue definition when a transmission of pending messages is taking place.
 boolean triggerTransmission(int triggerCount, MQeFields msg)
          This rule returns a boolean value which denotes whether or not to allow, at this time, the triggering of communications (where communications includes both the transmission of pending messages from remote asynchronous queue definitions and the stimulation of the Home Server Queue into polling its Store-and-Forward Queue).
 void undo(java.lang.String destQMgr, java.lang.String destQ, long confirmID)
          This rule is called when an undo operation occurs.
 
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

MQeQueueManagerRule

public MQeQueueManagerRule()
Method Detail

queueManagerActivate

public void queueManagerActivate()
                          throws java.lang.Exception

This rule is called when the queue manager is activated.

Returns:
void
Throws:
java.lang.Exception -

Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.

Example:
 // Called when the Queue manager is activated 
 public void queueManagerActivate()throws Exception {
     super.queueManagerActivate();
     // background thread which triggers transmission
     th = new Thread(this, "TriggerThread");
     toldToStop = false;
     th.start();    // start timer thread        
 }
 
 // Background thread run method.                                            
 // Triggers transmission every interval until thread is stopped.                 
    
 public void run() {
     // Do a sleep-trigger-sleep-trigger loop until the queue manager closes or we get
     // an exception.
     while (!toldToStop) {
         
         try {                   
             
             // Count down until we've waited enough
             // We do a tight loop with a smaller granularity because 
             // otherwise we would stop a queue manager from closing quickly
             long timeToWait = MILLISECS_BETWEEN_TRIGGER_TRANSMITS;
 
             while (timeToWait > 0 && !toldToStop) {
             
                 // sleep for specified interval                                 
                 Thread.sleep(MILLISECS_BETWEEN_CLOSE_CHECKS);
                 
                 // We've waited for some time. Account for this in the overall wait.
                 timeToWait -= MILLISECS_BETWEEN_CLOSE_CHECKS;
             }
             
             if (!toldToStop) {
                 // trigger transmission on QMgr (which is rule owner)       
                 ((MQeQueueManager) owner).triggerTransmission();
             }
         } catch (Exception e) {
             e.printStackTrace();
         }
     }
     }
 

queueManagerClose

public void queueManagerClose()
                       throws java.lang.Exception

This rule is called when the queue manager is closed.

Returns:
void
Throws:
java.lang.Exception -

Note : This exception is retained for backward compatibility only and any exception thrown in this method will be caught and ignored.

See Also:
queueManagerActivate()
Example:
 // Called when a Queue manager Close is called 
 public void queueManagerClose()throws Exception { 
     super.queueManagerClose();
     
     // Tell the background thread to stop, as the queue manager is closing now.
     toldToStop = true;
     
     // Now wait for the background thread, if it's not already stopped.
     if (th != null) {
         try { 
             // Only wait for a certain time before giving up and timing out.
             th.join(MAX_WAIT_FOR_BACKGROUND_THREAD_MILLISECONDS);
  
             // Free up the thread control block for garbage collection.              
             th = null;
         } catch (InterruptedException e) {// Don't propogate the exception. 
             // Assume that the thread will stop shortly anyway.
         }
     }    
    
     }
 

addQueue

public boolean addQueue(MQeQueueProxy Queue)
                 throws java.lang.Exception

This rule is called when a new queue is added to the queue manager.

The rule is called before the addition of the queue, and so the rule is able to reject the operation by throwing an exception.

This rule also decides whether to activate the queue immediately or to activate the queue when it is first used. The default behaviour of the rule is to activate all home-server queues immediately. All other types of queue are activated when they are first used.

Parameters:
Queue - An MQeQueueProxy object that is being added to the queue manager.
Returns:
A boolean value denoting whether the queue should be activated immediately, or when it is first used.
   true  -  Activate the queue immediately.
   false -  Activate the queue when first used.
 
Throws:
java.lang.Exception
See Also:
removeQueue(com.ibm.mqe.MQeQueueProxy)
Example:
 // Don't allow asynchronous queues to be added to this Queue Manager 
 public boolean addQueue(MQeQueueProxy queue) throws Exception {
     boolean result = super.addQueue(queue);
 
     if (queue.isRemoteQueue() && !queue.isSynchronous()) {
         result = false;
     }
     return (result);        
 }
 
 
 

removeQueue

public void removeQueue(MQeQueueProxy Queue)
                 throws java.lang.Exception

This rule is called when a queue is to be removed from the queue manager.

The rule is called before the removal of the queue, so the rule is able to reject the operation by throwing an exception.

Parameters:
Queue - An MQeQueueProxy object that is to be removed from the queue manager.
Returns:
void
Throws:
java.lang.Exception
See Also:
addQueue(com.ibm.mqe.MQeQueueProxy)
Example:
 // This rule prevents the removal of the Payroll Queue 
 public void removeQueue(MQeQueueProxy queue) throws Exception {
     
     if (queue.getQueueName().equals("PayrollQueue")) {
         throw new MQeException(Except_Rule, "Can't delete this queue");        
     }
     }
 

deleteMessage

public void deleteMessage(java.lang.String destQMgr,
                          java.lang.String destQ,
                          MQeFields filter)
                   throws java.lang.Exception

This rule is called when a delete message operation occurs.

The rule is called before the operation takes place, and so the rule can stop the operation by throwing an exception.

Parameters:
destQMgr - A String containing the name of the queue manager that owns the queue on which this operation takes place. A value of null denotes that the local queue manager is to be used.
destQ - A String containing the name of the queue on which this operation takes place.
filter - This is the filter to be used for the delete message operation. It is an MQeFields object containing message fields (for example, priority and message ID ).
Returns:
void
Throws:
java.lang.Exception
Example:
 // This rule blocks message deletes on 'TopSecretQueue'
 public void deleteMessage(String destQMgr, String destQ, MQeFields filter) 
     throws Exception {
     
     super.deleteMessage(destQMgr, destQ, filter);
     if (destQMgr == null || destQMgr.equals(((MQeQueueManager) owner).getName())) {
         if (destQ.equals("TopSecretQueue")) {
             throw new MQeException(Except_Rule, "Can't delete on this Queue");
         }
     }          
     }
 

getMessage

public void getMessage(java.lang.String destQMgr,
                       java.lang.String destQ,
                       MQeFields filter,
                       MQeAttribute attribute,
                       long confirmID)
                throws java.lang.Exception

This rule is called when a get message operation occurs.

The rule is called before the operation takes place, and so the rule can stop the operation by throwing an exception.

Parameters:
destQMgr - A String containing the name of the queue manager that owns the queue on which this operation takes place. A value of null denotes that the local queue manager is to be used.
destQ - A String containing the name of the queue on which this operation takes place.
filter - This is the filter to be used for the get message operation. It is an MQeFields object containing message fields. (for example, priority and message ID )
attribute - An MQe Attribute object used to provide message-level security.
confirmID - A long value denoting whether or not to use guaranteed message delivery. A nonzero value leaves the message locked on the target queue, it is not removed until a subsequent confirm flow. A value of zero removes the message from the target queue without the need for a subsequent confirm.

This value is also used in the event of a get message failure. The application should store the value, and use it to reset the messages that matched the get to their previous state (via the undo() command).

Returns:
void
Throws:
java.lang.Exception
See Also:
putMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeMsgObject, com.ibm.mqe.MQeAttribute, long)
Example:
 //This rule only allows GETs from 'OutboundQueue',if a password is 
 //supplied as part of the filter 
 public void getMessage(String destQMgr,
     String destQ,
     MQeFields filter,
     MQeAttribute attr,
     long confirmId)  throws Exception {        
   
     super.getMessage(destQMgr, destQ, filter, attr, confirmId);
     if ((destQMgr.equals(((MQeQueueManager) owner).getName()) && (destQ.equals("OutboundQueue")))) {
         if (!(filter.contains("Password"))) {
             throw new MQeException(Except_Rule, "Password not supplied");
         } else {
             String pwd = filter.getAscii("Password");
 
             if (!(pwd.equals("1234"))) {
                 throw new MQeException(Except_Rule, "Incorrect password");
             }
         }            
     }
     }
 

putMessage

public void putMessage(java.lang.String destQMgr,
                       java.lang.String destQ,
                       MQeMsgObject msg,
                       MQeAttribute attribute,
                       long confirmID)
                throws java.lang.Exception

This rule is called when a put message operation occurs.

The rule is called before the operation takes place, so the rule can stop the operation by throwing an exception.

Parameters:
destQMgr - A String containing the name of the queue manager that owns the queue on which this operation takes place. A value of null denotes that the local queue manager is to be used.
destQ - A String containing the name of the queue on which this operation takes place.
msg - The message object that is being placed on the target queue.
attribute - null , or an MQeAttribute object defining the authenticator, cryptor, and compressor to be associated with this message.
confirmID - A long value denoting whether or not to use assures 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.

Also, this value can be used in the event of a put message failure. By passing this value to the undo command, the application can remove any messages that were left in an incomplete state by the failed put operation.

Returns:
void
Throws:
java.lang.Exception
See Also:
getMessage(java.lang.String, java.lang.String, com.ibm.mqe.MQeFields, com.ibm.mqe.MQeAttribute, long)
Example:
 // Only allow msgs containing an ID field to be placed on the Queue 
 public void putMessage(String destQMgr,
     String destQ,
     MQeMsgObject msg,
     MQeAttribute attribute,
     long confirmId) throws Exception {
     
     if (!(msg.contains(MQe.Msg_MsgID))) {
         throw new MQeException(Except_Rule, "Msg must contain an ID");        
     }
     }
 

undo

public void undo(java.lang.String destQMgr,
                 java.lang.String destQ,
                 long confirmID)
          throws java.lang.Exception

This rule is called when an undo operation occurs.

The rule is called to inform the rule that the operation is taking place.

Parameters:
destQMgr - A String containing the name of the queue manager that owns the queue on which this operation takes place. A value of null denotes that the local queue manager is to be used.
destQ - A String containing the name of the queue on which this operation takes place.
confirmID - A long value that was the confirmID used by the operation which is being undone. All messages matching this confirmID are restored to their previous state.
Returns:
void
Throws:
java.lang.Exception
Example:
 public void undo(String destQMgr, String destQ, long confirmId) {
     // log the undo event
     System.out.println("Undo operation performed on queuemanager " + destQMgr + ", queue " + destQ);        
     }
 

triggerTransmission

public boolean triggerTransmission(int triggerCount,
                                   MQeFields msg)

This rule returns a boolean value which denotes whether or not to allow, at this time, the triggering of communications (where communications includes both the transmission of pending messages from remote asynchronous queue definitions and the stimulation of the Home Server Queue into polling its Store-and-Forward Queue).

This rule is invoked by the queue manager in two situations :


getRetryCount

public final int getRetryCount()
Deprecated. This method is no longer used.

This rule returns the number of retry attempts for a failed network operation.

The queue manager calls this rule when creating a new channel object. The value returned by this rule is passed to the channel, and it is used in the event of a network operation failure.

Returns:
An integer value that contains the number of times to retry a network operation. The queue manager acts on the value returned.
Throws:
none

activateQueues

public boolean activateQueues()

This rule decides whether to activate certain queues at queue manager startup time. The queues that can be activated are remote asynchronous queue definitions, home-server queues, and store-and-forward queues.

Activating these queues means that an attempt is made to transmit any messages that they hold. The triggerTransmission() method of the MQeQueueManagerRules class is also consulted to check that an attempt to transmit is allowed. Queues are normally not activated until an operation is performed on them. It can be useful to activate these queues immediately on queue manager startup because they may have transmission timer threads, or other functions associated with them.

Returns:
A boolean value denoting whether to activate certain queues at queue manager startup time. The queue manager acts on the value returned.
Throws:
none
Example:
 public boolean activateQueues() {        
     if (timeToTransmit()) {               // if in cheap transmission period
         return true;                      // then activate queues   
     } else {                               // otherwise
         return false;                     // don't activate queues        
     }       
 }
 
 private boolean timeToTransmit() {
     Calendar calendar = Calendar.getInstance();
     int currentHour = calendar.get(calendar.HOUR_OF_DAY);
 
     if (currentHour >= 18 || currentHour < 9) {
         return true;
     } else {
         return false;
     }
     
     }
 

transmit

public boolean transmit(MQeQueueProxy queue)

This rule is called for each remote asynchronous queue definition when a transmission of pending messages is taking place. The rule allows transmission to be disabled on a per-queue basis.

When a queue manager attempts to send all its pending messages, this rule is called for each queue that contains messages awaiting transmission. This rule decides whether to allow the transmission of those messages for the supplied queue.

Parameters:
queue - A MQeQueueProxy object that holds messages awaiting transmission.
Returns:
A boolean value denoting whether to allow the transmission of the messages held on this queue. The queue manager acts on the value returned.
Throws:
none
See Also:
triggerTransmission(int, com.ibm.mqe.MQeFields)
Example:
 // This rule allows queue transmission if current time is during the 
 // cheap rate transmission period 
 // If the current time is not during the cheap rate transmission period 
 // then transmission is only allowed if the queue is high priority 
 public boolean transmit(MQeQueueProxy queue) {
     // timeToTransmit() provides a time suitable for transmission at the
     // cheap rate hours.
     boolean ToTransmit = true;
 
     try {
         if (!timeToTransmit()) {  // not in cheap rate period
             if (queue.getDefaultPriority() <= 4) {
                 ToTransmit = false; 
             }
         }
     } catch (Exception e) {}                
     return ToTransmit;
     }
 

peerConnection

public void peerConnection(java.lang.String qmgrName)
Deprecated. This method is no longer called, as peer channels are not supported in version 2 of MQe

This rule is called when the queue manager’s peer channel listener receives an incoming connection request.

This method is called when a queue manager’s peer listener detects an incoming connection request from another WebSphere MQ Everyplace queue manager. The connection must be made over an MQePeerChannel, or its descendant.

Parameters:
qmgrName - A String containing the name of the WebSphere MQ Everyplace queue manager that is requesting a connection.
Returns:
void
Throws:
none
Example:
 public void peerConnection(String qmgrName) {        
     // block any connection attempt from 'RogueQMgr'
     if (qmgrName.equals("RogueQMgr")) {
         System.out.println("Connection on this QMgr not allowed");        
     }
     }
 

Websphere MQ Everyplace