Extensions - CFX Tags

Register and manage CFX custom tags built in C++ or Java

Overview

CFX (ColdFusion Extension) tags allow you to extend ColdFusion functionality by writing custom tags in C++ or Java. These tags integrate directly with the ColdFusion runtime and can perform operations that require access to native system resources, third-party libraries, or performance-critical processing that benefits from compiled code.

Modern Alternatives: Before implementing CFX tags, consider modern alternatives like Java integration via this.javaSettings in Application.cfc with createObject("java", ...), native CFML components, or REST API integration. These alternatives are usually simpler to build and maintain.

CFX Tag Types

ColdFusion supports two types of CFX tags with different implementation approaches.

Java CFX Tags

PurposeCustom tags implemented as Java classes
ImplementationJava class implementing com.allaire.cfx.CustomTag interface
PerformanceRuns in the same JVM as ColdFusion, good performance
RecommendationPreferred over C++ CFX for easier development and deployment
Advantages:
  • Platform-independent (works on Windows, Linux, macOS)
  • No compilation needed for deployment
  • Access to all Java libraries and APIs
  • Easier to debug and maintain
  • No separate process management

C++ CFX Tags

PurposeCustom tags implemented as native C++ libraries (DLL/SO)
ImplementationC++ code using ColdFusion CFX API, compiled to native library
PerformancePotentially faster for CPU-intensive operations
RecommendationUse only when Java CFX is insufficient
Limitations: Platform-dependent, requires compilation for each OS, harder to debug, potential stability issues if code crashes. C++ CFX tags are largely obsolete in modern ColdFusion development.

Registering CFX Tags

Configure CFX tags in the ColdFusion Administrator to make them available to your applications.

Tag Name

PurposeName used to invoke the tag in CFML code
FormatMust start with cfx_ prefix
Examplecfx_ImageResize, cfx_SendSMS
Naming Convention: Use descriptive names that indicate the tag's purpose. Case is preserved but tags are case-insensitive when invoked.

Tag Type

OptionsJava or C++
ImpactDetermines how ColdFusion loads and executes the tag

Java Class Path (Java CFX)

PurposeFully qualified Java class name implementing the CFX tag
Formatcom.company.package.ClassName
Examplecom.example.cfx.ImageProcessor
Class Requirements:
  • Must implement com.allaire.cfx.CustomTag interface
  • JAR file must be in ColdFusion classpath
  • Place JAR in {cf-home}/lib or add to Java classpath
  • Restart ColdFusion after changing the ColdFusion Class Path on the Java and JVM page

Library Path (C++ CFX)

PurposeFull path to the compiled library file
WindowsC:\cfx\mytag.dll
Linux/Unix/opt/cfx/mytag.so
Important: The library must be compiled for the specific operating system and architecture running ColdFusion. 64-bit ColdFusion requires 64-bit libraries.

Procedure (C++ CFX)

PurposeName of the exported function in the C++ library
DefaultPre-filled by the Administrator; Adobe's registration steps say to accept it
Note: The procedure name must match the procedure in your DLL or shared object, and it is case sensitive. Calling a nonexistent C++ CFX procedure or entry point causes a JVM crash on UNIX.

Keep Library Loaded

PurposeKeep C++ library in memory between calls
RecommendationClear it while developing the tag; select it for production use to keep the DLL in memory and improve performance
Trade-off: Keeping the library loaded improves performance but increases memory usage. Enable for production tags that are called frequently.

Description

PurposeDocumentation describing the tag's functionality
RecommendationInclude purpose, required attributes, and usage notes

Using CFX Tags

Once registered, CFX tags can be invoked like any other ColdFusion tag:

Using CFX Tags in CFML
<!--- Call a Java CFX tag --->
<cfx_ImageResize
  source="/images/photo.jpg"
  destination="/images/photo_thumb.jpg"
  width="200"
  height="150">

<!--- Call with return values --->
<cfx_ProcessData
  inputData="#myData#"
  outputVar="result">

<cfoutput>#result#</cfoutput>
<!--- Wrap CFX tag calls in error handling --->
<cftry>
  <cfx_ImageResize
    source="#filePath#"
    destination="#thumbnailPath#"
    width="200"
    height="150">

  <cfcatch type="any">
    <cflog
      file="cfx-errors"
      type="error"
      text="CFX tag error: #cfcatch.message#">

    <!--- Fallback behavior --->
    <cfset useDefaultImage()>
  </cfcatch>
</cftry>

Development Guidelines

Java CFX Development

Best Practices:
  • Thread Safety: ColdFusion creates a new instance for each invocation, so instance members are safe for per-request data; any static members shared across instances must be accessed in a thread-safe way
  • Error Handling: Throw clear exceptions with helpful error messages
  • Validation: Validate all required attributes and provide defaults
  • Documentation: Document all attributes, return values, and usage examples
  • Testing: Test thoroughly with various input combinations
  • Logging: Use ColdFusion logging for debugging and error tracking

Security Considerations

Security:
  • Input Validation: Always validate and sanitize user input
  • File System Access: Restrict file operations to allowed directories
  • Native Code: CFX tags run compiled Java or C++ code, so review them as carefully as any server-side library
  • Resource Limits: Implement timeouts and resource limits
  • Privilege Management: Run with minimum required privileges

Common Issues & Solutions

CFX Tag Not Found

Symptom: Error message "CFX tag is not registered" when calling the tag
Solutions:
  • Verify tag is registered in ColdFusion Administrator
  • Check tag name includes cfx_ prefix
  • Verify case-sensitive class name matches exactly
  • For Java CFX: Ensure the class is reachable from the Class Path setting on the Java and JVM page, and restart ColdFusion after changing that page (Adobe: Java and JVM page)
  • For C++ CFX: Verify library path is correct and file exists

ClassNotFoundException (Java CFX)

Symptom: Java ClassNotFoundException when invoking the tag
Solutions:
  • Verify JAR file is in ColdFusion classpath ({cf-home}/lib)
  • Check fully qualified class name is correct
  • Ensure JAR contains the specified class (verify with jar tf)
  • Check for package name mismatches

Library Load Failed (C++ CFX)

Symptom: Unable to load C++ library, error loading DLL/SO file
Solutions:
  • Verify library is compiled for correct platform (Windows/Linux) and architecture (32/64-bit)
  • Check file permissions (library must be readable by ColdFusion process)
  • Ensure all dependent libraries are available
  • On Linux: Check library dependencies with ldd command
  • Verify library exports required functions

CFX Tag Execution Errors

Symptom: Tag registered but fails during execution with runtime errors
Solutions:
  • Check ColdFusion logs for detailed error messages
  • Verify all required attributes are provided
  • Test tag with minimal inputs to isolate issue
  • Add logging to tag implementation for debugging
  • Check for thread safety issues if errors are intermittent
  • Verify tag has access to required resources (files, network, etc.)

Related Resources

Extensions - CFX Tags | ColdFusion Administrator | CFGuide