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, the only one that exists is Diez' contrib package ( org.enhydra.barracuda.contrib.dbroggisch ).
Hopefully we will get more excellent contributions such as this!
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
- The part that makes up the barracuda-contrib.jar which is built when running the "contrib" target in the Ant build process.
- 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 a 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
WEB-INF/lib, WEB-INF/lib-ext, or WEB-INF/jars. There is no hard-and-fast rule here. It will be addressed on 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 -Dsubproject=[all|dbroggisch|other...] -Dsubtarget=[all|clean|compile|install|remove] contrib
If we just want to build the barracuda-contrib.jar we do:
ant contrib
if we want to build a webapp in a particular subproject we do:
ant -Dsubproject=dbroggisch -Dsubtarget=compile contrib
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 build.properties file in the webapp that you wish to run these tasks upon and change:
- The manager username and password to match that of a user existing in Tomcat which has manager privileges.
- The system path to where $CATALINA_HOME exists on your machine.
You must also copy catalina-ant.jar from $CATALINA_HOME/server/lib to $ANT_HOME/lib. In addition, you must either use
Ant-1.4.1 or a recent alpha of
Ant-1.5.1 because there is a
bug in Ant-1.5 which causes the build to fail. Oh, and make sure that all the
XMLC, JTidy, and gnu-regexp libraries exist in $CATALNIA_HOME/shared/lib. The build expects them to be there. Everything else will be taken
care of for you by the build process.
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
|