Extensions - CFX Tags
Register and manage CFX custom tags built in C++ or Java
Last updated: November 13, 20268 min read
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 interfacePerformanceRuns 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_ prefixExample
cfx_ImageResize, cfx_SendSMSNaming 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
Format
com.company.package.ClassNameExample
com.example.cfx.ImageProcessorClass Requirements:
- Must implement
com.allaire.cfx.CustomTaginterface - JAR file must be in ColdFusion classpath
- Place JAR in
{cf-home}/libor 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
Windows
C:\cfx\mytag.dllLinux/Unix
/opt/cfx/mytag.soImportant: 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
lddcommand - 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.)