ProtocolBridgePropertiesExit: Looking up protocol file server properties

If we have a large number of protocol file servers, we can implement the com.ibm.wmqfte.exitroutine.api.ProtocolBridgePropertiesExit interface to look up protocol file server properties that are referenced in transfers. We can implement this interface in preference to maintaining a ProtocolBridgeProperties.xml file. You are recommended to use the ProtocolBridgePropertiesExit2.java interface but the ProtocolBridgePropertiesExit.java interface is also supported. If we have an existing implementation of the ProtocolBridgePropertiesExit.java interface from IBM® WebSphere MQ File Transfer Edition, we can use it in IBM WebSphere MQ Version 7.5 or later. The new getCredentialLocation method in ProtocolBridgePropertiesExit2.java uses the default location of the ProtocolBridgeCredentials.xml file, which is your home directory.

Configure user exits that look up protocol bridge properties

Any user exit that looks up protocol bridge properties must implement the interface com.ibm.wmqfte.exitroutine.api.ProtocolBridgePropertiesExit. For more information, see ProtocolBridgePropertiesExit.java interface.

You can chain multiple protocol server properties exits together in a similar manner to other user exits. The exits are called in the order that they are specified in using the protocolBridgePropertiesExitClasses property in the agent properties file. The initialize methods all return separately and if one or more returns a value of false, the agent does not start. The error is reported in the agent event log.

Only one overall result is returned for the getProtocolServerProperties methods of all of the exits. If the method returns a properties object as the result code, this value is the returned result and the getProtocolServerProperties methods of the subsequent exits are not called. If the method returns a value of null as the result code, the getProtocolServerProperties method of the next exit is called. If there is no subsequent exit, the null result is returned. An overall result code of null is considered as a lookup failure by the protocol bridge agent.

1. Compile the protocol server properties user exit.
2. Create a Java archive (JAR) file containing the compiled exit and its package structure.
3. Put the JAR file containing the exit class in the exits directory of the protocol bridge agent . This directory is found in the MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name directory.
4. Edit the property file of the protocol bridge agent to include the property protocolBridgePropertiesExitClasses. For the value of this property, specify a comma-separated list of classes that implement a protocol bridge server properties user exit. The exit classes are called in the order that they are specified in this list. For more information, see The MFT agent.properties file.
5. We can optionally specify the protocolBridgePropertiesConfiguration property. The value you specify for this property is passed in as a String to the initialize() method of the exit classes specified by protocolBridgePropertiesExitClasses. For more information, see The MFT agent.properties file.

ProtocolBridgePropertiesExit.java interface

package com.ibm.wmqfte.exitroutine.api;

import java.util.Map;
import java.util.Properties;

/**
 * An interface that is implemented by classes that are to be invoked as part of
 * user exit routine processing. This interface defines methods that will be
 * invoked by a protocol bridge agent to look up properties for protocol servers
 * that are referenced in transfers.
 * <p>
 * There will be one instance of each implementation class for each protocol
 * bridge agent. The methods can be called from different threads so the methods
 * must be synchronised.
 */
public interface ProtocolBridgePropertiesExit {

	/**
	 * Invoked once when a protocol bridge agent is started. It is intended to
	 * initialize any resources that are required by the exit.
	 * 
	 * @param bridgeProperties
	 *            The values of properties defined for the protocol bridge.
	 *            These values can only be read, they cannot be updated by the
	 *            implementation.
	 * @return {@code true} if the initialization is successful and {@code
	 *         false} if unsuccessful. If {@code false} is returned from an exit
	 *         the protocol bridge agent will not start.
	 */
	public boolean initialize(final Map<String, String> bridgeProperties);

	/**
	 * Obtains a set of properties for the specified protocol server name.
	 * <p>
	 * The returned {@link Properties} must contain entries with key names
	 * corresponding to the constants defined in
	 * {@link ProtocolServerPropertyConstants} and in particular must include an
	 * entry for all appropriate constants described as required.
	 * 
	 * @param protocolServerName
	 *            The name of the protocol server whose properties are to be
	 *            returned. If a null or a blank value is specified, properties
	 *            for the default protocol server are to be returned.
	 * @return The {@link Properties} for the specified protocol server, or null
	 *         if the server cannot be found.
	 */
	public Properties getProtocolServerProperties(
			final String protocolServerName);

	/**
	 * Invoked once when a protocol bridge agent is shut down. It is intended to
	 * release any resources that were allocated by the exit.
	 * 
	 * @param bridgeProperties
	 *            The values of properties defined for the protocol bridge.
	 *            These values can only be read, they cannot be updated by the
	 *            implementation.
	 */
	public void shutdown(final Map<String, String> bridgeProperties);

}