Using Jcontract: A Simple Example
Introduction
The following example demonstrates how to use Jcontract to instrument and compile a simple class, then check its contracts at runtime.
Before you try this example on your own system, make sure that you have already set your environment for Jcontract as described in Window Installation and Setup or UNIX Installation and Setup.
A Simple Example
The Example.java File
In this example, we check the contract of the following simple example file, Example.java. This file is located in the examples subdirectory of your Jcontract installation directory.
public class Example
{
/** @pre month >= 1 && month <= 12 */
static void setMonth (int month) {
// ...
}
//////////
public static void main (String[] args)
{
setMonth (13);
}
}
If you look at the contract in this code, you'll see that it contains a @pre tag that states that the month value must be an integer between 1 and 12. Preconditions check whether or not a method is called correctly. They are checked right before the method is called, and they can access anything accessible from the method scope except for local variables.
Checking the Contract
To check if this contract is met, compile the class with Jcontract's dbc_javac compiler, then run it as normal. To do this, perform the following steps:
- Compile the class by entering the following command at the prompt:
dbc_javac Example.java
- Run the class by entering the following command at the prompt:
java Example
If you have not modified the Jcontract default setting, the Jcontract GUI Monitor will then open.
Exploring Results
By default, the Jcontract Monitor reports runtime progress and lists any contract violations found. In addition, all result information is saved in a Jcontract log file. For more information about this log file, see The Log File.
If you look at the Jcontract Monitor, you will see that Jcontract found one contract violation in this example. This violation is listed in the Contract Violations branch in the right side of the monitor. The violation message reveals that the @pre contract condition that stated that the month value must be between 1 and 12 was not met and that the method was called incorrectly.
To learn more about the violation found, expand that branch by clicking the plus sign to the left of the violation message.
The stack trace information reveals that the violating value was set in line 13. To see the code in a source viewer, with line 13 highlighted, double-click the stack trace line that refers to line 13 of Example.java
This line of code sets the month value to 13. Because the @pre condition stated that the month value had to be an integer between 1 and 12, this value violates the contract.
Fixing Errors Found
When you are ready to fix any Design by Contract violation found, there are two main things you'll want to do:
- Examine the code to determine if there is a problem with the code or a problem with the contract.
- If the problem was with the code, fix the code; if the problem was with the contract, modify the contract.
In this case, the problem appears to be with the code. If you wanted to modify this code, you could do so by right-clicking any line of the stack trace information, then choosing Edit Source from the shortcut menu. This opens the code in the default editor (WordPad).
Note: You can configure Jcontract to open code in your preferred Source Editor by performing the following steps:
- Open the JContract preferences tab in one of the following ways:
- In the Jcontract Monitor, choose Edit> Preferences.
- Enter the following command at the command prompt:
dbc_preferences
- Choose Start> Programs> Jcontract> Edit Preferences.
- In the Editor tab, enter the command for your preferred editor as well as any parameters you want to pass to that editor.
- Click OK.
Additional Examples
A number of example .java files that contain DbC contracts are available in <jcontract_install_dir>/examples. To learn more about Jcontract, try compiling and running these examples on your system.
|