cfinterface

Description

Defines an interface that consists of a set of signatures for functions. The interface does not include the full function definitions; instead, you implement the functions in a ColdFusion component (CFC). The interfaces that you define by using this tag can make up the structure of a reusable application framework.

History

ColdFusion 8: Added this tag.

Category

Application framework tags, Extensibility tags

Syntax

<cfinterface 
    displayName = "descriptive name" 
    extends = "interfaceName1[,interfaceName2]..." 
    Hint = "hint text"> 
        <cffunction ...> 
            <cfargument ... > 
            <cfargument ... > 
            ... 
        </cffunction>  
        <cffunction ...> 
            ... 
        </cffunction>  
        ... 
</cfinterface>

See also

cfargument, cfcomponent, cffunction, GetComponentMetaData, IsInstanceOf

Attributes

Usage

The cfinterface tag declares a set of related functions that any ColdFusion component (CFC) that implements the interface must define. The interface specifies function signatures, but does not implement the functions; instead, the CFC that implements the interface must contain the full function definitions.

For example, you could create a create, read, update, and delete (CRUD) interface that defines the basic signatures of the four operations. All components that implement the interface must then conform to the interface signatures. You can then implement the interface in different components to manage different types of data sources. Because all the components implement the same interface, you can ensure that you can easily replace one component with another, depending on the specific data source that an individual application requires.

You define an interface by creating a ColdFusion file with a .cfc extension and specifying the cfinterface tag as the first and only top-level tag in the file. The filename determines the interface name, so myInterface.cfc defines the myInterface interface. You can specify any attributes in the cfinterface tag; however, only the names listed in the Attributes table are meaningful to ColdFusion. The filename must not contain commas, or any periods except for the separator before the .cfc extension.

Inside the cfinterface tag body, you specify the interface by declaring the functions of the interface. The interface definition must follow these basic rules:

• The cfinterface tag body can contain only cffunction tags and comments.

• The cffunction tag bodies can contain only cfargument tags, which declare the function arguments, and comments.

• The cffunction tag body is optional.

The following example shows the general format of an interface definition:

<cfinterface extends="IBasicInterface"> 
    <cffunction name="hello" description="Should print a greeting containing the input 
         argument or 'world'."> 
        <cfargument name="whom" type="string" default="world"> 
    </cffunction> 
    <cffunction name="calculateTwo" returnType="numeric" output="no" 
            description="calculates a result using two numbers and returns the result"> 
        <cfargument name="first" type="numeric" required="yes"/> 
        <cfargument name="second" type="numeric" required="no" default="0"/> 
    </cffunction> 
    <cffunction name="disclaimer"/> 
</cfinterface>

This interface extends the IBasicInterface interface, so any component that implements this interface must also implement the methods of the IBasicInterface interface. This interface requires the component to implement the following three functions:

• A hello function that can optionally take a single string argument, which has a default value of "world".

• A calculateTwo function that takes one required numeric argument, has an optional numeric argument with a default value of 0, and must return a number.

• A disclaimer function that takes no arguments and returns any type.

The CFC that implements an interface specifies the interface name in the cfcomponent tag’s implements attribute. It must implement all of the interface’s methods as specified in the interface cffunction tags. The order of function arguments in the interface definition and the component definition must be identical.

The following table lists the attributes that you can use in the cffunction and cfargument tags, and describes the requirements and limitations on how you can use them in the interface definition and the component implementation:

A CFC can implement multiple interfaces.

ColdFusion uses the same rules to locate interfaces as it does to locate components. You can use the GetComponentMetaData function to get information about an interface.

Adobe recommends that you use a consistent technique for identifying interface names, for example, by always starting the file (and therefore interface) name with a capital I. Any component that implements only that single interface could have a similar name, for example the same root prefixed by a capital C. You could have an IresourceInfo.cfc interface file and a corresponding CresourceInfo.cfc component file, for example.

Example

The following example defines an IBasicMath interface with add, subtract, multiply, and divide operations. The integerMath CFC implements this interface by defining integer arithmetic versions of the operations. The testMath.cfm application uses the integerMath functions to do arithmetic calculations on two decimal numbers (using the values of pi and e).

As an exercise, consider modifying the interface definition to take and return values of any type, and then implement a second CFC that uses the PrecisionEvaluate function to calculate arbitrary precision arithmetic and return the results. (These versions are omitted for brevity.)

The IBasicMath.cfc file defines the interface as follows:

<cfinterface> 
    <cffunction name = add returntype = "numeric" output = "no"  
            description = "Add two values"> 
        <cfargument name = "first" type="numeric" required = "no" default ="0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "0"> 
    </cffunction> 
    <cffunction name = subtract returntype = "numeric" output = "no"  
            description = "Subtract two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name ="second" type = "numeric" required = "no" default = "0"> 
    </cffunction> 
    <cffunction name = multiply returntype = "numeric" output = "no"  
            description = "Multiply two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "0"> 
    </cffunction> 
    <cffunction name = divide returntype = "numeric" output = "no"  
            description = "Divide two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default="0"> 
        <cfargument name = "second" type="numeric" required = "no" default="1"> 
    </cffunction> 
</cfinterface>

The integerMath.cfc file defines the integerMath component, which implements the IBasicMath interface, as follows:

<cfcomponent implements = "IBasicMath" > 
    <cffunction name = add returntype = "numeric" output = "no" 
            description = "Add two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "0"> 
        <cfreturn Round(first + second)> 
    </cffunction> 
    <cffunction name = subtract returntype = "numeric" output = "no" 
            description = "Subtract two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "0"> 
        <cfreturn Round(first - second)> 
    </cffunction> 
    <cffunction name = multiply returntype = "numeric" output = "no" 
            description = "Multiply two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "0"> 
        <cfreturn Round(first * second)> 
    </cffunction> 
    <cffunction name = divide returntype = "numeric" output = "no" 
description = "Divide two values"> 
        <cfargument name = "first" type = "numeric" required = "no" default = "0"> 
        <cfargument name = "second" type = "numeric" required = "no" default = "1"> 
        <cfreturn Round(first / second)> 
    </cffunction> 
</cfcomponent>

The testMath.cfm file uses the integerMath component methods to calculate integer values, as follows:

<cfscript> 
    arguments = StructNew(); 
    arguments.first = pi(); 
    arguments.second = "2.718281828459045235360287471352"; 
</cfscript> 
 
<cfobject name = "iMathObj" component = "integerMath"> 
<cfoutput> 
<h3>Function Arguments</h3> 
argument 1: #arguments.first#<br> 
argument 2: #arguments.second#<br> 
 
<h3>Addition</h3> 
#iMathObj.add(argumentCollection = arguments)# 
<h3>Subtraction</h3> 
#iMathObj.subtract(argumentCollection = arguments)# 
<h3>Multiplication</h3> 
#iMathObj.multiply(argumentCollection = arguments)# 
<h3>Division</h3> 
#iMathObj.divide(argumentCollection = arguments)# 
</cfoutput>