|
ColdFusion 9.0 Resources |
Event gateway elementsYou use the following the elements to create and configure a gateway: Note: The gateway interfaces and classes, except for
the GenericGateway class, are fully documented in Gateway
development interfaces and classes in the CFML Reference.
All interfaces and classes in this list, including the GenericGateway
class, are documented in less detail in the JavaDocs located in
the ColdFusion gateways\docs directory. The JavaDocs documentation
lacks examples and does not have the detailed usage information
that you find in the CFML Reference.
Gateway interfaceThe ColdFusion event gateway must implement the coldfusion.eventservice.Gateway interface. The following table lists the interface method signatures: Note: For detailed information on implementing each
method, see Building an event gateway. For reference pages for these methods,
see Gateway
interface in the CFML Reference.
GatewayServices classThe Gateway class uses the coldfusion.eventgateway.GatewayServices class to interact with the ColdFusion event gateway services. This class has the following methods:
CFEvent classThe Gateway class sends and receives CFEvent instances to communicate with the ColdFusion listener CFC or application. The Gateway notifies ColdFusion of a message by sending a CFEvent instance in a GatewayServices.addEvent method. Similarly, the Gateway receives a CFEvent instance when ColdFusion calls the gateway outgoingMessage method. The CFEvent class extends the java.util.Hashtable class and has the following methods to construct the instance and set and get its fields. (In CFML, you treat CFEvent instances as structures.)
GatewayHelper classColdFusion includes a coldfusion.eventgateway.GatewayHelper Java marker interface. You implement this interface to define a class that provides gateway-specific utility methods to the ColdFusion application or listener CFC. For example, an instant messaging event gateway could use a helper class to provide buddy list management methods to the application. The Gateway class must implement a getHelper method that returns the helper class or null (if the gateway does not need such a class). ColdFusion applications call the GetGatewayHelper CFML function, which calls gateway’s the getHelper method to get an instance of the helper class. The application can then call helper class methods using ColdFusion object dot notation. The following code defines the SocketHelper class, the gateway helper for the SocketGateway class. It has an empty constructor and two public methods: one returns the socket IDs; the other closes a specified socket. These classes let an application monitor and end session connections. public class SocketHelper implements GatewayHelper {
public SocketHelper() {
}
public coldfusion.runtime.Array getSocketIDs () {
coldfusion.runtime.Array a = new coldfusion.runtime.Array();
Enumeration e = socketRegistry.elements();
while (e.hasMoreElements()) {
a.add(((SocketServerThread)e.nextElement()).getName());
}
return a;
}
public boolean killSocket (String socketid) {
try
{
((SocketServerThread)socketRegistry.get(socketid)).socket.close();
((SocketServerThread)socketRegistry.get(socketid)).socket = null;
socketRegistry.remove(socketid);
return true;
}
catch (IOException e) {
return false;
}
}
}
Gateway configuration fileGateways can use a configuration file to specify information that does not change frequently. For example, the ColdFusion SMS event gateway configuration file contains values that include an IP address, port number, system ID, password, and so on. You can specify a configuration file path for each event gateway instance in the ColdFusion Administrator. ColdFusion passes the file path in the gateway constructor when it instantiates the event gateway. The configuration file format and content handling is up to you. It is the responsibility of the gateway class to parse the file contents and use it meaningfully. One good way to access and get configuration data is to use the java.util.Properties class. This class takes an ISO8859-1 formatted input stream with one property setting per line. Each property name must be separated from the value by an equal sign (=) or a colon (:), as the following example shows: ip-address=127.0.0.1 port=4445 The example SocketGateway event gateway uses this technique to get an optional port number from a configuration file. For an example of reading a properties file and using its data, see the code in Class constructor. Gateway development classesColdFusion provides two classes that you can use as building blocks to develop your event gateway classes. Each corresponds to a different development methodology:
The GenericGateway classColdFusion includes a coldfusion.eventgateway.GenericGateway abstract class that implements many of the methods of ColdFusion Gateway interface and provides some convenience methods for use in your gateway class. You can derive your gateway class from this class, which handles the basic mechanics of implementing a gateway, such as the getGatewayID and SetCFCListeners methods. Your derived class must implement at least the following methods:
Your derived gateway class also must implement the following:
The example JMS gateway is derived from the generic gateway class. The gateway class JavaDocs in the gateway\docs directory provide documentation for this class. (The CFML Reference does not document this class.) The EmptyGateway classThe gateway\src\examples\EmptyGateway.java file contains an event gateway template that you can use as a skeleton for creating your own event gateway. (The gateway directory is in the cf_root directory in the server configuration and the cf_root\WEB-INF-cfusion directory on J2EE configurations.) This file contains minimal versions of all methods in the coldfusion.eventgateway.Gateway interface. It defines a skeleton listener thread and initializes commonly used Gateway properties. The EmptyGateway source code includes comments that describe the additional information that you must provide to complete an event gateway class.  |
