What is jContractor?

jContractor is a 100% pure Java implementation of Design By Contract for the Java language. Contracts are written as methods that follow a simple naming convention. jContractor provides runtime contract checking by instrumenting the bytecode of classes that define contracts. jContractor can either add contract checking code to class files to be executed later, or it can instrument classes at runtime as they are loaded. All contracts are written in standard Java, so there is no need to learn a special contract specification language. jContractor is purely library based, requires no preprocessing or modifications to the JVM.

Licensing

jContractor is released under the Apache Open Source License.

What is Design by Contract?

Design By Contract, the brain child of Bertrand Meyer, is a method of building quality software by explicitly specifying what each function in a system requires to do its job, and what it provides to the caller. Design By Contract is fully integrated into the Eiffel language, designed by Dr. Meyer. Contracts as implemented by jContractor consist of preconditions, postconditions, and class invariants. Preconditions must hold at the beginning of a method, postconditions at the end of a method, and invariants at all observable points of execution.

What Design by Contract is good for

Design By Contract has many advantages. The simple act of thinking in terms of contracts and explicitly stating your assumptions can do much to clarify design and pinpoint problems. And once the contracts are explicitly stated, they provide a valuable documentation. Finally, a system like jContractor can be used to enforce the contracts at runtime, making them valuable for testing and quality assurance. If a contract is violated, then there is a problem that needs to be fixed. Unfortunately, no contract violations do not guarantee a bug-free program, but it does mean that the software is doing what you think it is doing. Runtime contract checking also increases the documentation value of contracts. A complaint frequently raised against comments in code is that code and comment may easily fall out of sync. But documentation that is code will always be current.

What Design by Contract is not good for

Contracts are statements that, in a successful run of the program, should never be violated. This implies that they should not depend on parameters beyond the programmer's control. For example, contracts should not be used as an input checking device, since this would allow the user to violate contracts simply by entering invalid input. In this case, input checking should be performed in normal, non-contract, code. After being checked and handed off to an internal part of the system, contracts may require valid data. If invalid data is received, it suggests an error in the input checking routine.

Is a contract the same as an assertion?

An "assertion" is a boolean expression that must evaluate true at a certain point in a program. If the expression is false, something is seriously wrong and the program should abort with an error message. C and C++ have long supported assertions through the assert macro. Java gained this ability in JDK 1.4. Contracts are like assertions, but they go beyond simple assertions. A method's contracts are part of its specification, and give invaluable information on how the method is to be used.

Contracts also surpass assertions because they inherit. Contracts in a superclass are enforced in all subclasses, which helps ensure that subclasses define methods that behave as the superclass author intended.

When are contracts checked?

In general, preconditions are checked when execution enters a method, and postconditions are checked when execution exits the method. Invariants must hold at every observable point, and are checked at the beginning and end of every public method.

What happens when a contract fails?

An error is thrown when a contract fails. The type of error depends on the type of contract that failed, the options being PreconditionViolationError, PostconditionViolationError, and ClassInvariantViolationError. The program usually terminates with an error message when a contract is violated. It is possible to catch and handle these errors, but bear in mind that a contract violation means that the program has moved from its normal operating environment into No Man's Land. It was never intended to function under these conditions. If you catch and handle the contract violation exception, then you are anticipating something that should never take place, and bringing this situation into the program's scope. Often, contract violations point to fundamental problems that demand solution rather than exception handling.

What about contracts and inheritance?

Contracts are inherited, just like methods. When a method is overridden in a subclass, that class may specify its own contracts that modify those of the superclass method. The for rules combining contracts go like this:

A subclass method must:

Accept all input valid to the superclass method.
Meet all guarantees of the superclass method.

Put another way, the method may "weaken the precondition and strengthen the postcondition". What this means is that the preconditions for the subclass method are logical or-ed with the super class preconditions, and the postconditions are logical and-ed. This requires that the subclass accept all input valid to the super class method, and may accept more that is invalid to the super class. However, it must abide by the guarantees made by its parent, though it is given the option of strengthening those guarantees.

Like postconditions, class invariants are logical and-ed.

For more information on Design by Contract, see the links page.

The history of jContractor

jContractor was proposed in a paper titled "jContractor: a Reflective Java Library to Support Design by Contract", by Murat Karaorman, Urs Hölzle, and John Bruno. After lying dormant for a few years, the project has sprung back to life under the care of Parker Abercrombie, a student of the College of Creative Studies in UCSB. The project also owes a debt of gratitude to Chris Niederauer for help with coding, moral support, and designing the jContractor logo. jContractor is currently hosted on SourceForge.