Programming ColdFusion MX: Web Services

Consuming Web Services

When a client makes a request to a web service, it is said to be a consumer of that service. ColdFusion MX makes consuming web services simple. There are three ways to consume a web service in ColdFusion MX. You can use the cfinvoke tag, the cfobject tag, or the createObject( ) function. It's also possible to use the cfhttp tag to manually consume a web service. Because of the complexity involved with that method, I'm going to limit my coverage to the first three methods.

In many cases, you don't need to know anything about the web service you want to consume other than the URL of its WSDL file. This is especially true if you use Dreamweaver MX to develop your ColdFusion MX applications. Generating the necessary CFML code to consume a web service using Dreamweaver MX is literally a point and click process:

Open the Components tab under the Application panel.

Choose Web Services from the dropdown box in the Components tab.

Click the plus (+) button next to the dropdown box where you selected Web Services. This opens the Add Using WSDL dialog box.

Enter the URL to the desired WSDL file and click OK.

Dreamweaver MX automatically generates a proxy for the web service and makes it available in the Components tab. From here, you can expand the proxy to show the web service's fields, methods, and properties as defined by the WSDL file.

If you don't use Dreamweaver MX, that's okay too. You can visually inspect a WSDL file by entering its URL into your web browser. Most modern browsers are capable of displaying the contents of a WSDL file inline. Regardless of whether you are using Dreamweaver MX, enter the URL to the XMethods currency exchange web service in your browser:

http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl

The resulting WSDL should look something like this:

<?xml version="1.0"?> <definitions name="CurrencyExchangeService" targetNamespace="http://www.xmethods.net/sd/CurrencyExchangeService.wsdl" xmlns:tns="http://www.xmethods.net/sd/CurrencyExchangeService.wsdl" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <message name="getRateRequest"> <part name="country1" type="xsd:string"/> <part name="country2" type="xsd:string"/> </message> <message name="getRateResponse"> <part name="Result" type="xsd:float"/> </message> <portType name="CurrencyExchangePortType"> <operation name="getRate"> <input message="tns:getRateRequest" /> <output message="tns:getRateResponse" /> </operation> </portType> <binding name="CurrencyExchangeBinding" type="tns:CurrencyExchangePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="getRate"> <soap:operation soapAction=""/> <input> <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output > <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation> </binding> <service name="CurrencyExchangeService"> <documentation>Returns the exchange rate between the two currencies</documentation> <port name="CurrencyExchangePort" binding="tns:CurrencyExchangeBinding"> <soap:address location="http://services.xmethods.net:80/soap"/> </port> </service> </definitions>

Before we continue, I'd like to briefly cover the pieces of a WSDL file. This is especially important if you aren't using Dreamweaver MX, as you'll need to know this to determine what methods are available in the web service, what, if any, parameters they take (and their datatypes), and any values you can expect to be returned. Since a WSDL file is nothing more than an XML file, let's break it down by its elements:

<definitions>

Root element of the WSDL document. This element specifies namespace definitions for the web service.

<types>

Although not shown in our example WSDL, the types element can be used to specify datatype definitions for the exchanged messages.

<message>

Message elements define the data being exchanged. Messages are typically used to define input, output, and input/output parameters.

<part>

Parts describe the contents of messages. They are typically used to name parameters.

<portType>

The portType element defines one or more operations that the web service can be called to perform. It acts as a wrapper for individual operations, just as a CFC acts as a wrapper for individual functions (methods). This element and its child elements, operation, input, and output, are the elements you should be most concerned with as together they tell you what the web service can do as well as what input and output parameters it has.

<operation>

The operation element defines an operation that can be invoked within the web service. Operations are akin to functions (methods) in a CFC.

<input>

Specifies an input parameter for its parent operation.

<output>

Specifies an output parameter for its parent operation.

<fault>

Specifies a message to be returned by its parent operation in the event an error occurs. Note that the fault element is not shown in our example.

<binding>

Defines a protocol for accessing the specified portType. Protocols include HTTP GET, HTTP POST, MIME, and SOAP. Any number of bindings may be defined for a given portType.

<service>

Defines a group of related ports.

<documentation>

Optional element for specifying human-readable documentation. The documentation element may be a child element of any WSDL element.

<port>

Defines an individual endpoint for a binding.