Using Gateways

More often than note, ColdFusion developers will not be writing brand new gateway types (although they definitely can do so). The majority of the work required of ColdFusion developers is the ColdFusion integration piece. Going back to a previous examples, to send a JMS message a ColdFusion developer must write code to make that action occur. Similarly, if a directory watcher gateway detects that a file has been added to a directory it sends a message to ColdFusion code that a ColdFusion developer must write, code that will do something with that new file.

Initiators

Initiating an event gateway request in ColdFusion requires the use of a single function named SendGatewayMessage(). This function requires two parameters be passed to it, as listed in Table 37.1.

Table 37.1. SendGatewayMessage() Parameters

PARAMETER	DESCRIPTION
gateway	The id of a registered (and running) gateway instance.
data	A structure to be passed to the gateway instance, the contents of the structure being specific to gateway type being used.

The following example send text to be logged to an asynchronous CFML gateway named logger:

 <cfset props=StructNew()> <cfset prop.message="Text to be logged goes here"> <cfset SendGatewayMessage("logger", props)> 

Here a single field is being set in the passed structure, some gateway types may require far more information. For example, to send an IM message you'd need to specify the recipient name as well as the message to be sent. SendGatewayMessage() instructs the event gateway service to send a request to logger passing the props structure to it..

The request will thus be routed to a ColdFusion Component that may look like this:

 <cfcomponent> <cffunction name="onIncomingMessage"             output="no">     <cfargument name="CFEvent"                 type="struct"                 required="yes">       <cflog text="#CFEvent.Data.message#"           file="mylog.log"           type="info"           thread="yes"           date="yes"           time="yes"           application="yes">   </cffunction> </cfcomponent> 

The default name for the CFC entry-point method is onIncomingMessage. This method is invoked by the event gateway service in response to the SendGatewayMessage() function. The method accepts a single argument, a structure that will contain the fields listed in Table 37.2.

Table 37.2. CFEvent Fields

FIELD	DESCRIPTION
CFCMethod	CFC method to be invoked (usually onIncomingMessage).
CFCPath	Location of associated CFC file.
CFCTimeout	Timeout interval in seconds.
Data	A structure containing the event data.
GatewayID	The id of the gateway that sent the event or will handle the outbound event.
GatewayType	The gateway type.
OriginatorID	Originator ID identifying message sender.

NOTE

Not all gateway types populate all of these fields listed in Table 37.2

In the example above the CFC code uses just one CFEvent field, data, to obtain the text to be logged.

Responders

Gateway responders obviously do not rely on CFML code to invoke them. A gateway type that acts as a responder (like the directory watcher) sends a message to the event gateway service when an event occurs (directory content changes, for example).

This executes the same CFC method seen previously, passing the CFEvent structure defined in Table 37.2.

If a gateway needs to respond to multiple events, two options are available:

• Use a single CFC method (probably onIncomingMessage) and pass a flag in the CFEvent data field defining the event type. The CFC CFML code can then check this flag and respond to different event appropriately.

• Alternatively, a different CFC method could be defined for each event, in which case the configuration file must define the CFC method name to be invoked for each event. (Incidentally, this is how the directory watcher gateway works, executing a different CFC method for file added, file changed, and file deleted).