Table of contents
21 May 2012
Adobe ColdFusion 10 makes Axis2 web services from Apache easily available to you in ColdFusion 10. Earlier, you could use Axis1 web services with ColdFusion 9 for publishing and consuming web services. Axis2 web services has lot of advantages over Axis1. In this section, you will learn about what is new and how you can work with Axis2 web services with ColdFusion 10, and how you can best take advantage of these new features.
The following list highlights what's available to you as you work with Axis2 web services in ColdFusion 10.
SOAP 1.1 and SOAP 1.2 support: ColdFusion 10 supports Soap 1.1 and SOAP 1.2 formats.
WSDL2 support: To fetch WSDL2, append
?wsdl2after the CFC URL, as you would do when you wish to fetch WSDL.
Wrapped, styled web-services support: Now ColdFusion supports wrapped style WSDL too. When you use Axis2, you will get WSDL in wrapped format by default.
Complex and nested data type support: Similar to Axis1 web services support, ColdFusion 10 supports all the ColdFusion data types, including "any".
Easy implementation: You can shift from Axis1 to Axis2 web services or vice-versa with minimal code changes. You can modify the settings for the Axis version that you use for publishing at the server, application and component level. It's very easy to change your existing code from Axis1 to Axis2.
The following section explains how you can best take advantage of web services in ColdFusion 10.
New settings for web services in the ColdFusion Administrator
We have added new settings in ColdFusion 10 that give you better administrative control of web services.
- Web Service version setting: You can set this option to 1 or 2. This setting specifies the Axis version that ColdFusion uses for publishing the web services at the server level. You can define this attribute at the component, application, and server level. The default value is 2. Thus, if you want to publish a CFC and you have not specified the version number at the application or component level, ColdFusion will publish the web service you have specified at the server level.
Note: If you have web services set up with ColdFusion 9, you can check their compatibility quickly by simply setting the web service version to 2 at the web server administrator level; if you do so, ColdFusion will publish all your existing web services using Axis2. Note that you can always revert back to 1.
- Proxy settings: Now along with web service name, WSDL URL, username, and password, you can also set the proxy settings in the administrator. Thus, if you need to use the proxy settings in all of your web services, you can simply set that up in administrator and ColdFusion implements the setting to all web services. These settings include: Proxy Server, Proxy Port, Proxy Username, and Proxy Password.
- Timeout setting: Set this server-level setting to time out any web service request in a particular time period.
There are also several behavior changes for web services in the ColdFusion Administrator.
Web services: The way it was before ColdFusion 10
Before ColdFusion 10, users registered a web service in the administrator in one of the following ways:
- You could register the web service directly within administrator user interface.
- Creating a web-service object from code will automatically register it in Administrator.
- Moreover even if someone accessed an already-registered web service from code, he/she could change its username/password, and other information for the web service in the ColdFusion Administrator.
- For example, let's say you registered a web service in the administrator with a name "xyz," username "foo," password "pass," and a WSDL path.
- Now, if a user accessed this web service from code with a username "foo1," password "pass1," ColdFusion Administrator registered the web service with this new username and password .
<!--- This will change the username/password in the administrator ---> <cfinvoke method="echo" webservice="xyz" username="foo1" password="pass1" >
The next time anybody accessed the registered service without specifying a username and password, ColdFusion would take, by default, the username "foo1" and password "pass1."
<!--- This will use the username/password as 'foo1/pass1' instead of 'foo/pass' ---> <cfinvoke method="echo" webservice="xyz" >
Now with ColdFusion 10, users register a web service in the administrator in one of the following ways:
- Now in ColdFusion 10, creating a web-service object from code will not register it in ColdFusion Administrator; instead a user must go to the ColdFusion Administrator and specifically register it there.
- If user uses a registered web service with the username/password "foo1/pass1" in the tags
createobject, the call will not change the username/password in the ColdFusion Administrator. This also means that the next time a user tries to access that registered web service without specifying a username/password, by default ColdFusion will use the username/password of "foo/pass."
<!--- This will NOT change the username/password in admin ---> <cfinvoke method="echo" webservice="xyz" username="foo1" password="pass1" > <!--- This will use the username/password as 'foo/pass' ---> <cfinvoke method="echo" webservice="xyz" >
This not only applies for username/password but all of the attributes for the web service that you can specify in ColdFusion Administrator, such as
proxypassword, and so forth.
Note: Do not panic if ColdFusion Administrator doesn't automatically register your web services accessed from code, it's expected behavior.
Web services: Why we implemented these behavioral changes for web services in ColdFusion 10
The ColdFusion team implemented these behavioral changes for security reasons. As I have mentioned earlier, whenever a user accessed a web service, ColdFusion server registered it in the ColdFusion Administrator with username/password details. Because of this, anybody who knew the URL you had registered for the web service in ColdFusion Administrator, could use the web service without specifying a username/password, as the call would pick up these details from ColdFusion Administrator. But now, nobody can use your web service until you register it in the ColdFusion Administrator.
New application-level attributes for web services
You can specify following attributes in Application.cfc and ColdFusion will apply the specifications to all the application files:
this.wssettings.version.publish="1/2": Use this attribute to set the Axis version used for publishing the web services. ColdFusion uses this setting for all the web services under an Application until and unless you override it with component-level settings.
this.wssettings.version.consume="1/2": Use this attribute to consume the web services in the same way you use
this.wssettings.version.publish="1/2"to publish the web services. Note that if you publish a web service using Axis2, you must consume it using Axis2 only; similarly, if you publish a web service published using Axis1, you must consume it using Axis1.
this.wssettings.style: Use this attribute to set a default publishing style for the WSDL. Valid values to specify include:
a. Wrapped: Use this attribute with Axis2 only
b. Document: Use this attribute with Axis1 or Axis2
c. RPC: Use this attribute with Axis1 only
this.wssettings.includeCfTypesInWsdl="true/false": By default this attribute is set to
true. If you set this attribute to
false, you will not be able to use complex data types with Axis2 in ColdFusion. In other words, if you are not using ColdFusion complex data types such as
Array, and so forth, in your web services, you can set this attribute to
falseto keep your schema simple. Behind the scenes, if you set this attribute to false, ColdFusion will not generate schema for complex data types in WSDL that Axis2 generates. By default, ColdFusion generates schema for complex data types. If you are unsure how to use this attribute, simply ignore it and everything will work fine.
<cfcomponent> <cfset this.wssettings.version.consume = "2"> <cfset this.wssettings.version.publish = "2"> <cfset this.wssettings.style = "Wrapped"> <cfset this.wssettings.includeCfTypesInWsdl = "true"> </cfcomponent>
New component-level attributes for web services
The following attributes override application-level and server-level settings.
wsversion="1/2": Specify this attribute at the component level to specify which Axis version you wish to use to publish your web service.
Style: Specify the style of WSDL you want to publish. Valid values are as follows:
- Wrapped: Use this with Axis2 only
- Document: Use this with Axis1 or Axis2
- RPC: Use this with Axis1 only
<cfcomponent wsversion="2" style="Document" > <cffunction name="echoString" access="remote" returnType="string"> <cfargument name="argString" type="string"> <cfreturn argString> </cffunction> </cfcomponent>
Specifying version for consuming web services
As I have already mentioned, you must consume the web service using Axis2 if you pu`blished the web service using Axis2; the same rule applies with Axis1. To consume the web service using the correct version, use the following steps:
this.wssettings.version.consumeat the application level, as described above.
- Pass the version number as an attribute while consuming the web service.
<cfinvoke webservice = "http://localhost:8500/mycfc.cfc?wsdl" method="echo" wsversion="2" returnVariable="foo" >
Ensuring WSDL2 Support
You can publish your web service with WSDL2 using Axis2 without specifying anything extra in the component. All you need to do is access your already published web service with the following URL: "
http://my_url/myservice.cfc?wsdl2". The WSDL generated will be in WSDL2 format.
This article described how you can take advantage of using advanced web services with the latest protocols, support almost all formats, use WSDL2, implement more security, manage web services better from the server-, application-, and component-level, so that you can build more stable, robust and powerful Applications and APIs using ColdFusion 10 web services. Read the ColdFusion 10 Help documentation for detailed information about web-services. Also, visit my blog, Milan Chandna: ColdFusion and other stuff, to learn more tricks and tweaks as you use web services.