This Web service in the preceding section contains only one method, but in the real world, a Web service may contain many methods. Create a file named WebService.cfc inside the com directory of your Web root (which you create in the component packages section of 22) and enter the code shown in Listing 25-1.

<cfcomponent> <cffunction name= ListPartners access= remote returntype= string output= no > <cfargument name= zipFilter type= string required= yes > <cfset Var xmlDoc = > <cfset Var partnerList = > <cfquery name= partnerList datasource= #Request.MainDSN# > SELECT CompanyID, CompanyName, Address, City, State, ZipCode, Comments FROM Company WHERE ZipCode LIKE #Arguments.zipFilter#% ORDER BY CompanyName ASC </cfquery> <cfsavecontent variable= xmlDoc > <companies> <cfoutput query= partnerList > <company id= #CompanyID# > <name>#XMLFormat(CompanyName)#</name> <street>#XMLFormat(Address)#</street> <city>#XMLFormat(City)#</city> <state>#XMLFormat(State)#</state> <zip>#XMLFormat(ZipCode)#</zip> <comments>#XMLFormat(Comments)#</comments> </company> </cfoutput> </companies> </cfsavecontent> <cfreturn xmlDoc> </cffunction> </cfcomponent>

The important points to consider in Listing 25-1 are as follows: access= remote is required to make a component method accessible to systems outside the ColdFusion server that serves the component. Because Web services are consumed remotely, your must set the access level to remote. output= no is required to suppress all direct output from the Web service, because the only way to return data to a consumer is through a formal Return value. This is necessary for providing WSDL with the data-typing metadata that it needs to specify the output interface of the Web service. required= yes is technically not necessary in the definition of a Web-service method, but all arguments of the input interface to a Web-service method are strictly required as it is invoked. If you do not pass an optional argument, the Web service throws an error. XMLFormat() should always be used to return XML-formatted values from dynamic data. If you don t do so, your XML-based Web-service output throws an error if the data contains an angle bracket or other characters not easily contained in XML. Other than these four points, your Web-service method is just the same as any other component function. You do have more potential caveats to work around in working with Web services, and we get to these in the section Web-Service Details and Caveats, at the end of this chapter, but for now, you can move on to testing your new Web service.

Before you unleash your Web service on the civilized world, make sure that your Web service itself is indeed civilized by thoroughly testing it in a test harness. Create a file named TestHarness.cfm and enter into it the code shown in Listing 25-2.

<cfinvoke method= ListPartners returnvariable= xmlPartners webservice= http://localhost/com/WebService.cfc wsdl > <cfinvokeargument name= zipFilter value= 3 > </cfinvoke> <cfset xmlObj = XmlParse(xmlPartners)> <cfdump var= #xmlObj# >

Notice the new webservice attribute of the CFINVOKE tag, which takes the place of the Component attribute that you see in s 22 and 23. The fact that, in ColdFusion MX, all you need to do to consume a Web service is to switch a tag attribute and specify a URL is pretty amazing, but basically that s it!

By appending the wsdl attribute to the URL of the component that serves the Web service, you tell ColdFusion to automatically generate the WSDL description for the Web service, and the consumer uses this WSDL description to interface with the Web service. Now run TestHarness.cfm. If you don t see output just like what s shown in Figure 25-1, go back and check your code. Notice that we have collapsed most of the Company elements in the figure for readability.

Figure 25-1: Checking the CFDUMP of the parsed XML object. Edit the Value attribute of the CFINVOKEARGUMENT tag in the test harness to contain various values, including invalid ones such as peoples names, and re-execute the harness to ensure that your Web service responds appropriately to all possible inputs that are accepted through the Web service s interface. Never publish a Web service that hasn t been thoroughly tested for all possible inputs. After you ve corrected any problems with your Web service and tested it thoroughly, the Web service is ready to be consumed.