I love Railo (And since recently: Lucee). However, recently I’ve ran into some problems with webservices that either required a complex object to be passed as an argument, or webservices that return a complex object. Most notorious are the .NET webservice which cause a lot of trouble when trying to access them using ColdFusion.
In the 4.2 release Railo fixed most of these bugs:
[RAILO-2976] – webservice Complex Objects as arguments don’t get accessible data.
[RAILO-2978] – Soap webservices Complex type composed of an array of complex types, throws exception
[RAILO-3003] – webservice with component argument breaks
But for one of our biggest projects these fixes didn’t seem to do the trick. I’ve got a Java background, and since ColdFusion is Java based I decided to give the WSDL2JAVA tool a go. WSDL2JAVA is a tool that reads a WSDL and converts it to Java classes (Stubs, skeletons etc.). You can then use these classes to access your web service. I guess Railo / ACF both use this tool internally to generate stubs etc, but probably not in the way I wanted them too, since using it manually magically solved all our problems 😉
This blog will show you how to do this, package everything into a single JAR and show you how to access the webservice.
First off you start out by downloading eclipse:
After it’s downloaded and installed we can begin the process of generating our JAR:
- Create a new Java project in Eclipse.
- Create a new folder in your project called ‘lib’.
- Go to your railo/lib folder and copy all the .jar files to the ‘lib’ folder in your project.
- Right-click on your project project and go to: Properties -> Java Build Path -> Libraries.
- Choose ‘Add jars’ and add all the .jar files from the ‘lib’ directory.
- Create a new ‘Run configuration’ (Little arrow next to the green play button on top).
- Choose ‘Java Application’ and change the main class to: org.apache.axis.wsdl.WSDL2Java
- Open the ‘arguments’ tab and add the address of the WSDL of the webservice.
- Click ‘Apply’ and then ‘Run’.
- Refresh your project folder.
- New folders will be generated (‘com’ and ‘Framework’). Copy those to the ‘src’ folder.
- Click File -> Export -> JAR file.
- Expand your project in the left pane and uncheck ‘lib’.
- Export the JAR to the location of your choice.
You will now have a JAR file which you can use to access your web service. The next step would be to copy the JAR file to your class path. For example: [drive]:\railo\lib and restart your Railo server. It can probably also be loaded using a Java classloader, but that falls outside the scope of this article.
Before using the JAR I usually like to take a look at the Java packages it contains, to that I know the exact packages / classes to use in my ColdFusion code. The easiest way is to create a copy of your JAR file and rename the extention to ‘.zip’ and unpack this ZIP file. You will see a folder structure that indicate the package / class structure. This will be different for any webservice you consume, but for this example we are using the following package structure:
com -> companyname -> xml -> Services -> WebServices -> MyWebService.V1_0.MyWebServiceLocator
To create the webservice component use the following ColdFusion code:
<cfset endPointURL = "http://www.myserver.com/mywebservice.asmx"/>
<cfset myURL = createObject("java","java.net.URL").init(endPointURL)/>
<cfset webservice = CreateObject("java", "com.companyname.xml.Services.WebServices.MyWebService.V1_0.MyWebServiceLocator").getWebServiceSoap(url)/>
The <cfdump> will expose the webservice object and al it’s methods you can now use in your ColdFusion project!
Off course the way these methods work will be different for every webservice you consume. So if you run into any problems setting this up: Let me know!