Building Web Services | Inside Coldfusion MX

We actually just produced a web service and consumed it, and we did it without knowing almost anything about SOAP or WSDL. Producing web services in ColdFusion is incredibly simple, much simpler than if you tried to do it directly with Java and AXIS and even easier than building web services with .NET!

ColdFusion web services are built around CFCs, which provide a simple and elegant method for defining your web services (see Chapter 6, "ColdFusion Components").

In the preceding section, we made a CFC called square.cfc that we made remotely accessible using the access attribute and setting it to remote. If you want to use a CFC as a web service, you must set the access attribute to remote.

That's all there is to making a simple web service. Things get a little more complex, though, when you try to work with ColdFusion web services you create that use parameters of type struct or query in that they do not directly map to a WSDL data type. (If you are working with a ColdFusion application that's going to consume a web service with parameter types of query or struct, you do not need to worry in that ColdFusion correctly handles these complex data types.)

The problem with structures stems from their capability to hold an unlimited number of key-value pairs, where the values can be of any ColdFusion data type. Because of this, it cannot be directly mapped to any XML data types defined in the SOAP 1.1 encoding and XML Schema specification.

ColdFusion structures are treated as a custom type, and the complex type in the XML Schema in WSDL looks like this:

 <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 defines a representation of a structure, where the structure keys and values can be any type.

In the WSDL mapping of a ColdFusion structure, each key-value pair in the structure points to the next element in the structure (such as a linked list) except for the final field, which contains a value.

ColdFusion queries also can cause issues , and ColdFusion publishes query data types as the WSDL type QueryBean. The QueryBean data type contains two elements, as illustrated here:

 <complexType name="QueryBean">    <all>      <element name="data" nillable="true" type="intf:ArrayOf_SOAP-ENC_Array" />      <element name="ColumnList" nillable="true"  type="intf:ArrayOf_SOAP-ENC_string" />    </all>  </complexType>

The two elements of QueryBean are as follows:

ColumnList. A string array that contains column names
data. A two-dimensional array that contains query data

The WSDL file for a QueryBean defines these elements as follows:

 <complexType name="ArrayOf_SOAP-ENC_Array">    <complexContent>      <restriction base="SOAP-ENC:Array">        <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="SOAP-ENC:Array[]" />      </restriction>    </complexContent>  </complexType>  <complexType name="ArrayOf_SOAP-ENC_string">    <complexContent>    <restriction base="SOAP-ENC:Array">      <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]" />    </restriction>    </complexContent>  </complexType>

You need to be aware of these issues when you're creating your own web services that need to interoperate with other systems like .NET. One way around this potential hurdle is to just pass the record set as WDDX instead of using a complex type of query. Almost every application platform can consume WDDX, and it's a lot easier than trying to programmatically deal with the ColdFusion MX QueryBean complex type.