In order to deploy a Rails app, I've had to learn the innards of Microcontainer's deployer framework. After a few wrong turns, I feel like I've finally gotten a handle on it.

While we're all used to dropping in an .ear or a .war, and might think in terms of deploying these archive formats, that's ultimately one step removed from true deployment through MC.

Within MC, when you deploy a .war or an exploded WAR directory, the first step is something recognizes that the chunk you're deploying is roughly shaped like a WAR. I'll address that phase of deployment in a future post.

Knowing that the deployment is a WAR also tells MC to look in WEB-INF/ for meta-data descriptors, such as web.xml and jboss-web.xml. This is where true deployment of components starts. Deployment runs through a series of stages, with deployers setup to match particular files and stages, doing the right things at the right time.

One of the earliest stages is the PARSE stage. A deployer can be bound to this stage to be given an early chance to match, parse, and act upon any meta-data file. For normal WAR deployment, the WebAppParsingDeployer does exactly that. There's a nice hierarchy of classes to make parsing XML descriptors such as web.xml super simple.

The WebAppParsingDeployer is the bridge from a web.xml file sitting on the filesystem or in an archive to the MetaData deployment bits. The parser reads web.xml, and produces a WebMetaData object associated with the deployment. The WebMetaData is simply a nice object-tree representing anything you can denote in web.xml.

We also might have a jboss-web.xml meta-data in our WAR, and that is parsed during the PARSE stage by the JBossWebAppParsingDeployer. This deployer, like the previous, reads the XML file and creates, in this case, a JBossWebMetaData object.

Once we've parsed these .xml files, the container has enough information to build up the classpath for the component. Some of these deployers have also thrown off or modified some ClassLoadingMetaData, which describe paths that should be added to the classpath.

As the container enters the CLASSLOADER stage of deployment, other magic occurs to actually set up the classpath.

In the end, it's the JBossWebMetaData that drives the ultimate deployment, but what if we don't have a jboss-web.xml? That's where the MergedJBossWebMetaDataDeployer comes in. It looks for a WebMetaData, and a JBossWebMetaData if one has been parsed, and merges them into a singular JBossWebMetaData. I think it also mixes in any defaults that you have set for server-wide settings.

Additionally, as jboss-web.xml is parsed by JBossWebAppParsingDeployer, it will perform the merge itself. Additionally, magic is occuring to merge any annotation-based meta-data.

I'm a little fuzzy on the ins and outs of the CLASSLOADER stage at this point, but magic occurs there.

And our app still isn't deployed yet. But we're getting there.

Finally, we enter the REAL stage of deployment, which fittingly-enough, is where the actual deployment occurs. Hooray!

Our TomcatDeployer is hanging out there, waiting for JBossWebMetaData objects to appear. When it sees one, it goes to work setting up information for Tomcat to deploy a web-app. It configures everything in Tomcat from the information other deployers figured out from web.xml and jboss-web.xml and embodied in the MetaData.

It jams it into Tomcat, hits the big red "go" button, and port 8080 is serving you web-app.

Finally.

In general, to deploy in AS5 using Microcontainer, you need some MetaData bits, and perhaps a bag of files/classes/resources. Nothing says they have to be bundled into a .war, or include some j2ee XML deployment descriptor. If you have other magical ways of bundling MetaData and resources, you're good to go.

Of course, Ales or Adrian may tell me I'm completely wrong. That's always a possibility. In fact, I'm sure I've got some things wrong, in reverse order, and otherwise mixed-up.

Here's a picture for you, though.

Update:

While discussing this on the Microcontainer user's forum, I discovered that there are indeed several errors and inconsistencies in the above.

Update #2:

New image, slightly new text to match the image better. Comments and clarifications still welcomed.