Barracuda - The org.enhydra.barracuda.contrib package explained
barracuda.gif (11357 bytes)Soon after the release of Barracuda-1.1.0, it was decided by the community that a contrib package was needed. The purpose of a contrib package is to enable developers who have generally useful code, which they use in their own projects, to be able to share that code with the whole Barracuda community in a structured fashion. In this doc, I will try to explain more about the contrib package in general including how one might get their own contrib package, the structure of the contrib package, and how to use the contrib package. Read on...

A General description of the contrib package

The contrib package is made up of everything in the package org.enhydra.barracuda.contrib. Under this package are the contributions of individual developers. Currently, two contrib projects exist. One is Diez B. Roggisch's contrib package ( org.enhydra.barracuda.contrib.dbroggisch ) and the other is Stefan Armbruster's contrib package ( org.enhydra.barracuda.contrib.sam ). Hopefully we will get more excellent contributions such as these!

There is much less scrutiny that goes into the contrib packages since they aren't part of the core build. That said, the code still needs to, at a minimum, compile and there should be a decently compelling reason that it exists there, meaning that it should provide some significant benefit to the Barracuda community in order to be accepted. The idea with contrib packages is that if the contrib code is deemed to be of high enough quality and adds some needed functionalty that Barracuda users are clamoring for, then the contrib stuff could be moved to the core or core/util packages.

Unless we figure out a better infrastructure to handle it, not everyone is going to get the opportunity to have their own contrib package. Those who do get a contrib package will be those who have made significant code contributions in the past and have proven their ability to create quality code and have shown their dedication to the Barracuda project. Those who get a contrib package should expect to be moderately dedicated to keeping the package useful and up-to-date.

Ultimately, the decision is in the hands of the Barracuda community itself. So, make some contributions and show the community that you care. You will likely be rewarded with the opportunity for your own contrib package.


The contrib package structure

There are a couple different aspects of the contrib package

  1. The part that makes up the barracuda-contrib.jar which is built when running the "contrib" target in the Ant build process.
  2. The part that makes up each contrib package's individual webapp which is not included in the barracuda-contrib.jar

The barracuda-contrib.jar makes available common libraries and utilities while each contrib package's webapp becomes an implementation of some of those contributed libraries. The structure of each contrib package is:

            org/enhydra/barracuda/contrib
                                    /mypackage
                                        /my1stSubpackage
                                        /my2ndSubpackage
                                        /my3rdSubpackage
                                        /webapp
            

Each of the general subpackages is just some package that the contributor wants to provide as a general library or utility which will end up in the barracuda-contrib.jar. The one exception is the "webapp" subpackage which, if it exists, is treated a special case. Everything within the "webapp" subpackage is excluded from the barracuda-contrib.jar and has its own webapp build files and webapp specific build structure.

Note that each webapp is an excellent place to look at as examples of relatively simple build structures for your own Barracuda projects. These builds are much simpler and more relevant to a normal webapp build than Barracuda's all-encompassing build.xml.

It is possible that some contrib packages may want to use external libraries which don't normally get distributed with Barracuda. In some cases, if they are webapp specific, they can just be included in the webapp's WEB-INF/lib directory. However, if the classes that use them are slated for inclusion in the general barracud-contrib.jar, we have to evaluate whether it makes sense to include them in one of Barracuda's lib directories such as Barracuda/WEB-INF/lib-cvs, or Barracuda/WEB-INF/jars. There is no hard-and-fast rule here. It will be addressed on a case-by-case basis. Just be prepared to make a good argument.


Using the contrib package

You may notice in Barracuda/src that there is a new build file called "build-contrib.xml". It is called from the main "contrib" target in Barracuda's main build.xml. It provides the logic to compile the contrib packages and allows for the ability to execute each contrib package's webapp build. The syntax goes like this:

            ant contrib -Dsubproject=[all|dbroggisch|sam|other...] -Dsubtarget=[all|clean|compile|catalina-install|catalina-remove]

            If we just want to build the barracuda-contrib.jar, we do:

            ant contrib

            If we want to perform a clean rebuild of the contrib package, we do:

            ant contrib -Dclean.contrib=true

            If we want to build a webapp in a particular subproject, we do:

            ant contrib -Dsubproject=dbroggisch -Dsubtarget=compile

            If we want to perform a clean rebuild of the contrib package and fully clean each contrib app, we do:

            ant contrib -Dclean.contrib=true -Dsubproject=all -Dsubtarget=superclean
            
Note that, additionally, you can just type "ant contrib" and you will be prompted for values of subproject and subtarget. Simply hitting <ENTER> on the first prompt (subproject) will, effectively, only build the barracuad-contrib.jar and not bother doing anything with the example contrib webapp projects.

In addition to just compiling, we can also install the application on the fly. This is provided by Tomcat-4.1.x catalina ant manager tasks which send signals to Tomcat manager app to list, install, remove, start, stop, reload, deploy, and undeploy applications. You must have Tomcat-4.1.x to use this capability. You must also modify the manager.username and manager.password properties in the build.properties file in Barracuda/src to ones matching an existing user with the manager role in Tomcat's tomcat-users.xml file in CATALINA_HOME/conf.

Note: Barracuda also imports the following build files (in order) dynamically:
  • ${user.home}/.${ant.project.name}-build.properties
  • ${user.home}/.build.properties
The above translates to the following on my Win2k system...
  • C:\Documents and Settings\jkjome\.BarracudaMVC-build.properties
  • C:\Documents and Settings\jkjome\.build.properties
Windows users will need to create files starting with a period via the command line. The Windows GUI doesn't allow the creation of files beginning with non-alphnumeric characters.

Adding the manager.username and manager.password properties to either of those properties files will override the values set in any properties files in Barracuda/src. This makes it so you can have your own defaults without ever touching Barracuda's properties files. You can use this technique for any properties you'd like to override. BTW, the same applies to the contrib projects so you can have properties files specific to those projects as well!

Now you can do the following to install the contrib webapp examples directly into Tomcat...
            ant contrib -Dsubproject=dbroggisch -Dsubtarget=catalina-install

            or

            ant contrib -Dsubproject=sam -Dsubtarget=catalina-install

            or better yet...

            ant contrib -Dsubproject=all -Dsubtarget=catalina-install
            

In order to build contrib example webapps, you must use Ant-1.5.1 or better because there is a bug in Ant-1.5 which causes the build to fail.


Final Notes

Some of this may change in the near future as the buld process gets more sophisticated, but it is already pretty slick and I'm kind of proud of it. I, pretty much, just made it up as I went along and it seems to work quite nicely, if I do say so myself :-) Plus it taught me a thing or two about Ant.

Let us know what you think. Is there is anything that might be improved upon? Also, don't hesitate to ask questions. I want to get more people using and, hopefully, contributing to the contrib packages (as well as Barracuda itself).

--Jacob Kjome

For all the latest information on Barracuda, please refer to http://barracudamvc.org
Questions, comments, feedback? Let us know...