| java.lang.Object org.kuali.core.util.AssertionUtils
AssertionUtils | public class AssertionUtils (Code) | | This class contains utility methods for making assertions in production code (not test code).
Kuali is not using the
assert keyword because those assertions
are not enabled by default. We can use the methods of this class instead, or throw
AssertionError directly. This makes
assertions effective in production and development, and avoids any risk of changes to functionality because any side-effects that
might be involved in the assertion are done consistently. Although
AssertionError can be thrown directly, and sometimes
the compiler requires this, in many cases these method invocations will be easier to read than the extra
if block with
its negated conditional.
These assertions are for use in production code. They should not be confused with
junit.framework.Assert ,
junit.framework.AssertionFailedError , nor
org.kuali.test.util.KualiTestAssertionUtils ,
which are for test code.
These methods
should be used such that when they fail and throw
AssertionError , it indicates that there is a bug in our software.
Drawing attention to the bug this way, as soon as it's discovered, reduces the amount of work required to fix it. So, we should
not catch
AssertionError (or
Throwable ) and try to handle or work around it; it indicates a need to change some
source code so that the assertion is never false. For more about why, when, and how to use assertions, see Kuali's guide to assertions and Sun's guide to assertions.
See Also: org.kuali.test.util.KualiTestAssertionUtils |
Method Summary | |
public static void | assertThat(boolean isTrue) Asserts that the
isTrue parameter is true. | public static void | assertThat(boolean isTrue, Object detailMessage) Asserts that the
isTrue parameter is true, with a detail message. | public static void | assertThat(boolean isTrue, String detailMessageFormat, Object... detailMessageArgs) Asserts that the
isTrue parameter is true. |
assertThat | public static void assertThat(boolean isTrue)(Code) | | Asserts that the
isTrue parameter is true. If this assertion fails, the
AssertionError it throws will have no
detail message, only a stacktrace indicating the source file and line number containing the assertion that failed. This
method's name is intended to avoid confusion with JUnit asserts (which are for test code, not production code), and its
signature is intended to resemble that of the
assert keyword.
Parameters: isTrue - whether this assertion succeeds. (Boolean objects are auto-unboxed by JDK 1.5.) throws: AssertionError - if isTrue is false |
assertThat | public static void assertThat(boolean isTrue, Object detailMessage)(Code) | | Asserts that the
isTrue parameter is true, with a detail message. The purpose of the detail message is to capture and
communicate details about the assertion failure that will help a developer diagnose and fix the bug that led this assertion
to fail. It's meant to be interpreted in the context of a full stack trace and with the source code containing the failed
assertion. It is not a user-level error message. Details like
"assertion failed" are redundant, not
useful. This method's name is intended to avoid confusion with JUnit asserts (which are for test code, not production
code), and its signature is intended to resemble that of the
assert keyword.
Parameters: isTrue - whether this assertion succeeds. (Boolean objects are auto-unboxed by JDK 1.5.) Parameters: detailMessage - value to use for the AssertionError 's detail message. If this is an instance ofThrowable, then it also becomes the AssertionError 's cause. (Primitives are auto-boxed by JDK 1.5.)Objects are converted Object.toString toString, but only if this assertion fails, so it's better not toconvert this detail in advance. The code will be a little easier to read, and there will be some performanceimprovement (altho it may be insignificant). For example, passing just accountingLine is better than passing accountingLine.toString() or "accounting line:"+accountingLine . Since the assertion has failed, anyinconsistent side-effects from the conversion are not an issue. A null reference is treated as the String "null" . throws: AssertionError - if isTrue is false |
assertThat | public static void assertThat(boolean isTrue, String detailMessageFormat, Object... detailMessageArgs)(Code) | | Asserts that the
isTrue parameter is true. This method is convenient for formatting the detail message, and as an
optimization for detail arguments that are expensive to convert to String. For example, suppose
foo and
bar are two objects with expensive
Object.toString methods. If you use
AssertionUtils.assertThat(foo.equals(bar), "foo: " + foo + " bar: " + bar);
then both object's
toString methods will be invoked every time this assertion is done, even though those details are
not normally needed because this assertion normally succeeds. You can use this method instead to only do those
toString invocations if this assertion fails:
AssertionUtils.assertThat(foo.equals(bar), "foo: %s bar: %s", foo, bar);
This method's name is intended to avoid confusion with JUnit asserts (which are for test code, not production code).
Parameters: isTrue - whether this assertion succeeds. (Boolean objects are auto-unboxed by JDK 1.5.) Parameters: detailMessageFormat - a to be used in constructing the AssertionError 'sdetail message. The purpose of this message is to capture and communicate details about the assertion failure thatwill help a developer diagnose and fix the bug that led the assertion to fail. It's meant to be interpreted in thecontext of a full stack trace and with the source code containing the failed assertion. It is not auser-level error message. Details like "assertion failed" are redundant, not useful. This detail messagecannot be null . Parameters: detailMessageArgs - one or more arguments to the format string. Nulls are allowed by some format conversions, such as "%s" . (Primitives are auto-boxed by JDK 1.5.) Zero arguments will invoke AssertionUtils.assertThat(boolean,Object)instead, so the detail message will not be treated as a format string. throws: AssertionError - if isTrue is false throws: java.util.IllegalFormatException - if detailMessageFormat contains an illegal syntax, a format specifier thatis incompatible with the given arguments, insufficient arguments given the format string, or other illegalconditions. For specification of all possible formatting errors, see the Details section ofjava.util.Formatter. throws: NullPointerException - if the detailMessageFormat is null See Also: String.format |
|
|