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"
   servicePort = "WSDL port name"
   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 number 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 number 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"
   servicePort = "WSDL port name"
   proxyPassword = "string user password for proxy server"
>

See also

cfargument, cfcomponent, cffunction, cfinvokeargument, cfobject, cfproperty, cfreturn

History

ColdFusion MX 7: Added the servicePort attribute.

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:




Required	Optional	Invalid	Required	Invalid
Required	Required	Required	Required	Required
Optional	Optional	Optional	Optional	Optional
Optional	Optional	Optional	Optional	Optional
Ignored	Ignored	Optional	Ignored	Optional
Ignored	Ignored	Optional	Ignored	Optional
Ignored	Ignored	Required	Ignored	Required
Invalid	Invalid	Optional	Invalid	Optional
Invalid	Invalid	Optional	Invalid	Optional
Invalid	Invalid	Optional	Invalid	Optional
Invalid	Invalid	Optional	Invalid	Optional
Invalid	Invalid	Optional	Invalid	Optional
Invalid	Invalid	Optional	Invalid	Optional
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.--->
<cfinvoke 
  webservice="http://www.xmethods.net/sd/2001/TemperatureService.wsdl"
  method="getTemp"
  returnvariable="aTemp">
    <cfinvokeargument name="zipcode" value="55987"/>
</cfinvoke>
<cfoutput>The temperature at zip code 55987 is #aTemp#</cfoutput>

For more information on web services, see Chapter 36, "Using Web Services" in ColdFusion MX Developer's Guide.

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.

String or component object; a reference to a component, or component to instantiate.

METHOD

	See Usage.

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.

INPUT_PARAMS ...



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

PROXYUSER

PROXYPASSWORD

SERVICEPORT

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.

SERVICEPORT

	Optional

Default value: "First port found in the WSDL" The port name for the web service. This value is case-sensitive and corresponds to the port element's name attribute under the service element. Specify this attribute if the web service contains multiple ports.