I'm currently writing my third book and I'm starting to notice a pattern. Whenever I write a book about a tool/framework to which I have access to the sources, the code ends up being better.

The way I work goes like this: I start writing about a topic. If it's taking too long to explain it, I consider that something is wrong about the code. I modify the source code so that the document I'm writing has the minimal required size to explain the topic.

The good thing with a book is that what you're explaining has to be simple and not convulted which leads to this nice effect of improving usability of your code. I get a bit of the same result when I write project documentation but not to the same level. This is probably simply because writing a book is a more involved process, you dedicate more time to it and thus you want it to be as perfect as possible (and thus as readable as possible).

I guess nothing here is new. This is all about having a user of your code. Tests are "users" of your code and thus leads to better design. I guess documentation can also be a "user" of the code and thus help improving it.

If you're writing some framework/tool, consider writing a book for it and if you're diligent in your writing your code will end up being better! As an added benefit your users will love you... :-)

Cargo is a container-manipulation library that allows configuring, starting and stopping containers. It also deploys modules to those containers. Version 0.7 has been released last week along with version 0.1 of a Maven2 plugin. The nice thing about Cargo is that it provides a uniform API across all containers and it has several end user APIs: a Java API, Ant tasks, a Maven 1 plugin, a Maven 2 plugin, a Netbeans plugin, an IntelliJ IDEA plugin, etc. You can use any of those extensions with all the supported containers.

Note: Adding a new container is very easy and you only have to implement a small interface and your container will be made available automatically through all the existing end user APIs - Make sure to contact us if you're interested in adding a new container support.

I'd like to quickly demonstrate how to use the new Maven 2 plugin on 2 use cases (more samples can be found here):

• Use case 1: Deploying a WAR to Tomcat 5.x and starting the container
• Use case 2: In-place webapp deployment with Jetty 4.x

Deploying a WAR and starting Tomcat 5.x

Create a Maven 2 project and put the following configuration in your pom.xml file:

[...] <packaging>war</packaging> [...] <build> <plugins> <plugin> <groupId>org.codehaus.cargo</groupId> <artifactId>cargo-maven2-plugin</artifactId> <configuration> <container> <containerId>tomcat5x</containerId> <home>c:/apps/jakarta-tomcat-5.0.30</home> </container> <configuration> <dir>${project.build.directory}/tomcat</dir> </configuration> </configuration> </plugin> </plugins> </build>

To generate your WAR, start Tomcat and deploy the WAR in it, simply type: mvn package cargo:start . That's all! Do you want to do the same in, say, Orion 2.0.5? Simply change tomcat5x with orion2x and the home element to point to where you have installed Orion 2.0.5. You don't have Orion on the machine running the build? No issue, simply replace <home> with:

<zipUrlInstaller> <url>http://www.orionserver.com/distributions/orion2.0.5.zip</url> </zipUrlInstaller>

Orion 2.0.5 will then be automatically downloaded and installed the first time you run your build.

Inplace webapp development with Jetty

Let's imagine you're using the same project as above but this time you'd like to start Jetty and make it point to your webapp directory (i.e. src/webapp ) so that whenever you make a change to your webapp's sources Jetty automatically picks it up and serves it. See Brett's nice blog post on this. Simply modify your pom.xml as follows:

[...] <packaging>war</packaging> [...] <build> <plugins> <plugin> <groupId>org.codehaus.cargo</groupId> <artifactId>cargo-maven2-plugin</artifactId> <configuration> <!-- No container specified thus it'll default to Jetty --> <configuration> <dir>${project.build.directory}/jetty</dir> <deployables> <deployable> <!-- Override location to point to the exploded webapp. Otherwise it'll deploy the generated WAR. We want to ensure that jetty reloads any change made to the webapp source tree... --> <location>${basedir}/src/main/webapp</location> </deployable> </deployables> </configuration> </configuration> </plugin> </plugins> </build>

Then open a shell prompt and type mvn cargo:start . Jetty will start and monitor your webapp's dir for any change (Note that the same can be achieved using other containers too).

If you're interesting in learning more, check the documentation and join us on the Cargo mailing lists.