WSDL

Web Services Description Language (WSDL) is an XML-based language specification that defines Web services and describes how to access them.

WSDL is used to explain the details needed to invoke a Web service over the Internet. WSDL defines XML syntax for describing services between a set of endpoints, usually a client and server, that exchange messages. This documentation can then act as a road map for automating the details of a Web service. WSDL describes the service interaction rather than the formats or network protocols used to communicate. It simply defines the endpoints and their data, regardless of the implementation detail. Early Web services existed without SOAP or WSDL and required constant communication among developers creating and consuming Web services. They needed to know what parameters and data types a Web service's function required, as well as how to encode and decode XML so as to convert one platform's complex data types to another's.

Thankfully, today's ColdFusion developers do not need to concern themselves with such intricacies, or the need to write documentation by hand, because ColdFusion MX generates WSDL automatically. To view the generated WSDL for a ColdFusion component deployed as a Web service, append the string ?wsdl to the component's URL. The WSDL document is then displayed in your Web browser.

The intent of this section is to give ColdFusion developers with little knowledge of Web Services architecture enough WSDL knowledge to recognize common WSDL syntax, to understand the MX-generated WSDL for a ColdFusion component, and to invoke a Web service by hand with only a WSDL document as a guide. Table 24.1 describes 11 tag elements that make up a WSDL document.

Table 24.1. WSDL Document Elements

NAME	DESCRIPTION
definitions	Defines XML name spaces that you use to avoid naming conflicts between multiple Web services. This is the root element of a WSDL file.
types	Defines data types that are used by the service's messages.
message	Defines the data transferred by a Web service operation, typically the name and data type of input parameters and return values.
portType	Defines one or more operations provided by the Web service.
port	Defines an operation and its associated inputs and outputs.
operation	Defines an operation that can be invoked remotely.
input	Specifies an input parameter to the operation using a previously defined message.
output	Specifies the return values from the operation using a previously defined message.
fault	Defines an optional error message returned from an operation.
binding	Specifies the protocol used to access a Web service, including SOAP, HTTP GET and POST, and MIME.
service	Defines a group of related operations.

These WSDL tag elements are important because they define everything about a WSDL document and therefore everything about a Web service. Some of the tag elements are useful only if you are dealing with a complex data type that ColdFusion doesn't understand, or if you are going to parse the returned XML on your own. Nevertheless, being able to recognize elements within a WSDL document will give you all the information you need to invoke the available methods of any Web service.

Listing 24.1 shows a sample WSDL layout containing descriptions about the sections of a WSDL document, and information on the tags within it. This document does not exist on the CD. It is simple presented here as an example.

Listing 24.1. Sample WSDL Layout

 <?xml version="1.0" encoding="UTF-8" ?> <!--  This is the WSDL declaration tag, which defines the XML version and  encoding format being used. It is the only tag in XML that does not  have an end tag. --> <wsdl:definitions> <!--  As the Root element of a WSDL file, the opening <wsdl:definitions> tag  defines all applicable XML namespaces to avoid naming conflicts  between identically named XML tags -->  <wsdl:types>  <!--  The <wsdl:types> tag defines platform-neutral data type  definitions from the XML Schema specification. These are the  data types that are used for messages.  -->  </wsdl:types>  <wsdl:message>  <!-- Code describing WSDL "message"  The <wsdl:message> tag defines the communication data elements.  Each message consists of one or more logical <wsdl:part> tags.  <wsdl:part> tags contain name and WSDL date type information and  are similar to the parameters of a method call in Java or  function call in C++ or ColdFusion.  -->  </wsdl:message>  <wsdl:portType>  <!-- Code describing WSDL "port"  The <wsdl:portType> tag defines operations (functions) that can  be called within a Web Service, and the messages (input & output  parameters) that are involved. You can think of a portType as  being somewhat similar to a class in Java or C++. In fact, a  portType is almost exactly like a CFC in that it contains methods  but can't be instantiated and doesn't have member variables. An  operation is extremely similar to a function in a structured  programming language such as C or ColdFusion.  -->  </wsdl:portType>  <wsdl:binding>  <!--  Code within the opening and closing <wsdl:binding> tag  defines the WSDL "binding" of data types for all input  and output parameters as well as to their encoding style.  -->  </wsdl:binding>  <wsdl:service>  <!--  Within a <wsdl:service> tag is a <wsdl:port> port, which defines  the connection point to a Web Service and its SOAP binding.  -->  </wsdl:service> </wsdl:definitions> 

Now that we have looked at the layout of WSDL and definitions of the tag elements that make up a document, we need to examine a simple WSDL document and get familiar with its syntax. To give us something for comparison with our WSDL document, here is an extremely simple ColdFusion Component (CFC) that is being deployed as a Web service. Listing 24.2 shows the Number-To-String Conversion Web Service.

Listing 24.2. Number-to-String Conversion Web Service (NumericString.cfc)

 <!--- DATE: 06/01/02 AUTHOR: Brendan O'Hara ([e-mail]) WEB SERVICE: NumericString.cfc DESCRIPTION: ColdFusion CFC deployed as a Web Service to return a passed-in integer into its String representation. ARGUMENTS: name="numberNumeric" type="numeric" required="false" default="0" ---> <!--- Here is a display name for the CFC/WS with a hint. ---> <cfcomponent displayname="NumericString" output="false"              hint="Converts a number to its String representation"> <!--- Here is a only function in the CFC. We know it is deployed as a Web Service because its access variable is set to "remote" ---> <cffunction name="IntegerToString" returnType="string" output="false"             access="remote">   <!--- Here is the argument variable --->   <cfargument name="numberNumeric" type="numeric" required="true">   <cfset var returnString = "">   <!--- Here is the "logic" of the CFC Web Service --->        <cfswitch expression="#arguments.numberNumeric#">               <cfcase value="0"><cfset returnString = "Zero"></cfcase>               <cfcase value="1"><cfset returnString = "One"></cfcase>               <cfcase value="2"><cfset returnString = "Two"></cfcase>               <cfcase value="3"><cfset returnString = "Three"></cfcase>               <cfcase value="4"><cfset returnString = "Four"></cfcase>               <cfcase value="5"><cfset returnString = "Five"></cfcase>               <cfcase value="6"><cfset returnString = "Six"></cfcase>               <cfcase value="7"><cfset returnString = "Seven"></cfcase>               <cfcase value="8"><cfset returnString = "Eight"></cfcase>               <cfcase value="9"><cfset returnString = "Nine"></cfcase>               <cfdefaultcase>                 <cfset returnString = "What am I a mathematician?">               </cfdefaultcase>        </cfswitch>   <!--- Now we return the returnString variable --->   <cfreturn returnString> </cffunction> </cfcomponent> 

This is a ColdFusion Component that is being deployed as a Web service. We know this because the access variable of at least one function is set to Remote. When we examine this CFC, we notice it contains a single function: The IntegerToString function takes one argument named numberNumeric, which is of numeric type and is required.

When IntegerToString is called, the passed value numberNumeric is evaluated in a <cfswitch> tag's expression statement. The corresponding <cfcase> tag sets the variable returnString with the appropriate string representation of the numericNumber variable. Finally, the returnString is returned to the Web service caller by the <cfreturn> tag. To display the WSDL for this CFC Web service, we append the string ?wsdl to the CFC's URL and get the results shown in Figure 24.5.

Figure 24.5. WSDL for CFC Web services.

NOTE

We will go further into the creation of Web services in the next section. For additional information on CFCs, read Chapter 19, "Creating Advanced ColdFusion Components."

Now that we have an understanding of what our Web service/CFC does, we need to go through the WSDL displayed in Figure 24.4 line by line and study the syntax. Let's examine the fraction of a WSDL definition in Listing 24.3.

Listing 24.3. portType and Operation from the WSDL (NumericString.cfc)

 <wsdl:portType name="NumericString">   <wsdl:operation name="IntegerToString" parameterOrder="numberNumeric">     <wsdl:input message="impl:IntegerToStringRequest" name="IntegerToStringRequest"/>     <wsdl:output message="impl:IntegerToStringResponse" name="IntegerToStringResponse"/>     <wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/>   </wsdl:operation> </wsdl:portType> 

On the first line of our WSDL code block, we notice that the portType matches the name of the .cfc file and really represents the .cfc and the Web service. In Java or object-oriented terms, you can think of the portType as being similar to a Java class. A port or portType defines the operations provided by a Web service and their associated inputs and outputs.

An operation in WSDL, and therefore in Web services, is very similar in function to a method name in Java or a function name in C++. The operation in the second line of our sample code defines the IntegerToString operation.

Directly below the operation definition are our wsdl:input, wsdl:output, and wsdl:fault tags. wsdl:input and wsdl:output contain a predefined message and aren't that helpful in determining what our Web service is doing or what we would need to do to call it. The wsdl:fault tag catches errors and outputs the applicable error message. The message and part tags really define the input parameters and the return value of our function. Listing 24.4 shows that WSDL snippet.

Listing 24.4. The message and part Tags from Our WSDL (NumericString.cfc)

 <wsdl:message name="IntegerToStringRequest">   <wsdl:part name="numberNumeric" type="xsd:double"/> </wsdl:message> <wsdl:message name="IntegerToStringResponse">   <wsdl:part name="IntegerToStringReturn" type="xsd:string"/> </wsdl:message> 

Listing 24.4 shows the two wsdl:message tags that map to our single operation IntegerToString. First is the IntegerToStringRequest message, which contains the wsdl:part tags. These tags are very important to recognize, because they define the input parameter variables and their WSDL data types.

NOTE

WSDL uses data types as they are defined in the XML Schema specification.

You have probably already guessed at the message-naming convention. For a request message, the message name is a concatenation of the operation name and the word Request; for example, IntegerToStringRequest. The wsdl:part tag's name is the same as the input parameter or argument for the CFC. In this case, it is numericNumber, which is a numeric ColdFusion type but maps to a xsd:double data type in WSDL. The wsdl:message and wsdl:part in this example are of the Request-response operation type. This is by far the most common operation in a Web service, but it is not the only one possible. Table 24.2 describes possible operation types within a WSDL document.

Table 24.2. Operation Types in WSDL

NAME	DESCRIPTION
Request-response	The Web service can receive a request and return a response.
Solicit-response	The Web service can send a request and wait for a response.
One-way	The Web service can receive a message.
Notification	The Web service can send a message.

The standard and most common operation type is Request-response. If an application server such as ColdFusion as a scheduled task that runs regularly, the server can handle it as a Solicit-response Web service connected to a Request-response Web service on the other end. One-way and Notification types are less common; they are used more often in messaging-based or asynchronous Web services. We will discuss asynchronous Web services briefly in the "Best Practices" section of this chapter. For Request-response operations, a Boolean value of true may be returned simply to confirm that a sent request message has indeed been received.

Now let's take a look at the entire WSDL document in Listing 24.5.

Listing 24.5. The WSDL for Our Simple Web Service (NumericString.cfc)

[View full width]

 <?xml version="1.0" encoding="UTF-8"?> <wsdl:definitions targetNamespace="http://c24.cfadv/"   xmlns="http://schemas.xmlsoap.org/wsdl/"   xmlns:apachesoap="http://xml.apache.org/xml-soap"   xmlns:impl="http://c24.cfadv/"   xmlns:intf="http://c24.cfadv/"   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"   xmlns:tns1="http://rpc.xml.coldfusion/"   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"   xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"   xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <!--WSDL created by Macromedia ColdFusion MX version 7,0,0,89494-->   <wsdl:types>     <schema targetNamespace="http://rpc.xml.coldfusion/" xmlns="http://www.w3.org/2001 /XMLSchema">       <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>       <complexType name="CFCInvocationException">         <sequence/>       </complexType>     </schema>   </wsdl:types>   <wsdl:message name="IntegerToStringResponse">     <wsdl:part name="IntegerToStringReturn" type="xsd:string"/>   </wsdl:message>   <wsdl:message name="IntegerToStringRequest">     <wsdl:part name="numberNumeric" type="xsd:double"/>   </wsdl:message>   <wsdl:message name="CFCInvocationException">     <wsdl:part name="fault" type="tns1:CFCInvocationException"/>   </wsdl:message>   <wsdl:portType name="NumericString">     <wsdl:operation name="IntegerToString" parameterOrder="numberNumeric">       <wsdl:input message="impl:IntegerToStringRequest" name="IntegerToStringRequest"/>       <wsdl:output message="impl:IntegerToStringResponse" name="IntegerToStringResponse"/>       <wsdl:fault message="impl:CFCInvocationException" name="CFCInvocationException"/>     </wsdl:operation>   </wsdl:portType>   <wsdl:binding name="NumericString.cfcSoapBinding" type="impl:NumericString">     <wsdlsoap:binding style="rpc"                       transport="http://schemas.xmlsoap.org/soap/http"/>       <wsdl:operation name="IntegerToString">         <wsdlsoap:operation soapAction=""/>         <wsdl:input name="IntegerToStringRequest">           <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"                          namespace="http://c24.cfadv/" use="encoded"/>         </wsdl:input>         <wsdl:output name="IntegerToStringResponse">           <wsdlsoap:body encodingStyle =                          "http://schemas.xmlsoap.org/soap/encoding/"                          namespace="http://c24.cfadv/" use="encoded"/>         </wsdl:output>         <wsdl:fault name="CFCInvocationException">           <wsdlsoap:fault encodingStyle =                           "http://schemas.xmlsoap.org/soap/encoding/"                           name="CFCInvocationException"                           namespace="http://c24.cfadv/" use="encoded"/>         </wsdl:fault>       </wsdl:operation>   </wsdl:binding>   <wsdl:service name="NumericString">     <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">     Converts a number to its String representation     </wsdl:documentation>     <wsdl:port binding="impl:NumericString.cfcSoapBinding"                name="NumericString.cfc">       <wsdlsoap:address location =                         "http://127.0.0.1:8501/cfadv/c24/NumericString.cfc"/>     </wsdl:port>   </wsdl:service> </wsdl:definitions> 

Now that we have a general idea of what is going on, let's try to figure out what we would need to know from the WSDL document in order to invoke our example Web service. The first thing we need is the URL for the WSDL document. We used this previously to get the WSDL to display in our browser. Next, we need to determine what the input parameters are and what their data types are. We know from the single <wsdl:part> tag within the IntegerToStringRequest message that the only input parameter is named numberNumeric, and its XML Schema data type is xsd:double. We now know everything needed in order to call the IntegerToString method of the NumericString Web service. We will review this more in the section on "Consuming Web Services."

NOTE

To learn more about the WSDL specification, visit the World Wide Web Consortium's WSDL note at www.w3.org/TR/wsdl.

We have analyzed the elements of WSDL and described how they relate to a Web service. In the next two sections, we will refer back to the knowledge gained here to understand what a WSDL document looks like for a Web service that we have created, and how to consume a Web service using nothing but its WSDL documentation as a guide. With the descriptive power of WSDL, it is substantially easier to access remote applications and databases as if they were local.