3 Extending SanityChecker

This section will discuss the methods that come with the SanityChecker that are intended to be used when creating an extension.

checkYourselfBeforeYouWreckYourself

This method, while light-hearted, is actually critical. The purpose and intention of this method is to be used within any created sanity check to ensure that the check method has been invoked prior to the first sanity check, as the behavior would be undefined otherwise.

It throws an IllegalStateException, and therefore this should be declared in the method signature. If including it in the JavaDoc, it is suggested to use the clause found in the other sanity checkers that come with this plugin.

Usage:

public boolean mySanityCheck(boolean allowPassOnNull) throws IllegalStateException {
    checkYourselfBeforeYouWreckYourself()
    // …
}

allowPassOnNull

allowPassOnNull allows for the behavior of sanity checks to short-stop if the entity being checked is null. This allows for flexible behavior, for example some sanity checks may apply to optional parameters in which null may be acceptable.

Therefore, best practice is to provide two forms of a sanity check:

1. Form that does not alter behavior.
2. Form that allows alteration of behavior.

The plugin enumerates both signatures, but the following form can also be used:

public boolean mySanityCheck(boolean allowPassOnNull = this.allowPassOnNull) throws IllegalStateException {
    checkYourselfBeforeYouWreckYourself()
    // …
}

Plugin example:

public boolean mySanityCheck() {
    mySanityCheck(allowPassOnNull)
}
public boolean mySanityCheck(boolean allowPassOnNull) throws IllegalStateException {
    checkYourselfBeforeYouWreckYourself()
    if (allowPassOnNull && entity == null) {
        // …
        return true
    }
    // Implicit isNotNull.
    isNotNull()
    // …
}

pass / fail

Passing / Failing a sanity check is provided. These methods implement the pass and fail of SanityCheckReport.

Since the entity and classification are inherent to the sanity checker, only the check and checkDescription are required.

The check is usually just the method name, as both are supposed to quickly symbolize the sanity check. For example, isNotNull is simply "isNotNull"

The checkDescription is usually just a succinct sentence that explains the intention of the sanity check. This description can also serve as a human-readable error message implying what condition the entity did not meet. For example, isNotNull states: "Must not be null".

public boolean mySanityCheck() {
    mySanityCheck(allowPassOnNull)
}
public boolean mySanityCheck(boolean allowPassOnNull) throws IllegalStateException {
    checkYourselfBeforeYouWreckYourself()
    if (allowPassOnNull && entity == null) {
        pass("mySanityCheck", "My sanity check condition."
        return true
    }
    // Implicit isNotNull.
    isNotNull()
    if (checkForFailure(myCondition)) {
        fail("mySanityCheck", "My sanity check condition."
        return false
    }
    pass("mySanityCheck", "My sanity check condition."
    return true
}

Note that the sanity check _does not return if isNotNull fails_. The sanity checker methodology is to be as informative as possible. Imagine a user experiencing a failure because they passed null. This will tell them that they cannot pass null, and that they also must meet another condition that was not met. Otherwise, they might only correct not sending null, and then get a subsiquent failure.