Introducing Web Services in ColdFusion MX | ColdFusion MX Professional Projects

After creating CFCs for ColdFusion applications, you can create Web services. Using the Internet, you can access the content on remote computers. The content can either be static, such as an HTML page, or dynamic, such as a ColdFusion page. The Web service technology allows you to access application functions on remote computers. Using a Web service, it's possible to make a request to a remote application to perform an action.

Web services allow you to avoid having to create the application logic that's been created by others, so you can build the applications much faster. The Web Services Description Language (WSDL) file is used to describe the functionality of the Web service, including the available functions, parameters, and results.

You can either reference a remote Web service in your ColdFusion MX application or create your own Web service and make it available to others for accessing remotely. The applications that can use the Web service can be implemented in ColdFusion. Accessing a Web service is similar to calling a function. A Web service references a remote function over the Internet. When you make a Web service available, you can also publish a description of the API to the Web service as a WSDL file.

Architecture of the Web Service

Before you create the Web service, you need to be familiar with the basic architecture of the Web service provider. There are three primary components of the Web services platform:

Simple Open Access Protocol (SOAP)
WSDL
Universal Description, Discovery, and Integration (UDDI)

Figure 17.2 illustrates the use of the Web services by ColdFusion MX Administrator.

click to expand
Figure 17.2: The architecture of Web services.

The client making the SOAP request communicates with the Web server, which then makes requests using a Web service to the ColdFusion MX server. ColdFusion MX contains the ColdFusion Web services engine and the WSDL file components. The ColdFusion Web services engine is based on the Apache axis SOAP engine that supports both SOAP and WSDL. These two components process the requests and send the response back to the Web server, which displays the output on the browser. The following section discusses the use of Web services with SOAP and UDDI.

Web Services with SOAP

SOAP provides a standard XML structure to send and receive Web service requests and then respond over the Internet. You can send SOAP messages using HTTP, SMTP, and other protocols. ColdFusion integrates the Apache Axis SOAP engine to support Web services. The ColdFusion Web services engine performs functions such as creating WSDL files.

Web Services with UDDI

UDDI allows client applications to locate the Web services dynamically. This is to allow others to find the information about your Web services. You need to use the UDDI query to search for the service providers. A UDDI response contains information such as business contact information, the category of the business operation, and any other technical data that explains how to invoke a Web service. ColdFusion MX does not directly support UDDI, but it is possible to manually register or search a Web service using a public UDDI registry, such as the IBM UDDI business registry.

What Is a WSDL File?

WSDL is an XML-based structure that defines the interface to the Web service. When a client application needs to interact with a Web service, it needs to access a WSDL file. If you publish application logic as a Web service, you need to create a WSDL file for the application. ColdFusion automatically generates a WSDL file with the information, such as the name, location, and supported operations of the Web service.

Analyzing the WSDL File

As explained in the previous sections, you can either view a WSDL file in a Web browser or an HTML editor, such as Dreamweaver MX. The major components of the WSDL file include the following:

Definitions. Indicate the root element of the WSDL file. This area contains the namespace definitions that enable you to avoid naming conflicts between multiple Web services.
Types. Defines the datatypes used by a service's messages.
Message. Defines the data transferred by a Web service operation, which involves the name and the datatype of the input parameters and return values.
Port type. Defines one or more operations provided by the Web service.
Operation. Defines an operation that can be invoked remotely.
Input. Specifies an input parameter to the operation using the message component.
Output. Specifies the return values from the operation using the message component.
Fault. Indicates an optional component that specifies an error message returned from the operation.
Binding. Specifies the protocol that enables you to access a Web service. This includes SOAP, HTTP, and so on.
Service. Defines a group of related operations.
Port. Defines an operation and its associated inputs and outputs.

Creating a WSDL File

You need to construct the functions of a Web service and then create the WSDL file to publish the Web service. CFCs enable you to create Web services in ColdFusion MX. You can view Web services with the WSDL file in any HTML editor, such as Dreamweaver MX. It contains a utility for viewing operation names, parameter names, and parameter datatypes. You can also view the WSDL file in the Web browser.

To view a WSDL file using Dreamweaver MX:

Choose Windows, Components to display the Components panel. Alternately, you can press Ctrl+F7 to display the Components panel.
In the Components panel, select the Web Services option from the drop-down list. Then, click the plus button to display the Add Using WSDL dialog box.
Specify the URL of the WSDL file.

Consuming Web Services in ColdFusion MX

After creating a WSDL file, you're ready to use a Web service for ColdFusion MX in the Web server. ColdFusion provides the following two ways to consume a Web service:

Using the <cfscript> tag. Enables you to consume a Web service in a cfscript block using the CreateObject method.
Using the <CFML> tag. Enables you to consume a Web service in a block of CFML code using the <cfinvoke> CFML operator.

Note

All the methods of consuming a Web service use the same technology and offer the same performance.

Using the <cfinvoke> Tag to Invoke a Web Service

With the <cfinvoke> tag, you can reference the WSDL file and then invoke an operation on the Web service:

 <cfinvoke webservice="URLtoWSDL" method="operationName"            inputParam1="var1" inputParam2="var2"... returnVariable="varName">

webservice. Enables you to specify the URL to the WSDL file for the Web service.
method. Specifies the operation of the Web service to be invoked.
inputParamN. Specifies the input parameters to the operation.
returnVariable. Specifies the name of the variable that contains any results returned from the Web service.

For example, to invoke the http://www.tdocs.com/sd/200l/Steffilina.wsdl Web service with the AddEmployee method:

Create a ColdFusion page using the following code:

 <cfinvoke          webservice = "http://www.tdocs.com/sd/2001/AddEmployee.wsdl "          method = "AddEmployee"          translationmode = "en_es"          sourcedata = "Employees Added"          returnVariable = "Employee">     <cfoutput>Employee#</cfoutput> </cfinvoke>

Save the file as AddEmployee.cfm in the Web root directory in the Web server.
View the AddEmployee.cfm file using the Web browser.

You can use other mechanisms to pass parameters to the Web service, including the <cfinvokeargument> tag and the argumentCollection attribute of the <cfinvoke> tag. The following code snippet shows the use of the <cfinvokeargument> tag to pass parameters to a Web service:

 <cfinvoke         webservice ="http://www.tdocs.com/sd/2001/AddEmployee.wsdl"         method =AddEmployee"        returnVariable = "varName" >     <cfinvokeargument name="translationmode" value="en_es">     <cfinvokeargument name="sourcedata" value="Hello world!"> </cfinvoke> <cfoutput>#varName#</cfoutput>

<cfinvokeargument> acts as a nested tag to <cfinvoke> that enables you to specify the name and value of the parameter passed to the Web service.

You can also use an attribute collection to pass parameters. An attribute collection is a structure in which each key corresponds to a parameter name, and each value is the parameter value passed for the corresponding key.

Consuming the Web Service Using the <cfscript> Tag

When you use the <cfscript> tag to consume a Web service, you need to use the CreateObject function to connect to the Web service. Then you can make requests to it. The following syntax is used for the CreateObject function:

 webservicename=CreateObject ("webservice", "URLtoWSDL")

URLtoWSDL is used to specify the URL to the WSDL file for the Web service. After creating an object of the Web service, you can call the operations using the dot notation:

 webservicename.operationName (inputVar1, inputVar2, ……)

To return the value from the Web service, you need to write the values to a variable:

 resultVar=webservicename.operationName (inputVar1, inputVar2,   )

Alternatively, you can pass the return values directly to a function, such as the AddUser function:

 AddUser (webservicename.operationName (inputVar1, inputVar2,   ))

Calling Web Services from Flash

You can call a Web service from various client applications, such as a Flash movie. The Flash movie does not call the Web service directly. You need to use the Flash Remoting service, which in turn calls the CFC that calls the Web service. The Flash movie can pass parameters to the component. In addition, the component can return to the Flash movie any data returned by the Web service.

Publishing Web Services in ColdFusion MX

In the previous sections, you learned how to create a ColdFusion component and the Web services. After you create them, you need to publish them so they're available for remote applications. ColdFusion Web services provide a powerful mechanism for publishing and consuming application functions. Some of the best practices before you produce a Web service for publication are as follows:

You should minimize the use of complex ColdFusion datatypes, such as query and struct, in the Web services. These datatypes require you to create special data structures to handle them.
You need to test the CFCs implemented for the Web services locally before publishing them on the Internet.

To publish a Web service, create a CFC for it with a .cfc extension, and then invoke the component in a ColdFusion page with the .cfm extension. The following are the requirements for creating a Web service for publishing:

The access attribute of the <cffunction> tag should have the value remote.
The <cffunction> tag should include a returnType attribute to specify the return type. If there's no value to return, use the void attribute.
The output attribute should be set to No to enable ColdFusion to convert all the output to XML to return it to the consumer.
The required= "false" attribute setting is ignored.

For example, if you want to create a LoginService component to check the validity of users in the ColdFusion application, use the following code snippet:

 cfcomponent name="loginservice"               displayName="Checks the Logins from the DataBase">   <cffunction name="login" access="remote" returnType="string">     <cfargument name="uname">     <cfargument name="pass"> <cfquery name="loginq" datasource="webservice">     select * from users     where UserName like '#uname#' and password like '#pass#' </cfquery>     <cfoutput query="loginq">       <cfset login="Success">     </cfoutput>     <cfif #loginq.RecordCount# eq 0>       <cfset login="Fail">     </cfif>     <cfreturn #login#>   </cffunction> </cfcomponent>

Save this component with a .cfc extension, such as LogiPnService.cfc. Then, create a ColdFusion page to invoke the LoginService Web service, as shown in the following code snippet:

 <cfinvoke component="loginservice" method="login" returnVariable="loginans">         <cfinvokeargument name="uname" value="#Form.uname#">         <cfinvokeargument name="pass" value="#Form.Pass#"> </cfinvoke>

Save the file with the .cfm extension, such as Client.cfm, in the Web root directory in the Web server. Then, run the Client.cfm file on the Web browser to view the output of the Client.cfm ColdFusion page.