Understanding Cargo

One of my clients has me working on revamping the infrastructure they use to build their products and run functional tests across them. They’re a Java shop, and so it’s no surprise that their product, a rather large web application, is built in Java Servlets and JSP; since they target a wide range of enterprise customers they need to test their app in as many application server “containers” as possible.

Not terribly unusual, but when you’re trying to run automated tests, it gets tricky. Although in theory one should be able to interchangeably use different app-servers, the different vendors (be they open source or commercial) who have implemented the Servlet, JSP, and J2EE specs all have their quirks. Even assuming the thing you are testing doesn’t use vendor specific extensions, you still have to deal with the problem of setting up, starting, and stopping the app-server containers themselves. And as you’d expect, each different app-server has a rather significantly different way of being configured and run.

Enter Cargo. It’s pretty slick! They have figured out how to configure, start, stop a wide range of different containers and in some cases can control them during runtime. This is all important if you’re trying to do automated testing of a Servlet based web application, because you need to have the container running and your app deployed into it before you can start doing functional tests against it. Their API is primarily meant to be used from within Java but they’ve also made ant tasks and maven plugins.

There are a few examples on the Cargo website, but figuring it out took some doing. Cargo has about three different ways to do any given task — you can set something up using the fully derived strongly typed implementing classes, or you can use one of two factory methods. Presenting all of this at the same time is confusing to say the least. Cargo consists of several very steep class hierarchies with parallel naming conventions. The terms “Local”, “Remote”, “Existing”, “Standalone” are used in permutation with “Container”, “Configuration” and “Deployer”; for instance you have a WebLogic8xLocalContainer and a Resin3xStandaloneLocalConfiguration. Gets confusing when you’re trying to learn the API for the first time, and makes code assist completion really hard (typing “Tomcat” and hitting assist, you have the joy of selecting from Tomcat3xLocalContainer, Tomcat3xStandaloneLocalConfiguration, Tomcat4xLocalContainer, Tomcat4xRemoteContainer, Tomcat4xStandaloneLocalConfiguration, Tomcat5xExistingLocalConfiguration, Tomcat5xLocalContainer, Tomcat5xStandaloneLocalConfiguration, TomcatCopyingLocalDeplyoer, TomcatLocalDeployer, TomcatRemoteDeployer, … you get the idea. Pretty crazy).

The point of me looking through all this was to be able to help my client make a decision about whether to use Cargo in their build & test architecture. I battled my way through their documentation and javadoc trying to duplicate a simple example. Once I started drawing some simple diagrams of the class hierarchies, though, it began to come together. I did up my notes in OpenOffice Draw to make them presentable. Here’s the result:

First, cargo has the notion of a “configuration” being a particular setup for an instance of a running app-server container. This takes a brief moment to grok because normally one installs WAR/EAR files directly into the appropriate directory within (under) wherever the server is installed — only since one normally only ever has one instance of a server on a given box, you don’t tend to think about it. It turns out (always something to learn) that the Servlet and Enterprise Application Server specs state that the information and data to be used in a running instance can all be bundled together and put … wherever. Cargo calls it a Configuration. It’s a steep hierarchy, but the important bits seem to be as follows:

Once you’ve got a configuration, then you bring up the app-server container with it. Cargo’s Container hierarchy is like this:

As you can see, there are considerable variations on the core theme – did you set it up before you ran the app-server, or after; is the app-server Local where Cargo can get at it, or Remote where it can’t…

Once you get the sense of it, though, it’s a very powerful tool. To accomodate the wide range of containers that Cargo does is a remarkable achievement, and watching it Do The Right Thing ™ in each different case is remarkable.

AfC