Using queue manager rules

This section describes some examples of the use of queue manager rules.

In the Java codebase, a user provides an implementation of a rule method by subclassing the MQeQueueManagerRule class.

In the C codebase, a user maps rules functions to relevant rules function pointers. These pointers are passed into the rules initialization function, which is also the entry point to the user's rules module.

For a description of all parameters passed to rules functions in the C codebase, see the WebSphere MQ Everyplace C Programming Reference.

Example put message rule

This first example shows a put message rule that insists that any message being put to a queue using this queue manager must contain a WebSphere MQ Everyplace message ID field:

Java codebase
	/* 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 )         {
   	 if ( !(msg.Contains( MQe.Msg_MsgId )) )    {
        		throw new MQeException( Except_Rule, "Msg must contain an ID" );
    	}
	}

C codebase
	MQERETURN myRules_putMessage( MQeRulesPutMessage_in_ * pInput,  
                              MQeRulesPutMessage_out_ * pOutput)    {
    // Only allow msgs containing an ID field to be placed on the Queue 
    MQERETURN rc = MQERETURN_OK;
    MQEBOOL contains = MQE_FALSE;
 
    MQeExceptBlock * pExceptBlock=(MQeExceptBlock*)(pOutput->pExceptBlock);
    SET_EXCEPT_BLOCK_TO_DEFAULT(pExceptBlock);
 
    rc = mqeFields_contains(pInput->hMsg,pExceptBlock, 
										&contains, MQE_MSG_MSGID);
    if(MQERETURN_OK == rc && !contains)     {
        SET_EXCEPT_BLOCK( pExceptBlock, 
                          MQERETURN_RULES_DISALLOWED_BY_RULE,
                          MQEREASON_NA);
    }
}
 

Notice the manner in which the exception block instance is retrieved from the output parameter structure and then set with the appropriate return and reason codes. This is the way in which the rule function communicates with the application, thus modifying application behaviour.

Example get message rule

The next example rule is a get message rule that insists that a password must be supplied before allowing a get message request to be processed on the queue called OutboundQueue. The password is included as a field in the message filter passed into the getMessage() method.

Java codebase
/* 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 )         {
   super.getMessage( destQMgr, destQ, filter, attr, confirmId );
   if (destQMgr.equals(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" );
           }
       }
   }
}

C codebase
MQERETURN myRules_getMessage( MQeRulesGetMessage_in_ * pInput,  
                              MQeRulesGetMessage_out_ * pOutput)    {
    MQeStringHndl hQueueManagerName, hCompareString, hCompareString2, 
                  hFieldName, hFieldValue;
    MQEBOOL isEqual = MQE_FALSE;
    MQEBOOL contains = MQE_FALSE;
    MQeQueueManagerHndl hQueueManager;
 
    MQERETURN rc = MQERETURN_OK;
    MQeExceptBlock * pExceptBlock = 
                           (MQeExceptBlock *)
										(pOutput->pExceptBlock);
    SET_EXCEPT_BLOCK_TO_DEFAULT(pExceptBlock);
 
    /* get the current queue manager */
     rc = mqeQueueManager_getCurrentQueueManager(pExceptBlock,
                                                &hQueueManager);
    if(MQERETURN_OK == rc) {
        // if the destination queue manager is the local queue manager
              rc = mqeQueueManager_getName( hQueueManager,                                
                                      pExceptBlock, 
                                      &hQueueManagerName );
        if(MQERETURN_OK == rc)     { 
            rc = mqeString_equalTo(pInput->hQueue_QueueManagerName, 
                                   pExceptBlock, 
                                   &isEqual, 
                                   hQueueManagerName);
            if(MQERETURN_OK == rc && isEqual)    {
                // if the destination queue name is "OutboundQueue"
                rc = mqeString_newUtf8(pExceptBlock,
                                       &hCompareString, 
                                       "OutboundQueue");
                rc = mqeString_equalTo(pInput->hQueueName,
                                       pExceptBlock,
                                       &isEqual,
                                       hCompareString);
                if(MQERETURN_OK == rc && isEqual)    {
                    // password required for this queue
                    MQEBOOL contains = MQE_FALSE;
                    rc = mqeString_newUtf8(pExceptBlock,
                                           &hFieldName, 
                                           "Password");
                    rc = mqeFields_contains(pInput->hFilter, 
                                            pExceptBlock, 
                                            &contains, 
                                            hFieldName);
                    if(MQERETURN_OK == rc && contains == MQE_FALSE)     {
                        SET_EXCEPT_BLOCK(pExceptBlock,
                                         MQERETURN_RULES_DISALLOWED_BY_RULE,
                                         MQEREASON_NA);
                    }
                    else   {
                            // parse password, etc.
                    }
                }    
            }
        }     
    }    
}

This previous rule is a simple example of protecting a queue. However, for more comprehensive security, you are recommended to use an authenticator. An authenticator allows an application to create access control lists, and to determine who is able to get messages from queues.

Example remove queue rule

The next example rule is called when a queue manager administration request tries to remove a queue. The rule is passed an object reference to the proxy for the queue in question. In this example, the rule checks the name of the queue that is passed, and if the queue is named PayrollQueue, the request to remove the queue is refused.

Java codebase
/* 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" );
    }
}

C codebase
This rule is not implemented in the C codebase.


© IBM Corporation 2002. All Rights Reserved