The ColdFusion event gateway services call the event gateway's outgoingMessage method to handle messages generated when an event gateway application listener CFC's listener method returns a message or any CFML code calls a SendGatewayMessage
function. This method must send the message to the appropriate external resource.
The outgoingMessage method's parameter is a CFEvent instance, containing the information about the message to send out. The CFEvent getData
method returns a Map object that contains event gateway-specific information about the message, including any message text. All CFEvent instances received by the outgoingMessage contain information in the Data and GatewayID fields.
CFEvent instances returned from listener CFC onIncomingMessage
methods include the incoming message's originator ID and other information. However, a gateway that might handle messages from the ColdFusion SendGatewayMessage
function cannot rely on this information being available, so it is good practice to require that all outgoing messages include the destination ID in the data Map.
The outgoingMessage
method returns a String value. The CFML sendGatewayMessage
function returns this value to the ColdFusion application. The returned string should indicate the status of the message. By convention, ColdFusion event gateway outgoingMessage
methods return "OK" if they do not encounter errors and do not have additional information (such as a message ID) to return.
Because event messages are asynchronous, a positive return normally does not indicate that the message was successful delivered, only that the outgoingMessage
method successfully handled the message. In some cases, however, it is possible to make the outgoingMessage
method at least partially synchronous. The SMS gateway, for example, provides two outgoingMessage
modes:
Asynchronous mode The outgoingMessage
method returns when the message is queued internally for delivery to the messaging provider's short message service center (SMSC)
Synchronous mode The method does not return until the message is delivered to the SMSC, or an error occurs.
This way, an SMS application can get a message ID for later use, such as to compare with a message receipt.
The following outgoingMessage method is similar to the version in the SocketGateway class. It does the following:
CFEvent class getData
method.
outDestID
field in the data Map.
public String outgoingMessage(coldfusion.eventgateway.CFEvent cfmsg) { String retcode="ok"; // Get the table of data returned from the event handler Map data = cfmsg.getData(); String message = (String) data.get("MESSAGE"); // Find the right socket to write to from the socketRegistry hashtable // and call the socket thread's writeoutput method. // (Get the destination ID from the data map.) if (data.get("outDestID") != null) ((SocketServerThread)socketRegistry.get(data.get("outDestID"))). writeOutput(message); else { System.out.println("cannot send outgoing message. OriginatorID is not available."); retcode="failed"; } return retcode; }