Web Services in ColdFusion 7JaxFusion November, 2006

About the Presenter

» David Fekke» API Team» Integration Developer» Working with SOAP based Web Services

since 2002 when .NET 1.0 was released

What will be Covered

» SOAP standard» WSDL files» Creating Web Services» Consuming Web Services» SOAP Headers in 6.1 and 7.0» RPC vs Document style» REST vs SOAP» Cross Platform issues» Changing location endpoints

SOAP standard

» Simple Object Access Protocol » Based on XML over HTTP» Used for application to application

communication» It is platform and language agnostic» Came from XML-RPC» SOAP standard ratified in 2001» ColdFusion uses Apache Axis

WSDL

» Web Service Description Language» XML file that describes methods,

parameters, data point and service address location

» 11 parts to a WSDL file» Four different styles, but only two

supported by ColdFusion 7

<?xml version="1.0" encoding="UTF-8"?><wsdl:definitions targetNamespace="http://DefaultNamespace" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="http://DefaultNamespace" xmlns:intf="http://DefaultNamespace" 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,2,142559--> <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="echoResponse"> <wsdl:part name="echoReturn" type="xsd:string"/> </wsdl:message> <wsdl:message name="echoRequest">

Creating Web Services

» CFCs are used to create Web Services» Method access modifier set to “Remote”» Duck typing should not be used with SOAP

or Flash Remoting» Avoid using complex types such as

Structures, multi-dimensional arrays, Query objects

<cfcomponent name="EchoService" displayname="myEchoService" hint="Echos a string">

<cffunction name="echo" hint="This echos a string back to the caller" access="remote" output="false" returntype="String">

<cfargument name="inString" type="String" required="true" />

<cfset var returnString = "" />

<cfset returnString = arguments.inString /><cfreturn returnString />

</cffunction>

</cfcomponent>

Consuming Web Services

» CFObject tag» CFInvoke tag, CFInvokeArgument tag» CreateObject() function» wsObj =

createObject(“webservice”,”http://localhost/EchoService.cfc?wsdl”)

» returnValue = wsObj.echo(“Echo this string”)

Handling Complex return values

» Hosting CF based SOAP, use separate CFC with CFProperty tags instead of structures to describe in the WSDL file.

» CFDump tag really good for debugging» Complex values look like Java objects to

ColdFusion

SOAP Headers

» Different ways of handling in 6.1 and 7» Some vendors require SOAP headers» Different from cgi.Headers

SOAP Headers in 6.1

» Requires patch after 6.1 or the 6.1 updater

» Adobe has UDFs that mimic most of the behavior in 7

» Create a HeaderElement using Java object» "org.apache.axis.message.SOAPHeaderEle

ment“» Pass to setHeader method

<cfset WSObj = createObject("webservice","https://www.somecompany.com/services/somews.asmx?wsdl") /> <cfset doc = XMLNew() />               <cfset doc.Authentication = XmlElemNew(doc, "https://www.somecompany.com/services/ ", "Authentication") /><cfset doc.Authentication.username = XmlElemNew(doc, "username") /><cfset doc.Authentication.username.XmlText = "myUsername" /><cfset doc.Authentication.password = XmlElemNew(doc, "password") /><cfset doc.Authentication.password.XmlText = "myPassword" /><!---<Authentication>   <username>myUsername</username>   <password>myPassword</password></Authentication>-<cfset jXMLdoc = doc.getDocumentElement() /> <cfset headerElement = createObject("java","org.apache.axis.message.SOAPHeaderElement") /><cfset headerElement.init(jXMLdoc) /><cfset WSObj.setHeader(headerElement) /><cfset responseValue = WSObj.makeWSCall() />

SOAP Headers in 7

» Built-in methods» AddSOAPRequestHeader()» AddSOAPResponseHeader()» GetSOAPRequestHeader()» GetSOAPResponse()» GetSOAPResponseHeader()» IsSOAPRequest()» GetSOAPRequest()

RPC vs Document style

» Style attribute in the cfcomponent tag» <cfcomponent style="document">» Default style is RPC» Common WSDL styles are RPC/encoded

and Document/literal and are supported by ColdFusion

REST vs SOAP

» Representational State Transfer » Simple HTTP get or post» REST popular with AJAX applications

because of simplicity» REST does not require verbose XML like

SOAP» SOAP based on standard XML syntax» SOAP libraries can handle extra complexity

Cross Platform issues

» Java and .NET support types not supported by standard SOAP types

» DataSet is supported by .NET» Standard XML types supported» Fix is to serialize XML into a string

Changing location endpoints

» Endpoint is the URL for the web service » Default endpoint is set in the WSDL file» ws = CreateObject("webservice",

"http://localhost/service.cfc?WSDL");» ws._setProperty("javax.xml.rpc.service.end

point.address", "http://92.169.1.20/service.cfc");

Useful tools

» CFusionMX/runtime/bin/sniffer.exe» http://www.soapclient.com/» MicroSoft Fiddler» NetBeans 5 Web Service

Links

» http://tjordahl.blogspot.com/2005/12/changing-target-endpoint-on-web.html

» http://www.macromedia.com/go/tn_18939» http://www.fekke.com/blog/index.cfm/200

5/9/21/UsingSOAPRequestHeadersinCFMX61

» http://www.fekke.com/blog/index.cfm/2006/6/9/Make-SOAP-based-Web-service-calls-with-Spry

» http://rip747.wordpress.com/2006/10/30/dotnet-dataset-to-cf-structure-of-queries/