Programming ColdFusion MX: Web Services | 7

Programming ColdFusion MX: Web Services

Handling Datatype Mapping in ColdFusion-Produced Web Services

To see the WSDL for the web service we created in Example 24-5, point your browser to http://localhost/programmingcf/ch24/helloworld.cfc?wsdl. The results should look like those in Figure 24-9.

Figure 24-9. WSDL for a ColdFusion-based web service

This WSDL file looks a little bit different than the one we saw earlier for the currency exchange service. Don't worry. The basic parts of a WSDL you learned about are still there. ColdFusion MX merely adds additional web service information that you would otherwise have to generate yourself.

One thing to note is the way in which ColdFusion datatypes are represented in the WSDL file generated by ColdFusion MX. Every ColdFusion datatype with the exception of structures and queries maps directly to a WSDL datatype, as shown in Table 24-2.

Table 24-2: ColdFusion datatype to WSDL mapping

ColdFusion datatype	WSDL datatype
String	SOAP-ENC:string
Numeric	SOAP-ENC:double
Boolean	SOAP-ENC:boolean
Array	SOAP-ENC:Array
Binary	xsd:base64Binary
Date	xsd:dateTime
Guid	SOAP-ENC:string
Uuid	SOAP-ENC:string
structure*	Map
query*	QueryBean
Any	Complex type
component definition	Complex type
void (operation returns nothing)

When you use a ColdFusion structure as an input or output parameter, the corresponding WSDL datatype is defined as a complex type named Map. This is necessary because the SOAP specification currently does not have an equivalent datatype for the ColdFusion structure. Example 24-7 shows a simple ColdFusion web service that returns a structure (Map).

Example 24-7: Returning a structure (Map) from a ColdFusion web service

<cfcomponent>
  <cffunction name="getStruct" access="remote" returntype="struct"
              output="no">
    <cfset var employee = structNew(  )>
    <cfset employee.name = "Pere Money">
    <cfset employee.title = "President">
    <cfset employee.department = "Executive Management">
    
    <cfreturn employee>             
  </cffunction>
</cfcomponent>

The resulting WSDL file contains the Map mapping, as follows:

<complexType name="Map">
  <sequence>
    <element name="item" minOccurs="0" maxOccurs="unbounded">
      <complexType>
        <all>
          <element name="key" type="xsd:anyType"/>
          <element name="value" type="xsd:anyType"/>
        </all>
      </complexType>
    </element>
  </sequence>
</complexType>

This complex type represents an arbitrary number of key/value pairs. Note that keys and values can be any datatype (xsd:anyType).

The WSDL representation of a ColdFusion query is a little more complex. It is represented as a complex type called a QueryBean. A QueryBean is essentially an object containing a one-dimensional array of column names and a two-dimensional array containing the actual query data. Example 24-8 shows a simple ColdFusion web service that returns a query (QueryBean).

Example 24-8: Returning a query (QueryBean) from a ColdFusion-based web service

<cfcomponent>
  <cffunction name="getQuery" access="remote" returntype="query"
              output="no">
    <cfquery name="getEmployees" datasource="programmingcf">
      select *
      from employeeDirectory
    </cfquery>
    
    <cfreturn getEmployees>             
  </cffunction>
</cfcomponent>

The resulting WSDL file contains the QueryBean mapping, as follows:

<complexType name="QueryBean">
  <sequence>
    <element name="columnList" nillable="true" type="impl:ArrayOf_xsd_string"/>
    <element name="data" nillable="true" type="impl:ArrayOfArrayOf_xsd_anyType"/>
  </sequence>
</complexType>
   
<complexType name="ArrayOf_xsd_string">
  <complexContent>
    <restriction base="soapenc:Array">
      <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[  ]"/>
    </restriction>
  </complexContent>
</complexType>
   
<complexType name="ArrayOfArrayOf_xsd_anyType">
  <complexContent>
    <restriction base="soapenc:Array">
      <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:anyType[  ][  ]"/>
    </restriction>
  </complexContent>
</complexType>

Created: March 27, 2003
Revised: Sept 1, 2003

URL: http://webreference.com/programming/coldfusion/2