Note: This project is obsolete and is not being maintained. It might be useful for research purposes, but is not suitable for real-world usage!

Barter - beyond design by contract

What is Barter?
Quick reference
Advanced features
F.A.Q.
Examples
License
To do
Contact

What is Barter?

Barter is a tool for increasing the quality of applications written in Java. It allows the programmer to use design by contract and define other development aspects right in the classes and interfaces where they are relevant, as JavaDoc comments. It is essentially a code generator for AspectJ, implemented as an xDoclet task. If this is confusing, take a look at some examples below, and ye shall be enlightened.

Please visit the Barter project page at SourceForge for downloads.

Quick reference

Special variables

$this: Refers to the instance the contract is being evaluated on. Available in @barter.invariant, @barter.pre, @barter.post, @barter.before, @barter.after.
$result: Available in @barter.post, @barter.after.

Class level

@barter: Triggers aspect generation for the class.
@barter.invariant booleanExpression: Class invariant. Expression is evaluated before and after the invocation of any public method on the class.
@barter.warning aspectjPointcut : String: Emit a compilation-time warning if the pointcut exits in the program.
@barter.error aspectjPointCut : String: Emit a compilation-time error if the pointcut exists in the program.

Method level

Note: in method level expressions, you can refer to all the parameters passed in to the call.

@barter.pre booleanExpression: Precondition: expression is checked before the method is executed.
@barter.post booleanExpression: Postcondition: expression is checked after the method returns.
@barter.before javaExpression: Expression is executed before the method is invoked.
@barter.after javaExpression: Expression is executed after the method returns.

Advanced features

Violation handlers

Barter provides a flexible way to handle assertion failure. You can specifiy your own implementation of barter.runtime.ViolationHandlerI, that will be invoked when a pre-/postcondition or invariant fails. The default implementation throws a BarterAssertionFailed error. To specify an alternative class, you have to set the barter.invariantHandler system property (see build.xml for an example of how to do this). A "tracing" handler that simply prints the exception is also included (barter.runtime.impl.TracingViolationHandler) - this is useful if you are instrumenting an existing application.

Assertion configuration

It is possible to selectively evaluate assertions. You just need to provide an implementation of barter.runtime.AssertionConfigurationI, and set the barter.assertionConfig system property to the classname. This way you gain runtime control over which assertions to evaluate on a per-class basis. You could help out by writing a nice AssertionConfigurationI that can read a configuration file.

F.A.Q.

How is Barter different from using AspectJ?

Barter focuses on capturing the "usage policy" of classes and interfaces where they are the most convenient: right in the source code of the class. AspectJ requires you to maintain these aspects in separate files. AspectJ is very expressive, however, it can be overwhelming for common things, like verifying pre- and postconditions. Barter attempts to keep simple things simple.

How is it different from other Java design-by-contract tools?

Other tools, like iContract also provide design-by-contract. Barter leverages the advanced features of AspectJ, so you can define more interesting contracts/policies about a class, and add other development aspects.

Does this mean that I don't have to write any boring test-cases?

Barter significantly reduces complexity of testing, but doesn't replace it. Even though assertions are now consistently enforced (and inherited), you still need to excercise the classes, and test interactions between them. And as usual, aspects come to the rescue.

Is it buzzword-compliant?

Hell, yeah. You can easily use Barter and any of the following expressions in the same sentence: aspect oriented / extreme / literate programming, agile development, continuous integration, and a lot more...

Examples

The following code demonstrates simple pre- and postconditions and inheritance of contracts.

/** @barter */
interface Foo {

	/**
	 * @barter.pre bar>0		
	 * @barter.post $result!=null
	 */
	public String getFoo(int bar);

}

/** @barter */
class FooImpl implements Foo {

	/**
	 * @barter.post !$result.equals("ugly")
	 */
	public String getFoo(int bar) {
		switch (bar) {
			// intentional bugs :-)
			case 10: return "ugly";
			case 100: return null;
		}
		return "ok";
	}
	
	public static void main(String args[]) {
		Foo f = new FooImpl();
		f.getFoo( 5 );		// everything's fine
		f.getFoo( -2 );		// caller violates the precondition defined in Foo
		f.getFoo( 10 );		// implementation violates the postcondition defined in Foo
		f.getFoo( 100 );	// implementation violates the postcondition defined in FooImpl
	}
}

License

Barter is released under the terms of the LGPL (GNU Lesser General Public License).

To do

Implement ability to refer to "old" variables in postcondition
Fix unusal (shall we say broken) precondition inheritance. Preconditions are evaluated the same way as postconditions: using AND instead of OR. This goes againts the Liskov Substitution Principle, and general DbC implementations. I haven't really figured out how to implement this properly with AspectJ. Looks like other people also ran into this issue (page 10).
Implement simplified accessors for Collections (eg. foreach, exists)
Test effect on exception handling
More documentation
More examples

Contact

For discussing Barter, please subscribe to the barter-users mailing list. If you have any comments, questions or contributions, feel free to drop me an email.