Adobe ColdFusion 8

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

Attribute

Req/Opt

Default

Description

displayName

Optional

 

A value to be displayed when using introspection to show a descriptive name for the interface.

extends

Optional

 

A comma-delimited list of one or more interfaces that this interface extends. Any CFC that implements an interface must also implement all the functions in the interfaces specified by this property.

If an interface extends another interface, and the child interface specifies a function with the same name as one in the parent interface, both functions must have the same attributes; otherwise ColdFusion generates an error.

hint

Optional

 

Text to be displayed when using introspection to show information about the interface. The hint attribute value follows the syntax line in the function description.

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:

Attribute

Interface requirements

Implementation requirements

cffunction

access

Optional; only public is allowed

Optional; can be public or remote.

description

Optional

Can differ from value in interface.

displayName

Optional

Can differ from value in interface.

hint

Optional

Can differ from value in interface.

name

Required

Must be identical to value in interface.

output

Optional

Must be identical to value in interface.

If you omit this attribute in the interface, you must omit it in the implementation.

returnType

Optional

Must be identical to value in interface; however, an omitted type option and an option value of any are equivalent and ColdFusion treats them as a match.

roles

Not allowed

Can be any valid value.

cfargument

default

Optional

Must be identical to value in interface.

If you omit this attribute in the interface, you can specify any value in the implementation.

displayName

Optional

Can differ from value in interface

hint

Optional

Can differ from value in interface

name

Required

Must be identical to value in interface.

required

Optional

If the interface specifies yes, this attribute must also specify yes. If the interface specifies no or omits this attribute, you can specify no or omit the attribute.

type

Optional

Must be identical to value in interface; however, an omitted type option and an option value of any are equivalent and ColdFusion treats them as a match.

A CFC can implement multiple interfaces.

Note: If a CFC implements multiple interfaces and two or more of the interfaces define functions with identical names, the signatures of these functions must be the same in all the interfaces; ColdFusion does not support function overloading.

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. (We have omitted these versions 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" outpu = "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>