Using Positional URL Arguments When Invoking A ColdFusion Web Service

Posted April 21, 2011 at 10:01 AM by Ben Nadel

Tags: ColdFusion

A couple of months ago, I was super excited to find out that you could use an ArgumentCollection URL parameter when invoking a ColdFusion web service. Yesterday, I took that excitement up a notch when I discovered that this same approach to ColdFusion web services works with positional arguments. And, not only does the ArgumentCollection URL parameter work with positional arguments, each positional argument can, alternatively, be passed through independently.

To demonstrate this functionality, I have set up a very simple ColdFusion web service - Greeting.cfc. This web service just takes two Named arguments and builds a response. When we invoke this web service, we will be using ordered / positional arguments in lieu of named arguments.

Greeting.cfc

  • <cfcomponent
  • output="false"
  • hint="I provide a simple greeting method.">
  •  
  •  
  • <cffunction
  • name="sayHello"
  • access="remote"
  • returntype="string"
  • returnformat="json"
  • output="false"
  • hint="I say something to the given person.">
  •  
  • <!--- Define arguments. --->
  • <cfargument
  • name="name"
  • type="string"
  • required="true"
  • hint="I am the person we are talking to."
  • />
  •  
  • <cfargument
  • name="compliment"
  • type="string"
  • required="false"
  • hint="I am the optional compliment."
  • />
  •  
  • <!--- Check to see if the compliment exists. --->
  • <cfif structKeyExists( arguments, "compliment" )>
  •  
  • <!--- Return just the hello with a compliment. --->
  • <cfreturn "Hello, #arguments.name#, you are #arguments.compliment#." />
  •  
  • <cfelse>
  •  
  • <!--- Return just the hello. --->
  • <cfreturn "Hello, #arguments.name#." />
  •  
  • </cfif>
  • </cffunction>
  •  
  • </cfcomponent>

Pretty straightforward stuff. Now, let's test it. In the following demo, I am going to invoke the above ColdFusion web service using positional arguments. When doing this, I am going to use two different approaches: the first approach will pass the positional arguments through as a single serialized ArgumentCollection value; the second approach will pass the positional arguments through as individual URL parameters.

  • <!--- Build the URL for the web service. --->
  • <cfset webServiceUrl = (
  • "http://" &
  • cgi.server_name &
  • getDirectoryFromPath( cgi.script_name ) &
  • "Greeting.cfc"
  • ) />
  •  
  • <!---
  • Build the arguments collection that we are going to use to
  • invoke the Greeting.cfc.
  • --->
  • <cfset webServiceArguments = {} />
  • <cfset webServiceArguments[ 1 ] = "Katie" />
  • <cfset webServiceArguments[ 2 ] = "looking super adorable" />
  •  
  •  
  • <!--- ----------------------------------------------------- --->
  • <!--- ----------------------------------------------------- --->
  • <!--- ----------------------------------------------------- --->
  • <!--- ----------------------------------------------------- --->
  •  
  •  
  • <!---
  • Invoke the web service. In this pass, we're going to use the
  • above web service arguments structure and pass it through as
  • a serialized "argumentCollection" URL variable.
  • --->
  • <cfhttp
  • result="get"
  • method="get"
  • url="#webServiceUrl#">
  •  
  • <!--- The method we are invoking. --->
  • <cfhttpparam
  • type="url"
  • name="method"
  • value="sayHello"
  • />
  •  
  • <!--- Serialize the argument collection as JSON. --->
  • <cfhttpparam
  • type="url"
  • name="argumentCollection"
  • value="#serializeJSON( webServiceArguments )#"
  • />
  •  
  • </cfhttp>
  •  
  •  
  • <!--- Output the response. --->
  • <cfoutput>
  •  
  • <strong>ArgumentCollection Response:</strong>
  •  
  • #deserializeJSON( get.fileContent )#
  •  
  • </cfoutput>
  •  
  •  
  • <!--- ----------------------------------------------------- --->
  • <!--- ----------------------------------------------------- --->
  • <br />
  • <br />
  • <!--- ----------------------------------------------------- --->
  • <!--- ----------------------------------------------------- --->
  •  
  •  
  • <!---
  • Invoke the web service again. This time, however, rather than
  • passing in an argumentCollection URL variable, we are going to
  • pass in individual, ordered arguments as separate URL variables.
  • --->
  • <cfhttp
  • result="get"
  • method="get"
  • url="#webServiceUrl#">
  •  
  • <!--- The method we are invoking. --->
  • <cfhttpparam
  • type="url"
  • name="method"
  • value="sayHello"
  • />
  •  
  • <!---
  • Pass first argument. Notice that the NAME of the url
  • variable is the index of the positional argument.
  • --->
  • <cfhttpparam
  • type="url"
  • name="1"
  • value="#webServiceArguments[ 1 ]#"
  • />
  •  
  • <!---
  • Pass second argument. Notice that the NAME of the url
  • variable is the index of the positional argument.
  • --->
  • <cfhttpparam
  • type="url"
  • name="2"
  • value="#webServiceArguments[ 2 ]#"
  • />
  •  
  • </cfhttp>
  •  
  •  
  • <!--- Output the response. --->
  • <cfoutput>
  •  
  • <strong>Ordered Argument Response:</strong>
  •  
  • #deserializeJSON( get.fileContent )#
  •  
  • </cfoutput>

When we run the above code, we get the following output:

ArgumentCollection Response: Hello, Katie, you are looking super adorable.

Ordered Argument Response: Hello, Katie, you are looking super adorable.

This works in both ColdFusion 8 and ColdFusion 9 (NOTE: both of these probably have updaters installed). And, just so you know that there's no false correlation of behavior taking place, let's try switching the order of the parameters:

  • <cfset webServiceArguments = {} />
  • <cfset webServiceArguments[ 2 ] = "Katie" />
  • <cfset webServiceArguments[ 1 ] = "looking super adorable" />

This time, when we invoke the ColdFusion web service (in both CF8 and CF9), we get the following output:

ArgumentCollection Response: Hello, looking super adorable, you are Katie.

Ordered Argument Response: Hello, looking super adorable, you are Katie.

As you can see, ColdFusion is clearly honoring the defined position of the URL parameters, both in ArgumentCollection format and in individual parameter format. This is awesome!

NOTE: This works for both GET and POST methods.

What If My Web Service Doesn't Have CFArgument Tags

As I have demonstrated before, using positional arguments in ColdFusion can get tricky, especially across different versions of ColdFusion. As I have shown above, the URL-based, positional argument approach is consistent in ColdFusion 8 and ColdFusion 9 when you use CFArgument tags. If you do not use CFArgument tags, however, inconsistencies do pop up. If I were to strip out my CFArgument tags and use the following CFReturn statement (within my web service):

  • <cfreturn "Hello, #arguments[ 1 ]#, you are #arguments[ 2 ]#." />

... I would get the following output when using positional arguments in a ColdFusion 8 web service:

ArgumentCollection Response: Hello, Katie, you are looking super adorable.

Ordered Argument Response: Hello, Katie, you are looking super adorable.

... and I would get the following output when using positional arguments in a ColdFusion 9 web service:

ArgumentCollection Response: Hello, looking super adorable, you are Katie.

Ordered Argument Response: Hello, looking super adorable, you are Katie.

As you can see, ColdFusion 9 fails to adhere to the stated index of the given positional arguments. The take away: always use CFArgument tags. Of course, that should be pretty obvious in general. CFArgument tags allow for self-documenting code; and, other than some outlier situations involving a variable-number of arguments, I can't see any valid, rational, defendable reason for not using CFArgument tags.

One of ColdFusion's most powerful (and most subtle) features is its ability to invoke methods using both named and positional arguments. I have made extensive use of this within my ColdFusion applications. However, I am thrilled to learn that this kind of invocation duality can exist when communication with a 3rd party application through the use of ColdFusion web services. This definitely opens the door for some interesting interactions.




Reader Comments

There are no comments posted for this web log entry.

Post A Comment

Comment Etiquette: Please do not post spam. Please keep the comments on-topic. Please do not post unrelated questions or large chunks of code. And, above all, please be nice to each other - we're trying to have a good conversation here.

Please review the following issues:

Author Name:
Author Email:
Author Website:
Comment:
Supported HTML tags for formatting: <strong>bold</strong>   <em>italic</em>   <code>code</code>







  • Help Wanted - Find Your Next ColdFusion Job
InVision App - Prototyping Made Beautiful With Prototyping Tools Ben Nadel's Company - Epicenter Consulting Recent Blog Comments
Kévin
May 21, 2012 at 1:58 AM
Updated: Converting A ColdFusion Query To CSV Using QueryToCSV()
Hi Ben, why do you need to have so many double quotes when adding the field and field name to the row data? ----------------------------------------- <cfset LOCAL.RowData[ LOCAL.ColumnIndex ] = ... read »
AXL
May 21, 2012 at 1:24 AM
URL Rewriting And ColdFusion's WriteToBrowser Image Functionality (CFFileServlet)
@Mounir, Open your lower case URL Rewrite rule and add the following condition. Condition input: {REQUEST_URI} Check if input string: Does Not Match the Pattern Pattern: ^/CFFileServlet/_cf_ca ... read »
John
May 20, 2012 at 4:28 AM
Understanding The Complex And Circular Relationships Between Objects In JavaScript
@Will Vaughn I tried your javascript example but got this error:- foo.print is not a function ... read »
Perl hacker
May 19, 2012 at 5:37 AM
A Graphical Explanation Of Javascript Closures In A jQuery Context
Thanks for this article, but I fear you missed an important point. If variables in the outer context change, these changes affect the inner anonymous functions as well. That means: if you change the ... read »
Alexander
May 18, 2012 at 3:39 PM
Parsing CSV Data With An Input Stream And A Finite State Machine
Can you use file upload button with this? and read live? or does the file have to already be on the server saved? ... read »
horoskop
May 18, 2012 at 1:06 AM
VIRGO (Aug. 23-Sept. 22): Dead On The Money!
A friend of mine and I were arguing about astrology and she told me that he believes in astrology. She hasn't provided me with any evidence that the belief makes any sense to me. She she been telling ... read »
Manuel
May 17, 2012 at 11:32 PM
Using ColdFusion to Handle 404 Errors (Page Not Found) On Development Server
Very easy the configuration. I read a lot pages and I can't find the solution. I open the administrator and change this Administrator/server settings/Error Handlers/Missing Template Handler and p ... read »
Curt Self
May 17, 2012 at 3:13 PM
LOCAL Variables Scope Conflicts With ColdFusion Query of Queries
I never cease to be amazed that almost EVERY random CF issue I come across lands me on your site. Thank you for documenting your findings for the world. ... read »