Creating Your Own Custom Gateways

Although CFMX7 comes with a number of useful gateways, what happens when you want to connect to something that's not covered by one of the gateways provided? What if you want to connect to your MQ Series server, or SAP via the BAPI messaging interface? The answer is to create your own gateway. Writing CFMX7 gateways is a fairly straightforward task, but gateways are developed completely in Java and you'll need to have a solid understanding of Java to write your own event gateways.

The ColdFusion Event Gateway Architecture

Event gateways listen for events and pass them to ColdFusion for handling by an application's listener CFC. The gateway does this by implementing the ColdFusion.eventgateway.Gateway interface and by using the ColdFusion gatewayServices class.

Let's take a more detailed look at the overall architecture of the ColdFusion Gateway. In Figure 31.4 you can follow the path of a simple event through the system. Consider an incoming Instant Messaging event. The event gateway has a listener thread that will receive the message and call the Gateway Services addEvent method to send ColdFusion a CFEvent HashMap, which will be converted into a ColdFusion structure.

Figure 31.4. This figure shows the flow of a Event through a Gateway application.

Now let's say your ColdFusion event application sends an event pack to the same IM source from a CFC. The event from the CFC would be passed to the ColdFusion event gateway via the event gateway's outgoingMessage method, which creates a CFEvent object with the appropriate destination and payload information.

The following sections introduce each of the major elements in constructing an event gateway.

Event Gateway Elements

There are six basic elements that are used to create and configure a ColdFusion Gateway: the Gateway interface, the GatewayServices class, the CFEvent class, the GatewayHelper class, the Gateway configuration class, and the Gateway development tools.

NOTE

The classes for the ColdFusion Gateway are in the cfusion.jar. Make sure when you compile your Java event gateways that you add the cfusion.jar to your classpath as well as any other .jar files you plan to use. The cfusion.jar file can usually be found in the C:\CFusionMX7\lib directory.

Gateway Interface

All ColdFusion event gateways have to implement the ColdFusion.eventservice.Gateway interface. Table 31.3 gives a list of the Gateway interfaces methods. You can also find this information in a handy Javadoc at cf_root/gateway/docs/api/index.html.

Table 31.3. Methods of the ColdFusion Gateway Interface

DATA TYPE	METHOD	DESCRIPTION
void	setGatewayID(String id)	Sets the ID that uniquely defines the gateway instance.
void	setCFCListeners(String[]listeners)	Sets an array of CFC listeners.
GatewayHelper	getHelper()	Returns a gateway helper class (if there is one) so that athis.status = STOPPING; CFC can invoke gateway-specific functions that might be useful to the CFML developer.
String	getGatewayID()	Returns the gateway ID.
int	getStatus()	Gets the event gateway status, which can be either STARTING, RUNNING, STOPPING, STOPPED, FAILED.
void	start()	Starts the event gateway. ColdFusion calls this method on startup.
void	stop()	This method stops the event gateway and kills any threads and cleans up any resources it was using.
void	restart()	Restarts a running event gateway.
String	outgoingMessage (CFEvent cfmesg)	Sends a message from the gateway to a resource.

Gateway Services Class

To interact with the ColdFusion event gateway services, you used the Gateway class ColdFusion.eventgateway.GatewayServices. Table 31.4 lists the methods that the GatewayServices class implements. Like the Gateway interface, GatewayServices is summarized in the gateway Javadoc.

Table 31.4. Methods of the GatewayServices Class

DATA TYPE	METHOD	DESCRIPTION
GatewayServices	getGatewayServices()	Returns a GatewayServices object.
int	getQueueSize()	Returns the current size of the gateway event queue.
int	getMaxQueueSize()	Returns the maximum size of the gateway event queue.
Logger	getLogger()	Gets the default event logging object.
Logger	getLogger(String logfile)	Gets a custom event logging object
boolean	addEvent(CFEvent msg)	Adds an event to the ColdFusion event service processing queue for delivery to a listener CFC.

CFEvent Class

As you have seen earlier in the chapter, the CFEvent object is the container for the message passed to CFCs from gateways. Your gateway does this by using the GatewayServices.addEvent method to send an instance of the CFEvent object. Gateways receive CFEvents when ColdFusion calls a gateway's outgoingMessage method.

The CFEvent class uses java.util.Hashtable to create a HashMap that models your message. That HashMap converts the contents into case-insensitive information for consumption by ColdFusion (which is caseless). Table 31.5 relates the methods for the CFEvent class.

Table 31.5. Methods of the CFEvent Class

DATA TYPE	METHOD	DESCRIPTION
CFEvent	String gatewayID)	CFEvent constructor that expects a string, which is the gatewayID.
void	setGatewayType(String type)	Sets the type of event gateway, such as IM, SMS, or EMail.
void	setData(Map data)	Adds the gateway-specific data, including any message contents, as a Java Map to the CFEvent object.
void	setOriginatorID(String id)	Sets the originator of an incoming message.
void	setCFCPath(String path)	Specifies the listener CFC that will process this event.
voids	setCFCMethod(String method)	Sets the name of the CFC method that should process an incoming message.
void	setCFCTimeout(String seconds)	Sets the timeout, in seconds, during which the listener CFC must process the event request before ColdFusion gateway services terminates the request and logs an error in the application.log file.
String	getGatewayType()	Identifies the type of the gateway from which this message originated.
Map	getdata()	Gets the message contents and other gateway-specific information.
String	getOriginatorID()	Identifies the originator of an incoming message.
String	getCFCPath()	Gets the path to the listener CFC that processes this message.
String	getCFCMethod()	Gets the name of the CFC method that processes the message.
String	getGatewayID()	Identifies the event gateway instance, as specified in the ColdFusion Administrator.

Gateway Helper Class

The GatewayHelper class provides an interface (Marker class) that can be used to mark a helper class that can be returned by a gateway. ColdFusion developers creating CFCs can use the functions Gateway.getHelper() and getGatewayHelper to invoke gateway-specific utility functions such as retrieving an IM phone book.

This class is returned by the CFML function getGatewayCFCHelper(gatewayID). CFCs cannot get a direct reference to the Gateway object in order to protect the gateway's key operations, such as start, stop, and restart. Look in cf_root\gateway\src\examples\socket\SocketGatewat.java to see an example of how to implement a GatewayHelper.

Gateway Configuration Files

Depending on what your gateway will do, creating a configuration file can be very useful. The example in Listing 31.4, which we'll examine shortly, connects to a POP3 server to see if there are new messages on the mail server. Instead of hard-coding the hostname, login, and password for the mail account, we'll use a configuration file to store this information. To do this, you'll want to use the java.util.Properties to create a properties file using name=value pairs.

NOTE

The Sun Javadoc for the Properties class can be found here: http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html.

Gateway Development Tools

ColdFusion ships with several useful tools to help you in developing your ColdFusion custom gateways. The first of these is a generic abstract gateway class from which you can derive your gateway class.

Another useful tool is the EmptyGateway class found in cf_root\gateway\src\examples\EmptyGateway.java. You can use this Java class as a template for building your own custom classes. Before reading the next section on the POP3 Custom Gateway, it's recommended that you review this class, as well as compare it to some of the example classes provided in the examples directory which can be usually found in your cf_root\gateway\src\examples.

If you are an Apache ANT user, look into the build.xml file found at cf_root\gateway\src\ build.xml. This useful tool lets you build all the examples in the examples directory and contains the paths to all the .jar files needed by these examples. If you are an Eclipse user, right-click gateway/src/build.xml and Run to compile the examples.

All the CFCs to create gateway instances to deploy and test the examples are found in cf_root\ gateway\cfc. Also, the configuration file for any of the examples can be found in cf_root\gateway\config. You can use these configuration files as samples for making your own. The ColdFusion MX 7 documentation has even more comprehensive information on the gateway classes and tools available to you.