MXUnit Blog

A Generic ColdFusion Struct Visitor

2009-07-10T05:00:00.007-04:00

Warning: No unit tests accompany this code.

Recently, I mentioned on Twitter that I wish CF had a regex version of StructFindValue, and this started a conversation between me, Ben Nadel, and Nathan Mische. Ben and Nathan, both of whom I swear are code factories, had code out there within hours to do what I was looking for. Bless their hearts. While I normally try to hold to the “Twitter is not a Chat” maxim, in this case, I ran with it and it yielded fruit.

During our conversation, what I came to realize was that I didn’t want just a reStructFindValue, what I wanted was a generic means of looping over structures and then “doing stuff” with each key that it encountered, as it walked recursively through a structure, no matter how deep/nested.

Some of you may recognize this as the Visitor pattern. I tweeted thusly:

@bennadel what ColdFusion really needs is a StructVisitor. With that, a man could do great things.

2:12 PM Jul 7th from TweetDeck in reply to bennadel

Inspired by our conversation, and by the quick contributions of these two fine gents, I decided to take a quick stab at a basic implementation of some code, which I’ll call “StructEach.cfc” (Nathan called his version StructEach, and I liked it). It should behave like so:

Take a Struct and a Visitor object as arguments to an “each()” function
Loop over all keys in the input Struct, recursing as it went
For all keys in the struct, pass the key and struct value into the “visit()” function of the Visitor object
The visit function of the Visitor must return a boolean indicating whether the code should continue looping over the struct
The visit function of the Visitor can do whatever the hell it wants to do.

Before showing the code for StructEach.cfc, let’s look at why you’d want to use something like this, and then how you would use it.

Why? What are the use cases for this?

Perhaps you’d like to take a structure and convert it to XML
Perhaps you’d like to do really weird or granular searching of the stuff inside the structure, even if the structure has arrays in it, queries, etc.
Perhaps you’d like to “dump” the values of a struct, but you want them in textareas b/c you need to see exactly what the strings look like, whitespace and all
Perhaps you’d like to do a deep comparison of two structures and report the differences in a way that’s easy to read

That last one, by the way, is my own personal use case for MXUnit.

What Kind of Structures should it take?

For me, I wanted this thing to be able to handle nastiness, not just simple structures. At the very least, it should take a struct that was this ugly:

How do you use it?

First off, you’d write a CFC that implemented the “visit” function. Here’s a really simple visitor that just outputs anything passed into it, along with the full path to the value’s key in the structure

OutputVisitor.cfc


<cfcomponent hint="" output="false">
	<cffunction name="visit" output="true" access="public" returntype="boolean" hint="">
		<cfargument name="key" type="string" required="true"/>
		<cfargument name="value" type="any" required="true"/>
		
		<cfif isSimpleValue(value)>
			<cfoutput>#key# = #value# <br></cfoutput>
		<cfelse>
			<cfdump var="#value#" label="#key#" expand="true">
		</cfif>
		
		<cfreturn true>
	</cffunction>
</cfcomponent>

You’d then use this visitor like so:

<cfset outputVisitor = createObject("component","OutputVisitor")>
<cfset runner = createObject("component","StructEach")>
<cfset runner.each(struct,outputVisitor)>

In the case of the sample struct shown above, you’d get this output:

Where it gets interesting

That’s not very useful, is it? But it demonstrates how you’d use it. What you can trust in your visitor is that for every key in the structure, your visit function will get called. That’s the sweetness of this approach… you’re free to do whatever you wish with the data coming in.

This gets interesting when you start to consider how this is all implemented: you’re passing an object into the StructEach… think about that. Objects can contain state. This means that you can “remember” things through the iterations of the struct, as your visit function is repeatedly hit.

Let’s look at an example that implements “regex find” functionality over a structure. My implementation will

provide an init() function for taking in searchString and scope arguments

return a struct containing keys “found”, “path”, and “value” as soon as it finds something that matches the regular expression, and it will return false so that the StructEach will stop searching. Consider this a findOneOf() >

return an array containing multiple structs if scope is set to “all”. Consider this a findAll() >

You’d call it like this:

<!--- a RegExFindVisitor that searches for 'even'; as soon as one is found, it'll stop searching --->
<cfset regexFindVisitor = createObject("component","RegExFindVisitor").init("even","one")>
<!--- a RegExFindVisitor that searches for 'even' or 'ix'; it will search every key in the struct --->
<cfset regexFindAllVisitor = createObject("component","RegExFindVisitor").init("even|ix","all")>

<cfset runner.each(struct,regexFindVisitor)>
<cfset runner.each(struct,regexFindAllVisitor)>

<cfdump var="#regexFindVisitor.getFound()#" label="regexFindVisitor">
<cfdump var="#regexFindAllVisitor.getFound()#" label="regexFindAllVisitor">

And here’s what you’d see:

This is all made possible because the Visitor object can provide any other functions that it wants to… as long as it has a “visit()”, nothing else matters. In addition, the object can retain state. Thus, as visit is called, it can store stuff inside of itself for later computation and retrieval.

RegExFindVisitor.cfc

<cfcomponent hint="" output="false">	
	
	<cffunction name="init" output="false" access="public" returntype="any" hint="">
		<cfargument name="searchString" type="string" required="true"/>
		<cfargument name="scope" type="string" required="false" default="one" hint="'one' or 'all'. If scope is 'all', returns an array; otherwise, returns a struct"/>
		<cfset StructAppend(variables,arguments)>
		<cfset variables.instance.found = []>
		<cfreturn this>
	</cffunction>
	
	<cffunction name="visit" output="true" access="public" returntype="boolean" hint="">
		<cfargument name="key" type="string" required="true"/>
		<cfargument name="value" type="any" required="true"/>
		<cfset var tmp = "">
		
		<cfif isSimpleValue(value) && reFind(variables.searchString,value)>
			<cfset tmp = {path=key,value=value,found="true"}>
			<cfset ArrayAppend(variables.instance.found , tmp)>
			<cfif variables.scope eq "one">
				<cfset variables.instance.found = variables.instance.found[1]>
				<cfreturn false>			
			</cfif>
		</cfif>
		
		<cfreturn true>
	</cffunction>
	
	<cffunction name="getFound" returntype="any">
		<cfreturn variables.instance.found>
	</cffunction>
</cfcomponent>

Note that our source structure contains keys that have arrays and queries in them, but we’re only concerned with the keys that have simple values (and any nested structs that have simple values). Consequently, I’ve wrapped the chunk of code that does the work in an “isSimpleValue()” check.

But imagine… what if you wanted to also search through the arrays or queries that are passed into this thing? You could do that by implementing some additional searches inside of here.

Here’s another one I whipped up: Imagine you had a big ugly struct with various and sundry data in it, and you wanted to get just the queries.

Here's how you'd call it:

<cfset queryHarvester = createObject("component","QueryHarvester")>
<cfset runner.each(struct,queryHarvester)>
<cfdump var="#queryHarvester.getQueries()#">

And here's its implementation:

QueryHarvester.cfc


<cfcomponent hint="" output="false">
	<cfset queries = {}>
	<cffunction name="visit" output="true" access="public" returntype="boolean" hint="">
		<cfargument name="key" type="string" required="true"/>
		<cfargument name="value" type="any" required="true"/>
		
		<cfif isQuery(value)>
			<cfset queries[key] = value>			
		</cfif>
		
		<cfreturn true>
	</cffunction>
	
	<cffunction name="getQueries" returntype="struct">
		<cfreturn queries>
	</cffunction>
	
</cfcomponent>

And here’s what you’d get

How does it work?

This is not sexy code, and it’s certainly not a) optimized or b) complete (for example, I’d like it to loop through arrays of structs as well). But it’s a start, and it’s very simple:

StructEach.cfc

<cfcomponent>
	<cffunction name="each" output="true" access="public" returntype="any" hint="">
		<cfargument name="struct" type="struct" required="true"/>
		<cfargument name="visitor" type="any" required="true"/>
		<cfargument name="path" type="string" required="false" default="" hint="don't touch this, suckers">
		<cfscript>
		var loopkey = "";
		var thisPath = arguments.path;
			
		for(loopkey in struct){
			thisPath &= "[ ""#loopkey#"" ]";
			if(isStruct(struct[loopkey])){
				each(struct[loopkey],visitor,thisPath);
			}else if(!visitor.visit(thisPath,struct[loopkey])){
				return;
			}			
			thisPath = arguments.path;
		}
		</cfscript>
	</cffunction>
</cfcomponent>

Final Thoughts

This code, and even this approach, is purposely simple. There is nothing clever about it. I believe the value in an approach like this is in thinking about tasks in a more generic sense. Think of all the code out there in the world that does this: loops over keys in a structure recursively, and does stuff with the values it encounters. I imagine if you compared all of this code, it’d look remarkably similar in its recursion, but the details in the “else if” clause would be different.

Thus, in this approach, we’re extracting the common stuff into StructEach and providing hooks for implementations to get plugged into that “else if” part, in the form of a Visitor. Code gets much simpler and easier to understand; and code gets much easier to unit test because you’d be testing just your “visit” function, not the looping/recursion.

The downside is where you have recursion conditions that themselves require state external to the visitor; in this case, the StructEach approach wouldn’t work well, and there’s danger in trying to shoehorn an approach just to avoid a few lines of code. So, as with most things OO, you use this approach when it’s warranted, not just when it’s easy.

When you start thinking in more generic terms, you start to see opportunities for code reuse. For example, how much code is out there in the world, do you think, that loops over directories and "does stuff" to the directories and files in those directories? Imagine the dozen or so lines of boilerplate recursion code required to do the looping part, and the one line of code to delete the file. Multiply that by a gazillion. How much code in your own codebase does this looping, with the only difference being "what I do when I hit each file"?

If you think generically, you see there's a better way to do this: you create a DirectoryWalker type of deal that handles the looping, and then you provide a FileVisitor type of implementation that acts on each file it hits. So if you have code that deletes certain files in directories, or "touches" them to make them current, or archives certain files, or makes jpg thumbnails of pdfs that don’t already have thumbnails... you can separate that out into really small, easy-to-test Visitor implementations and just use DirectoryWalker to handle the boilerplate.

Consider the unit test for that last example, the one that generates thumbs. If you were to write a “generateThumbsForDirectory"()” function, that’s hard to test! Seriously… think about what would be required in a unit test to test it. You’re testing two things: 1) your recursion and 2) your thumbnail generation. But the recursion is boilerplate, and testing boilerplate sucks. What you really want to test is your thumb generation. So if you extract that out into a simple function that takes an existing File path, your job is simple: look for an existing thumb for that file, and if one doesn’t exist, create it. That’s a really small unit test comprising two functions: makeThumbnail_should_GenerateThumbnails_When_ThumbnailDoesNotExist() and makethumbnail_shouldNot_GenerateThumbnails_When_ThumbnailDoesExist(). You could write that in maybe 15 lines of code. You trust that the StructEach works because it’s been tested separately, and you can now trust your code because you’ve proven, with your tests, that your code works.

Fewer lines of code + easier-to-test functions = fewer bugs.

"Look, Ma. No Password!" - Secure Hashing in ColdFusion

2009-06-24T08:02:00.003-04:00

I soaked up tons of great stuff at Frank Kim's recent Sansfire 2009 training
in Baltimore. As a matter of fact, it was the single best training event I have ever attended and I highly recommend it. After the module on Java Cryptography Architecture (JCA) -- which was at the end of Day 3 and though my brain was fried -- I realized I had a big gap in my own knowledge in something that should be a fundamental skill for programmers today. Broadly and simply stated, that skill is to be able to protect data in your application. Now, if you're anything like me and you start hearing some terms like symmetric and asymmetric ciphers, MD5, SHA-1/2/3 message digest, cryptographically secure random number generation, etc., you might be inclined back away slowly (or quickly) and leave all that to someone else. Well, I'm here to say that implementing strong cryptography in ColdFusion is a lot easier than I expected. And knowing how do this and why will give you valuable skills that can only make your software safer and your programming stronger.

Let's start with a common web application task - storing credentials in a database. One appealing NIST recommendation is that you should not store the passwords at all. Rather, you should store a secure hash of the password instead. When authentication needs to take place, instead of reading the password from a database and comparing that to the password entered by the user, you retrieve the password hash from the database, hash the password entered in the form, then compare the hashes. If you understand why we do this and just want to see how, skip down to Secure Hashing. If you're mumbling to yourself "That sounds like a fucking waste of time," read the next two paragraphs.

The driver here is that passwords are secret and nobody should have access to a user's password other than the user. System administrators and support staff should have the ability to reset passwords but not to read them. You might ask, "But my sites don't contain any sensitive information, why should I care?". Though true, how much do you want to bet that users registered on your site are using the same set of credentials to log into other sites, even banks?
Does this possibly make your site a target for harvesting? Could this challenge customers' trust in you over time? Play that tape couple of times ...

The good news is that password hashing is so simple I can see no real reason not to do it. I'm not claiming to make your site secure; I'm simply saying that if you securely store password hashes instead of passwords, you can mitigate a number of potential attacks; for example, the Rainbow Table attack [7]. Note that password hashing differs from storing passwords encrypted. Why is this important? Because anything encrypted needs to be unencrypted to be read. To unencrypt, there must be a key and frequently it will be one key that can be used to read all passwords. We don't ever want passwords to be read by anyone. Period. So, we want to create a strong, secure, one-way hash.

Secure Hashing

The technical term is Cryptographic Hash Function, and there are several algorithmic variations : most notably, Message Digest (MD5), Secure Hash Algorithm (SHA), and others. Essentially, a hash function generates a unique and fixed-sized representation of some data; aka a Fingerprint. A correct hash will always produce the same result for a given input; e.g., f(x)=y. For example, the string foo, when hashed with MD5 should always produce ACBD18DB4CC2F85CEDEF654FCCC4A4D8 in ColdFusion. If another algorithm is used, the output will be different than this, yet it still should always produce
consistent output.

Now, what if there are users with the same passwords? Won't the hashes be the same in the database? Right you are. What a Rainbow Table[7] is, is essentially a large list of passwords that have been hashed using a number of algorithms. The attacker compares the hashes in your database with the ones in his Rainbow Table and then finds the matching password. The solution to this is to create unique hashes using salt and to repeatedly hash the hash. Salting is the process of inserting random data into the original data. Then, we repeat the hashing about 1000 times. This creates a unique and, if done correctly, a more secure hash.

Let's start with some usage. We use an example utility component ,Crypto , to perform the hashing. Full source code can be found here.

When run, this generates a password hash that looks something like 72C2CA24AD19EF7A8A9FC89184BA17BFA2D65CF3BE4FD2F0BBF3B460BD123550BC2D6BAB3AADF76EEAA4D8B5F6641A73365B21D17158779468049CACC32F0F2E and a base64 secure random salt value of 4OP5GFmp/z0YYgUUlprVoig4pkGWhNGgMl37Tn4sLPw=. When a user creates or changes their password, store only the hash and salt:

Now, to authenticate a user, you do something like this:

We're simply comparing the hashed value of the password entered by the user to the hashed value stored in the database. We do this by first retrieving the salt from the database and using that to generate the hashedFormPassword value. If you've read this far, I'm sure you want to look under the hood:

It doesn't get much easier for a complex topic, does it? computeHash() accepts 4 arguments: password, salt, iterations, and algorithm. The required ones are password and salt - salt should be a secure random base64 string. iterations is the number of times the hash will be rehashed. PKCS 5 recommends doing this "a modest" 1000 times[9]. This would be a performance concern if this operation were done frequently, but since it is done only when a user logs in or creates an account, it's considered acceptable. The last parameter, algorithm, is a specific message digest algorithm. It's specified here are SHA512, which is the strongest FIPS-140 approved secure hashing algorithm. Adobe has some very good documentation on available security providers and other related security best practices - this is required reading for ColdFusion developers! [5]

Salt Generation:

The core concept behind salt generation is to create a random set of bytes of N length. Since ColdFusion sits on Java, I chose the java.security.SecureRandom class.

Summary

Using the example Crypto component or your own variation will give you a viable option to storing passwords directly in the database and contribute to better security in your application. However, do not take my word alone for this. Please do some thorough research and learn for yourself. When it comes to protecting your customer's data and privacy (and your job) make sure you know what you are doing and why.

Test and be Happy!

References (Many are PDFs):
[1] OWASP Java Hashing - http://www.owasp.org/index.php/Hashing_Java
[2] NIST Secure Hash Standard - http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf
[3] FIPS-140-2 Draft (June,18,2009) - http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf
[4] Guide to Enterprise Password Management (Draft) - http://csrc.nist.gov/publications/drafts/800-118/draft-sp800-118.pdf
[5] ColdFusion 8 developer security guidelines - http://www.adobe.com/devnet/coldfusion/articles/dev_security/coldfusion_security_cf8.pdf
[6] Java Cryptography Architecture (JCA) - http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html
[7] Rainbow table - http://en.wikipedia.org/wiki/Rainbow_table
[8] NIST Advanced Encryption Standard Algorithm Validation List - http://csrc.nist.gov/groups/STM/cavp/documents/aes/aesval.html
[9] PKCS #5 v2.1: Password-Based Cryptography Standard - ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-5v2/pkcs5v2_1.pdf

IntelliJ IDEA Plugin for CFML

2009-06-13T12:21:00.021-04:00

As ColdFusion developers, unlike many other languages, the one thing we simply don't have is code insight or object & method resolution for 3rd party Java or ColdFusion products. I understand that this is difficult to achieve for dynamic languages, but, just because it's "hard" is not an excuse, imo.

I'm a big fan of IntelliJ IDEA and it's the best tool for Java and Groovy development I've used - these guys know what an IDE should do and they also support open source projects. IDEA also gives you the ability to create Flex and Air projects. Recently, developer Valeria Nikolaenko, has built a CFML plugin for IDEA and has consistently been releasing updates. The most recent one fits especially nicely with any project that uses ColdFusion and Java together. Specifically, if you use Mark Mandel's JavaLoader you'll find this feature of particular interest. Basically, it allows you to get Java method resolution inside of CFML for classes loaded with JavaLoader. Check it out:

So, what we've done here is create a JavaLoader instance using createObject(...) and then we create a Java class, esapi, in the editor. When you type esapi. then hit Ctrl+Space, Voila!, all the methods and their signatures for the ESAPI class are presented in the editor. You do have to perform a few project set up tasks in order to make this happen in IDEA, assuming you've installed the CFML plugin already:

Add your 3rd party jars to your project's class path
Add the ColdFusion facet to your project and tell it where your webroot and subdirectory are located
In your source code, tell the CFML plugin about your JavaLoader variable and jar locations:

If you've ever done Java development without code insight, you know what the typical process is - you need to constantly go back and forth between the Javadoc APIs, copy and paste, or you dump out the object's metadata and try to figure out how to call it. The configuration above steps seem like minimal effort compared to the typical manual process required to work with Java inside of ColdFusion. It's not the end-all-be-all solution, but it's big step in the right direction. Ideally, if all the configuration could be done at the project level, that would even be better.

Now, if we could just have an MXUnit plugin for IDEA, it could be a seriously dangerous all-around IDE for $249 US.

Continuous Integration with Hudson, CF, and MXUnit: Setting up Notifications

2009-06-04T05:00:00.001-04:00

In previous entries, I wrote about configuring a project in Hudson and setting up your project to run your MXUnit tests and report results. Before we talk about setting up email and IM communication, let’s briefly look at what you should now have, in pictures, if you’ve set up a project. I’m using MXUnit as the example project here.

First, an entry in the project list, indicating the build’s health

Next, when you drill into the project, you’ll see your recent build results on the left, along with your test trends on the right

On the left side, with your list of previous builds, you can click the “trends” link and see a time trend graph

You can click on a link for your last build and see more details about it. When you click on the Test Results link, you get this view

From there, you can drill down into the reports for more information, should you need it

If a build fails, it’ll show you something like this:

Communicating This Information

All of this information is lovely; however, we’re not interested in monitoring the Hudson interface every time a build runs. Instead, we want to get notified when things change. That’s it: when build status changes. For me, continuous integration is as much about communicating results as it is about providing an easy, scheduled mechanism for running your tests (we don’t care about compiling and linking in CF applications, so that core benefit of CI doesn’t apply to us either).

Ideally, only interested parties would be notified on a change in build status. For example, let’s say a build runs at 8:00 AM, and all tests pass. It runs again at 8:15 AM, and tests fail. What I want to happen is:

Hudson looks at source control for the users who have committed code since the last build
Hudson notifies *just* those people that the build is now failing.
Hudson does this either via email, instant message (SMS), or both.

Fortunately, this is all possible. Let’s set it up.

Configuring Email Settings

From the main Hudson screen, type “configure” in the search box

Scroll down to the bottom and find the E-mail notification section.

I’m using gmail in this case, so I plugged in my gmail credentials, using “smtp.gmail.com” as the server. I’m keeping “default email suffix” blank since this can’t be computed (this would be more for corporate email accounts where you can trust that the email would end up as “firstname” + “lastname” + default email suffix, for example).

In the Advanced settings, I checked “use smtp authentication”, entered my email address into the username field, added my password, checked “use ssl”, and specified the port as 465

Configuring SMS (Jabber) via GTalk

From the “manage Hudson” screen, click on Manage Plugins

go to “Available Plugins”, and find the “Hudson Jabber notifier plugin”. Click things and install it. Restart if necessary.

Now, back in your Manage Hudson screen, you’ll have a new section, right above the Email section, for Jabber.

I entered my gmail address and password, and “talk.google.com” as the server. That’s it!

For the visually inclined, here’s what all of this looks like:

Noise Control

At the project level, you can also configure how noisy you want this communication to be. Here’s what that looks like:

From that image, you’ll see that I can configure when I want to be notified… every build, just on change, etc. Thus, to substantially reduce the noise from your scheduled builds, go into the project and configure it to only notify via IM on status change. This, in my humble opinion, is gold.

Configuring Users

Now that the communication mechanisms are set up, we have to associate email addresses with the subversion users. Quite possibly there’s an easier way to do this via some batch process, but as I’m just getting started with my Hudson investigation, I haven’t looked into it. So please don’t take this as “the only way” or “best practice”, because I do not know that to be true.

For my setup for MXUnit, I linked it to SVN and when it updated and there were changes, it created new a new user for any user that was associated with a change. So, I committed some code to MXUnit, ran a Hudson build, and Hudson added me as a user, silently.

To give the “marc.esher” user notification details:

from the main Hudson screen I clicked on “people” then on “marc.esher”. (You can also get here if you know the username you want to configure by typing that username in the "Search” box at the top of the screen)
click Configure
enter my email address
since I installed the Jabber plugin, it also has a space for jabber credentials. I entered my gmail address again.

So what’s all this get me?

After this configuration was finished, here’s what I get:

Emails on build failure that look like this:

GTalk notifications on build failure that look like this:

And corresponding messages for when things go back to normal.

Importantly, what I don’t get: noise. I don’t get notified on every build via email. I don’t have to constantly go to a website to check the build status. I get notifications when I care about them: when things go bad, and when things go from bad back to good.

Summary

Continuous Integration is about communication. It’s about noise control. And so far I’m discovering that Hudson is performing admirably. You can configure different methods of communication, all hooked into source control, with different “strategies” (on every build, on every change, etc). I appreciate this level of configurability. In addition, I was able to get all of this going without reading a single page of documentation. I think that speaks to Hudson’s ease of use.

7 Totally Stupid Useless Ways to Invoke ColdFusion Components

2009-05-31T00:44:00.034-04:00

Warning:
The content contained herein contains utterly useless, potentially offensive, and very juvenile language. This is not suited for just about everyone.

There are many levels of stupidity - I believe in, and have worked very hard at, exploring many such levels in theory and in practice. Though some individuals are gifted with natural stupidity, I believe to be a true and utter mooncalf demands rigorous discipline and hours of practice. To support this process, you can explore other distinct facets of stupidity ranging from the simple-moron to the mullet-sporting-crank-snorting-utter-fucking-bonehead. To be more than a mere journeyman dolt, however, demands discipline and, above all, dedication.

In this small and inane piece, I will attempt to demonstrate how a programmer can proceed from a state of being simply moronic to a high level random-self-inflicted-headwound-fuckhead. The key lies is in using what little brain power you might have towards something of little or no utility whatsoever. Remember this and I truly believe you will go nowhere but backwards.

7 Totally Stupid Useless Ways to Invoke ColdFusion Components

Full stupid source code available here
(click the Download button for a zip/tar file)

This is the stupid component under test we will invoke in 7 truly dumb ass ways.

All these examples are written as MXUnit tests, which, by doing so, has arguably decreased my own stupidity rating. Note also that these are written in <cfscript>. This reduces the number of keystrokes required in order to write useless piss-ant code.

Here's the setUp():

#7 (Simply Moronic)

#6 (Approaching Idiocy)

#5 (The Java Loser)

#4 (Douche Bag)

#3 (Turd Mongrol)

#2 (Dumbass Pissant)

#1 (Asshat Monkey Shit Hurler)

Stupid source code here

Feel free to post stupid code or links to such. Using Gists might be cool, though they're not stupid.

CI with Hudson, CF, and MXUnit: Configuring ANT and Running Tests

2009-05-29T05:00:00.001-04:00

If you’re already running your MXUnit tests with ANT, then this should go quickly. If not, then you’ll need to read this first. Create your ANT build file (build.xml), create your “runTests” target (or whatever you want to call it), and get your test runs working from within Eclipse or at the command line. Only after you get those working should you try integrating with Hudson… one thing at a time.

Configuring ANT within Hudson

Hudson needs to know where your ANT install lives. If you haven’t downloaded ANT, do so now, unzip it, and put it somewhere. Then, copy the path to that location.

From your main Hudson screen, click on “Manage Hudson”, then “Configure System”. More quickly, type “configure” into the search box and it’ll take you to the same place. Go down to the “ANT” section, click “Add”, and paste that path to your ANT install. Note, this is NOT the “bin” directory… just the ANT root. Give it a name, like “ANT 1.7” or whatever. Click Save

Hudson will not treat this ANT location as the default location. You must (at least, I did) have to explicitly choose this ANT instance for every project setup. Just so you know. This tripped me up at first.

Sample ANT build file



<?xml version="1.0" encoding="ISO-8859-1"?>

<project name="Sample" basedir="." default="main">

 <target name="init">

  <property name="testroot" location="../tests/framework" />
  <property name="componentPath" value="mxunit.tests.framework" />
  <property name="server" value="localhost" />
  <property name="port" value="80" />

  <!-- wherever the mxunit-ant.jar lives -->
  <property name="mxunitant" location="../ant" />
  <property name="mxunitjar" location="${mxunitant}/lib/mxunit-ant.jar" />
  <property name="mxunitxsl" location="${mxunitant}/xsl" />

  <!-- this is where the xml and html will live -->
  <mkdir dir="testresults" />
 </target>

 <target name="runtests" description="Make output directories and run the MXUnit task" depends="init">
  <taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask" classpath="${mxunitjar}" />
  <mxunittask server="${server}" port="${port}" outputdir="testresults" verbose="true">
   <directory path="${testroot}" recurse="false" packageName="${componentPath}" componentPath="${componentPath}" />
  </mxunittask>

  <mkdir dir="junithtml" />
  <junitreport todir="junithtml">
   <fileset dir="testresults">
    <include name="*.xml" />
   </fileset>
   <report format="frames" todir="junithtml" styledir="${mxunitxsl}" />
  </junitreport>
 </target>


</project>

Configuring your project’s test runner step

Navigate to your project, then click “Configure”. More quickly, you can search for your project by name, then search for “configure”, and you’ll get to the same screen.

Find the "Build" section. click "Add build step". Select "Invoke ANT". Select the ANT instance from the dropdown list of installed ANTs. In the "target" field, type the name of the target in your ANT build file that you use to run tests. For example, "runTests"

This might be all you need. so you could save this and try to do a build now, and see what happens.

Test Runner Step Configuration, Part 2: Properties

Now’s a good time to talk about the weirdo nature of ColdFusion projects with respect to CI. Remember, you checked out your project from Subversion into Hudson’s workspace, but that’s not the code you care about… your code already lives on a DEV server and is updated by some other means. However, there is one file that gets checked out that you do care about: Your ANT build file.

When Hudson runs your ANT file, it’ll be running the one from its workspace. And then that build file will be executing its tests against the components you specify on your DEV server. Got it? Good. Confused? I know.

It’s possible that your build file’s runTests target might need some properties that are possibly set in a properties file that you don’t keep in SVN or which otherwise you need to override. For example, for MXUnit itself, our build file looks at a file named “unames.properties” to get some configuration information such as server name, port, usernames/passwords, webroot location, and some other things. This is NOT kept in SVN b/c it’s unique for each MXUnit contributor. When MXUnit’s runTests is run, it tries to read that properties file and then set the server, port, and webroot properties. But since that file isn’t checked out from SVN, it’s not visible in Hudson’s workspace and thus those properties never get set. It’s super easy to get around this though!

In your ANT step’s “Advanced” tab, you’ll see a “properties” box. In here, you can type in any properties in name=value format, linebreak-delimited, and poof, properties problem solved. For example, here’s what I put into the properties box for the MXUnit job:

server=localhost

port=80

webroot=c:/inetpub/wwwroot

Configuring your project’s JUnit XML Output

In that sample ANT build file above, you saw how easy it was for MXUnit to spit out JUnit-compliant XML. Basically, no matter where your tests actually run (http://blah/whatever/HttpAntRunner.cfc), your JUnit XML files will go in a directory relative to the build file that is running. Got that? That means that, as discussed above, your JUnit xml files will go in your Hudson workspace somewhere. This is perfect, because that’s where Hudson wants them to be.

For example, with the MXUnit build, the build file is at mxunit/build.xml. It specifies a location for the JUnit xml output as something that evaluates to tests/testresults/tmp/. So in the Hudson configuration for the MXUnit job, I specify the JUnit XML location as:

tests/testresults/tmp/*.xml

That’s it. So wherever your xml files go relative to your workspace root, simply go to the “Post Build Action” section of your job configuration, check the “Publish JUnit XML” checkbox, and enter in the path to your xml files, with *.xml, as I did above. Click save

Re-saving ant.bat

After I got the MXUnit project all set up, I ran the build; it executed the tests; Hudson read the JUnit XML (all tests passed). And then…. Failed. Failed?! WTF? WTF was failing? The Hudson console output (thank you, Hudson!) read: “The system cannot find the batch label specified”.

This wasn’t a Hudson problem. It wasn’t an MXUnit problem. Turns out, it was the ant.bat file giving me grief. That’s right… the ant.bat that ships with the eclipse ANT install. Perhaps had I been using a “proper” install, this wouldn’t have been the case. Nonetheless, I wasn’t. So, how to fix it? Simple

Open up ant.bat in Textpad. Notice that it’s in Unix format. Change the format to “PC”. Click Save.

Rerun the Hudson build. Oh Joy. Oh Rapture. A fully functioning test run with test results. Let the CI begin.

What’s Next?

Next up, configuring notifications.

Continuous Integration with ColdFusion, Hudson, and MXUnit: Getting Started

2009-05-28T05:00:00.000-04:00

This series will demonstrate how to set up a continuous integration (CI) environment for ColdFusion projects using Hudson CI and MXUnit. We’ll cover Hudson setup, MXUnit test runs and JUnit XML output, and a few notification mechanisms (email, IM).

Installing Hudson

This will cover the super-duper simple way to run Hudson, which you'd do for testing this stuff out. DO NOT RUN YOUR REAL CONTINUOUS INTEGRATION ENVIRONMENT IN THIS MANNER. If you already have Tomcat set up, then you know how to install war files so follow that procedure instead (i.e. drop the war where you put your war files, or use the admin to deploy the war. It's that simple)

Download the Hudson war file and put it somewhere
Open a command line and navigate to the war file location
type “java –jar hudson.war”
This will launch Hudson. You can navigate to http://localhost:8080 and from there, you’re ready to start

Pulling your project from Subversion (SVN)

Click "create a new job"
Give your job a name, and then select Freestyle Software Project
Under Source Code Management, select SVN, and then plug in your project’s SVN location, eg http://svn.myproject/whatever/trunk
From here, you can click “Save” and then perform a build by clicking “Build”. This will check out your code into the Hudson workspace for your project

But this code isn’t where I need the code to be! Good point. As I get started with this, I’m going to just keep doing it this way until I figure out a better approach. At least where I work, we have DEV servers where code is automatically updated from SVN anyways, and our unit tests all run against the DEV server. I’m not setting up a CI environment in order to set up yet another server; instead, I’m setting it up so that I can get better reporting and notifications while still executing the same tests against the same code.

Hudson does allow you to choose a “custom workspace”, but I’m not going to get into that right here as I’m not sure yet whether it’s relevant for ColdFusion projects. I can see people being tempted to set the Hudson workspace to an existing project location on a Dev server, for example. Time will tell if this proves to be a good idea

What’s Next?

See how easy that was? Next up, configuring ANT, running your tests, and recording results

ColdFusion and LiveCycle ES: Rights Management

2009-05-22T14:00:00.001-04:00

This is the final part of a planned 3-part series on getting started with LiveCycle ES for ColdFusion developers. With this post, I aim to:

walk through the steps for Configuring LiveCycle Rights Management
show how to invoke the RightsManagementService webservice
address some additional issues I hit which stakeholders should understand

Big Caveat: I’m just learning this stuff. I have not worked with an Adobe salesman or tech support, so it’s highly probable that the stuff I’m talking about in configuration is complete crap. This post is a diary of what I went through to merely get it all working, and by “working”, I mean “I was able to create a rights-managed PDF that communicates with the LC server”.

Configuring LiveCycle

Make sure the service is enabled in LC Admin: Services, Applications and Services, Services Management, Filter on “Rights Management”, and ensure “RightsManagementService” is running. Click on that link and ensure the default soap endpoint is enabled.

Create a new group

I’m not sure if I needed to do this, but I did it, so I’m documenting it.

Settings – User management – Users and Groups
Click “New Group” button. Created group named “Rights Management”
Clicked through and gave the group permissions associated with Rights Management stuff. You do this when you get to Step 4 and then click “Find Roles”, then select the stuff that looks rights-management-ish. Again… consult a professional, not me.

Create a new user

For the purposes of this post, I’m going to skip anything related to creating new domains. Instead, when we invoke the webservice, we’ll just invoke with the default domain that ships with LC. It goes without saying that when you do this in the real world, you’ll need to a) know your sh*t and b) probably consult with a company to help you get all this set up. Again, this is just to get up and running for a POC.

Now, then:

Settings – User Management – Users and Groups
Click “New User”. Give this user a name, username, password, blah blah blah. For this POC, select “DefaultDom” as the domain. Click next
Click “Find Groups”, and select the new Rights Management group that you created above
At step 3, I ignored Find Roles and went to Finish.

Create a new Policy Set

Services – Live Cycle Rights Management ES – Policies -- Policy Sets.
Click “New”. Give it a name. Click next
Search for a domain. I selected “Default Domain”. Click through and accept the addition.
Click Next, then search for the User you just created. Click Next and give that user permissions to monkey with policies in documents
I added that user to Document Publishers, too. Click through to finish

Create a new Policy

Services – LiveCycle Rights Management ES – Policies
Click the link for the Policy Set you just created
Click the Policies tab, then click “New”
Give your policy a name
Apply whatever settings you want. Click Save
Check its checkbox, then click the Enable Button. Click through to finish.
In your webservice call, you’ll use the policy set name and the policy name, along with the user and domain you associated with the policy set

Grrrrrrr

If you do all the stuff I’ve just talked about, you might be thinking “Gee, the LC Administrator is a bit tough to get around”. I’d respond with “ya think, Beav?”. I have come to despise the administrator. I’m assuming that Adobe wants you to use Workbench for most of this stuff. That, to me, is the only possible explanation for creating an admin that is so user-unfriendly. It’s a navigational nightmare.

Configuring SSL

Set the Rights Management Server URL

Services – LiveCycle RightsManagement ES – Configuration – Server Configuration

Set the Base URL to an SSL URL. For my POC, I used https://localhost:8443

Enable SSL in JBoss

I followed Duane Nickull’s excellent instructions. A few gotchas though:

First, in a “note” in the middle of the page, he writes: “Note: If you installed the Adobe LiveCycle 7.2 release using the turnkey installers, the path to this will be different. It should be:
$JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar”.

Pay attention to that note. Don’t gloss over it.

Second, a very very important point that is not addressed (well… I believe it’s just plain wrong, at least as of this writing): when you create the keystore, you need to set the “first and last name” as the name of the server on which you intend to deploy this. For my POC, I used “localhost”. In fact, I used “localhost” for every damn answer. Note that this is just if you’re using a self-signed keystore; if you used a real one (i.e. you buy a cert), you won’t have to go through this rigamarole.

Finally, Duane shows how to get the cert installed via FireFox. On my Vista machine, this didn’t work. I had to use Internet Explorer, and I had to follow the steps below.

Now, if you haven’t done so already, restart JBoss.

Making your cert a “trusted” cert on your machine

In Internet Explorer, navigate to the URL you specified in the Server Config above. For example, I navigated to https://localhost:8443
It’ll give you a red error address bar, so you’ll need to install the certificate. Right click and hit “install” or whatever the options are.
This will launch IE’s certificate install wizard. Start the process, and when you get to the certificate store page, do not accept the default. Instead, select “Place all certificates in the following store”, click “browse”, and select “Trusted Root Certificate Authorities”.
Click through to the end and you should be all set up.

Invoking the RightsManagementService with ColdFusion


<cfscript>
creds = {username='administrator',password='password'};
serviceRoot = "http://localhost:8080/soap/services/RightsManagementService";
wsdl = "#serviceRoot#?wsdl";
ws = createObject("webservice",wsdl,creds);
ws._setProperty("javax.xml.rpc.service.endpoint.address","#serviceRoot#?blob=base64");

filePath = expandPath("readme.pdf");
theFile = fileReadBinary(filePath);

inPDFDoc = {contentType="application/pdf",binaryData=theFile};
documentName="readme.pdf";
policySetName="Marc Policy set";
policyName="loose2";

response = ws.applyPolicy(inPDFDoc,documentName,policySetName,policyName,"cf","DefaultDom");

outputData = toBinary(response.getBinaryData());
</cfscript>

<cfset newfile = expandPath("readme_withrights.pdf")>
<cffile action="write" file="#newFile#" output="#outputData#">

Additional Issues and Considerations

As of this writing, whenever I open a rights-managed PDF created using the above steps, the PDF still prompts me twice: Once telling me that the PDF has to connect to the LC server, and once asking me for a username/password. I am 99% certain this is a configuration problem on my end. I just haven’t dug enough to figure it out yet. If you know how, please let me know. When I get back to my LC proof of concept, I’ll get the answers and update this post.

I believe it’s important for stakeholders deciding whether Rights Management is right for them to get solid answers – with proof – regarding the user experience with RM-managed PDFs. In my specific case, the PDFs wouldn’t be for internal consumption; rather, they’d be sent out to the masses, whose technical savvy could range from “My grandmother” to “my boss”. Bottom line: know your users.

ColdFusion and LiveCycle ES: Reader Extensions

2009-05-21T06:00:00.002-04:00

With this post, I aim to

walk through the steps I took to get LiveCycle configured for applying Reader Extensions
show how to invoke the ReaderExtensions webservice with ColdFusion

With this post, I do not aim to show you how you’d actually use the ReaderExtensions in real life. I have no idea if “real” production applications would be invoking these services; It seems that “The LC Way” involves you creating new processes in LC Workbench and using watched folders and such. I do not know what benefits are conferred by that approach over the approach I’ll demonstrate below. Again, as I said in my first post on this topic, this series is my way of recording what I went through to get this stuff working as I build a proof-of-concept.

Configuring LiveCycle

Login to LC, and click “Services”. Then go to “Applications and Services”, then “Services Management”. In the resulting dropdown, select “Reader Extensions” and submit. Check off the “ReaderExtensionsService” checkbox, and hit the “start” button if it’s not started.

Click on that link, and then select the checkbox beside “Default Soap Endpoint”. Click the “enable” button if it’s not enabled.

Click on the Services tab, and from there you can control whether to require authentication (which you’ll pass in the “creds” struct below) and also how to run the service. I kept mine at “System”, but I imagine in real production you’d run it as something else. I’m no LC expert, so I have no valid opinions here.

Invoking the ReaderExtensions webservice with ColdFusion

Invoking the ReaderExtensionsService from ColdFusion is reasonably easy, once you get around a few gotchas. First, you will probably need to pass authentication credentials. To get started, I just used the credentials I use to log in to LC Admin. You can turn off the need for credentials by going into LC Admin, navigating to the ReaderExtensionsService config, and turning authentication off.

According to the docs, you can get your extended PDF back from the webservice in 4 formats: base64-encoded, mime, dime, and as binary via a URL. I’ll show you the base-64 and remote URL approaches.

Base64

<cfscript>
creds = {username='administrator',password='password'};
serviceRoot = "http://localhost:8080/soap/services/ReaderExtensionsService";
wsdl = "#serviceRoot#?wsdl";
ws = createObject("webservice",wsdl,creds);
ws._setProperty("javax.xml.rpc.service.endpoint.address","#serviceRoot#?blob=base64");

filePath = expandPath("readme.pdf");
theFile = fileReadBinary(filePath);

inPDFDoc = {contentType="application/pdf",binaryData=theFile};

usageRights = {enabledComments=true,enabledCommentsOnline=true,
 enabledDigitalSignatures=true,enabledDynamicFormPages=true,enabledFormFillIn=true,
 enabledOnlineForms=true};
applyOptions = {message="",modeFinal=true,usageRights=usageRights};

response = ws.applyUsageRights(inPDFDoc,"marc","njUvw9Lnftxxxx",applyOptions);

outputData = toBinary(response.getBinaryData());
</cfscript>
<cfdump var="#outputdata#">

<cfset newfile = expandPath("readme_extended_withbinary.pdf")>
<cffile action="write" file="#newFile#" output="#outputData#">

Notables

First, note the very important couple of lines for getting LC to return the data in base64 format. Possibly this trick is new to you. It was to me, too, before I needed to dig into CF webservices and find out how to change the endpoint address after setting the wsdl in the createObject call. If you wanted mime or dime return, you’d do blob=dime or blob=mime, respectively. You can also do blob=http and it’ll give you the same result as the way I’ll do it down below. This endpoint resetting really tripped me up at first. I kept trying to call response.getBinaryData(), and the binary was empty. So, this is for you google searchers: empty binary data.

Second, note that in your call to applyUsageRights, you need to pass valid user credentials. That crazy username/password combo was what I got from LC when I downloaded the trial version.

Finally, the webservice call returns a datatype named “Blob”. No, this isn’t like a database blob. Instead, it’s an object of Adobe’s devising (I presume) that contains several methods you can call. CFDUMP it to see what’s available to you. Anyway, when you specify blob=base64 in the endpoint address, you can get back the new reader-extended PDF by calling response.getBinaryData(), and then you write that to a new file. Not that it matters, but I really like the Blob return type. It’s a great way to get consistent webservice calls across the various LC services. Props, dudes.

RemoteURL


<cfscript>
creds = {username='administrator',password='password'};
ws = createObject("webservice","http://localhost:8080/soap/services/ReaderExtensionsService?wsdl",creds);

filePath = expandPath("readme.pdf");
theFile = fileReadBinary(filePath);

inPDFDoc = {contentType="application/pdf",binaryData=theFile};

usageRights = {enabledComments=true,enabledCommentsOnline=true,
 enabledDigitalSignatures=true,enabledDynamicFormPages=true,enabledFormFillIn=true,
 enabledOnlineForms=true};
applyOptions = {message="",modeFinal=true,usageRights=usageRights};

response = ws.applyUsageRights(inPDFDoc,"marc","njUvw9Lnftxxxx",applyOptions);
</cfscript>

<cfset newfile = expandPath("readme_extended_withRemoteURL.pdf")>

<cfhttp url="#response.getRemoteURL()#">
<cfdump var="#cfhttp#">

<cffile action="write" file="#newFile#" output="#cfhttp.filecontent.toByteArray()#">

Notables

Note that I’m using normal old createObject with a wsdl path… no resetting the endpoint here. When you call the service by default you get the response via a remote URL, NOT binary. This means you need to do a cfhttp call to the response object’s getRemoteURL() method, and then you use cfhttp.filecontent.toByteArray() to write it to a new file.

Finally, I’m using the inline struct notation in these examples, but if you’re on a previous version of CF you can convert this code to normal old structnew() and you’ll be fine. Nothing about these calls should be specific to a version of CF.

Credits

Props to this blog post, which was the first post I read on using ColdFusion and LC together. This saved me a lot of time getting started.

Getting started with LiveCycle ES for ColdFusion Developers

2009-05-11T05:00:00.000-04:00

What is LiveCycle and why am I doing this?

From the website: “Adobe LiveCycle® ES (Enterprise Suite) software is an integrated server solution that blends data capture, information assurance, document output, process management, and content services to help you create and deliver rich and engaging applications that reduce paperwork, accelerate decision-making, and help ensure regulatory compliance.”

If you have trouble wrapping your mind around what exactly it is that LC ES can do you for you, you’re not alone. It’s not that LC is a solution in search of a problem; rather, it’s that LC does a lot of stuff! At its heart, LC is an enterprise Java app that provides a suite of services around document and information management.

I, however, do not yet have my head around all of its awesome. For me, it’s about one thing: doing stuff to PDFs that I otherwise couldn’t do, namely 1) unlocking functionality that lives in the PDF but which can only be exercised with Acrobat and 2) programmatically applying security policies to those PDFs. My company produces PDFs for public consumption, and the people opening those PDFs will probably not have Acrobat… just Reader.

Specifically, what I’m interested in is enabling Reader to save PDFs with form data still in tact; enabling “add comment” functionality in Reader; enabling digital signatures; and adding a “kill switch” into PDFs so that if the data goes out of date or is shown to be incorrect, the next time a user opens the PDF, the PDF can “phone home”, get instructions that the PDF is no longer valid, and give the user instructions for how to get a new version of the PDF. And I need to do all of this programmatically.

You can do all of this with LiveCycle; you can do all of it with web service calls (i.e. SOAP); and you can do it all with ColdFusion.

To be clear: you are not dropping some jar files into your ColdFusion install. You are setting up a full JEE server (JBoss, WebSphere, whatever version of LC you download), and you are writing ColdFusion code that will send PDFs to the LiveCycle server, ask LC to do stuff to the PDF, and get new bytes in return. Then, rather than distribute the “source” PDF, you’ll distribute the new “extended” PDF.

Finally, this is not about LiveCycle Data Services (LCDS). That’s a part of LiveCycle ES, but it’s not the part I’m interested in for this short blog series. Lots of people have written (with copious examples) about using LCDS with CF. This series will be about using other parts of LC, namely Reader Extensions and Rights Management.

Installing LiveCycle ES

For me, the fastest way to get LiveCycle up and running on my machine was to download the "Turnkey" trial edition here: http://www.adobe.com/cfusion/tdrc/index.cfm?product=livecycle

I selected the JBoss option because I have no experience with WebLogic or WebSphere.

I'd say leave yourself at least a couple of hours to have LiveCycle installed and operational. This isn't a 5-second Tomcat download and 10-second exe install. It's a massive application, so adjust your expectations. Don't start this when you have an hour to go before you leave work (well... start the download then, and then let it go while you're driving home) It's a weighty download, at almost 3 gig.

You'll notice that there's no 64 bit download. This bit me in the ass. I am running this on 64 bit Windows, running the latest 64 bit JDK. The docs tell you that this only works on JDK5. Now, I don't know about you, but I'm the kind of guy who says "yeah, right", and proceeds. Fortunately, the LiveCycle installer asks you for your JDK path, and when you give it a Java 1.6 path, it won't let you proceed. Good on you, LiveCycle.

So, off I went to get a 1.5 JDK (http://java.sun.com/javase/downloads/index_jdk5.jsp). I downloaded the 64 bit JDK cuz that's how I roll. Installed it, changed the JAVA_HOME environment variable to point to it, and off I went with the installer.

Remarkably, I hit no other problems during the install. It takes a very long time, mind you. At times it might *appear* to be hung. Let it ride.

So, it finished installing, then said "Starting JBoss Service". And at that point, FAIL. JBoss started, then shut down right away. Now this is more like it! I expected more of this, honestly, so I was kind of pleasantly surprised. Off I traipsed to the Windows Event Viewer, where I found this gem: "The LoadLibrary function failed for the following reason: LoadLibrary is not a valid Win32 application."

Obviously, this is due to my 64 bit JDK. So I proceeded to futz about in the JBoss install directory, looking for a .config or .properties or .xml or .whatever file that appears to point to my jdk, thinking I can just go download the 32 bit JDK, install it, change the config file to point to that, and be done with it. This was not to be. I'm no rocket surgeon, but as near as I can tell, the JDK path is either a) set into a registry entry or b) stuck in the Windows service config somewhere. I doubt it's the latter though because even starting JBoss with the bat file produced the error. So my money's on the registry entry. Anyhoo, not being adventurous (this was later in the evening), and being generally lazy when it comes to this stuff, I just installed a 32 bit JDK and restarted the LiveCycle install. A few "OK" button clicks and gin & tonics later, and I was up and running.

It takes about 10-15 minutes for LiveCycle to become responsive once JBoss starts, so don't be surprised when "starting JBoss" or 'starting LiveCycle" takes a really long time.

You hit the admin UI link that they tell you on the installer, and up it pops. You will be greeted with a login screen reminiscent of the ColdFusion administrator. You’ll log in, and the similarities will end there. Queue the spooky music… you have entered a new dimension of sight and sound….

Summary

1) download the JDK 32 bit version
2) set your java_home variable to point to that version
3) when you download the installer, you'll be given a "serial number". I imagine this is just a stock trial serial. At any rate, copy it into a text file because you will need it later.
4) You will be prompted for a "credential" at some point during all of this. This is important! Write it down. I chose "Marc" as my credential, and then it gives some gibberish password. You will need this.

Next up.... Invoking the ReaderExtensions web service.

Articles on TDD and ColdFusion on Adobe Developer Connection

2009-05-05T08:06:00.003-04:00

We're happy to announce a 2-part series on TDD and ColdFusion is now on the Adobe Developer Connection.

Part 1 is here: http://www.adobe.com/devnet/coldfusion/articles/testdriven_coldfusion_pt1.html

Part 2 is here: http://www.adobe.com/devnet/coldfusion/articles/testdriven_coldfusion_pt2.html

Enjoy!

Timesavers: GMail Keys

2009-05-04T05:30:00.001-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

I’ve been a GMail user for quite some time, but only recently have I started using the GMail Keys feature. What a bonehead! Keys rock.

Why I love Keys

Read every single email without clicking the mouse
Easily "mark" emails read/unread/archived. For example, I get a lot of digest emails. I do skim most of them, but some days, I don't have time, so I'll mark em and archive em for later
Perform common searches (all unread items in inbox) with just a few keys
See the Keys Help with a single key combination (shift-Q)

Here's what that help looks like, by the way:

Frequently Used Keys

From a message list (like the Inbox)

c to compose
x to select messages.
j to go to next message. key to go to previous message
y to archive
enter to go into a message

From a message (i.e. you're reading an email)

x to get back to your list
if it’s a multi-message conversation, use n to go to the next message, and p to go to the previous message. hit enter to expand if it’s not expanded

You can also do searching really easily. Hit “/” to focus on the search box, then type some common phrases like “is:unread in:inbox” to show all unread messages in the inbox. In the video below, you’ll see more of that.

And finally, shift-? shows the help for Keys

See it in Action

This isn’t the greatest video, but I love the java posse and the content of this lightening talk is a solid intro to using GMail Keys. I give you… the Dick Wall’s introduction to Keys.

Timesavers: Firefox Goodies

2009-05-01T05:30:00.003-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

This Timesaver is a quickie for some of the ways I stay fast in Firefox. I’m purposely leaving out Firebug, Greasemonkey, and any other add-ons for now. This is just native Firefox stuff.

Keyboard Shortcuts

Ctrl-T to open a new tab
Ctrl-L to focus on the address bar. I probably use this more times during the day than any other shortcut
Ctrl-Enter to prefix with www and suffix with .com. For example, I’ll ctrl-L to the address bar, type facebook, then ctrl-enter. This could be shortened even further by adding a bookmark for facebook and giving it a keyword, like “fb”. Then I’d just type “fb” in the address bar and off I’d go to waste more time.
Ctrl-F to find. I am amazed at how many times I see developers use the mouse to pop up the find box in Firefox and IE.
“/” to start finding text right away without hitting ctrl-F
‘ to start finding links right away. That’s an apostrophe if you couldn’t make it out. This is fast because if you have an idea of the links you’re searching for, like “contact”, you can hit apostrophe, then start typing “cont…” and then when it focuses on the link, you hit “enter”
Backspace to go Back. Shift Backspace to go forward
Ctrl-page-down to go to the next tab. Ctrl-page-up to go backwards through the tabs
Ctrl-+ to zoom in. I need this because so many of the young hipster bloggers these days think it’s cool to write in 5 pt verdana. Ctr- - to zoom out (that’s control minus). And Ctrl-0 to return everything to normal.

The full list of shortcuts is here: http://support.mozilla.com/en-US/kb/Keyboard+shortcuts

Substitutions in Bookmarks

You know how when you focus in the address bar, and you type “google cat pictures”, and it does a Google search on cat pictures? It’s doing that with substitutions. Or try this -- Add this bookmark: "http://dictionary.reference.com/browse/%s" and give that bookmark a keyword of "dict". Then, Ctrl-L to your location bar and type “dict pedantic”. It’ll do a Dictionary search for the word pedantic. All that’s happening is that there’s a link stored in a bookmark, and somewhere in the link is “%s”. And the bookmark has a keyword assigned to it. So when you type the keyword -- “dict” for example – it loads that bookmark. Then, it sees the %s and expects something to come after the “dict”. so whatever else comes after the keyword in the address bar, Firefox will substitute for the %s.

Where I work, this is particularly useful for loading URLs with a well-known pattern whose identifiers only differ by some ID number. Let's say I have a bookmark for executing the "build PDF" function in one of our applications. We'll give it a bookmark of http://app.foo.com/index.cfm?fuseaction=build&id=%s. I'll give it a keyword of "build". Then, to execute it in the url, I would type "build 1041", and it'd replace %s with "1041".

Think of all the URLs you visit that differ only by some word or ID or whatever... they're prime candidates for keyword substitution.

Something I'm missing

I wish Firefox had a shortcut for "Send Link...". I know, I know... this is being rather pedantic. After all, you can just hit alt-f-e and do it the normal old windows shortcut start-with-alt-and-follow-the-letters way. But that feels cheap. I wish I could assign keys, so that I could do Ctrl-M.

What are some of your favorite built-in Firefox timesavers?

Timesavers: CFEclipse Snippets

2009-04-29T05:52:00.001-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

Of all CFEclipse's features, none save me as much time as "Snippets". Eclipse has a built-in snippets feature, but for my part, I think CFEclipse's implementation is superior.

You create snippets in the Snip Tree view. You give it a name, a "start block", and optional "end block", and a "trigger". In addition, you can use "variables" to have the snippet inserter prompt you for stuff. More on that later.

First, here's what the dialog looks like for creating/editing a snippet:

Trigger Text

For me, its killer timesaver is trigger text. I don’t have to open up the snip tree view, navigate through a tree of snippets, and click to insert. Just type the trigger text and hit Ctrl-J.

For example, I have a snippet for creating a new CFFUNCTION. In a cfc, I simply type: function and then hit Ctrl-J. Here's what my snippet looks like:

And here's the popup I get when I hit Ctrl-J

I assign triggers to all the snippets I use on a day to day basis. I do have a number of snippets I use rarely, but I keep them as snippets because I figure if I have to type it more than once, it’s worth being in a snippet. But since I rarely use them, I’d forget the snippet trigger anyway.

If you were to chop out the trigger functionality tomorrow, I could measure my productivity loss in hours over the course of a year. And I’m not a fan of losing hours.

Variables

Variables are placeholders for text that you will be prompted to enter when you insert a snippet. For example, in that function snippet above, you saw this:

cffunction name="$${Function Name}" output="false" access="$${Access:public|private|package|remote}" returntype="$${Return Type:any|void|string|numeric|struct|array|query}" hint="$${Hint}"

And then when I inserted the snippet, it gave me a dialog where I'd populate those placeholders. If you don't enter anything, it just enters an empty string instead. Note also that you can create a dropdown list by using a pipe-delimited list, as in the "returntype" attribute above. Finally, if you use the same variable twice in a snippet, it will only prompt you for it once and then it will insert it in each place it was requested.

CFEclipse comes with several useful built-in variables you can use, too. They can be found at the official documentation site: http://trac.cfeclipse.org/cfeclipse/wiki/CFSnippets

You can watch Mark Drew’s video on using snippets here: http://cfeclipse.org/assets/movies/07_Snippetsfla.html

Finally, if you’re interested, here are some of the snippets I use every day. Many of these were created by my former colleague and all around good egg, Mike Rankin.

Bottom line: Next time you find yourself typing code that you've typed more than once, stop. Add it as a snippet, assign it trigger text, and execute the snippet by typing your trigger text then hitting Ctrl-J

Timesavers: CFEclipse Scribble Pad

2009-04-27T05:25:00.001-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

One of my favorite CFEclipse features is the "Scribble Pad". Its primary purpose is exactly what its name suggests: to jam out some quick, throwaway code. I use it all the time when I come across a new function I want to test, or I want to see how a chunk of code will behave in isolation before I drop it into real production code.

The scribble pad is simply a .cfm file that you keep in a project somewhere. I'm a big fan of having at least one "Sandbox" project in my workspace, so that's where I keep my scribble pad file. Here's how I set up scribble pad:

Ctrl-N and create new CFML project named "Sandbox"
Store project at c:\inetpub\wwwroot\sandbox
Ctrl-N to create new file named "scribble.cfm" in that project
Hit the scribble icon in the toolbar (it's the one that looks like a pencil).
The first time you do this, it should prompt you for the location of your scribble file. Point to your scribble.cfm, and give it the appropriate URL. In my case, it's http://localhost/sandbox/scribble.cfm

Then, when you have some code you want to try out, hit F8 or click the scribble icon. This will load your scribble file. It will also load the CFEclipse Browser View and run the scribble.cfm page. As you modify your code, hit F5 to refresh the Browser view and see your changes. You do not need to give the browser focus in order for F5 to refresh it; you can keep your cursor in the code.

Here’s what it looks like:

Then, as you monkey with the code, you simply hit refresh in the Browser view to see the changes.

Note: if you hit the scribble icon and nothing happens, you may need to set up the scribble in your preferences.

Window -- Preferences -- filter on Scribble

It'll pop up a box that looks like this:

Then, enter in the appropriate information. In my case, I entered "scribble.cfm" as the file, "sandbox" as the project, and http://localhost/sandbox/scribble.cfm as the URL. If you don't enter in the URL, then the browser view will NOT load with the scribble URL; rather, it'll load empty, and this isn't what you want.

For me, scribble is a huge timesaver because it gives me a quick place to test stuff without having to a) run the code inside my app or b) create new files for running it in isolation.

Bottom line: Scribble pad rocks. F8 loads it.

Timesavers: Eclipse Quick Diff

2009-04-24T05:30:00.002-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

Have you ever been editing your code, and sometime down the road -- maybe 5 minutes, maybe 2 hours, maybe after lunch -- you break something. It used to work, and now it doesn't. You're thinking, "what change, of all the beautiful edits I've made, broke my fortress of code?" Being an experienced Eclipse user, you smile and say to yourself, "I know, I'll compare to my local history!". Or maybe you decide to simply compare to the latest SVN Version.

So off you go, right-clicking on the file, selecting "compare", and then choosing a comparison target. Often, this is a perfectly reasonable decision. Well done, good sir.

There is, however, a quicker way to easily see the changes you've made to your code in an editing session, or even across sessions: Quick Diff

On the left side of your Eclipse editor is the "ruler" bar. It's the thing with the line numbers. And if you have Quick Diff enabled, it's also the thing with the pretty colors showing you what lines have been added, changed, and deleted. Here's what Quick Diff looks like when I change a line of code and then hover over the ruler bar color decorator:

Notice there's an "F2 for focus" line at the bottom of the popup. Here's what it looks like when you do that:

What's cool is that you can select this text from the popup. So if you see something in your Quick Diff that you think "OOOH! That's the code I monkeyed with. Let me grab that and drop it back in and see if that fixes my problem", you can simply copy it from the popup and off you go.

"Added" lines of code will merely result in a "+" for each added line in the popup; Changes will show the full lines that were changed (though they won't give you the nifty "Compare Editor", which is one of the compelling reasons for using the full-on "Compare With" stuff). Deleted lines will give you a small line in the ruler bar. For example, I deleted a function, hovered over the black line, and this is what I got:

To enable Quick Diff, simply open the Eclipse preferences (ctrl-shift-L, ctrl-shift-L), filter on "Quick", select the "Quick Diff" label, and have at it. Here you can also choose the Reference Source and change colors. It looks like this:

I use "Pristine SVN Copy" as the source for projects connected to SVN, and "Version on Disk" for non-SVN projects.

Bottom line: Enable Quick Diff, then hover in the gutter for popups showing you what’s changed. F2 to focus so you can select code

Timesavers: Tabaholic

2009-04-22T06:00:00.001-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

Eclipse Resource Navigation

If you're like me, you probably have a lot of files open in Eclipse at any one time. You probably have done the following things at some time in your career:

Moused over to an already open file whose tab is visible in your window
Clicked on the little double arrow and drilled down to an already open file that wasn't visible in your window
edited a file, saved it, opened another file to check something out, then wanted to go back to the place where you were last editing

This TimeSaver is dedicated to showing how Eclipse makes these operations a snap. Of course, we're talking about the keyboard. As you work with Eclipse, you'll learn that its developers are highly fond of keyboard shortcuts. Hit CTRL-Shift-L to see the current active shortcuts, also known as "Bindings".

Getting to open files quickly

First, put down the mouse. It's sucking time away from you and your precious code! Every time you find yourself grabbing the mouse to go to an already opened file, stop. Pinch yourself. Yank on the cilice. Whatever. But put the damn thing down.

And hit:

Ctrl-E

Go ahead, try it right now. We'll still be here. Go to Eclipse, open up a few files, and then hit Ctrl-E. Pretty, isn't it?

Notice how, like so many popups in Eclipse, it has a little area at the top where you can type? It's a filter. You can use wildcards, too. My favorite way to use it is when I know what file I'm looking for, let's call it "SomeTest.cfc", I hit Ctrl-E, type "So" and it'll filter down to the file I'm looking for. Hit Enter, and bam, you're at the file.

Back from whence you came

In that third scenario up above, you edited a file, went somewhere else, and then wanted to go back where you were. Eclipse has a shortcut for that: Ctrl-Q.

Go ahead, try it.

Did it work? If you were editing a CFM or CFC file in CFEclipse, it probably didn't. That's OK. We're going to take care of that.

CFEclipse overrides the Ctrl-Q binding with the "repeat last tag" action. I personally don't use that, so I want to get rid of it. Let's open up the Keys preference page.

The sloooooow way: Window -- preferences -- filter on keys

The fast way: Ctrl-Shift-L, Ctrl-Shift-L again. Go ahead, try it. It's going to pop up a window that looks like this.

Now, in the filter box, type Ctrl+Q. Note the "+".

You should see two entries. Simply remove the binding for "Repeat last tag" by selecting it and then clicking the "Unbind Command" button, or if you like that, you can assign it to another keyboard shortcut.

Now, edit some text, move to another file, then hit Ctrl-Q. Bam... back where you were. Nice, eh?

I need to get to line 500... of line 2529

You know you've written some really long files in your day. Admit it. Sometimes, you actually have to maintain those works of modern art, and it's nice to be able to get quickly to where you need to go within that file. Usually this comes from a bug report with a tag context / stack trace attached to it.

Simply hit Ctrl-L, then type in the line.

Tab-to-Tab

Ever wanted to just toggle through your open tabs? Simple: Ctrl-PgUp to go leftward through your tabs, and Ctrl-PgDown to go rightwards

The Back Button, Eclipse Style

I'll admit, this isn't one I use much, but maybe you'll get some mileage out of it. It's like your browser's Back button, but for Eclipse: Alt-Left

Go ahead, try it.

Guess how you go "forward".... yup. Alt-Right

Summary:

Ctrl-E to navigate open files
Ctrl-Q to go back to your last edit location
Ctrl-L to go to a specific line
Ctrl-PgUp and Ctrl-PgDown to toggle through your tabs
Alt-Left and Alt-Right to go back and forth

Driven By The Cold - TDD, MXUnit, and ColdFusion (Part 1)

2009-04-21T06:33:00.003-04:00

It was a great learning experience to work with such talented people to deliver this collaborative writing project - peer/technical reviews, editing, editing, and more editing. This made blogging look like post-it hacks! A big thanks to Adobe for providing the venue, support, and process to publish technical know-how and best practices. Building good tools is one thing; showing people how best to use them is another. It's becoming glaringly apparent to this developer that a software product's strength lies equally in its ability to educate as well as it's ability to solve real-world problems. Community involvement is critical, and organizations that foster this collaboration will have a positive impact on the community.

Part 1 is available now with Part 2 coming very soon.

http://www.adobe.com/devnet/coldfusion/articles/testdriven_coldfusion_pt1.html

Test and be Happy!
the guys at mxunit.org

Timesavers: Ctrl-Shift-R

2009-04-20T06:00:00.002-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

What you think of as files, Eclipse thinks of as resources. Resources represent a file in the Navigator or Package Explorer view; they represent a file opened in an editor. Your workspace comprises all the resources in your workspace (and a whole lot more).

This TimeSaver is dedicated to finding resources in your workspace.

How To Quickly Find Resources

By now, you should know I'm a fan of the keyboard. Navigating through trees of files is dog slow. I don't mean 8-week-old-yappy-rat-terrier-puppy slow. I mean 25-year-old-coon-hound-eyes-are-crusted-over slow. Fortunately, Eclipse gives us the "Resource" finder. Lucky people learn about this beauty early on in their Eclipse usage; others go without for a long time, to their woe. They Twitter, "How did I not know about Ctrl-Shift-R?" or "w00t! Ctrl-Shift-R!" or "OH: the dumbass in the cube beside me just found Ctrl-Shift-R. Dumbass. Wonder when he'll learn to breath out his nose". Why is this? I think it's because of the "resource" vs. "file" nomenclature discussed above. Why, for example, would you think to:

Navigator --> Open Resource

and expect that to pop up the single greatest popup in the history of bits and bytes?

You wouldn't. That's why it goes undiscovered for so long.

Notice the keyboard shortcut for "Open Resource": Ctrl-Shift-R.

Burn that into your brain. Ctrl-Shift-R. Ctrl-Shift-R. Ctrl-Shift-R. Stop drinking. Stop eating. Stop smoking stogies. Stop raising your children. Stop everything until you have absorbed Ctrl-Shift-R. It is the fastest way to get to files. It looks like this, and it is my friend:

Notice how it filters when you type stuff? Notice I used a * to do a wildcard filter? Also, notice that little black triangle on the right hand side? You can drop that down and filter your search on Working sets for added radness.

Another neat feature: it lets you select multiple files and open them. Need to super fast find all your TestCases and open them (why? I dunno)? Ctrl-Shift-R, then *Test.cfc. Tab into the "Matching Items Window, hit Ctrl-A, then Enter. Bam... you've got more open files than you know what to do with.

Next time you find yourself grabbing the mouse and navigating through your tree of files, Stop. Put the mouse down. Even if you've found it already. Put the mouse down, hit Ctrl-Shift-R, and start typing.

Timesavers: Common Eclipse Shortcuts

2009-04-17T06:00:00.003-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

This TimeSaver is dedicated to common keyboard shortcuts that everyone should know. Well, let me back off of that. If you like being slower than a 3-toed Sloth, that's your prerogative. If you want to be fast, put the mouse down and use these shortcuts.

Ctrl-S to Save
Ctrl-Shift-S to Save All

Ctrl-W to close the current document
Ctrl-Shift-W to close all current documents

Ctrl-N to pop up the "New..." dialog. Please, when you're creating new files, don't use the mouse. In your navigator or package explorer, put your mouse where you want your new file, and hit "Ctrl-N", then filter on the type of file or project or whatever you want to create, and hit Enter.

Ctrl-M to maximize (and minimize) the current active window. This works for editors and views.

Ctrl-F to find stuff within your active editor
Ctrl-K and Ctrl-Shift-K to do "find next". I love these things! You highlight a word in your file, then hit ctrl-k to find other instances of it, one at a time. Go ahead, try it. use Ctrl-Shift-K to find backwards

Ctrl-H to find stuff in other files in your workspace.

Ctrl-Space to pop up content assist (aka tag/function insight). This one bears some elaboration for us CFMLers. You know how when you type a function name, say reFind(, and it pops up the content assist? but then when it disappears you don't know how to get it back up again? Just hit Ctrl-Space. Go ahead, try it. Go find a function in your code, put your cursor after the paren, and hit Ctrl-Space. For the energetic, read my long diatribe with a mini-section on what I call "Ctrl-Space-Learn".

Alt-Up and Alt-Down to move a whole "selection" (a line, or a chunk of lines) up or down

Tab to indent, Shift-Tab to de-indent

Ctrl-Shift-L to pop up a box showing other keyboard shortcuts

How do you get the swing of these?

I started by keeping a printout on my desk. It was a start. But the real key for me was to try to develop a palpable aversion to the mouse. For example, if I found myself mousing to create a new file, even if I were almost finished. I'd cancel it and do it with the keyboard. I'd do the same thing for all the other operations above.

I try to nurture good developer habits; becoming keyboard-addicted is one worth developing yourself.

Timesavers: Launchy

2009-04-15T05:30:00.004-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

Launchy is in my top 5 favorite applications, ever. Simply put, it makes it braindead simple to "do stuff" with just the keyboard. Some of the things I use it for:

Running bat files
Opening applications (Eclipse, Fireworks, TweetDeck, etc)
Opening/executing RDP shortcuts
Quickly navigating to directories

To use launchy, you simply hit "alt space", and the launchy window pops up. You start typing, and it looks in its cache for stuff that matches what you're typing. When you find something, you hit "enter". Your "thing" launches. That's it.

Here's what it looks like:

Once installed, Launchy by default will scan everything in your "All Programs" in the Start Menu. However, it's highly configurable, and this is where it shines.

To register anything with Launchy:

pop up Launchy with "alt space"
click the "gear" icon in the top right
click the "catalog" tab
In the "Directories" box, you can use the "+" and "-" buttons to add directories. Once a directory is selected, you can add the File Types in that directory to add to the catalog. I commonly use .bat, .lnk (those are windows shortcuts), .rdp, and .exe
Then you click "Rescan Catalog" and you're set! (you can set it to auto-scan the catalog every X minutes. Play around in the "General" tab to find out how)

Example

Remember the "Bat File Timesaver" post? At the end, I said that there was a better way to launch bat files. You can launch them with no mouse clicks at all by simply registering them with Launchy! For example, in the screenshot above, I started typing "ecl" to launch eclipse. But I don't launch eclipse with its executable; instead, I launch it with a bat file that contains certain settings:

runEclipse.bat

c:\eclipse_34_rcp\eclipse.exe -showlocation -vm "C:\Program Files\Java\jdk1.6.0_12\bin\javaw.exe" -vmargs -Xmx512M -XX:MaxPermSize=256m -XX:+AggressiveOpts -XX:+UseParallelOldGC -XX:ParallelGCThreads=2 -XX:ThreadPriorityPolicy=1 -Xverify:none

This file lives with all my other bat files in a directory somewhere on my file system. So to register this and the others with Launchy, I just add that bat file directory in the "Catalog" tab, add the .bat file type, and hit Rescan. Done! Now, when I want to launchy eclipse, I simply hit "alt space" and start typing "eclipse" and up it will pop.

Here's what the config looks like:

Easy access to directories

If you find yourself accessing certain directories over and over again, you may have created a shortcut to that directory. Then you point and double-click to open it. You can shorten this even further by adding directories into Launchy. For example, I poke around in the mxunit and mxunit-cfmeetups directories all the time. Rather than point and click to them, I use launchy. For example, if I want to get into the "plugindemotests" directory inside of mxunit, I hit "alt space" to pop up Launchy, then start typing "plu" and it'll autofill that directory. I hit enter, and it opens in Windows Explorer. So far, I've added a lot of common directories and I've seen no slowdown in launchy's ability to find just what I'm looking for.

To configure launchy for directories, just add a directory into the "Directories" box, and on the left hand side, don't add any file types. Instead, check the "Include Directories" checkbox.

Here's what launchy looks like after adding a Directory:

Alt Space, baby!

Timesavers: Batch Files

2009-04-13T06:00:00.007-04:00

This is part of an ongoing series on Timesavers. The goal is simple: short, easily-digestible posts designed to help developers get faster and more productive

A batch file on Windows is a .bat file that contains one or more commands. You can execute .bat files by double-clicking, via the command prompt, or even as an "executable" in a scheduled task. Their power as a timesaver is in their ability to encapsulate common functionality so that you don't have to click a lot or remember a lot. This is predicated on the idea that every mouse movement/click is itself a time waster.

Common Example
How do you start/stop/cycle ColdFusion? Certainly one way to do it is through the Windows Services panel. Let's count the mouse movements:

Start Menu
Control Panel
Administrative Tools
Services
Scroll to Macromedia JRun CFusion Server
Click the "Stop" or "Start" button up top

And that's just for one action. Multiply that by the other services you frequently cycle. SQLServer? MySQL?

Bat Files for Scenario Above

CF_Stop.bat

NET STOP "Macromedia JRun CFusion Server"
NET STOP "Macromedia JRun Admin Server"

CF_Start.bat

NET START "Macromedia JRun CFusion Server"
NET START "Macromedia JRun Admin Server"

CF_Cycle.bat

NET STOP "Macromedia JRun Admin Server"

NET STOP "Macromedia JRun CFusion Server"

NET START "Macromedia JRun Admin Server"
NET START "Macromedia JRun CFusion Server"

Where to store them?
Obviously, you don't want to go putting dozens of bat files on your desktop. So where to put them? I keep mine in a directory, and then add a shortcut to that directory into my windows taskbar by following these steps:

Right click in taskbar
select "Toolbars"
select "New Toolbar"
Navigate to the directory where your bat files live. Click "OK" through to the end.

From there, you can access your bat files from that new toolbar right from your windows taskbar. The nice thing about this approach is that you don't need to double-click on the file... just single click. Here's a screenshot of what it might look like:

Isn't there a better way?

Yup.... Stay tuned for the next Timesaver!

New MXUnit released: The Community Edition

2009-04-01T06:00:00.003-04:00

We're pleased to announce a new release of MXUnit. This one's especially meaningful to us because it's largely contributions from the community. Big props to:

Barney Boisvert for contributing "run this method" links to the standard HTML test output. This has been in the EXT Grid view since its inception, but that feature never made its way back into the original runner. This is a particularly welcome addition because the standard test runner is much faster than the EXT view.

Jamie Krug contributed a patch and tests for deficiencies in makePublic(). Our exchange is here. I gotta tell you, I wish open source worked like this all the time. Jamie posted a bug to the bug tracker -- a very well written bug, by the way -- included patches, went back and forth with me, wrote tests. Outstanding.

Denny Valliant has been bugging us forever about making debug() available to all components, not just your tests. He got sick of waiting on me, so he did it himself. Thus, request.debug() was born. It rocks! This is one of those things that will cause some folk to throw up their hands and say "but you're violating [insert whatever it is we're violating] here". I agree. We are. Don't use it if it offends you.

Adam Haskell contributed the first of several planned function attributes: mxunit:ExpectedException. Bill, Adam, and I have been going on about this for a very long time (too long!) in preparation for MXUnit 2.0. Blah blah blah. Meanwhile, while we were yapping, Adam wrote the expectedException functionality (and Tests). It's such a time saver!

In addition, you'll notice that the links above all point to the new MXUnit wiki. Thank Adam for all of that! We still have a lot of content to move over from the existing MXUnit docs. It'll get there (some day).

We've also had a lot of great feedback and ideas contributed from community members. Thanks to Bim Paras, Tim Farrar, Bill Rawlinson, Bob Silverberg, and all the other smart people for the excellent dialogue!

Finally, the eclipse snippets have been updated to reflect the expectedException attribute over the old try/fail/catch method for testing expected exceptions. If you like to code fast, please open up the instructions in the mxunit/cfeclipse/snippets directory. You'll be glad you did.

Thanks everyone!

How to piss off a developer

2009-03-27T06:56:00.004-04:00

This is something I whipped up years ago to brighten up a coworker's sour mood. Enjoy!

Want to piss off developers? Aggravate them? Drive them toward crowbar-bashing road rage when driving home? Follow these steps for guaranteed asshole-ness:

1. Field a call from the customer. Say YES to everything. Promise it in 5 minutes

2. Run (do not walk) to the developer's desk. Huff and Puff and breathe like you just ran a marathon. If you have trouble affecting such respiratory dynamics, hold your breath for a minute and run in circles.

3. Say something urgent like "This is urgent". Sweat is good. Tears are better.

4. Explain your hands were tied and it's a production emergency and if the client doesn't get [insert thing they want here] right away we're going to lose all their business and we'll be closing up shop tomorrow. For added effect, say something like "Think of the children"

5. DO NOT....LISTEN UP...THIS IS IMPORTANT.... DO NOT give the developer any documentation, specification, guidance, or explanation.

6. Say "They want this [again, insert thing here] right now. Please get it to me. It's urgent" (repetition is key, as you may be sensing)

1. Super-Duper Ladder-Climber Tip: when you get sufficiently good (or are certified by a professional certifying agent), you can just forward emails from clients directly to developer without any additional need for commentary. Certificates generally confer upon the sender some degree of telepathic skill. Little known fact!

2. All 9th graders learn that a 1 must have a 2. Here's my 2.

7. Then, start to whisper to the developer so no managers hear the conversation. God forbid they know what you're working on

8. Thank them profusely, effusively, gushingly, for the work they're about to do.

9. Return to seat. Surf internet. Play some games. But do set your timer.

10. In 3 minutes, email the developer. Use this template: "Dear [insert lackey's name here], Thanks so much again for getting this done on such short notice. It really means a lot to me, and to the client, that we continue to provide such world class service. You're a gem!"

11. In 6 minutes, email the developer. use this template: "Dear [insert lackey's name here], Can you give me a report on your status? YOU'RE THE BEST!!!!". The timing of your use of ALL CAPS is a finely honed skill. Guidelines are thus:

1. IN GENERAL, USE THEM WHENEVER POSSIBLE. THERE IS NO MORE FORCEFUL MEANS OF PUNCTUATING YOUR POINTS THAN WITH CAPITAL LETTERS.

2. EXCEPT WITH EXCLAMATION POINTS!!!!!!!!!!!!!!!!!!!!!!!!!!

3. As the time between the initial client request and the current time increases (now() - InitialClientRequest --> Infinity), so too should the percentage of CAPITAL letters to lowercase ones.

4. Post-issue communications, however, should use lowercase except in cases where use of lowercase violates standard written English. Like so:

1. Initial issue letter: I CANNOT STRESS ENOUGH THE IMPACT THAT NOT MEETING THIS DEADLINE WILL HAVE ON OUR FUTURE RELATIONS WITH THIS CLIENT

2. Post-issue followup letter: "Received rpt. Pls forward to [insert list of people that you are too busy to forward this to yourself here]. tks." (See below for proper use of tks).

12. Repeat that step every 5 minutes. Each time, add another upper level manager to the CC list. In addition, BCC your colleagues so they can see how hard you're working and how slow the developer is and how it's so hard to deal with people who just don't get things done. This facilitates post-issue commiseration and is a critical team-building tool. Do not discount the importance of this step.

13. Upon completion of task, forward report to client. Bask in your glory

14. Email all management explaining what a good job the team did. Pepper with phrases like "here's another example of how our team provides world class service". Be liberal in your use of phrases such as "team" and "we". Third-person plural is GOLD. If it's good enough for the Queen of England, it's good enough for you.

15. DO NOT DOCUMENT THIS. It's imperative that this go down the memory hole so that next time it comes up, the entire process can be started from scratch. Bug trackers are the devil's playground: avoid them.

16. In 2 weeks, when client finally reads said report and complains that the headings are in the wrong font, send email to developer requesting a new report. use this template: "Dear [lackey], Remember that one report? The font was wrong. Please fix. This is urgent. Tks." Click the little red exclamation point in outlook. CC management. BCC colleagues. Also BCC your friends so they can see how tough you are. Make 50 printouts and leave at printer for all to see.

1. Note use of 'tks' in template

2. This is a crucial communication technique. Your abbreviation is a cue that any socially adept recipient will immediately recognize as a manifestation of your disapproval of their performance. Most will respond by working harder. All people crave unabbreviation. It's human nature.

3. If you feel you're dealing with a less emotionally intelligent recipient, start removing subjects from your sentences. This will serve to punctuate said disapproval. To wit: NOT "The font was wrong" but "Font was wrong". better yet: "Font wrong. Will follow up. Urgent. Tks."

1. Super-Duper Ladder-Climber Tip: do not perform this subject-cide when communicating with those whose position you wish to assume someday...only lackeys and those too inferior to be graced by your pronouns. Conserve your verbiage for those who matter.

17. One final basking. Hooooold it..... Hoooooold it...... Wait for it........... Ah, yeah. That was good.

Good job

Debugging WebService errors in ColdFusion

2009-03-24T05:34:00.021-04:00

Overview

This is an article about the process of debugging a strange error I received while trying to execute an external webservice using ColdFusion 8. The external service is a java service, using Axis2, running in WebSphere. But if you're just searching for an answer b/c maybe you've hit the same problem, scroll to the bottom. Otherwise, enjoy the show.

I was executing the service like so:


<cfset ws = createObject("webservice","http://XXXXX/webservices/services/WFIService?wsdl")>
<cfset result = ws.initiateOrder(IlexCode="enr",OrderXML="<orders/>")>

It Started with this Error

Here's the error:

Cannot perform web service invocation initiateOrder.
The fault returned when invoking the web service operation is:

AxisFault
faultCode: {http://www.w3.org/2003/05/soap-envelope}Server.userException
faultSubcode:
faultString: org.xml.sax.SAXParseException: Invalid encoding name "UTF-8; ACTION="URN:INITIATEORDERRESPONSE"".
faultActor:
faultNode:
faultDetail:
{http://xml.apache.org/axis/}stackTrace:org.xml.sax.SAXParseException: Invalid encoding name "UTF-8; ACTION="URN:INITIATEORDERRESPONSE"".
at org.apache.xerces.util.ErrorHandlerWrapper.createSAXParseException(Unknown Source)

(for the lone bleary-eyed googler trying desperately to solve the same problem, i give you these keywords:
faultString: org.xml.sax.SAXParseException: Invalid encoding name "UTF-8; ACTION="
)

Here's what it looked like so you can bask in its awesomeness:

Running the service from outside ColdFusion

First, I wanted to be sure that the problem wasn't with the service itself, so I needed to execute it outside of ColdFusion. For me, the simplest way to do this is with the "Web Services Explorer" that comes with Eclipse WST (Google it, it's handy). So I fired that up, saw there were 3 different "Bindings", and I hit the first SOAP one (the Soap11 porttype) just fine.

The SOAP12 binding was unsupported, so I ignored it. I also ignored the HTTP Post binding. So in my head, what I'm thinking is "I can hit the service successfully from outside of CF. Now I'm in black box hell."

Trying to view the SOAP messages with TCPMon

First, I needed to find out what differed between the SOAP being sent by the Web Services Explorer and the SOAP being sent by ColdFusion. Having done a fair amount of development with Apache Axis back in 2002/2003, and more recently while developing the MXUnit Eclipse plugin, I was familiar with using TCPMon for doing this kind of debugging. However, I never tried to use it for debugging remote services, only local ones. (And after spending a half hour or so with it yesterday, I still don't know how to use it for debugging remote services. If you know, please tell me!). Eventually, because all I was really interested in was seeing the SOAP envelope and the http headers being sent, I just copied the wsdl from the remote services, stuck it in an xml file on my computer, and pointed my webservice call in Scribble pad to the new URL: http://localhost:8124/playground/WFIService.xml?wsdl. I then fired up TCPMon and added a listener at Port 8124

from command line, navigate to C:\jrun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\cfusion\lib
type java -cp axis.jar org.apache.axis.utils.tcpmon
The swing app pops up
Type 8124 into Listen Port (this is arbitrary!)
Target Port = 80 (though in my case, it doesn't matter anyway)
Click "add"

I then executed my local version of the service like so:


<cfset ws = createObject("webservice","http://localhost:8124/playground/WFIService.xml?wsdl")>
<cfset result = ws.initiateOrder(IlexCode="enr",OrderXML="<orders/>")>

Again, This wouldn't actually "work work", but CF would at least try to send a soap request to this address, so I'd be able to see what was being sent to the remote server. Honestly, this didn't pan out. Based on the original error, I suspected the problem wasn't with the SOAP envelope but with the headers. If you'll remember from the original error message, it displayed: Invalid encoding name "UTF-8; ACTION="URN:INITIATEORDERRESPONSE"". I suspected the problem was with the Content-Type header being sent to the service, but when I looked at it in tcpmon, it showed up like so:

POST /webservices/services/WFIService HTTP/1.0
Content-Type: application/soap+xml; charset=UTF-8
Accept: application/soap+xml, application/dime, multipart/related, text/*
User-Agent: Axis/1.2.1

And I had expected to see this in that header: "UTF-8; ACTION="URN:INITIATEORDERRESPONSE""

For the screenshot lovers, it looked like this:

So as of that moment, I was kind of perplexed. I'm sure folk with more experience consuming web services from a variety of external producers would know exactly what was going on. I, however, did not. Me + TCPMon = Fail.

Debugging with the Generated Java stubs

Some time back I had read Nathan Mische's excellent article in FusionAuthority Quarterly Update on using complex datatypes in CF web services. In the article, he mentions something new in CF8: the ability to easily view the generated java stubs created by axis (this is how CF works under the hood: it uses the wsdl2java tool from axis to dynamically generate bindings based on the WSDL).

I change my web service invocation like so:


<cfset args = {refreshWSDL=true,savejava=true}>
<cfset ws = createObject("webservice","http://XXXXX/webservices/services/WFIService?wsdl",args)>
<cfset result = ws.initiateOrder(IlexCode="enr",OrderXML="<orders/>")>

So I run the service again, get the error, and traipse on down to the stubs directory (in my case: C:\jrun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\cfusion\stubs) and open up the most recent directory. Navigate on down, and there are the java files. I decided that I wanted to see if I could execute the service from outside of CF but using these source files, so I opened up my java playground project in Eclipse (you DO have at least one playground/sandbox/scratch project, right?!), added a new package, and dropped the source files in there. The screenshot below shows the eclipse directory where I copied the generated java files on the left; on the right is the stubs directory that ColdFusion creates. Note that it's a mix of java and class files. Normally, the java files aren't in there, but the "savejava=true" key in the arguments struct that I'm now passing to CF in the createobject() call ensures the java files stay there.

When I first copied the files over into my new Eclipse package, I naturally got a bunch of errors. First, I needed to change the package declaration in the source files (alternately, I could've simply renamed my package). Second, I needed to add jar files to the the build path so that the source files would compile. This is simple:

In Eclipse, in the project's "lib" directory, I created a new subfolder called "axis12". I did this b/c I didn't want to pollute my existing lib directory, and at the time I had suspected that maybe the problem was with CF using axis 1.2 and not 1.4 (I use 1.4 for the Eclipse plugin, so I had thought maybe I'd end up running these sources files under both axis 1.2 and 1.4 and therein would've lied the bug... turned out that's not what it was at all).

Then, in C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\cfusion\lib, I copied a whole bunch of jar files that looked like they'd be required. in the end, I copied all the ones you see highlighted in the "referenced libraries" from the screenshot below. I didn't need all of these to get the java to compile, but I did need them to get it to run without getting NoClassDefFound errors when actually running the code.

In addition, I created a new JUnit TestCase for executing the generated code (simply a start... no assertions, just something to run the code):

WFIServiceTest.java:

package marc.axis;

...imports...

public class WFIServiceTest extends TestCase {
public void testCompleteOrder() throws RemoteException, ServiceException, MalformedURLException {
WFIServiceLocator locator = new WFIServiceLocator();
System.out.println(locator.getWFIServiceSOAP11port_http().initiateOrder("enr", "<orders/>"));
}
}

After doing this stuff, the damn test case didn't error! Confound it all Samwise Gamgee! I had hoped against hope that by running the service using the stubs generated from CF that I'd hit the same error that I was hitting inside of CF. This way, I could at least step through it in the debugger and have a fighting chance of getting inside the black box to figure out how to fix this. Alas, this was not to be. It was time to take a break.

Distance

Every programmer knows that one of the worst things you can do when faced with a hard-to-get-at problem of this type is to stare and obsess over it endlessly. You get tired. Your eyes hurt. Your brain turns to mush. Your shoulders ache. I really, really wanted to keep at this. Thankfully, in the background I hear my wife yell at my daughter, my daughter has a low-grade conniption (she's 5 and of late prone to such outbursts...), and Daddy has to swoop in and save the day. Being a dad always comes first. About an hour after the meltdown, it's tubby time. Afterward, I'm drying my daughter's hair, my brain's still working on the problem, and it hits me: it's the other bindings! Remember the ones from when I executed the service successfully in the Web Services Explorer (the Soap11 binding worked fine)? And remember how the Soap12 binding was unsupported, and I ignored the HTTP Post binding? Well.... they stuck in my head. And they had to be in the generated sources. So as I'm drying my daughter's hair, I'm thinking... what if CF is using one of those other bindings, and that's why I'm getting the error?

It's all about the PortName

Now, at this point, I can think of nothing else. I HAVE to get downstairs and see if that's it. Problem is, I have a wet-headed kid. So I race through that, hand her off to my sweet wife (who's busy with our littlest daughter), and hit the computer again. I change this line in my test case like so:

from System.out.println(locator.getWFIServiceSOAP11port_http().initiateOrder("enr", "<orders/>"));

to

System.out.println(locator.getWFIServiceSOAP12port_http().initiateOrder("enr", "<orders/>"));

Sweet, sweet stack trace:

AxisFault
faultCode: {http://www.w3.org/2003/05/soap-envelope}Server.userException
faultSubcode:
faultString: org.xml.sax.SAXParseException: Invalid encoding name "UTF-8; ACTION="URN:INITIATEORDERRESPONSE"".
faultActor:
faultNode:
faultDetail:
{http://xml.apache.org/axis/}stackTrace:org.xml.sax.SAXParseException: Invalid encoding name "UTF-8; ACTION="URN:INITIATEORDERRESPONSE"".
at org.apache.xerces.util.ErrorHandlerWrapper.createSAXParseException(Unknown Source)
at org.apache.xerces.util.ErrorHandlerWrapper.fatalError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLEntityManager.createReader(Unknown Source)
at org.apache.xerces.impl.XMLEntityManager.setupCurrentEntity(Unknown Source)
at org.apache.xerces.impl.XMLVersionDetector.determineDocVersion(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
.....

That was it... CF was using the Soap12 binding instead of the Soap11 binding. So all I needed to do was get CF to use the correct binding, and my problem would be solved. How to do that? I remember reading in the docs that you could use the "portname" attribute to force CF to use a specific binding, so that's what I needed to do. Now... what's the portname to use? It's simple to discover what is available to you. Just look in the WSDL, scroll to the bottom, and find stuff that looks like this:


<wsdl:service name="WFIService">
<wsdl:port name="WFIServiceSOAP11port_http" binding="ns0:WFIServiceSOAP11Binding">
<soap:address location="http://XXX/webservices/services/WFIService"/>
</wsdl:port>
<wsdl:port name="WFIServiceSOAP12port_http" binding="ns0:WFIServiceSOAP12Binding">
<soap12:address location="http://XXX/webservices/services/WFIService"/>
</wsdl:port>
<wsdl:port name="WFIServiceHttpport" binding="ns0:WFIServiceHttpBinding">
<http:address location="http://XXX/webservices/services/WFIService"/>
</wsdl:port>
</wsdl:service>

The names available to you for use in the portname attribute are the names in the wsdl:port elements. So I took the Soap11 portname, added it to the webservice invocation like so, and bam... problem solved:


<cfset ws = createObject("webservice","http://XXXXX/webservices/services/WFIService?wsdl","WFIServiceSOAP11port_http")>
<cfset result = ws.initiateOrder(IlexCode="enr",OrderXML="<orders/>")>

What I still don't understand

According to the CF Documentation, if you don't specify the portname, then CF will pick the first one it finds. Looking at the WSDL, the first element is the Soap11 binding. Why is CF using the Soap12 binding? I don't get it.

There's another lesson here, aside from the fact that portname is scalded into my brain. It's a lesson about struggle. I believe that struggle is key to learning deep. You have to be willing to fight for your answers. Sure, I tried googling for the answer first! But when I didn't find it, I didn't stop there. You have to do the same thing. If you resort to the mailing lists or forums and paste in your 1000 lines of code, you're not just annoying the people who would otherwise try to help you; you're doing yourself a great disservice. Learning is hard; it takes time; it's even worse when you're under deadline pressure and you just gotta get this thing done. Still, if you want to grow, you gotta welcome the pain.