Basic Requirements

Installing ColdFusion on Windows Platform

This tutorial is based on programs developed on a Windows XP Professional machine which has IIS 5.1 installed on it. Since this tutorial deals with creating a web service with ColdFusion, it is assumed that Cold Fusion MX Server software is installed. If you need to know how to install Cold Fusion MX.

 What is a web service?

A web service is a software related technology that facilitates machine-to-machine interaction over a network. The WSDL (Web Services Discovery Language) format is supposed to be understood and processed by all the machines. The WSDL therefore sets up the rules of engagement for this interaction. These rules are enforced by sending the messages to be carried by SOAP (Simple Objects Access Protocol) envelopes. The envelopes are carried and delivered by such all too well known protocols as HTTP, SMTP and others. The language used between machines for interaction will be the now familiar, text format based, XML (eXtensible Markup Language).

A web service, because of its open source origin, should be transparent to the diverse, existing programs and operating systems in its ideal embodiment. The web service when it is ready may be published in what is called a UDDI (Universal Description Discovery Integration) registry, a repository akin to the telephone directory of companies. UDDI is again an open source standard agreed to universally. The best place to learn more about these various acronyms is W3C.

Virtual Directories on the IIS

Virtual directories are those directories that are accessed by Internet/intranet users, normally seen in the URL address of the page being browsed. However, the actual files are located somewhere on the machine, more often in the root directory of the host. This way those who arrive at the web page will not actually know where the related file is kept. The web service related files are placed in a Virtual Directory called CF_WebSvc, and the Web client related files consuming this service are placed in another virtual directory called TestingCF as shown in Fig.1. The actual files are kept on the machine at the indicated physical locations.

CF_webSvc----------- C:\Documents and Settings\computer user\

My Documents\ColdFusionWebSvc 

TestingCF----------- C:\Documents and Settings\computer user\

My Documents\MyCFusion

ColdFusion background for Web Service

If you have been developing custom functions and ColdFusion components you are already well on your way to creating a web service. This tutorial assumes that you are starting at the very beginning.

ColdFusion components are almost OOP based but not totally; they have methods and constructs, and they provide reusable code. We will look at it in more detail during this tutorial. However, if you know what functions achieve in any programming language, you are not far from understanding components. They turn functions into objects whose methods can be accessed. ColdFusion function methods morph themselves into ColdFusion Web Service methods via CFC.

If you have read my previous article, you would know that ColdFusion code can be written in two ways: tag based and script based with ColdFusion specific <cfscript/>. You need to know a number of function-specific tags and CFC related tags, such as the following:

cffunction [argument list]
cfargument
cfreturn
cfcomponent

Create function justFunction.cfm

I will show how to create a function. Of course you need to know all those tags. But this next code shows a very simple function which outputs a string after accepting a different string. This file is called justFunction.cfm. The function is called by its name. The argument is sent through the vehicle "arguments. name" which is "Jay" in this case.

<cffunction name="WelcomeMsg"  returntype="string">
<cfargument name="name" type="string" required="yes">
<cfreturn "<h3><font color='blue'>Welcome to my Web Service Site</font>

</h3> " & arguments. name &"! " & "What would you like to do?">

</cffunction>
<cfoutput>
#WelcomeMsg("Jay")#
</cfoutput>

justFunction.cfm display

You need to place this file into the TestingCF virtual directory (which means in the physical directory shown earlier). Now if you browse this file in your favorite browser, this is what you will see.

In this step you will turn this function into a web service by using the CFC tags. This is the easy part. The web service we create using this function will be called justFunction.cfc. CFCs have this extension, and this is important to note. Here is the code for this CFC.

<cfcomponent>
<cffunction name="WelcomeMsg" access="remote" returntype="string"
output="no">
<cfargument name="name" type="string" required="yes">
<cfreturn "<h3><font color='blue'>Welcome to my Web Service Site</font>

</h3> " & arguments.name &"! " & "What would you like to do?">

</cffunction>
</cfcomponent>

First of all, you notice that the function code is nested in the cfcomponent tags. You also notice that a couple more attributes are added to the function. The web service is accessed remotely and therefore the access is set to 'remote'. Since it is a service you cannot access it directly for an output, so we have set it for 'no' output. Actually, when your consumer calls, this service gets it for you, after massaging what he gets from the server. The tag cfreturn is also needed, because this is what the service returns.

Now you save it in the other directory mentioned earlier, CF_WebSvc. Now, let us see what happens if we access this file with your browser. This is a component, so it should be viewed with a component browser. This is what you will see.

Now if you have permission to log on to this screen (go back to the installation at the very beginning; I could because I am the admin, and in fact the only user), you enter and click on Login. This is what you will see. It's the description of the service and the methods therein. You will see that WelcomeMsg() is a method that takes a string argument. Well, folks, this is all there is to it. When this service is called by the consumer, he or she should provide a string.

We want to know whether this service is working. How are we going to test it? Easy, let us create a client who will consume this service. Writing client code is not different from writing a CFM page. Of course you use the special tags, like "cfinvoke" which calls up the service. Where does it call it from? This is where the WSDL we spoke of earlier comes in. The functions of the CFC function are similar to the ASMX in the dotNet environment. When you invoke the service, you invoke it with an argument, in this case "Mr.Bond". The return variable is a string which you display as you normally would, with the 'cfoutput' tags. Now you save this as ConsumejustFunction.cfm and store in the appropriate virtual directory.

<cfinvoke 
webservice="http://localhost/CF_WebSvc/justFunction.cfc?wsdl"
method="WelcomeMsg"
returnvariable="strg">
<cfinvokeargument name="name" value="Mr. Bond"/>
</cfinvoke>
<cfoutput>
#strg#
</cfoutput>

It's show time! Browse to the 'ConsumejustFunction.cfm', and you will see the following.

Summary

It is pretty easy to create a web service in ColdFusion.  For those who already know how to write functions and components, it is a snap. When you make changes to the CFC make sure you browse to it and review it in the Control Viewer, otherwise the MX may return a "not found" message.

Coding a consumer is just as easy. All you need to do is provide a WSDL reference, a return variable, and the necessary arguments needed by the service. Although the function used is quite simple, more complex data types as well as data from the backend can be provided with the service. The keyword is interoperability. The consuming client could very well use another programming language, perhaps from a UNIX work station in Outer Mongolia.