NOTE: I retired the dedicated contract4j.org domain. You can now find the home page and other content at polyglotprogramming.com/contract4j.

News:

  • Contract4J is now available through Maven and the source code is now managed on GitHub. (March 13, 2010) Releases will still be available through SourceForge.
  • Contract4J v0.8.0 is now available (Sept. 13, 2007). Deprecated JRuby support, made the use of the Bean Scripting Framework optional, and improved robustness (better support for testing generics and referencing other objects in test expressions).
  • Aquarium v0.1.0, an AOP toolkit for Ruby is now available (Sept. 1, 2007). It includes a simple Design by Contract module. AOP in Ruby is an interesting and different experience!
  • Contract4J v0.7.1 is now available (Jan. 21, 2007). Documentation changes, only. It fixes some documentation "bugs" and adds more information on using load-time weaving (LTW).
  • Contract4J v0.7.0 is now available (Dec. 31, 2006). It adds support for defining test scripts using Groovy and JRuby, in addition to Jexl. In fact, Groovy is now the default language.

Contract4J is a tool that supports Design by Contract® (DbC) programming in Java 5. Contract tests are defined using Java 5 annotations and aspects written in AspectJ evaluate the test expressions at runtime and handle failures.

In DbC, the designer considers the conditions required for a module or method to successfully perform its intended services, the preconditions, and what results it can guarantee to deliver, the postconditions, if the preconditions are satisfied. The designer can also specify invariants that must be satisfied.

DbC is an underused technique for improving software quality, by thinking through design issues more carefully and testing compliance during development and testing. It also complements other techniques very well, such as Test-Driven Development (here and here).

Contract4J, like the original implementation of DbC in Eiffel and the XDoclet-based Barter for Java 1.4 and earlier, provides a standard way to define DbC tests and to evaluate them at runtime. Barter uses XDoclet tags and generates AspectJ test code. Contract4J uses Java 5 annotations to define the condition tests and it uses "prebuilt" AspectJ aspects to advise the execution points ("join points") where the tests should be evaluated. If the tests fail, both tools terminate program execution.

Annotations have a few advantages over javadoc-style tags: they can be included in the generated Javadocs and the JVM can be aware of the annotations at runtime. The runtime awareness can support other aspect behaviors.

For more information:

Quick Example A quick example demonstrating usage of Contract4J5.
Contract4J5 README Detailed information on installation, usage, theory, etc. for the annotation-based version of Contract4J.
Contract4JBeans README Detailed information for an earlier, "JavaBeans-like" version of Contract4J
GitHub: GitHub Repo.
SourceForge: project and downloads pages.
White Papers I presented two papers on Contract4J at AOSD 2006 in March. They discuss the Aspect Design issues encountered while developing Contract4J and the lessons learned for building reusable Aspect libraries. The papers can be found here.

Contract4J is a project of Aspect Research Associates.