Umber Tools Project

Project Summary

The latest release of Umber Tools is 0.3.5.

The Umber project provides simple, flexible, free, "earthy" Java tool libraries for developers. The tools supplement common tasks like XML handling, data processing, and PDF generation, but without the complex and arcane APIs of most modern implementations.

Dependencies on external libraries are minimized wherever possible, to keep Umber deliverables lean and efficient. In most cases, third party libraries are auto-detected and optional.

The core of the initial source code was imported from the Bellows and Catalan projects in WritersForge. Those projects are now maintained within the Umber Tools Project, and no further releases will be made for them in the WritersForge Project.

In order to keep the dependencies lean, it will be necessary to implement some Umber Tools functionality (already available in competing software libraries) from scratch. However, because the Umber libraries have a much more focused scope, the APIs are much smaller and easier to use than the broader-scoped standards. For example, Bellows is essentially a simplified version of DOM XML and XPath, without the mandated APIs and peripheral feature sets of those full industry specifications.


Core is the foundation upon which all other Umber projects rest. It provides common, universal functionality, such as text manipulation, logging, regular expressions, easy email access, resource and class helpers, and even a simple socket server class.

Core has no required external dependencies, but does provide some "soft" wrappers around optional dependencies, like JavaMail, regexp APIs, some logging frameworks, and the Velocity template engine. These wrappers will detect the presence of the external libraries and fail gracefully if not found. In some cases (logging and regexp), Core wraps more than one implementation behind the same front-end API, and can dynamically select for you which implementation to use, by testing for the libraries on the CLASSPATH. You can also explicitly choose one if you prefer that.

For example, you can specify that Core should use Sun's java.util.logging API instead of Log4J, even if Log4J is on the CLASSPATH. By contrast, Jakarta Commons Logging wraps both frameworks, but will force use of Log4J if that jar is on the CLASSPATH.


Bellows is a lightweight XML loader and extraction tool. It implements a narrow subset of the XPath querying language with a few small enhancements (e.g., support for Python-style array ranges). The goal of Bellows is to provide an easy way to access and manage XML documents in arbitrary formats, and thus it does not attempt to use the more complex, rarely used parts of the XML, DOM, and XSLT specifications. Bellows uses a SAX loader to parse the XML into a tree of Bellows Datum objects (analogous to DOM Nodes), which can then be queried with the DatumQuery class. Bellows also supports HTML parsing with the optional TagSoup library.


Catalan is a framework for processing data of various formats, using the concept of a queue to encapsulate discrete actions upon a series of data objects.

NOTE: The Catalan library is currently under heavy revision. Much of its former code base is being offloaded into Bellows and Crucible, and the core API is being re-engineered from the ground up to better support its new direction. As such, it is probably not as usable now as it has been in the past. Anyone interested in using the latest Catalan is welcome to post questions to the Mailing List or Discussion Forum. The Catalan library should be stable by the 0.4.0 release.

The Catalan Forge is a style of blacksmith forge developed in 8th century Catalonia. Its hallmark was the use of a water-driven bellows. It was commonly used in the American frontier colonies.


Crucible is a document layout and generation suite (spun off from Catalan). It can convert plain text documents with a few simple formatting rules into XML, HTML, and PDF documents. It also offers a simple high level wrapper API for creating PDFs, with the popular PDF libraries, iText, PDFBox, and GNU jPDF. As this generic PDF API matures, applications will be able to build sophisticated PDF documents without regard to which PDF framework they are using. It also has an easy wrapper around JasperReports.

The project is brand new, and initial specifications are still underway. Later versions will include a JavaBean PDF model and editing support for PDF documents.


The Ballast project was created to help automate the creation of Hibernate bindings from live databases, using JDBC metadata and the Velocity template engine. Ballast loads database metadata into a simple JavaBean model which Velocity can expand into templates to create arbitrary Java, XML, etc. files; it is bundled with default templates for creating simple Hibernate JavaBeans and XML bindings. Future versions will improve the default bindings, and add new input sources and output formats.

The word "ballast" means both "heavy material that is placed in the hold of a ship to enhance stability" and "something that gives stability, especially in character."


Palm OS PRC resource explorer.

An Open Source Project
Copyright © 2004-2005 John R. Sheets