TechNote (Archived)

ColdFusion MX: Using CFCs as Datatypes with Web Services

Using ColdFusion components to define data types for web services

This TechNote will explore using the cfproperty tag within ColdFusion Components that are called through Web Services. The cfproperty tag defines properties for use in the component definition that is returned to the consumers of the web service. One unique feature of this approach is that ColdFusion recognizes when a remote access CFC function is called as a Web Service, and automatically creates get andset methods for each cfproperty value.

The code samples provided below demonstrate a web service managing a Contacts table schema that is defined throughcfproperty. The code includes 3 files: one base component used for error handling, one invoker CFM file and one web service CFC. The sample code is written to have all files placed in the root directory, if you place the tags in another directory you will need to change the component name to reflect the correct package.

Once all 3 files are created on your test server's application root directory, you can run the code by going to \invoke_ws.cfm. Once you review the code and run the examples, you should see the value of combining cfproperty with CFCs and Web Services. It offers a great way to build CFCs that manage data through web services. The example code does not use shared scopes to store the returned components but this could be added to hold references to component instances.

One technique employed in this example is to use a Base level component that is extended by the datatype CFC. By extending contact.cfc from basecomp.cfc, it allows you to pick up the 2cfproperty fields defined for error handling. Since error handling is a global feature, you would want to use it for all datatype components. In this example, basecomp.cfc was created for this purpose. You will undoubtedly find other uses for basecomp.cfc as you build more datatype CFCs. Some examples of functionality that you might place in basecomp.cfc could include logging, security calls, code table storage and custom corporate level or project level functionality.

Once the tags are set up and you invoke_ws.cfm, you will see the below output:

Below you will find the 3 files you will need to create to run the examples. You may also download the code here (3K).

Step One: Define the Base Web Service ColdFusion Component

basecomp.cfc

 <cfcomponent   hint="Base Corporate Component used for all DataType Components"   output="no"><cfproperty name="returncode" type="string"><cfproperty name="returnmessage" type="string"></cfcomponent>

Step Two: Build the Web Service ColdFusion Component

contact.cfc

 <cfcomponent displayname="Contact Manager" extends="basecomp"   output="no"><!--- Define components datatype information using CFProperty ---><cfproperty name="Contactid" type="numeric"><cfproperty name="Firstname" type="string"><cfproperty name="Lastname" type="string"><cfproperty name="Phone" type="string"><cfproperty name="Address" type="string"><cfproperty name="City" type="string"><cfproperty name="State" type="string"><cfproperty name="Zip" type="string"><cfproperty name="Country" type="string"><!--- Initialize a small structure to simulate a database. ---><cfset init()><!--- We will use a common get method to demonstrate using cfproperty            with web services ---><cffunction name="getContactByPrimaryKey" returnType="contact"        access="remote" hint="Returns a datatype of itself"><cfargument name="id" type="numeric"><!--- Initialize local variables used in this function ---><cfset var comp_contact = ""><cfset var foundcontact = ""><cfobject component="contact" name="comp_contact"><!--- This function would most likely retrieve the contact from              a database, we will use a structure for this example. ---><!--- If id is not found return an error within component---><cfif not StructKeyExists(variables.contactsdb, "#arguments.id#")><cfset comp_contact.returncode = "-1"><cfset comp_contact.returnmessage = "No Contact Found"><!--- Return component of type Contact with error information ---><cfreturn comp_contact></cfif><!--- Populate the component using data from structure and return to              consumer ---><cfset foundcontact = variables.contactsdb["#arguments.id#"]><cfset comp_contact.contactid = arguments.id><cfset comp_contact.firstname = foundcontact.firstname><cfset comp_contact.lastname = foundcontact.lastname><cfset comp_contact.phone = foundcontact.phone><cfset comp_contact.address = foundcontact.address><cfset comp_contact.city = foundcontact.city><cfset comp_contact.state = foundcontact.state><cfset comp_contact.zip = foundcontact.zip><cfset comp_contact.country = foundcontact.country><cfset comp_contact.returncode = "1"><cfset comp_contact.returnmessage = "Contact Found"><!--- Return component of type Contact to the web service ---><cfreturn comp_contact></cffunction><cffunction name="init"             hint="Build an in-memory structure to simulate a db"><!--- Initialize structure in 'variables' scope to simulate a                  database ---><cfset variables.contactsdb = structNew()><cfset variables.contactsdb["1"] = StructNew()><cfset variables.contactsdb["2"] = StructNew()><cfset contact1 = variables.contactsdb["1"]><cfset contact2 = variables.contactsdb["2"]><cfset contact1.firstname = "John"><cfset contact1.lastname = "Smith"><cfset contact1.phone = "(212) 867-5309"><cfset contact1.address = "211 Madison Ave"><cfset contact1.city = "NY"><cfset contact1.state= "NY"><cfset contact1.zip= "12345"><cfset contact1.country = "USA"><cfset contact2.firstname = "Mary"><cfset contact2.lastname = "Smith"><cfset contact2.phone = "(212) 867-5310"><cfset contact2.address = "333 Madison Ave"><cfset contact2.city = "NY"><cfset contact2.state= "NY"><cfset contact2.zip= "12345"><cfset contact2.country = "USA"></cffunction></cfcomponent>

Step Three: Build the ColdFusion tag that will consume the Web Service

Invoke_ws.cfm

 <!--- Form to retieve requested Contact ID ---><cfform method="post">   Contact Id:<cfinput type="text" name="cid" validate="integer"      message="Please enter a numeric value!"><input type="submit" value="Get">   (Enter 1 or 2 to retrieve a contact)</cfform><cfoutput><!--- If we have an incoming ID create a web service          object and attempt to get contact information.  ---><cfif isdefined("form.cid") and len(form.cid) GT 0><!--- Adjust the below variables for your test if necessary ---><cfset wshost = cgi.http_host><cfset wserv = "contact.cfc"><!--- Create web service object and make a call to retrieve a              contact ---><cfscript>         ws = CreateObject("webservice", "http://#wshost#/#wserv#?wsdl");         wscontact = ws.getContactByPrimaryKey(#form.cid#);</cfscript><!--- Display return code and message --->     Result properties using properties on the extended        component (basecomp.cfc):<br>     Return Code: #wscontact.getreturncode()#<br>     Message: #wscontact.getreturnmessage()#<br><br><!--- Display Contact information if one was found ---><cfif #wscontact.getreturncode()# GT 0><!--- Use the automatically created Get Method to retrieveproperties --->       Contact Information:<br>       #wscontact.getFirstname()# #wscontact.getlastname()# <br>       Phone: #wscontact.getPhone()#<br>       Address: #wscontact.getAddress()#                #wscontact.getCity()#,#wscontact.getState()#                #wscontact.getZip()#                #wscontact.getCountry()# <br><br></cfif><!--- Dump the returned Contact component --->     Object Definitions: Notice the automatically created get and set methods for each cfproperty value<br><cfdump var="#wscontact#"><br></cfif></cfoutput>