Writing channel exits in Java for IBM MQ classes for JMS

You create channel exits by defining Java classes that implement specified interfaces.

Three interfaces are defined in the com.ibm.mq.exits package:

WMQSendExit, for a send exit
WMQReceiveExit, for a receive exit
WMQSecurityExit, for a security exit

The following sample code defines a class that implements all three interfaces:


public class MyMQExits implements 
WMQSendExit, WMQReceiveExit, WMQSecurityExit {
    // Default constructor
  public MyMQExits(){ 
  }
    // This method implements the send exit interface
  public ByteBuffer channelSendExit(
                                    MQCXP channelExitParms,
                                    MQCD channelDefinition,
                                    ByteBuffer agentBuffer)
  {
    // Complete the body of the send exit here
  }
    // This method implements the receive exit interface
  public ByteBuffer channelReceiveExit(
                                    MQCXP channelExitParms,
                                    MQCD channelDefinition,
                                    ByteBuffer agentBuffer)
  {
    // Complete the body of the receive exit here
  }
    // This method implements the security exit interface
  public ByteBuffer channelSecurityExit(
                                    MQCXP channelExitParms,
                                    MQCD channelDefinition,
                                    ByteBuffer agentBuffer)
  {
    // Complete the body of the security exit here
  }
}

Each exit receives as parameters an MQCXP object and an MQCD object. These objects represent the MQCXP and MQCD structures defined in the procedural interface.

When a send exit is called, the agentBuffer parameter contains the data that is about to be sent to the server queue manager. A length parameter is not required because the expression agentBuffer.limit() provides the length of the data. The send exit returns as its value the data to be sent to the server queue manager. However, if the send exit is not the last send exit in a sequence of send exits, the data returned is passed instead to the next send exit in the sequence. A send exit can return a modified version of the data that it receives in the agentBuffer parameter, or it can return the data unchanged. The simplest possible exit body is therefore:


{ return agentBuffer; }

When a receive exit is called, the agentBuffer parameter contains the data that has been received from the server queue manager. The receive exit returns as its value the data to be passed to the application by IBM® MQ classes for JMS. However, if the receive exit is not the last receive exit in a sequence of receive exits, the data returned is passed instead to the next receive exit in the sequence.

When a security exit is called, the agentBuffer parameter contains the data that has been received in a security flow from the security exit at the server end of the connection. The security exit returns as its value the data to be sent in a security flow to the server security exit.

Channel exits are called with a buffer that has a backing array. For best performance, the exit should return a buffer with a backing array.

Up to 32 characters of user data can be passed to a channel exit when it is called. The exit accesses the user data by calling the getExitData() method of the MQCXP object. Although the exit can change the user data by calling the setExitData() method, the user data is refreshed every time the exit is called. Any changes made to the user data are therefore lost. However, the exit can pass data from one call to the next by using the exit user area of the MQCXP object. The exit accesses the exit user area by reference by calling the getExitUserArea() method.

Every exit class must have a constructor. The constructor can be either the default constructor, as shown in the previous example, or a constructor with a string parameter. The constructor is called to create an instance of the exit class for each exit defined in the class. Therefore, in the previous example, an instance of the MyMQExits class is created for the send exit, another instance is created for the receive exit, and a third instance is created for the security exit. When a constructor with a string parameter is called, the parameter contains the same user data that is passed to the channel exit for which the instance is being created. If an exit class has both a default constructor and a single parameter constructor, the single parameter constructor takes precedence.

Do not close the connection from within a channel exit.

When data is sent to the server end of a connection, TLS encryption is performed after any channel exits are called. Similarly, when data is received from the server end of a connection, TLS decryption is performed before any channel exits are called.

In versions of IBM MQ classes for JMS earlier than IBM WebSphere® MQ 7.0, channel exits were implemented using the interfaces MQSendExit, MQReceiveExit, and MQSecurityExit. You can still use these interfaces, but the new interfaces are preferred for improved function and performance.