CFINVOKE |
Description
Does either of the following: Invokes a component method from within a ColdFusion page or component. Invokes a web service.
This tag works as follows: Transiently instantiates a component or web service and invokes a method on it Invokes a method on an instantiated component or web service
This tag can pass parameters to a method in the following ways: With the cfinvokeargument tag As named attribute-value pairs, one attribute per parameter As a structure, in the argumentCollection attribute
Category
Extensibility tags
Syntax
    <!--- Syntax 1 - this syntax invokes a method of a component. --->
    <cfinvoke
       component = "component name or reference"
       method = "method name"
       returnVariable = "variable name"
       argumentCollection = "argument collection"
       ...>
    OR
    <!--- Syntax 2 - this syntax can invoke a method of a component only
       from within the component. --->
    <cfinvoke
       method = "method name"
       returnVariable = "variable name"
       argumentCollection = "argument collection"
       ...
    >
    OR
    <!--- Syntax 3 - this syntax invokes a web service. --->
    <cfinvoke
       webservice = "URLtoWSDL_location"
       method = "operation_name"
       username = user name"
       password = "password"
       timeout = "request timeout in seconds"
       proxyServer = "WSDL proxy server URL
       proxyPort = "port on proxy server"
       proxyUser = "user id for proxy server"
       proxyPassword = "password for proxy server"
       inputParam1 = "value1"
       inputParam2 = "value2"
       ...
       returnVariable = "var_name"
       ...>
    OR
    <!--- Syntax 4A - this syntax invokes a component.
    This syntax shows instantiation with the cfobject tag.
    This cfinvoke syntax applies to instantiating a component
    with the cfobject tag and to instantiating a component
    with the createobject function. --->
    <cfobject
       component = "component name"
       name = "mystringname for instantiated object">
    <cfinvoke
       <!--- value is object name, within pound signs --->
       component = "#mystringname for instantiated component#"
       method = "method name"
       returnVariable = "variable name"
       argumentCollection = "argument collection"
       ...
    >
    OR
    <!--- Syntax 4B - this syntax invokes a web service.
    This syntax shows instantiation with the cfobject tag.
    This cfinvoke syntax applies to instantiating a web service
    with the cfobject tag and to instantiating a web service
    with the createobject function. --->
    <cfobject
       webservice = "web service name"
       name = "mystringname for instantiated object"
       method = "operation_name">
    <cfinvoke
       <!--- value is object name, within pound signs --->
       webservice = "#my stringname for instantiated web service#"
       timeout = "request timeout in seconds"
       proxyServer = "WSDL proxy server url
       proxyPort = "numeric port on proxy server"
       proxyUser = "string user id for proxy server"
       proxyPassword = "string user password for proxy server"
    >
See also
cfargument, cfcomponent, cffunction, cfinvokeargument, cfobject, cfproperty, cfreturn
History
ColdFusion MX 6.1: Added the following attributes: timeout, proxyServer, proxyPort, proxyUser, and proxyPassword.
ColdFusion MX: Added this tag.
Note: | If you do not specify any the proxy attributes, and a corresponding system property is set (typically in the JVM startup arguments) ColdFusion uses the system property value.
Usage The following table shows when you can use each attribute:
This attribute is required, optional,ignored, or invalid: | For this cfinvoke tag syntax:
--- | ---
Syntax 1 | Syntax 2 | Syntax 3 | Syntax 4A | Syntax 4B
component | Required | Optional | Invalid | Required | Invalid
method | Required | Required | Required | Required | Required
returnVariable | Optional | Optional | Optional | Optional | Optional
argumentCollection | Optional | Optional | Optional | Optional | Optional
username | Ignored | Ignored | Optional | Ignored | Optional
password | Ignored | Ignored | Optional | Ignored | Optional
webservice | Ignored | Ignored | Required | Ignored | Required
timeout | Invalid | Invalid | Optional | Invalid | Optional
proxyServer | Invalid | Invalid | Optional | Invalid | Optional
proxyPort | Invalid | Invalid | Optional | Invalid | Optional
proxyUser | Invalid | Invalid | Optional | Invalid | Optional
proxyPassword | Invalid | Invalid | Optional | Invalid | Optional
input_params ... | Optional | Optional | Optional | Optional | Optional
If the component attribute specifies a component name, the component with the corresponding name is instantiated, the requested method is invoked, and then the component instance is immediately destroyed. If the attribute contains a reference to an instantiated component object, no instantiation or destruction of the component occurs. On UNIX systems, ColdFusion searches first for a file with a name that matches the specified component name, but is all lower case. If it does not find the file, it looks for a file name that matches the component name exactly, with the identical character casing. Method arguments can be passed in any of the following ways. If an argument is passed in more than one way with the same name, this order of precedence applies: Using the cfinvokeargument tag Passing directly as attributes of the cfinvoke tag (they cannot have the same name as a registered cfinvoke attribute: method, component, webservice, returnVariable) Passing as struct keys, using the argumentCollection attribute For example, the params struct contains three keys: a=1, b=1, c=1. The following call is evaluated as if the arguments were passed to the method in the order a=3, b=2, c=1:
    <cfinvoke ... a=2 b=2 argumentCollection=params>
          <cfinvokeargument name="a" value="3">
       </cfinvoke>
Note: | The following cfinvoke tag attribute names are reserved; they cannot be used for argument names: component, method, argumentCollection, and result.
Example This example uses Syntax 1.
    <!--- immediate instantiation and destruction --->
    <cfinvoke
       component="nasdaq.quote"
       method="getLastTradePrice"
       returnVariable="res">
       <cfinvokeargument
          name="symbol"
          value="macr">
    </cfinvoke>
    <cfoutput>#res#</cfoutput>
Example This example uses Syntax 1.
    <!--- passing the arguments using argumentCollection --->
    <cfset args = StructNew()>
    <cfset args.symbol = "macr">
    <cfinvoke
       component="nasdaq.quote"
       method="getLastTradePrice"
       argumentCollection="#args#"
       returnVariable="res">
    <cfoutput>#res#</cfoutput>
Example This example uses Syntax 2.
    <!--- called only from within a component, MyComponent--->
    <cfinvoke
       method = "a method name of MyComponent"
       returnVariable = "variable name">
Example This example uses Syntax 3.
    <!--- using cfinvoke to consume a web service using a ColdFusion component --->
    <!--- put the following code in a ColdFusion page named wscfml.cfm:--->
    <cfinvoke
       webservice='http://www.xmethods.net/sd/2001/BabelFishService.wsdl'
       method='BabelFish'
       translationmode="en_es"
       sourcedata="Hello world, friend"
       returnVariable='foo'>
    <cfoutput>#foo#</cfoutput>
For more information on the BabelFish web service example, see Chapter 32, "Using Web Services," in Developing ColdFusion MX Applications.
Example This example uses Syntax 4A.
    <!--- separate instantiation and method invocation; useful for
       multiple invocations using different methods or values--->
    <cfobject
       name="quoteService"
       component="nasdaq.quote">
    <cfinvoke
       component="#quoteService#"
       method="getLastTradePrice"
       symbol="macr"
       returnVariable="res_macr">
    <cfoutput>#res#</cfoutput>
    <cfinvoke
       component="#quoteService#"
       method="getLastTradePrice"
       symbol="mot"
       returnVariable="res_mot">
    <cfoutput>#res#</cfoutput>

COMPONENT |
| See Usage section
String or component object; a reference to a component, or component to instantiate.

METHOD |
| See Usage section
Name of a method. For a web service, the name of an operation.

RETURNVARIABLE |
| Optional
Name of a variable for the invocation result.

ARGUMENTCOLLECTION |
| Optional
Name of a structure; associative array of arguments to pass to the method.

USERNAME |
| Optional
Overrides username specified in Administrator > Web Services.

PASSWORD |
| Optional
Overrides password specified in Administrator > Web Services.

WEBSERVICE |
| Required
The URL of the WSDL file for the web service.

TIMEOUT |
| Optional
The timeout for the web service request, in seconds

PROXYSERVER |
| Optional
Default value: "http.proxyHost system property, if any." The proxy server required to access the webservice URL.

PROXYPORT |
| Optional
Default value: "http.proxyPort system property, if any." The port to use on The proxy server.

PROXYUSER |
| Optional
Default value: "http.proxyUser system property, if any" The user ID to send to the proxy server.

PROXYPASSWORD |
| Optional
Default value: "http.proxyPassword system property, if any" The user's password on the proxy server.

INPUT_PARAMS... |
Input parameters. For each named input parameter specify paramName=paramValue.