Responding to a ColdFusion function or listener CFC

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.

Example outgoingMessage method

The following outgoingMessage method is similar to the version in the SocketGateway class. It does the following:

  1. Gets the contents of a MESSAGE field of the Data Map returned by the CFEvent class getData method.
  2. Gets the destination from an outDestID field in the data Map.
  3. Uses the destination's socket server thread to write the message.
    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;
    }
    

View comments in LiveDocs