Event Gateways - Gateway Types

Configure gateway types and drivers for event processing

Overview

Gateway types define the underlying drivers and Java classes that implement specific event gateway protocols. Each gateway type represents a communication protocol or integration pattern (SMS, XMPP, directory monitoring, etc.) and provides the foundation for creating gateway instances.

ColdFusion includes several built-in gateway types, and you can add custom gateway types by developing Java classes that implement the ColdFusion Gateway API interfaces.

Gateway Type Configuration

Essential settings for configuring gateway types.

Gateway Type Name

PurposeUnique identifier for the gateway type
RequirementsMust be unique across all gateway types
ExamplesSMS, XMPP, DirectoryWatcher, CustomQueue
Note: Gateway type names are case-sensitive and should follow naming conventions that clearly indicate their purpose.

Java Class

PurposeFully qualified Java class name that implements the gateway
Built-in ClassesProvided by ColdFusion in cf_root/lib/
Custom ClassesMust be in ColdFusion classpath or cf_root/lib/
Required Interfacescoldfusion.eventgateway.Gateway
coldfusion.eventgateway.GatewayServices (provided by runtime)
Development: Custom gateway classes must implement the Gateway interface and handle lifecycle methods (start, stop, outgoingMessage). Refer to ColdFusion documentation for Java API details.

Startup Timeout (seconds)

PurposeMaximum time allowed for gateway to start before timing out
Default30 seconds
RecommendationIncrease for gateways that need time to establish connections
Warning: If a gateway consistently times out during startup, investigate connection issues or increase the timeout. Very high timeouts can delay ColdFusion startup.

Stop on Startup Error

PurposeControls whether gateway instances continue running if startup fails
OptionsYes: Stop gateway if startup fails
No: Keep trying to start
RecommendationYes for production to prevent resource consumption by failed gateways

Description

PurposeHuman-readable description of the gateway type's purpose
RecommendationInclude protocol, use cases, and any special requirements
Best Practice: Write clear descriptions that help other administrators understand when to use this gateway type and what it does.

Built-in Gateway Types

ColdFusion provides several pre-configured gateway types for common integration scenarios.

SMS

Java Class
coldfusion.eventgateway.sms.SMSGateway
Protocol
Short Message Peer-to-Peer (SMPP)
Use Cases
SMS notifications, two-factor auth, mobile alerts

Bidirectional SMS messaging through SMPP-compatible SMS providers.

XMPP

Java Class
coldfusion.eventgateway.xmpp.XMPPGateway
Protocol
Extensible Messaging and Presence Protocol
Use Cases
Instant messaging, chat bots, presence detection

Jabber/XMPP instant messaging integration for real-time communication.

DirectoryWatcher

Java Class
coldfusion.eventgateway.file.DirectoryWatcherGateway
Monitoring
File system changes (add, modify, delete)
Use Cases
File import automation, batch processing

Monitors directories for file changes and triggers CFC processing.

DataManagement

Java Class
coldfusion.eventgateway.flex.FlexGateway
Protocol
BlazeDS data synchronization
Status
Legacy (Flash EOL December 2020)

Provided data services for Adobe Flex applications. No longer recommended.

FMS

Java Class
coldfusion.eventgateway.fms.FMSGateway
Protocol
Flash Media Server
Status
Legacy (Flash EOL December 2020)

Integration with Flash Media Server. No longer recommended for new development.

DataServicesMessaging

Java Class
coldfusion.eventgateway.messaging.MessagingGateway
Protocol
BlazeDS messaging
Status
Legacy (Flash EOL December 2020)

BlazeDS messaging services for Flex applications. Legacy technology.

Creating Custom Gateway Types

You can extend ColdFusion's event gateway capabilities by developing custom gateway types in Java.

Custom Gateway Requirements

ProgrammingJava development knowledge required
InterfacesMust implement coldfusion.eventgateway.Gateway
Required Methodsstart(), stop(), outgoingMessage()
DeploymentJAR file in cf_root/lib/ or added to classpath
Development Process:
  • Create Java class implementing Gateway interface
  • Compile and package as JAR file
  • Deploy JAR to ColdFusion lib directory
  • Restart ColdFusion server
  • Add gateway type in Administrator
  • Create gateway instances

Custom Gateway Java Interface

Basic structure of a custom gateway implementation:

Custom Gateway Implementation
package com.example.gateway;

import coldfusion.eventgateway.*;
import java.util.Map;

/**
 * Custom event gateway for processing webhook events
 */
public class WebhookGateway implements Gateway {

  private String gatewayID;
  private GatewayServices gatewayServices;
  private int listenPort = 8080;
  private WebhookServer server;

  /**
   * Initialize the gateway
   */
  public void setGatewayID(String id) {
    this.gatewayID = id;
  }

  /**
   * Receive gateway services from ColdFusion
   */
  public void setGatewayServices(GatewayServices services) {
    this.gatewayServices = services;
  }

  /**
   * Start the gateway
   */
  public void start() throws GatewayException {
    try {
      // Read configuration
      Map config = gatewayServices.getGatewayConfiguration(gatewayID);
      if (config.containsKey("port")) {
        listenPort = Integer.parseInt((String)config.get("port"));
      }

      // Start webhook server
      server = new WebhookServer(listenPort);
      server.setMessageHandler(new MessageHandler() {
        public void handleMessage(String payload) {
          processIncomingWebhook(payload);
        }
      });

      server.start();

      gatewayServices.info(gatewayID,
        "Webhook gateway started on port " + listenPort);

    } catch (Exception e) {
      throw new GatewayException("Failed to start gateway: " + e.getMessage());
    }
  }

  /**
   * Stop the gateway
   */
  public void stop() throws GatewayException {
    try {
      if (server != null) {
        server.stop();
      }
      gatewayServices.info(gatewayID, "Webhook gateway stopped");
    } catch (Exception e) {
      throw new GatewayException("Failed to stop gateway: " + e.getMessage());
    }
  }

  /**
   * Handle outgoing messages from ColdFusion
   */
  public String outgoingMessage(CFEvent event) {
    Map data = event.getData();

    // Process outgoing webhook
    String url = (String)data.get("url");
    String payload = (String)data.get("payload");

    try {
      // Send HTTP request
      sendWebhook(url, payload);
      return "success";
    } catch (Exception e) {
      gatewayServices.error(gatewayID,
        "Error sending webhook: " + e.getMessage());
      return "error: " + e.getMessage();
    }
  }

  /**
   * Process incoming webhook
   */
  private void processIncomingWebhook(String payload) {
    // Create event data
    Map<String, String> data = new HashMap<>();
    data.put("payload", payload);
    data.put("timestamp", String.valueOf(System.currentTimeMillis()));

    // Create CF event
    CFEvent event = new CFEvent(gatewayID);
    event.setData(data);

    // Route to CFC
    boolean success = gatewayServices.addEvent(event);

    if (!success) {
      gatewayServices.warning(gatewayID,
        "Failed to route webhook event to CFC");
    }
  }

  /**
   * Send outgoing webhook
   */
  private void sendWebhook(String url, String payload)
      throws Exception {
    // HTTP client implementation
    // ... webhook sending logic ...
  }
}
# webhook.cfg - Gateway configuration file

# HTTP server port
port=8080

# Timeout for outgoing webhooks (milliseconds)
timeout=30000

# Retry attempts for failed webhooks
retryAttempts=3

# Security token for incoming webhooks
securityToken=your-secret-token-here

# Enable SSL/TLS
useSSL=false

# SSL certificate path (if useSSL=true)
# sslCertPath=/path/to/certificate.jks

# SSL certificate password
# sslCertPassword=password
Key Implementation Points:
  • start(): Initialize connections, start listeners, read configuration
  • stop(): Clean shutdown, close connections, release resources
  • outgoingMessage(): Handle messages sent from ColdFusion CFCs
  • addEvent(): Route incoming events to ColdFusion CFCs
  • Logging: Use GatewayServices for logging (info, warning, error)

Gateway Type Management

Adding Gateway Types

Steps1. Deploy Java classes to classpath
2. Add gateway type in Administrator
3. Configure type settings
4. Create gateway instances
Important: ColdFusion must be restarted after adding new JAR files to the lib directory before they can be used in gateway types.

Editing Gateway Types

ImpactChanges affect all instances using this type
Restart RequiredGateway instances must be restarted to use new settings
Best Practice: Test gateway type changes in development before modifying production configurations.

Deleting Gateway Types

PrerequisitesAll gateway instances using this type must be deleted first
Warning: Cannot delete gateway types that have active instances. Stop and delete all instances before removing the type.

Common Issues & Solutions

Gateway Type Class Not Found

Symptom: ClassNotFoundException when adding gateway type or starting instances
Solutions:
  • Verify JAR file is in cf_root/lib/ directory
  • Check that fully qualified class name is correct
  • Ensure ColdFusion was restarted after adding JAR
  • Verify JAR file is not corrupted (test with jar -tf command)
  • Check that class implements required Gateway interface

Gateway Type Already Exists

Symptom: Error when trying to add a gateway type with existing name
Solutions:
  • Choose a different, unique name for the gateway type
  • Edit the existing gateway type instead of creating new one
  • Delete old gateway type if no longer needed (remove instances first)

Custom Gateway Not Working

Symptom: Custom gateway instances fail to start or don't process events
Solutions:
  • Review coldfusion-event.log for Java exceptions
  • Verify all required Gateway interface methods are implemented
  • Check that start() method completes without throwing exceptions
  • Ensure configuration file is properly formatted and accessible
  • Add logging in Java code to debug initialization
  • Test gateway class standalone before integrating with ColdFusion

Related Resources