Added by jgarnett, last edited by Martin Desruisseaux on Jan 16, 2008  (view change) show comment

Labels:

pending pending Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

The Java language has for a couple of years now made an assert keyword available; this keyword can be used to perform debug only checks. While there are several uses of this facility, a common one is to check method parameters on private (not public) methods. Other uses are post-conditions and invariants.

Reference: Programming With Assertions

Pre-conditions (like argument checks in private methods) are typically easy targets for assertions. Post-conditions and invariants are sometime less straighforward but more valuable, since non-trivial conditions have more risks to be broken.

  • Example 1: After a map projection in the referencing module, an assertion performs the inverse map projection and checks the result with the original point (post-condition).
  • Example 2: In DirectPosition.equals(Object) implementations, if the result is true, then the assertion ensures that hashCode() are identical as required by the Object contract.

Use Assert to check Parameters on Private methods

private double scale( int scaleDenominator ){
    assert scaleDenominator > 0;
    return 1 / (double) scaleDenominator;
}

You can enable assertions with the following command line parameter:

java -ea MyApp

You can turn only GeoTools assertions with the following command line parameter:

java -ea:org.geotools MyApp

You can disable assertions for a specific package as shown here:

java -ea:org.geotools -da:org.geotools.referencing MyApp

Use IllegalArgumentExceptions to check Parameters on Public Methods

The use of asserts on public methods is strictly discouraged; because the mistake being reported has been made in client code - be honest and tell them up front with an IllegalArgumentException when they have screwed up.

public double toScale( int scaleDenominator ){
    if( scaleDenominator > 0 ){
        throw new IllegalArgumentException( "scaleDenominator must be greater than 0");
    }
    return 1 / (double) scaleDenominator;
}

Use NullPointerException where needed

If possible perform your own null checks; throwing a IllegalArgumentException or NullPointerException with detailed information about what has gone wrong.

public double toScale( Integer scaleDenominator ){
    if( scaleDenominator == null ){
        throw new NullPointerException( "scaleDenominator must be provided");
    }
    if( scaleDenominator > 0 ){
        throw new IllegalArgumentException( "scaleDenominator must be greater than 0");
    }
    return 1 / (double) scaleDenominator;
}