|
ColdFusion 9.0 Resources |
Using the example event gateways and gateway applicationsColdFusion provides several example event gateways and applications in the cf_root\WEB-INF\cfusion\gateway directory on J2EE configurations or the cf_root\gateway directory on server configurations. These gateways provide example code that you can examine or use in developing your gateways. They are intended as examples only, and are not complete, product-quality, implementations. Example event gatewaysThe gateway\src\examples directory and its subdirectories include the sources for the example event gateways. Compiled versions are located in the gateway\lib\examples.jar file. This document briefly describes the event gateways and their functions. For more detailed information, see the code and comments in the files. EmptyGatewayThe EmptyGateway.java file contains an event gateway template that you can use as a skeleton for creating your own event gateway. For more information on this class, and on creating new event gateways, see Creating Custom Event Gateways SocketGatewayThe SocketGateway event gateway listens on a TCP/IP port. Therefore, you can use this gateway for applications that send and respond to messages using TCP/IP-based protocols such as Telnet, or for applications that send messages between sockets. For example, a simple gateway application that responds to messages from a Telnet terminal client without supporting the full Telnet protocol. Note: The ColdFusion Administrator
uses Socket as the gateway type name for the SocketGateway class.
The SocketGateway.java file defines two classes: SocketGateway, the event gateway, and SocketHelper, a GatewayHelper class. The Source file is located in the gateway\src\examples\socket directory.
DirectoryWatcherGatewayThe DirectoryWatcherGateway event gateway sends events to the listener CFC when a file is created, deleted, or modified in a directory. The watcher runs in a thread that sleeps for an interval specified in the configuration file, and when the interval has passed, checks for changes since the last time it was awake. If it finds added, deleted, or changed files, it sends a message to a listener CFC. You can configure separate CFCs for add, delete, and change events, or use a single CFC for all events. The source for this event gateway is located in the gateway/src/examples/watcher directory. Note: The ColdFusion Administrator uses
DirectoryWatcher as the gateway type name for the DirectoryWatcherGateway
class.
Configuration fileThis event gateway requires a configuration file, consisting of lines in the following format: directory=C:/temp Note: If you use backward slash characters (\) as directory
separators in Windows the file paths, escape them by using double
slashes, as in C:\\temp. You can use forward slashes (/) as the
directory separator on all operating systems, including Windows.
Note: When you specify filename extensions in the Directory
Watcher configuration file, do not include the period, instead use
a comma, for example, doc,txt.
The configuration file can have comment lines, preceded by a number sign (#). If you omit a property or comment it out, ColdFusion uses the default value. If you specify a property with no value, ColdFusion sets an empty property. The configuration file can define the following values:
An example configuration file is located in the gateway\config\directory-watcher.cfg file. CFC methodsWhen the directory contents change, the event gateway calls one of the following CFC listener methods, unless you change the names in the configuration file:
The CFEvent.Data field sent to the listener methods includes the following fields:
The event gateway supports multiple listener CFCs and sends the event messages to all listeners. The event gateway is one way; it watches for events and dispatches event information to a CFC, but it does not accept return values from the CFC or input from SendGatewayMessage functions. The directory watcher logs errors to the watcher.log file in the ColdFusion logs directory. Example DirectoryWatcher applicationThe following code shows a simple directory watcher application. It enters a line in a log file each time a file is added, deleted, or changed in the directory specified in the configuration file. ColdFusion includes the date and time that a log entry is made. However, if the directory watcher monitors changes infrequently, for example once every minute or more, the time in the log entry could differ from the time a file was added or changed, so the information includes the time (but not date) for these actions. <cfcomponent>
<cffunction name="onAdd" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfset data=CFEvent.data>
<cflog file="MydirWatcher" application="No"
text="ACTION: #data.type#;FILE: #data.filename#;
TIME: #timeFormat(data.lastmodified)#">
</cffunction>
<cffunction name="onDelete" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfset data=CFEvent.data>
<cflog file="MydirWatcher" application="No"
text=" ACTION: #data.type#;FILE: #data.filename#">
</cffunction>
<cffunction name="onChange" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfset data=CFEvent.data>
<cflog file="MydirWatcher" application="No"
text=" ACTION: #data.type#;FILE: #data.filename#;
TIME: #timeFormat(data.lastmodified)#">
</cffunction>
</cfcomponent>
JMSGatewayThe JMSGateway class acts as a Java Messaging Service consumer or producer. The source for this event gateway is located in gateway/src/examples/JMS. The gateway requires a configuration file, which is in gateway/config/jmsgateway.cfg. For full documentation of the configuration options, See the configuration file. The ColdFusion Administrator lists the compiled gateway (which is included in the gateway\lib\examples.jar file) on the Gateway Types page. Note: The ColdFusion Administrator uses JMS as the gateway
type name for the JMSGateway class.
Using the JMS Gateway as a consumerThe JMSGateway class creates a subscriber to the topic specified in the configuration file. The gateway consumes the following types of messages:
The gateway passes the contents of the message to the configured CFC in the event structure, as follows:
The listener CFC method must be named onIncomingMessage. If the CFC method does not send a message in response, it should return a structure containing a status field with a value of OK or EXCEPTION. (In this case, The gateway checks the return status field, but does not process these return values further.) To send a message, the CFC method must return a structure as documented in the following section. Using the JMS Gateway as a producerTo send a JMS message, the return value of your CFC method or the second, messageStruct, parameter to the SendGatewayMessage function must be a structure with the following fields:
If you send the message in a SendGatewayMessage function, the function returns OK if the gateway sends the message, or EXCEPTION if it fails to send the message. Menu example applicationColdFusion is installed with a menu-based responder application. The menu application is written to work with any of the standard ColdFusion event gateways (SMS, XMPP, and Sametime) and with the Socket example event gateway, and ColdFusion is preconfigured with an instance of the application that uses SMS, as follows:
The application presents users with a drill-down menu of tools that they can use, including a weather report, stock information, status and configuration information, and language tools such as a dictionary. The code for this application is relatively complex and is distributed among 13 files. The following brief description provides an overview of how it works. To get a full understanding of how the application works, see the source code.
Use the menu application with the Socket event gateway
 |
