| Delphi Clinic | C++Builder Gate | Training & Consultancy | Delphi Notes Weblog | Dr.Bob's Webshop |
 |
 |
 |
| Delphi Clinic | C++Builder Gate | Training & Consultancy | Delphi Notes Weblog | Dr.Bob's Webshop |
|
|
|
| |||||||
Assertions can be used as a debugging tool to test that conditions assumed to be true are never violated. When an assertion is violated an exception will be raised, and program execution is halted. This way the program will not run, when unanticipated conditions have been met.
Java doesn't provide assertions to be implemented in our applications. But luckily for us, JBuilder does (in a way). The key class is borland.jblc.util.Diagnostic. This class contains a lot of useful methods to debug our program flow. And with a simple compiler directive we can exclude this class from the final compiled version of our application or applet, so the assertions are excluded from the class. We have to remember that assertions are useful for in the development process of our program, not for running a final version of the program.
We will take a look at some of the methods in the Diagnostic class, and see how to use them in our programming.
check(boolean condition) and check(boolean condition, String description)
The check method takes the condition to be checked as parameter, and an optional descriptive message for the condition.
If the condition fails, and thus returns false, a DiagnosticCheckException is raised.
We don't have to catch this exception, so when a check fails, all statements following this check will be ignored.
And besides we don't want to catch the exception, because if we do, we can't remove all the Diagnostic statements from our class file, when compiled.
Suppose we have the following method, with a check statement:
private void loadImage(String fileName) {
// try to create url object
//
java.net.URL url = getClass().getResource(fileName);
// Perform check on url result. The result should always be an url object,
// if not, something is wrong, and needs to be fixed !
//
borland.jbcl.util.Diagnostic.check( url != null, "URL must not be null");
// Print url object to System.out
//
System.out.println("Value of URL: " + url.toString());
}
If the the getResource method returns null the check failes, and an exception is raised.
When we run this method, and the getResource method returns null, we get something like the following output:check failed: URL must not be null borland.jbcl.util.DiagnosticCheckException: URL must not be null ... error stack trace omitted ...We see the failure of the check, and our description as explanation. If the url wouldn't be null, we would see the output line, displayed when the System.out.println statement following the check is invoked.
precondition(boolean condition) and precondition(boolean condition, String description)
The precondition method can be used to check parameter values and state before a method body is executed.
If the precondition fails, a borland.jbcl.util.DiagnosticPreconditionException is raised.
Basically it is the same as the check method, only with a different name.
Implementing this method will make it clear in our code what we are checking for: a precondition or a check inside a method body.
When we invoke the following method:
private void loadImage(String fileName) {
// Precondition check for fileName parameter
//
borland.jbcl.util.Diagnostic.precondition( fileName != null, "fileName must have value");
// try to create url object
//
java.net.URL url = getClass().getResource(fileName);
// Print url object to System.out
//
System.out.println("Value of URL: " + url.toString());
}
and if the fileName parameter is null, the following output will be shown:
precondition failed: fileName must have value borland.jbcl.util.DiagnosticPreconditionException: fileName must have value ... error stack trace omitted ...The method body is not executed, because the precondition failed.
enableChecking(boolean enable)
When developing and deploying our application or applet, we don't always want the checks or preconditions to be invoked.
One way to make sure the methods aren't invoked, we can put these statement in comments.
But the borland.jbcl.util.Diagnostic class provides a method that will enable or disable all check and precondition method calls in our program.
When we invoke borland.jbcl.util.Diagnostic.enableChecking(true) all checks and preconditions will be checked.
And if we invoke the enableChecking method and set the parameter to false, the checks and preconditions will not be called.
This way we can easily activate and deactivate all checks and preconditions in our programs.
Removing assertions from the final build
Assertions are meant as a tool for developing our programs.
So when we ship our program, and it is time for the final build, we don't want to include our assertions in the class files.
Luckily we can very easily remove all method calls from the borland.jbcl.util.Diagnostic class in our program.
We can use the compiler to strip the calls, using the following steps:
Now when we compile our class all check and precondition statements are excluded from the class.