Overview

This guide is about the Eclipse plug-in net.sourceforge.c4jplugin.runtime and the C4J Library it encapsulates. Most of this documentation has been extracted from the homepage of C4J.

What is C4J and Design by Contract (DBC)

Contracts for Java (C4J) is a Design By Contract (DBC, see Wikipedia DBC definition and Eiffel DBC docs) framework for Java 1.5 and later. The primary goal for C4J is ease of use. DBC is about design and quality, aspects of programming that a lot programmers don't spend enough time and energy on.

Therefore a DBC framework must be simple and painless to use. At the same time the framework must be powerful.

C4J is simple and powerful.

Two favourite ideas of the author of C4J, underlying the philosophy of Design by Contract, are:

• To be able to define meaningful contracts you are forced to split lengthy methods in to small, well defined, methods with a single responsibility. This single "side effect" of DBC has very positive effects on the code quality, maintainability, and readability.
• Your tests are verified against the real usage of your application, not against some test cases that may not even be real use cases.

How does it work

Adding class invariants, pre conditions, and post conditions to your regular Java objects is easy with C4J. Contracts for a class (the target) are implemented in a separate class (the contract). The contract is linked to the target at compile time using an annotation, and the actual contract verification code is tied to the target using instrumentation during class loading at run time.

Contracts implementations have a reference to the instance of the target that it is verifying. This reference is used to implement class invariants. Pre and post conditions also have access to the target reference, as well as the parameters that the target method is invoked with. If the contract class extends a C4J ContractBase class, post conditions will also have access to method return values, and pre invokation values (i.e. values of instance variables in the target prior to the method invocation).

There are several reasons for defining contracts in plain Java and in a separate class:

• You don't have to learn any new language constructs.
• You will get help from your IDE when implementing the contract (as opposed to implementing contracts in comment blocks).
• It is possible to put break points in your contract if you want to debug them.
• Separating the contract code from the application makes it possible to remove the risk of accidentally deploying the contracts together with your application.
• You get to keep your beautiful code nice and clean without all the ugly assertions.

The plug-in net.sourceforge.c4jplugin.runtime

This plug-in is part of the C4JPlugin sourceforge project and acts as a wrapper for the c4j.jar and javassist.jar library. In addition, it contains this guide which is integrated into the Eclipse help system. This eases the use of C4J for Eclipse developers and constitutes the basis for the net.sourceforge.c4jplugin plug-in. This additional plug-in extends Eclipse with useful capabilities in order to write and manage contracts more easily. A description of it can be found in the C4J Plug-in User Guide in the Eclipse help system.