Runtime Handlers
The classes instrumented with Jcontract use a Runtime Handler to perform appropriate actions when a contract is violated and to gather statistics on the running program.
A Runtime Handler is a class extending "jcontract.RuntimeHandler". A single Runtime Handler object is created when the first instrumented class is loaded; this same Runtime Handler object is shared by all the classes that have the same Runtime Handler class associated to them.
Jcontract provides several built-in Runtime Handlers. If you would prefer to use a customized Runtime Handler, you can create one by extending "jcontract.RuntimeHandler".
The Runtime Handler associated with a class can be specified either in the Jcontract preferences file or using the -Zruntime_handler flag with "dbc_javac".
Runtime Handlers provided with Jcontract
jcontract.MonitorRuntimeHandler
This is the default Runtime Handler used. This Runtime Handler is completely non-intrusive. The instrumented program behaves exactly the same as the non-instrumented program. When a contract violation occurs, the violation is logged into the monitor, but program execution continues as if nothing has happened.
For more information about the monitors provided with Jcontract see Jcontract's Monitors.
jcontract.ExceptionRuntimeHandler
With this Runtime Handler, a jcontract.ContractException is thrown whenever a contract is violated.
The exceptions thrown are:
Type of Violation
|
Exception Thrown
|
@pre violated |
jcontract.PreException: ... |
@post violated |
jcontract.PostException: ... |
@invariant violated |
jcontract.InvariantException: ... |
@concurrency violated |
jcontract.ConcurrencyException: ... |
@assert violated |
jcontract.AssertException: ... |
jcontract.LogRuntimeHandler
This is a non-intrusive logging Runtime Handler. Whenever a contract is violated, the stack trace where it occurred is logged into a "./jcontract.log" file. The logging information also includes the instrumented classes loaded, environment information, and statistics collected while running the program.
jcontract.LogStdoutRuntimeHandler
This is a "jcontract.LogRuntimeHandler" that writes the logging information to the standard output.
jcontract.LogStderrRuntimeHandler
This is a "jcontract.LogRuntimeHandler" that writes the logging information to the standard error output.
To run programs with the "jcontract.MonitorRuntimeHandler" Jcontract must be installed in the target machine.
To run programs with the "jcontract.ExceptionRuntimeHandler" and "jcontract.LogRuntimeHandler" the file "jcontract.jar" must be in the classpath of the target machine.
To generate programs that do not require any support in the target machine see Generating Instrumented Classes that Require no Runtime.
Note that you can also define your own Runtime Handlers. For details, see Defining Your Own Runtime Handler.
Multiple Runtime Handlers
A single Runtime Handler object is created when the first instrumented class is loaded and this same Runtime Handler object is shared by all the classes that have the same Runtime Handler class associated to them.
If there is more than one Runtime Handler class type in the running program a single Runtime Handler object is created for each type and those single instances are shared by all the classes that have the same runtime handler associated to them. The Runtime Handler that a class as associated is the one that was specified when the class was compiled using "dbc_javac".
Overriding the Runtime Handlers at Runtime
The Runtime Handler that was associated with a class when it was compiled with "dbc_javac" can be overrided by setting the property "jcontract.runtime.handler". For example if a program is run using:
$ java -Djcontract.runtime.handler jcontract.LogRunt-
imeHandler Main
then all the classes will use "jcontract.LogRuntimeHandler" as their Runtime Handler.
Generating Instrumented Classes that Require no Runtime
Jcontract can generate classes that require no runtime at all (i.e., classes that can be run without requiring "jcontract.jar" on the classpath).
To generate classes that require no runtime at all, use "-Zruntime_handler NONE" when compiling with "dbc_javac". Note that for those classes, the Runtime Handler cannot be specified by setting the property "jcontract.runtime.handler". Also, those classes will throw the following exceptions when a contract is violated:
Type of Violation
|
Exception Thrown
|
@pre violated |
java.lang.RuntimeException: @pre: ... |
@post violated |
java.lang.RuntimeException: @post: ... |
@invariant violated |
java.lang.RuntimeException: @invariant: ... |
@concurrency violated |
java.lang.RuntimeException: @concurrency: ... |
@assert violated |
java.lang.RuntimeException: @assert: ... |
Defining Your Own Runtime Handler
You can define your own Runtime Handler by writing a class that extends "jcontract.RuntimeHandler" and overriding at least the "contractViolation (RuntimeException ex)" method.
For an example see <jcontract_install_dir>\examples\ UserDefinedRuntimeHandler.java.
For Jcontract API documentation, see <jcontract_install_dir>\docs\api\index.html.
|