Wednesday, October 22, 2008

LiveCycle Data Services Capicity Planning Guide

Adobe has published a Capacity Planning Guide white paper that gives guidance and test results on how LiveCycle Data Services scales up to to thousands of end users.

Stealing from the introduction:

This document presents the results of software benchmark tests performed by Adobe engineers in 2008. These tests show how LiveCycle Data Services 2.6 software can scale and perform under load using various messaging scenarios that represent real-world situations. The goal of this paper is to provide a starting point for those who need to plan a hardware and software infrastructure that can scale to meet peak demand.

Check it out here: Adobe LiveCycle Data Services 2.6 Capacity Planning Guide

Friday, August 29, 2008

BlazeDS HTML LiveDocs updated

The BlazeDS HTML Livedocs are now updated to match the updated PDF files I posted about a while ago. This brings the BlazeDS document up to date with the release of LCDS 2.6, including a much better organization of the chapters to explain the RPC and messaging concepts.

I think most folks use the HTML version, not the PDF (I know I do), so it was pretty confusing having two different versions of the doc around, with the most popular being the out of date version.

Thanks to the documentation team for responding to our complaints!

Invoking Flash remoting requests using the Java AMF Library

In a follow up to my recent post about the new Java AMF client available in BlazeDS, I was recently asked how to send a 'typical' flash remoting request to ColdFusion.

Here is how you do that in Java:

Object[] args = ...
String sourceName = "my.cfc.path.Component";
RemotingMessage message = new RemotingMessage();
Object returnValue =, message);

and accessing the body of the response like this.

Object body = ((AcknowledgeMessage) returnValue).getBody();

Not that the "args" variable is an array of the arguments you are passing to the CFC function. It can also be a Java List, or a simple object. See the BlazeDS source for for details. This sends the same kind of message that the mx:RemoteObject tag does in MXML, so in ColdFusion terms you are using the "Flash Remoting Update". If you use the 'raw' AMFConnection API, you would be using the "classic" Flash Remoting. Both will work, but I recommend using the RemotingMessage style.

What does this do for you? Well if you are exclusively using Flex as a client, not much. But if you would like to write Java code to invoke a CFC, this alows you to do that very easily.

Wednesday, August 06, 2008

New Java AMF Client feature in BlazeDS

You may not have noticed, (what, you aren't subscribed to the BlazeDS commits forum?) but a few weeks ago Mete committed an enhancement that adds a Java AMF client API to the flex-messaging-core.jar file in BlazeDS.

You can find a specification posted here and its linked from the Developer Documentation page.

What does this do? Well, you can use this API to call (from Java) Flash Remoting end points in BlazeDS, LiveCycle Data Services, ColdFusion, PHP or whatever you have that supports AMF. Which of course is a published specification.

This feature is available in any nightly build after or in the trunk nightly build. Find those builds on the BlazeDS build download page.

Thursday, July 31, 2008

BlazeDS Documentation Update

The documentation team has posted an update of the BlazeDS documentation that includes all of the relevant content from the new LCDS 2.6 Developers Guide.

By the way, here is a gateway page to all of the LCDS 2.6 documentation, which has been reorganized to be much easier to read and use.

The HTML in Livedocs has not been updated yet, but a new PDF version is available.

See details on the Flex documentation blog here.

Tuesday, July 22, 2008

AIR Data Synchronization via LiveCycle Data Services ES 2.6

This is a nice article on the offline sync feature of LiveCycle Data Services 2.6 - AIR Data Synchronization via LiveCycle Data Services ES 2.6. It was written by John C. Bland II.

I worked on this feature for LCDS 2.6 (which by the way just got released last week). The SQLite DB built in to AIR is really nice to work with and the Actionscript APIs for using it were nicely designed by Jason, one of my coworkers here at Adobe.

I think the offline feature is pretty neat. There is still lots of room for improvement, but the basics that we do have are pretty powerful. We are in the planning stages for the next LCDS release and I expect that improving our offline story, particularly for AIR, will be on the list.

Check it out!

Friday, July 11, 2008

Setting optional parameters in the SMS Gateway

Paul Hastings sent me a questions yesterday about the ColdFusion SMS Event Gateway. He wanted to know how users could set their own optional parameters in the text messages sent from the gateway. He blogged my answer, which means I can just link to it without writing it up myself.

A few notes: If the gateway receives optional parameters in a message, it will be included in the data struct that is returned to the onIncomingMessage CFC function under the "optionalParameters" key. CFDump to a file or console is your friend in these cases.

If you do not format the key (has to be able to be parsed by the Java Short.decode(String) function) or the value (must be a byte[], which in CFML is a "binary object") correctly the setting is silently ignored.

This functionality has been in the SMS Gateway since 7.0.2. It is not in the 7 or 8 documentation, which is bad, but we will correct this moving forward.

Wednesday, July 02, 2008

Special Axis types and ColdFusion

A mere hours after I posted about how to figure out why CF does not like the arguments you are passing to invoke an operation in a web service, Sean Corfield pinged me with a problem exactly like that. Feeling pretty good, I pointed him to the post I made hours before. He of course had already tried the wsdl2java trick and still could not get CF to do the deed.

He sent me the WSDL and his test and everything looked OK. It was a pretty complex input to an operation (names changed to protect privacy):
public com.example.RegisterResponse register(com.example.RegisterRequest parameters)

The RegisterRequest was a JavaBean that included the following members:

private java.lang.String sessionID;
private com.example.ThingyType importantThing;
private com.example.ThingyType otherThingy;
private com.example.ThingsILike likeList;
private org.apache.axis.types.UnsignedInt duration;

Fun stuff. Sean had done all the right things creating CFML structs that matched each of the JavaBean types (ThingyType, and ThingsILike). ThingsILike was interesting because it contained a single item that was an array. His code was right on the money here, notice that the ThingsILike object had a single member named "things" that was the array. Here is what he did and (rightfully) expected to work:

thing1 = { name = "bobby", location = "Portland" };
thing2 = { name = "sally", location = "Boston" };
iLike = { things = ["Bunnies", "Kittens", "Koalas", "ColdFusion"] };
args = { sessionID = 0, importantThing = thing1, otherThingy = thing2, likeList = iLike, duration = 60 };

Bonus points to Sean for using the new ColdFusion 8 syntax to create arrays and structures. So the array wasn't the problem. What was? Well you may have noticed that duration is listed in the Java function as being of type org.apache.axis.types.UnsignedInt. this is because the XMl Schema type in the WSDL says that the number is an Unsigned Integer:

<xsd:element name="Duration" type="xsd:unsignedInt" />

As an aside here, XML Schema has a lot of different types that elements can be. Things like NonNegativeInteger, nonPositiveInteger and other slightly wacky things. Java on the other hand doesn't have any of these. So the Axis folks (which included me) came up with a set of classes that would enforce the limitations of the Schema types and allow you to 'round trip' a service that you generated from a WSDL, then deployed and allowed Axis to create the WSDL from the Java. This is good, and when you are writing Java directly against the WSDL2Java generated code no big deal because you can pretty quickly notice that you need one of these types and make one.

But back to ColdFusion. In order for the "60" given in the code to turn in to the class UnsignedInt, ColdFusion has to be smart about how to construct this object. It's not. However there is a simple work around - create the object yourself. Here is how that would look:

duration = CreateObject("java", "org.apache.axis.types.UnsignedInt").init(60);

Notice that I call init(60), which invokes the constructor of the class. Setting this object as the value of duration in our argument structure works like a charm. So problem solved, and I hope that we can make CF smarter about these types in a future release, but encountering these XML Schema types in the wild is pretty rare so I don't expect you will need this workaround much if at all.

Using WSDL2Java to figure out CFML arguments to a Web Service

For some reason I haven't actually even written up the procedure I use to figure out how to invoke a web service from ColdFusion when people ask me what CFML structures they need to pass in so CF can match the arguments to a function in the Apache Axis stub it generated from the WSDL.

I encourage you to read the reprint of Consuming Web Service complex types in ColdFusion which goes in to some great detail on how to figure this out. This posting is going to be the cheat sheet version of that.

First, if you can't figure out why CF gives you an error about not finding the right function to invoke, you probably aren't passing in the right arguments. How do you figure these out? You run the WSDL2Java command in Apache Axis, and take a look at the Java code CF is trying to invoke. Here's a batch script for Windows and ColdFusion 8:

set CFLIB=c:\ColdFusion8\lib
set CLASSPATH=%CFLIB%\axis.jar;%CFLIB%\wsdl4j-1.5.1.jar;%CFLIB%\log4j-1.2.12.jar;%CFLIB%\commons-logging.1.0.4.jar;%CFLIB%\commons-discovery-0.2.jar;%CFLIB%\xercesImpl.jar;%CFLIB%\xml-apis.jar;%CFLIB%\saaj.jar;%CFLIB%\jaxrpc.jar;%CFLIB\..\runtime\lib\jrun.jar

java org.apache.axis.wsdl.WSDL2Java %1 %2 %3 %4 %5 %6 %7 %8 %9

Save this as "wsdl2java.bat". This will also work with ColdFusion MX 7. You will need to change the log4j-1.2.12.jar file to be just log4j.jar.

Change to an empty directory. Wsdl2Java is going to spew directories and files all over the current directory, so I find its best to create something like c:\temp\x and run the command from there. Otherwise you can give the -o option and specify the output directory.

wsdl2java.bat -v -o c:\temp\x

The -v is the verbose argument. I like to see all the files that are being created.

Now you can start browsing through the Java files and see what we have to work with. Look for a file named the same as the "portType" name in your WSDL. For instance, if your WSDL contains a portType that looks like this:
<wsdl:portType name="CodexWS">

Then you would look for This will be the interface of the service, and you should be able to see each of the operations in your service, and the Java objects that ColdFusion will be trying to create to call them.

How do you create the CFML to pass to the operation? Simple. Most likely there will be JavaBeans created from the XML Schema in the WSDL. These aren't that big of a deal, basically they are structures with name/value pairs, which is why you will need to make a CFML structure with the same names in it.

Check out this Bean:

public class AddThingRequest implements {
private java.lang.String manifestfile;
private java.lang.String uri;
private java.lang.String certlevel;
private java.lang.String statusname;
private com.adobe.Ldapcredentials ldapcredentials;

There would be a getManifest() and setManifest() function in the bean also, along with a get and set function for each one of the other bean properties. These only matter because this is what CF will look for when it finds a "manifest" entry in your CFML structure. So what would we pass in to an operation that takes an "AddThingRequest" object as an argument? Something like this:

atr = StructNew();
atr.manifestfile = "foo";
atr.uri = "uri:gimme";
atr.certlevel = "high";
atr.statusname = "Alert";
art.ldapcredentials = mycreds;

But wait, you say, what is "mycreds"? Well, the process just repeats here - we would go find the com.adobe.Ldapcredentials Java object, look at the properties it contains and make a CFML structure (mycreds in this example above) that matches it.

So that's all (ha!) there is to it. You now have the magic to invoke almost any web service out there. This isn't exactly "making the hard stuff easy" (that would be that WSDL2CFML tool I haven't written yet), but once you understand how the process works, you should very rarely have to resort to grunging through the Java code generated from a WSDL to construct the right CFML inputs. My opinion is that Web Services should be designed to present an easy to use interface, simple inputs with only reasonably complex outputs. I know that isn't the case for many services out there that you are forced to used. But with this technique you should be able to easily figure out how to use the more complex ones.

Friday, June 27, 2008

CFUnited LiveCycle and ColdFusion session online

For those who were unable to attend my session at CFUnited this year, the CFUnited blog has posted the URLs of many of the sessions that got recorded via Adobe Connect. My session was recorded and is now online here. This talk has some new content about the difference between BlazeDS and LiveCycle Data Services.

The audio is very "hot" - when setting up the microphone the output from the in-room audio system was just super loud so I am distorted, but I think the session is still tolerably understandable. I am much better in person however. See you at MAX 2008. :-)

Wednesday, May 28, 2008

MAX 2008 registration is now open

MAX 2008 registration is now open. Check out more information at the MAX web site here.

MAX is the descendant of the Allaire ColdFusion Developers Conference, which turned in to the Macromedia DevCon, which morphed in to Macromedia MAX and is now Adobe MAX. This year it is going to be in San Francisco, which will be great. Not as great as MAX 2006 in Las Vegas IMHO, but SF is a fun place to visit. :-)

I will be giving a session on Livecycle Data Services and BlazeDS deployment, probably with a slant toward integrating with ColdFusion. But anyone who is interested in learning more about Data Services, BlazeDS and how they can leverage the power of these technologies in to their web applications using Flex should get a lot out of it.

Tuesday, May 20, 2008

Offline sync sample application

Christophe has posted another great LCDS sample application that uses the offline synchronization feature of Data Services to good effect. This is one of the features that I worked on for the upcoming LiveCycle Data Services 2.6 release, which is in beta right now up on Adobe Labs. Check it out here.

Friday, May 09, 2008

New blog on FlexBuilder 4 features

Scott Evans, a lead engineer on the FlexBulder team, has started a new blog - Getting and Setting that will be for public discussion of new FlexBuilder 4 IDE features. I am really excited by some of the "IDE Maturity" features that I've seen on the drawing boards for the next FlexBuilder. As an avid InteilliJ IDEA user for my Java development, my tumultuous affair with builder has been a tough ride. I am drooling over most of the improvements that I see coming.

He starts out with his lead post asking about how you use Actionscript "getters" and "setters". Do you use a special prefix for your class member variables? Do you create functions as a matter of course? Or only when you actually need them? Post a comment and let Scott know.

I also encourage you to check out Tim Buntel's $100 test posting asking for feedback on what feature you think are worth investing our resources in. He has recently posted an update on the results, which, I pointed out to Scott, valued the getter/setter generation very high on the list. Of course improving the MXML compiler speed was at the top of many folks lists.

Tuesday, May 06, 2008

Conflict bug in ColdFusion Extensions for Eclipse

If you are trying to use ColdFusion as the back end to a LiveCycle Data Services Data Management application, you should know about the extensions to Eclipse/FlexBuilder that ship with ColdFusion 8 (and 7.0.2). You can download them from the CF download page here.

One of the great features of these extensions is the ability to use the RDS Dataview window to generate CFCs and Actionscript classes from your database tables, saving you lots of tedious typing. To do this go to Window -> Show View -> Other... -> ColdFusion -> RDS Dataview. This will open the panel that allows you to browse your data sources via RDS. Right click on the panel and select "RDS Configuation" to open the settings dialog and configure your RDS server. For instance I have my local CF server configured as:
Description: localhost
Host Name:
Port Number: 8500

I am using the built in web server (port 8500) and the stand alone configuration, so there is no context root. You must have RDS turned on in your installation (see technote here for details) .

Once you have the panel open and have access to your ColdFusion data sources, you can open up a DSN, open the "Tables" folder and right-click on a table name. You can show the contents of the table or open up the Query Viewer (on Windows) and run an arbitrary query. At the bottom of the context menu you should see "ColdFusion Wizards". Select that and the sub menu is "Create CFC".

This gives you a dialog that allows you to create CFCs that correspond to this table in your database. Not only that, it will create either "Active Record" or "Bean/DAO" style CFCs that know how to create, read, update and delete (CRUD) themselves! This is pretty cool in an of itself, but if you are using LCDS to write a Data Management application, this wizard can also write the Assembler CFC (the component that has the required methods for LCDS) for you. This selection is named "LiveCycle Data Services Assembler CFC's". It will generate the Bean CFC (representing 1 row of data), the Data Access Object (DAO) CFC, which has read/write/update/delete methods and the Assembler CFC itself, which uses the Bean and the DAO CFCs to do its work.

Neat, huh?

You can even create the Actionscript class that is used in the Flex application to represent your data when it gets to the client.

This code will work right out of the gate if you have a simple single table application. You can use it as a jump start for more complex applications that have multiple assemblers and a more complex data dependencies.

Unfortunately, there is a bug in the generated code when it comes to conflict detection. As part of the "sync" method, there are private functions which perform the create, update and delete operations (named doCreate, doUpdate and doDelete respectively). If you examine the doUpdate and doDelete methods, you will see a cfcatch clause with type="conflict". This calls the ChangeObject's conflict() function. This function takes as its argument the server's version of the object we are trying to update or delete, so the client application will have all three versions of the data - old, new and the server version:

<!--- If there was a conflict, mark the change object.
Include the current version of the record --->
<cfcatch type="conflict">

The problem is that the code is using the DAO read() method to get the server's version of the object. If you take a look at the DAO code, the return type is defined to be this:
<cffunction name="read" output="false" access="public" returntype="[]">

This is an array, which is not what we want to put in the ChangeObject for LCDS. What we really want to put in this object is a single record and to do this, we have to unwrap the array returned by read():

<cfcatch type="conflict">
<cfset readresult =>
<cfset serverversion = readResult[1]>
<cfset co.conflict(serverVersion)>

You may want to include some error checking code in here to verify that the call to read() has returned exactly one result (it should as in the case ARTISTID is the primary key in the table). You also may want to "var" the readResult and serverVersion variables at the top of the function to keep them local (yes, this is annoying, yes we need to fix that).

An alternative approach is to invoke the get() method on the Assembler itself, which will take care of unwrapping the array and throwing errors if there is a problem. In order to do this you would need to create a Struct that contained "ARTISTID" as the get() function takes a map of name/value pairs to support the possibility of multiple primary keys. So this fix would look like this:

<cfcatch type="conflict">
<cfset uid = {ARTISTID=new.getARTISTID()}>
<cfset serverVersion = read(uid)>
<cfset co.conflict(serverVersion)>

Notice the use of the new ColdFusion 8 structure initialization!

I can't believe we (specifically I) didn't notice this problem before, but as it turns out my conflict functions did not make use of the server version of the records in all of the applications I have written so I (and I guess our QA folks) didn't notice the problem until just recently. On the bright side, this should be an easy thing to fix (and hopefully we will fix it in future releases of the Eclipse extensions) and gives me an opportunity to talk about this really helpful feature of the Extensions.

Wednesday, April 16, 2008

About me updated

I realized that my "About Me" link article hadn't been updated in quite a while, so I added some recent information and filled in my resume (such as it is) for the time before I worked at Allaire/Macromedia/Adobe. It was hard for me to remember (I've been here for 11 years last month!) but I found out you can download DCE as open source, and that there isn't really much information about OSF/1 out on the web. This is a real shame since I still am very proud of what I was part of waaaay back in 1990. :-)


Thursday, April 10, 2008

Reprint: Consuming Web Service complex types in ColdFusion

In previous posts I have referenced an excellent article written by Doug James and Larry Afrin from the University of South Carolina. The link for that article has since gone dead, but someone helpfully posted a link to the article via a web archive. I am going to reproduce it here so I have an easy reference for it and so its close to my earlier post on array types.

Notes on Interfacing ColdFusion MX to External Web Services Requiring Complex-within-Complex XML Documents as Input

Doug James (
Larry Afrin, MD (
Hollings Cancer Center

Medical University of South Carolina
March 31, 2005

The authors would like to acknowledge Macromedia's Tom Jordahl (who we understand is sort
of the principal developer and "guru" of ColdFusion's web services functionality) both for his
assistance in helping them understand how ColdFusion handles certain complex web service
interactions and for his critical review of the following document.

While the authors have tried to ensure the accuracy and utility of the information below, they
offer the following information with no warranties whatsoever and hereby explicitly state that their employer has had absolutely nothing to do with the development of this document and
therefore also bears no liabilities with regard to how the information presented here may be used.

The authors are also quite sure that despite Tom Jordahl's review of this document, Macromedia
takes no responsibility for this information, either. By their posting of this information, the
authors are not offering themselves as support resources for other developers wrestling with the
problems addressed herein. Requests for assistance in this area that are communicated to the
authors may or may not be acknowledged or answered, solely at the authors' whim. After all, we
do have to attend first to our day jobs (which often spill over into our night jobs, too.) ;-)


CFMX is able to communicate with web services hosted in arbitrary computing environments as long as the SOAP standards are followed. The SOAP standards require that all input arguments to a web service be passed as XML documents. The expected format of the XML document for any given input argument is defined either directly in the service's WSDL (Web Services Description Language) document, or by reference in that WSDL document to another data element definition document.

Before proceeding further to discuss how CFMX handles "complex"-type web service input arguments, it is helpful to review how CFMX handles a <cfinvoke> (or equivalent) request in general. CFMX first retrieves the target service's WSDL, then runs this WSDL through the WSDL2Java tool (see below for more information), which outputs Java code defining Java-based classes equivalent to the XML data structures defined in the WSDL. This Java code is then compiled. The input arguments provided to <cfinvoke> are then mapped to the Java types generated by the compilation, and finally the Java stub functions for those types are called. In this fashion, CFMX *automatically* converts input values referenced in <cfinvoke> or
<cfinvokeargument> tags to XML documents of the appropriate formats based on input argument format information provided in the service's WSDL. The burden on the coder, of
course, is to ensure the input values are structured in accordance with what CFMX expects to
find based on the translation by WSDL2Java from an XML-based data structure to a Java-based
data structure.

A similar process is followed to handle the service's return value and other output arguments.

This process is quite straightforward for "simple" type input arguments, such as simple strings or numeric values. Because ColdFusion variables, strictly speaking, are untyped, CFMX
automatically converts simple input ColdFusion variables to the equivalent string-based simple
XML structures.

However, some web service input arguments are XML documents of "complex" type. As briefly
described in the ColdFusion MX 7 documentation at: for complex-type arguments, CFMX expects to find a ColdFusion structure provided as the value for the input argument. Unfortunately, the ColdFusion MX documentation only provides clear examples of how to compose a ColdFusion structure that corresponds merely to a relatively simple form of a "complex" XML document in which the child elements of an outer "complex" parent element are simple scalar values, as illustrated in Example 1:

---------Example 1:------------------------------------
WSDL snippet:

<s:complexType name="Employee">
<s:element minOccurs="1" maxOccurs="1" name="fname" type="s:string" />
<s:element minOccurs="1" maxOccurs="1" name="lname" type="s:string" />
<s:element minOccurs="1" maxOccurs="1" name="age" type="s:int" />

Sample XML document:


CFML snippet:
<!--- Create a structure using CFScript, then call the web service. --->
stUser = structNew();
stUser.fname = "John";
stUser.lname = "Smith";
stUser.age = 23;
ws = createObject("webservice", "http://somehost/echosimple.asmx?wsdl");


While the above is helpful for "simple" complex-type input arguments, the ColdFusion MX
documentation provides no examples of how to compose a ColdFusion structure that corresponds to a more complex form of a complex-type XML document in which the child elements of an outer "complex" parent element are themselves "complex" parent elements (so-called "complex-within-complex" XML documents), as illustrated in Example 2:

---------Example 2:------------------------------------

WSDL snippet:

<s:complexType name="Employee">
<s:element minOccurs="1" maxOccurs="1" name="fname" type="s:string" />
<s:element minOccurs="1" maxOccurs="1" name="lname" type="s:string" />
<s:element minOccurs="0" maxOccurs="unbounded" name="nickname" type="s:nickname" />
<s:element minOccurs="1" maxOccurs="1" name="age" type="s:int" />
<s:element ref="s:address" minOccurs="0" maxOccurs="unbounded" name="address" />
<xsd:attribute name="employeeGender" type="string" use="required"/>

<s:complexType name="nickname">
<s:extension base="string" />

<s:complexType name="address">
<s:element minOccurs="1" maxOccurs="1" name="street" type="s:string" />
<s:element minOccurs="1" maxOccurs="1" name="street" type="s:string" />
<s:element minOccurs="1" maxOccurs="1" name="state" type="s:state" />
<s:element minOccurs="1" maxOccurs="1" name="zip" type="s:zip" />
<xsd:attribute name="addressType" type="string" use="required"/>
Sample XML document:
<Employee employeeGender="Male">
<address addressType="Home">
<street>25 Main Street</street>
CFML snippet:
<!--- Create a structure using CFScript, then call the web service. --->
stUser = structNew();
stUser.fname = "John";
stUser.lname = "Smith";
stUser.age = 23;
<!--- If .x corresponds to *element* <x>, then what syntax is used to specify an *attribute*?
How should employeeGender get set up in this struct? Read on to find out. --->
<!--- And what about the *two* nicknames? stUser.nickname = ... clearly won't work.
Read on to find out how this is handled. --->
<!--- And what about <address>? Does that get coded simply as stUser.address = structNew(),
stUser.address.street = "25 Main Street", etc. etc.????? The answer is "No."
Read on to find out more. --->
ws = createObject("webservice", "http://somehost/echosimple.asmx?wsdl");
There are just a few key (pardon the pun) principles you need to understand in order to determine how to compose a CF structure that CFMX will map to the properly formatted XML document needed as an input argument to an arbitrary web service:

(1) Principle #1: Any given key in a CF structure will be mapped by CFMX into *either* an
element name *or* an attribute name depending on what role the WSDL says that particular
name should play at that level in the document. In other words, you do not need to differentiate
between attributes and elements in the CFML structure you create; ColdFusion will automatically
handle for you the proper mapping of each key into either an attribute or element as required by
the WSDL.

Following along with Example 2 above, then, stUser.age will get translated into an <age> child *element* within the <Employee> parent element, and stUser.employeeGender will get translated as the employeeGender *attribute* within the <Employee> element.

(2) Elements in a WSDL that can occur more than once (cf. the "address" element in Example 2 above) are represented in the CF struct as an array. OK, but an array of what? Well, it depends on how the WSDL defines the subelements.

Again, following along with Example 2 above, <address> would be coded into the stUser
structure as follows:

  stUser.address = arrayNew(1);
stUser.address[1] = structNew();
stUser.address[1].street = "25 Main Street";
stUser.address[1].city = "Townville";
stUser.address[1].state = "Anystate";
stUser.address[1].zip = "99999";
stUser.address[1].addressType = "Home";
and the nicknames would be coded as follows:
  stUser.nickname = arrayNew(1);
stUser.nickname[1].value = "Jack";
stUser.nickname[2].value = "Johnny";

Hey! Where did ".value" come from? Read on:

(3) As the complexity of the format of the required input XML document increases, it may
become increasingly difficult to "guess," using the above two principles, how the corresponding CF structure should be coded. (Similarly, when working with web service return variables, or
output arguments, of complex-within-complex type, it may become difficult understanding why
CFMX has translated the output into the rather complex structure revealed by <cfdump>.) To help work through this, the coder should apply the WSDL2Java tool (see below for more
information) against the target service's WSDL and carefully examine the output of this tool.
WSDL2Java is an open source utility that takes a WSDL as input and outputs the Java beans
corresponding to the methods of the web service described by the provided WSDL; importantly,
the inputs and outputs for these methods are also defined in the corresponding beans. Upon
careful examination, the WSDL2Java output -- i.e., the Java code defining each bean -- clearly
identifies the expected layouts of the CF structures corresponding to the inputs and outputs of the service's various methods.

For example, one of the things that becomes clear upon examining the WSDL2Java output has to
do with the use of ".value" above. This is complicated, so read carefully: If an element (or
sub-element) of an input argument defined in the WSDL is declared in the WSDL to be of
"complex" type, but the corresponding definition in the WSDL of that complex datatype declares
that the value of that datatype is in fact only a simple scalar value, then CFMX assumes the value to be passed as input for that element (i.e., the value placed between the <x> and </x> tags) will be found in the corresponding CF structure (at the appropriate level) in association with a key named "value".

Below is another example of a web service input argument formatting problem that was solved by examining the output of the WSDL2Java tool. This is a real-world example of using CFMX to interface to a UDDI server. UDDI stands for Universal Data Discovery & Integration. UDDI servers are sort of the Domain Name System (DNS) of the web services world. UDDI servers store information about web services, including their addresses. A given web service could have many implementations around the world. An application that wants to make use of these implementations doesn't have to know their addresses as long as (1) the service and its implementations are registered in UDDI, and (2) the application knows the address of at least one UDDI server (part of the UDDI standard includes, a la the Network News Transport Protocol (NNTP, used by Usenet discussion groups), a replication protocol so that UDDI servers exchange database updates with each other in order for them all to stay in sync). UDDI servers can have a number of programmatic interfaces (e.g., URL-parameterized HTTP GETs), but the most robust interface they support is a web service interface. That's right: you can use web services to query UDDI servers about web services. However, the WSDL for the web service one uses to query a UDDI server is quite complex. More information about UDDI can be found at

Here's an example of using the "find_business" method defined in the UDDI WSDL to retrieve information from the target UDDI server about the first 50 businesses known to that server whose names begin with "A":

---------Example 3:------------------------------------

WSDL snippet:
<xsd:complexType name="find_business">
<xsd:element ref="uddi:name" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="uddi:identifierBag" minOccurs="0"/>
<xsd:element ref="uddi:categoryBag" minOccurs="0"/>
<xsd:element ref="uddi:tModelBag" minOccurs="0"/>
<xsd:element ref="uddi:discoveryURLs" minOccurs="0"/>
<xsd:element ref="uddi:findQualifiers" minOccurs="0"/>
<xsd:attribute name="generic" type="string" use="required"/>
<xsd:attribute name="maxRows" type="int" use="optional"/>

<xsd:complexType name="name">
<xsd:extension base="string">
<xsd:attribute ref="xml:lang" use="optional"/>
CFML snippet:
// define the main outer structure, findBiz in this case, can be named anything one chooses
findBiz = structNew();

//generic and maxRows are attributes (required and optional, respectively) of the uddi:find_business tag
findBiz.generic = "2.0";
findBiz.maxRows = 50;

//uddi:find_business tag accepts one *or more* "name" values, so an array is used = arrayNew(1);[1] = structNew();

//uddi:name tag is a complex type with a string value, so 'value' is used as the key to the structure[1].value = "A";

Important note:
In the <cfinvoke> below, the URL to the UDDI WSDL is the value of the "webservice"
parameter; the "method" parameter specifies the UDDI inquiry method called "find_business",
which returns a uddi:businessList object in the returnVariable "busList".

In the UDDI WSDL, the "find_business" method is defined as requiring an input parameter
named "body" of complex type "find_business" which is also defined in the WSDL. The
parameter name "body" shown in the <cfinvoke> below could also have been set up as a
<cfinvokeargument name="body" value="#findBiz#"> tag within the <cfinvoke>.

The actual version 2.0 UDDI WSDL is at This address
cannot be referenced as the "webservice" parameter in the <cfinvoke> tag because this particular
WSDL does not define the addresses of any actual UDDI servers. Thus, to query a UDDI server,
one has to copy this "generic" WSDL to somewhere else and modify it by adding in the proper
WSDL code to identify at least one actual UDDI server. The <cfinvoke> is then pointed at this
modified WSDL. CFMX will read the modified WSDL from this location, and in this modified
WSDL CFMX will find where it has to go to contact the actual UDDI service being targeted by
the coder.

The WSDL code that identifies an actual UDDI server is as follows. This happens to be the
real code for pointing at the main IBM UDDI server. This code gets inserted just ahead of the
closing </definitions> tag of the "generic" UDDI WSDL.

<service name="InquireSoap">
<port name="InquireSoap" binding="tns:InquireSoap">
<soap:address location="" />

webservice = ""
method = "find_business"
body = #findBiz#

And another example from the world of UDDI, this time using the get_businessDetail method:

---------Example 4:------------------------------------

WSDL snippet:
<xsd:complexType name="get_businessDetail">
<xsd:element ref="uddi:businessKey" maxOccurs="unbounded"/>
<xsd:attribute name="generic" type="string" use="required"/>

<xsd:simpleType name="businessKey">
<xsd:restriction base="string"/>
CFML snippet:
// busDetail is outer main structure
busDetail = structNew();

// generic is the required attribute of the "get_businessDetail" tag
busDetail.generic = "2.0";

//businessKey tag can occur many times, so it is mapped to an array
busDetail.businessKey = arrayNew(1);

Because the "get_businessDetail" tag has attributes and sub-elements, the sub-elements have to
be mapped into structures as well, and, similar to the uddi:name above, the sub-element
"businessKey" just contains a string, so the key name 'value' is used. */

for (x = 1; x LTE arrayLen(busKeys); x = x + 1) {
busDetail.businessKey[x] = structNew();
busDetail.businessKey[x].value = busKeys[x]; //busKeys is an array predefined from another process

As in Example 3, the UDDI WSDL declares that an input parameter named "body", of
complex type "get_businessDetail", is required for the "get_businessDetail" method.
webservice = ""
method = "get_businessDetail"
body = #busDetail#


WSDL2Java is a Java program that was created by the Apache group and is included in the CFMX distribution with the Axis package, the Apache group's implementation of the W3C SOAP standard.

To run WSDL2Java from the command line:

  1. The current directory needs to be the ColdFusion installation's 'lib' directory:
    • Windows: C:\CFusionMX\lib
    • RedHat Linux: /opt/coldfusionmx/lib

  2. Set classpath to include the following jar files:
    • RedHat Linux:
      • axis.jar
      • saaj.jar
      • jaxrpc.jar
      • xercesImpl.jar
      • wsdl4j.jar
      • commons-logging-1.0.2.jar
      • commons-discovery.jar
      • xml-apis.jar
      • activation.jar (This jar file can be found by adding runtime/lib/jrun.jar to the end of the classpath. Alternatively, it can be downloaded from Sun's Java Activation Framework web site.)

    • Windows:
      • SET

  3. Run the WSDL2Java program:
       Usage:  java org.apache.axis.wsdl.WSDL2Java [options] WSDL-URI
    '-v' option prints informational messages
    '-o' option is the output directory for emitted files.
    WSDL-URI can be either local or remote

    Example: java org.apache.axis.wsdl.WSDL2Java -v -o C:\wsdl2java_output

  4. More information about WSDL2Java can be found on the Apache Web Service web site, currently

LiveCycle Data Services 2.6 Public Beta

We are close to releasing LiveCycle Data Services version 2.6, which is the technology that allows you to do some really cool stuff with Flex 3 data driven applications. This release is based on the BlazeDS 3.0 open source technology, which includes RPC and Messaging technologies for Flex, but in addition gives you better scalability by including RTMP based channels, a new scalable HTTP based channel technology and some very powerful abilities to manage datasets, including automatic synchronization of changes, conflict detection, paging and support for Flex and AIR offline data caching.

In preparation for the final release, we released a public beta (we call it beta 2) on Adobe Labs last night.

Check out details at

Tuesday, April 08, 2008

Array types in ColdFusion web services

I get asked questions about publishing web services in ColdFusion often and this is one that many folks run in to that I wanted to post about as I just got asked this. Usually people send mail to Ben Forta, and he just forwards them on to me. :-)

Question - How do I create a function that has an array of custom made objects as an argument or return value?

First, let me recommend reading the ColdFusion 8 Developers guide chapter on web services ( I would also recommend reading Ben Forta's (et al) book, the Web Application Construction Kit Volume 3, chapter 68 – Creating and Consuming Web Services.

The first piece of information to know is that the CFML complex types, such as they are, might not the best things to use when creating a Web Service. Lets take Struct's for example. When you define an argument to a function as a struct, the XML Schema that is emitted for the WSDL defines an object that has the "any" type as both the key and the value. But this doesn't give the consumer of the web service much information - are there strings or complex types as the key? What kind of values should there be? Should there be various different things contained in the structure?

A better way to create this service is by defining exactly what kind of things you expect or return. To do this you would create a ColdFusion Component (CFC) that used the (mostly useless except for web services) cfproperty tag to describe the structure. Lets say our structure contained a just string pairs. Here is how you would define that:

<cfproperty name="key" type="string">
<cfproperty name="value" type="string">

Now our XML Schema in the WSDL would define a complexType that has two element in it at key (of type string) and value (also of type string). This has the advantage of clarity and also is potnetially much more interoperabile.

But the original question was about arrays. Lets get back to that.

If you want to publish a web service using CFC's then you would define the cffunction that takes an array as an argument or as a returnType. You can define this array to be of a particular CFC type that you have defined using the cfproperty tag as we did above. The example in the Forta book (Volume 3, page 298, listing 68.11 and 68.12) also shows this. The missing piece is how to specify that the argument is an array.

<cffunction name="GetCreditRating" returntype="string" output="no" access="remote">
<cfargument name="person" type="CreditPerson[]" required="yes">

Notice the "[]" after the name of the component. This will indicate that the WSDL should define the CreditPerson complexType and that the argument to the function should be 1 or more (MaxOccurs="unbounded") of these complex type elements i.e. an array. You can use this with types defined by CFCs or even for simple types (e.g. string[]). This syntax is valid in both the returnType attribute and the type attribute of cfargument.

This information is in the ColdFusion 8 documentation at

The follow up to this is if you want to consume a web service (such as the one above) you would define an array in CFML and put in it Structs that correspond to the complex type in the WSDL. Here is an example again based on the GetCreditRating that uses the new CF8 syntax for creating stuctures:

arg = ArrayNew(1);
s1 = { FirstName=Tom, Lastname=Jordahl, …};
s2 = { FirstName=Ben, Lastname=Forta, …};

arg[1] = s1;
arg[2] = s2;

Then you would pass the “arg” array as the parameter to the invocation of the web service.

I hope this fleshes out a little but about array types for ColdFusion web services.

Another Flex and BlazeDS demo application

Christophe has posted another really neat demo application that shows BlazeDS collaboration with an application that uses Messaging to allow more than one person to fill out a form at the same time. Not exactly practical in the real world, but a good example if the power of BlazeDS.

Sweet Flex and BlazeDS sample application

Check out this great sample application posted by Christophe Coenraets, complete with instructions and source code, showing a really nice mashup of Yahoo Maps, Flex and BlazeDS.

Monday, April 07, 2008

BlazeDS and LiveCycle Data Services Channels

Back in January, Damon Cooper posted a really great chart of all the channels types and the pros and cons of each written up by Seth Hodgson, a member of the LCDS and BlazeDS teams.

I wanted to post this to my blog for two reasons. 1. In case you missed it and 2. Because I wanted to have a link to it easily available on my blog for future reference.

Boston gets a Flex User Group

The first meeting of the Boston area Flex users group is tomorrow (Tuesday April 8th) at 7:00pm in the Adobe offices in Newton, MA. You can get details at and to RSVP for the even you should go here.

Pete Farland will be speaking about the open source Flex SDK at the first meeting. I have a dentist appointment that night, so I wont be there, but if you are using Flex and live around Boston, this ought to be worth your time.

ColdFusion 8 Update 1 released

The first update for ColdFusion 8 (aka version 8.0.1) was released this past weekend.

What does is have in it? Quoting from the from FAQ:

ColdFusion 8 Update 1 provides full 64-bit support for several new platforms including versions of Windows, Mac OS X, and Linux, in addition to Solaris (which was added with the initial ColdFusion 8 release). We have also improved functionality in several areas including AJAX functions, CFPDF, and CFIMAGE. We have also updated several software libraries.

Full details on these and other enhancements/fixes are available in the Update Release Notes.

Short answer: Lots of goodness.

To answer one question I have already gotten, there is NO update to the LiveCycle Data Services 2.5.1 bundled in with ColdFusion 8. Nor does the update contain BlazeDS. There are instructions that come with BlazeDS on how to integrate it with ColdFusion (see the resources/ColdFusion directory in the BlazeDS distribution).

Wednesday, April 02, 2008

Facelift for my blog page

Evey once in a while I click through the blogger provided dashboard to see what new things I can do with my blog. Today I managed to improve the fonts and colors, add a picture of myself, and add category information to most of the posts that deserve it. I even added a list of subjects on the left navigation pane of the page so you (and I) can find posts about specific things (like those web service related posts I am always looking for the link to).

If you are reading through an aggregator, come to my page ( and check it out.

CFUnited for 2008

I recently got confirmation that I will be attending CFUnited again this year. I believe I will be giving the "Adobe Speaker TBA" talk on ColdFusion 8 and LiveCycle Data Services. I will make sure to include a good discussion about BlazeDS and how that fits in to the picture.

I always enjoy attending CFUnited. It is being held at a new location this year. There probably isn't going to be a Dave & Busters handy to play games at, which is was always a highlight. But the crowd is always good and I really enjoy the sessions. Should be a good time, see you there!

Monday, March 24, 2008

Adobe Online Developer Week - March 24-28

Adobe is hosting a free "virtual conference" this week. It looks like a really good lineup of topics, including Adam Lehman (CF Evangelist) on Whats New in CF8 (Today at 1pm PDT), CF and RIA's and a CF & BlazeDS talk both on Wednesday. Christophe Coenraets (LCDS/BlazeDS Evangelist) is also doing an intro to BlazeDS session (Tuesday 9am PDT) and a LiveCycle Data Services intro on Thursday.

The lineup seems pretty good and you can pick and choose which sessions you want to attend. Check out more details at

Friday, March 07, 2008

ColdFusion 8 wins Dr. Dobb's Jolt Award!

ColdFusion 8 has been announced as the winner of the “Web Development” category of the Dr. Dobb’s 18th Annual Jolt Awards. Winners will be featured in the June issue of Dr. Dobb’s Journal.

Sales are great, awards are being won and ColdFusion continues to rock the web development world!

Monday, March 03, 2008

BlazeDS and Flex 2 compatibility

There was a question over on the BlazeDS forums about weather Flex 2 would work with BlazeDS. The answer is most definitely YES. You can use Flex 2.0.1 hotfix 2 or Flex 3 with BlazeDS 3. Jon Rose also blogged about this question back in January.

Jon was getting a message:
“Destination ’simple-topic’ requires FlexClient support which was introduced in version 2.5. Please recompile the client application with an updated client framework.”
The “2.5″ in the message that refers to LiveCycle Data Services 2.5, which was shipped requiring a hotfix (#2) for the Flex compiler/SDK.

The AMF3 protocol did not change. The remoting and proxy services interoperate without issue between Flex 2 and BlazeDS.

However, the messaging and data management service implementations on the server required several core changes in channel/endpoint handshaking and in how messages are queued and routed to subscribers that are not backwards compatible with clients compiled against the ORIGINAL Flex 2 client library. This is a low level incompatibility, so previous messaging and data management code doesn’t need to be altered or edited in any way. You just need to recompile your app against the hotfixed Flex 2 or Flex 3 SDK.

Thanks for Seth Hodgson for the details about what changed (it predates me moving over to Data Services).

Friday, February 29, 2008

Recording of my BlazeDS presentation

I gave my "BlazeDS Revealed" presentation to the ColdFusion Online Meetup group last night to about 55 people via Acrobat Connect. Charie Arehart does a great job of organizing these online-only meetings that cover just a ton of ColdFusion and related topics and each presentation is recorded so you can watch topics that interest you after the fact.

As he reminded me more than once last night, he is always looking for speakers.

The recording of my BlazeDS session is available here.

Thursday, February 28, 2008

Using ColdFusion with SQL Server XML/SOAP Endpoints

John Jarrad has blogged a very nice explanation on how he got ColdFusion 8 working with SQL Server 2005's XML/SOAP Endpoints. John referenced a few of my older posts like the one about how to use the Apache Commons HTTPClient instead of the built in HTTPSender class.

The interesting thing is that he did not use the HTTPClient library (although using this should have allowed the Digest and NTLM authentication to work since the library supports it) because the HTTPSender class (see source here) does in fact support HTTP 1.1, just not by default. The trick is to set the right property on the web service stub so that the Axis engine does the right thing.

The other note to John's post is that you can use cfinvoke if you want to, but you just have to use cfobject/CreateObject to create the web service "stub" first, then pass that in as the webservice attribute of cfinvoke.

<cfset ws = CreateObject("webservice", "")>
<cfset ws._setProperty("axis.transport.version", "1.1")>
<cfinvoke webservice="ws" method="JJData" returnvariable="result">

John also notes that processing the result set and turning it in to a query is pretty slow. Not sure what is causing this other than there is a large amount of data getting processed.

Wednesday, February 27, 2008

BlazeDS presentation Feb 28, 2008

I will be giving a presentation about BlazeDS to the ColdFusion Online Meetup this Thursday, February 28. I believe anyone can join the Acrobat Connect room (from anywhere in the world, how cool is that?) and the session will be recorded so you can watch me again and again. :-)

Check out the details here.

Here is the description:
Recently Adobe announced the release of BlazeDS which will make some key server technologies open source and free to use in any application. These technologies are critical to building great applications with Flex and AIR. Tom will talk about exactly what you get in BlazeDS and how it relates to LiveCycle Data Services and will detail some of the reasons why you might want to use these server technologies. He will also explain how ColdFusion developers can take advantage of BlazeDS in their applications.

Monday, February 25, 2008

BlazeDS and Flex 3/AIR 1.0 out today!

Today Adobe shipped Flex 3 and Air 1.0 along with releasing the open source BlazeDS technology. These are some amazing and world changing things that just hit the streets.

I'll let others talk about how revolutionary AIR is and how great Flex 3 is going to be. The BlazeDS open source project is what I am excited about (and not only because I work on the BlazeDS/LiveCycle Data Services team).

In a nutshell, two of the three important technologies included in LCDS 2.5.1 have been released a) for free (as in beer) and b) as open source. This means that you can use Remoting (aka Flash Remoting) and Flex Messaging in your Flex applications, backed by Java or ColdFusion, without any licensing whatsoever. You can file bugs on the technology in the public JIRA bug tracking system. You can even check out the source and see what makes it work (or debug a problem when it doesn't).

Anyway, the team is very excited about BlazeDS and the whole company is pumped for AIR 1.0. Check them out!

Wednesday, February 20, 2008

Directory Watcher talk by Dave Ferguson

It looks like I will be giving a talk to the Online ColdFusion Meetup next week (details to follow). In browsing around the meetup site, I decided to watch a talk about the Directory Watcher Event Gateway, one of the example gateways we shipped in ColdFusion 7 (& 8). I am always impressed at how useful folks find this gateway as I wrote it on a whim in just a few hours because we wanted to provide some source code examples for those who wanted to write their own gateway.

Anyway, if you do watch Dave's talk, there are a few questions and quirks he mentions that I wanted to try and clear up.

First, note that the Java source for this gateway is shipped with every copy of CF in /gateway/src/examples/watcher. I am still waiting for someone else to fix the problem of slow uploaded files triggering the "ADD" event before it is done writing the file. Dave gives a CFML/Java based work around for this problem in his talk (and makes the files available on his blog here).

Dave notes that the "Out"count in the CF administrator is always 0 for this gateway. This is the number of messages/events that the gateway has sent, well, out. For instance how many times SendGatewayMessage() was called for this gateway. Since the Directory Watcher doesn't do outgoing messages (see line 187), this count will of course always be zero.

Dave mentioned that when he returns something from (in his case) one of the onAdd, onChange or onDelete functions, he gets a meaningless error in the logs. I filed a bug on this for Dave (#71311). The problem is that as a convenience the gateway system will take the return value of an event processing CFC function and send that "out" to the gateway. For instance if you receive an SMS or IM message to one of those gateways, you can return a Struct with a reply message from the onIncomingMessage function and the system will (in effect) call SendGatewayMessage() on that gateway with that struct. Since he was returning a simple value (i.e. "1") CF tries to make that a Struct, fails and reports the strange error. It *should* ignore that return value and log a warning (in the eventgateway.log) that it is doing this.

Dave was asked about timeouts for the CFC processing functions. Event Gateway CFC function calls are subject to the same timeout value as ColdFusion requests. A gateway can override this value (in the Java code) by calling CFEvent.setCfcTimeOut(). Otherwise the timeout is the same as for "regular" CFML page requests.

There was a question about file renames and what the Directory Watcher does when it sees this. The watcher does in fact report an ADD and a DELETE event when you change the name of a file. This is by design and I verified this on ColdFusion 7 and 8.

Hope this info helps those looking for more information about this gateway.

30 On Air launches

Check out the new 30 On Air site for some fun videos answering the questions
Why AIR? Why Flash Player? Why Flash? Why Flex? Why Coldfusion? Why AJAX? Why LiveCycle? Why Dreamweaver?

You can upload your own video also, just tag it on YouTube with the "30onair" tag. I like the rocking guitar solo video, but maybe I have been playing too much Guitar hero.

Monday, January 07, 2008

Take a quick ColdFusion IDE Survey

The ColdFusion development team is running a survey to try and collect information about how you develop CFML code and what tools you use. Specifically, what features you look for and use in a IDE. Your chance to give your input can be found here.

Having a ColdFusion specific IDE is something that certainly the server team has wanted for a while ("Bring back ColdFusion Studio!") but for various reasons (*cough* Dreamweaver *cough*) we were unable to get. Remember also that the CF team are Java/server developers, which aren't the right people to develop an IDE tool for the desktop. This may explain why we haven't written one ourselves yet. :-)

Friday, January 04, 2008

Spell checker in the CF8 Rich Text editor

Rakshith has a useful posting on his blog on how to enable a spell checker in the new rich text form field available in ColdFusion 8. Read it here.