bb.util
Class Check

java.lang.Object
  extended by bb.util.Check
Direct Known Subclasses:
Check.CheckAdaptor

public abstract class Check
extends Object

Contains methods that perform various checks on data. The goal is to support Design By Contract style programming.

This class may not be directly used because it is abstract: while it contains full implementations of all the checking methods, it does not implement onFailure. Instead, a concrete subclass which implements onFailure must be used. The action performed by the subclass's onFailure is arbitrary: it could throw a RuntimeException (usually a more specific subclass), log the failure, send it over the network, ignore it, etc.

This class provides three inner classes, Check.Arg, Check.State, and Check.Assert, which are concrete subclasses meant for direct use. Arg is meant for checking method arguments, while State and Assert are meant for checking arbitrary state. Instances of these classes need not be created by the user, but may be conveniently obtained by the static accessors arg, state and azzert. Here is a typical scenario for checking preconditions and postconditions:


        /**
        * Returns the value from map that is associated with key.
        * <p>
        * @param map the Map that will be queried; precondition: must not be null
        * @param key the key used to query map; precondition: must not be null
        * @return the value from map that is associated with key; postcondition: result is never null
        * @throws IllegalArgumentException if any precondition is violated
        * @throws IllegalStateException if any postcondition is violated
        */
        public Object getValue(Map<Object,Object> map, Object key) {
                Check.arg().notNull(map);
                Check.arg().notNull(key);

                Object value = map.get(key);
                Check.state().notNull(value);
                return value;
        }
 

The design priorities of this class, which will hopefully promote its use across all projects, are

  1. code clarity: usage should read well, be very clear as to what constraint is being checked
  2. ease of use: usage should require minimal typing, so method names are short and require minimal arguments
  3. low impact: the checks themselves must not significantly degrade performance; only the abnormal case (failure to pass the check) should result in significant processing

Every checking method has some constraint stated in its name that the variable is expected to pass. For instance, notNull(object) means "check that object is not null".

Most of these checking methods also return the data if the check is passed. This allows them to be used in contexts like field assignments, for example


        /**
        * Caches the value of the line.separator System property.
        * <p>
        * Contract: is never blank.
        */
        private final String lineEnd = Check.state().notBlank( System.getProperty("line.separator") );
 
We also could have written the getValue method above in this more compact form:

        public Object getValue(Map<Object,Object> map, Object key) {
                Check.arg().notNull(map);
                Check.arg().notNull(key);
                return Check.state().notNull( map.get(key) );
        }
 

This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).

Author:
Brent Boyer

Nested Class Summary
static class Check.Arg
          Concrete subclass of Check which is meant for checking method arguments.
static class Check.Assert
          Concrete subclass of Check which is meant for checking arbitrary state.
static class Check.CheckAdaptor
          Abstract subclass of Check which merely implements onFailure(String) to forward to onFailure(String, Throwable).
static class Check.State
          Concrete subclass of Check which is meant for checking arbitrary state.
static class Check.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private static Check.Arg argInstance
           
private static Check.Assert assertInstance
           
private  boolean doCheck
          Records whether or not to perform each check.
private static Check.State stateInstance
           
 
Constructor Summary
Check()
          Convenience constructor that merely calls this(true).
Check(boolean doCheck)
          Fundamental constructor.
 
Method Summary
static Check.Arg arg()
          Returns a Check.Arg instance.
static Check.Assert azzert()
          Returns a Check.Assert instance.
 Thread edt()
          Checks that the current thread is EventQueue's dispatch thread (aka the "EDT").
<T> T[]
empty(T[] array)
          Checks that array is empty (i.e. either is null or array.length == 0).
 boolean equals(boolean value1, boolean value2)
          Checks that value1 == value2.
 byte equals(byte value1, byte value2)
          Checks that value1 == value2.
 char equals(char value1, char value2)
          Checks that value1 == value2.
 double equals(double value1, double value2)
          Checks that value1 == value2.
 float equals(float value1, float value2)
          Checks that value1 == value2.
 int equals(int value1, int value2)
          Checks that value1 == value2.
 long equals(long value1, long value2)
          Checks that value1 == value2.
 Object equals(Object obj1, Object obj2)
          Checks that obj1.equals(obj2).
 short equals(short value1, short value2)
          Checks that value1 == value2.
 boolean[] hasSize(boolean[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 byte[] hasSize(byte[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 char[] hasSize(char[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
<T> Collection<T>
hasSize(Collection<T> collection, int sizeRequired)
          Checks that collection is not null and has the required number of elements (i.e. collection.size() == sizeRequired).
 double[] hasSize(double[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 float[] hasSize(float[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 int[] hasSize(int[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 long[] hasSize(long[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
<K,V> Map<K,V>
hasSize(Map<K,V> map, int sizeRequired)
          Checks that map is not null and has the required number of elements (i.e. map.size() == sizeRequired).
 short[] hasSize(short[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
<T> T[]
hasSize(T[] array, int sizeRequired)
          Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).
 double infinite(double value)
          Checks that value is infinite.
 float infinite(float value)
          Checks that value is infinite.
 boolean isFalse(boolean value)
          Checks that value == false.
 Object isNull(Object object)
          Checks that obj is null.
 boolean isTrue(boolean value)
          Checks that value == true.
 double naN(double value)
          Checks that value is NaN.
 float naN(float value)
          Checks that value is NaN.
 byte negative(byte value)
          Checks that value is strictly negative (i.e. value < 0).
 double negative(double value)
          Checks that value is strictly negative (i.e. value < 0).
 float negative(float value)
          Checks that value is strictly negative (i.e. value < 0).
 int negative(int value)
          Checks that value is strictly negative (i.e. value < 0).
 long negative(long value)
          Checks that value is strictly negative (i.e. value < 0).
 short negative(short value)
          Checks that value is strictly negative (i.e. value < 0).
 double normal(double value)
          Checks that value is "normal", which is defined as it passing all these tests: is not NaN is not infinite
 float normal(float value)
          Checks that value is "normal", which is defined as it passing all these tests: is not NaN is not infinite
 double normalNegative(double value)
          Checks that value is normal and negative.
 float normalNegative(float value)
          Checks that value is normal and negative.
 double normalNotNegative(double value)
          Checks that value is normal and not negative.
 float normalNotNegative(float value)
          Checks that value is normal and not negative.
 double normalNotPositive(double value)
          Checks that value is normal and not positive.
 float normalNotPositive(float value)
          Checks that value is normal and not positive.
 double normalPositive(double value)
          Checks that value is normal and positive.
 float normalPositive(float value)
          Checks that value is normal and positive.
 String notBlank(String string)
          Checks that s is not "blank".
 boolean[] notEmpty(boolean[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 byte[] notEmpty(byte[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 char[] notEmpty(char[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
<T> Collection<T>
notEmpty(Collection<T> collection)
          Checks that collection is not empty (i.e. is not null and collection.size() > 0).
 double[] notEmpty(double[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 float[] notEmpty(float[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 int[] notEmpty(int[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 long[] notEmpty(long[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
<K,V> Map<K,V>
notEmpty(Map<K,V> map)
          Checks that map is not empty (i.e. is not null and map.size() > 0).
 short[] notEmpty(short[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
<T> T[]
notEmpty(T[] array)
          Checks that array is not empty (i.e. is not null and array.length > 0).
 double notInfinite(double value)
          Checks that value is not infinite.
 float notInfinite(float value)
          Checks that value is not infinite.
 double notNaN(double value)
          Checks that value is not NaN.
 float notNaN(float value)
          Checks that value is not NaN.
 byte notNegative(byte value)
          Checks that value is not strictly negative (i.e. value >= 0).
 double notNegative(double value)
          Checks that value is not strictly negative (i.e. value >= 0).
 float notNegative(float value)
          Checks that value is not strictly negative (i.e. value >= 0).
 int notNegative(int value)
          Checks that value is not strictly negative (i.e. value >= 0).
 long notNegative(long value)
          Checks that value is not strictly negative (i.e. value >= 0).
 short notNegative(short value)
          Checks that value is not strictly negative (i.e. value >= 0).
 Object notNull(Object object)
          Checks that obj is not null.
 byte notPositive(byte value)
          Checks that value is not strictly positive (i.e. value <= 0).
 double notPositive(double value)
          Checks that value is not strictly positive (i.e. value <= 0).
 float notPositive(float value)
          Checks that value is not strictly positive (i.e. value <= 0).
 int notPositive(int value)
          Checks that value is not strictly positive (i.e. value <= 0).
 long notPositive(long value)
          Checks that value is not strictly positive (i.e. value <= 0).
 short notPositive(short value)
          Checks that value is not strictly positive (i.e. value <= 0).
 byte notZero(byte value)
          Checks that value !
 double notZero(double value)
          Checks that value !
 float notZero(float value)
          Checks that value !
 int notZero(int value)
          Checks that value !
 long notZero(long value)
          Checks that value !
 short notZero(short value)
          Checks that value !
abstract  void onFailure(String errMsg)
          Called whenever a check fails and the code has just errMsg to report.
abstract  void onFailure(String errMsg, Throwable throwable)
          Called whenever a check fails and the code has both errMsg and throwable to report.
 byte positive(byte value)
          Checks that value is strictly positive (i.e. value > 0).
 double positive(double value)
          Checks that value is strictly positive (i.e. value > 0).
 float positive(float value)
          Checks that value is strictly positive (i.e. value > 0).
 int positive(int value)
          Checks that value is strictly positive (i.e. value > 0).
 long positive(long value)
          Checks that value is strictly positive (i.e. value > 0).
 short positive(short value)
          Checks that value is strictly positive (i.e. value > 0).
static Check.State state()
          Returns a Check.State instance.
<T> Collection<T>
unmodifiable(Collection<T> collection)
          Checks that collection is unmodifiable (i.e. cannot be mutated).
<K,V> Map<K,V>
unmodifiable(Map<K,V> map)
          Checks that map is unmodifiable (i.e. cannot be mutated).
 File validDirectory(File directory)
          Checks that directory is a valid filesystem directory, which is defined as it passing all these tests: is not null is a path that exists can be read by this application resolves to an actual directory, and not some other type of file (e.g. a normal file)
 File validFile(File file)
          Checks that file is a valid filesystem file, which is defined as it passing all these tests: is not null is a path that exists can be read by this application resolves to a normal filesystem file
 int validIndex(int index, boolean[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, byte[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, char[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
<T> int
validIndex(int index, Collection<T> collection)
          Checks that index is valid for collection (i.e. 0 <= index < collection.size()).
 int validIndex(int index, double[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, float[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, int[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, long[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 int validIndex(int index, short[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
<T> int
validIndex(int index, T[] array)
          Checks that index is valid for array (i.e. 0 <= index < array.length).
 void validOffsetLength(int offset, int length, int lengthArray)
          Checks that offset >= 0, length >= 0, and (offset + length) <= lengthArray.
 int validPort(int value)
          Checks that value is a valid TCP or UDP port number.
 double validProbability(double value)
          Checks that value is a valid probability.
 byte zero(byte value)
          Checks that value == 0.
 double zero(double value)
          Checks that value == 0.
 float zero(float value)
          Checks that value == 0.
 int zero(int value)
          Checks that value == 0.
 long zero(long value)
          Checks that value == 0.
 short zero(short value)
          Checks that value == 0.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

argInstance

private static final Check.Arg argInstance

stateInstance

private static final Check.State stateInstance

assertInstance

private static final Check.Assert assertInstance

doCheck

private final boolean doCheck
Records whether or not to perform each check. Normally, this is true, however, subclasses like Check.Assert may choose to suppress checks.

Constructor Detail

Check

public Check()
Convenience constructor that merely calls this(true).


Check

public Check(boolean doCheck)
Fundamental constructor.

Method Detail

arg

public static Check.Arg arg()
Returns a Check.Arg instance. The same instance is always returned.


state

public static Check.State state()
Returns a Check.State instance. The same instance is always returned.


azzert

public static Check.Assert azzert()
Returns a Check.Assert instance. The same instance is always returned. This method should be named "assert", but that is now a Java keyword.


onFailure

public abstract void onFailure(String errMsg)
Called whenever a check fails and the code has just errMsg to report.


onFailure

public abstract void onFailure(String errMsg,
                               Throwable throwable)
Called whenever a check fails and the code has both errMsg and throwable to report.


isTrue

public boolean isTrue(boolean value)
Checks that value == true.

Returns:
value, if it passes the check

isFalse

public boolean isFalse(boolean value)
Checks that value == false.

Returns:
value, if it passes the check

zero

public byte zero(byte value)
Checks that value == 0.

Returns:
value, if it passes the check

zero

public short zero(short value)
Checks that value == 0.

Returns:
value, if it passes the check

zero

public int zero(int value)
Checks that value == 0.

Returns:
value, if it passes the check

zero

public long zero(long value)
Checks that value == 0.

Returns:
value, if it passes the check

zero

public float zero(float value)
Checks that value == 0.

Returns:
value, if it passes the check

zero

public double zero(double value)
Checks that value == 0.

Returns:
value, if it passes the check

notZero

public byte notZero(byte value)
Checks that value != 0.

Returns:
value, if it passes the check

notZero

public short notZero(short value)
Checks that value != 0.

Returns:
value, if it passes the check

notZero

public int notZero(int value)
Checks that value != 0.

Returns:
value, if it passes the check

notZero

public long notZero(long value)
Checks that value != 0.

Returns:
value, if it passes the check

notZero

public float notZero(float value)
Checks that value != 0.

Returns:
value, if it passes the check

notZero

public double notZero(double value)
Checks that value != 0.

Returns:
value, if it passes the check

negative

public byte negative(byte value)
Checks that value is strictly negative (i.e. value < 0).

Returns:
value, if it passes the check

negative

public short negative(short value)
Checks that value is strictly negative (i.e. value < 0).

Returns:
value, if it passes the check

negative

public int negative(int value)
Checks that value is strictly negative (i.e. value < 0).

Returns:
value, if it passes the check

negative

public long negative(long value)
Checks that value is strictly negative (i.e. value < 0).

Returns:
value, if it passes the check

negative

public float negative(float value)
Checks that value is strictly negative (i.e. value < 0). NaN fails this check.

Returns:
value, if it passes the check

negative

public double negative(double value)
Checks that value is strictly negative (i.e. value < 0). NaN fails this check.

Returns:
value, if it passes the check

notNegative

public byte notNegative(byte value)
Checks that value is not strictly negative (i.e. value >= 0).

Returns:
value, if it passes the check

notNegative

public short notNegative(short value)
Checks that value is not strictly negative (i.e. value >= 0).

Returns:
value, if it passes the check

notNegative

public int notNegative(int value)
Checks that value is not strictly negative (i.e. value >= 0).

Returns:
value, if it passes the check

notNegative

public long notNegative(long value)
Checks that value is not strictly negative (i.e. value >= 0).

Returns:
value, if it passes the check

notNegative

public float notNegative(float value)
Checks that value is not strictly negative (i.e. value >= 0). NaN fails this check.

Returns:
value, if it passes the check

notNegative

public double notNegative(double value)
Checks that value is not strictly negative (i.e. value >= 0). NaN fails this check.

Returns:
value, if it passes the check

positive

public byte positive(byte value)
Checks that value is strictly positive (i.e. value > 0).

Returns:
value, if it passes the check

positive

public short positive(short value)
Checks that value is strictly positive (i.e. value > 0).

Returns:
value, if it passes the check

positive

public int positive(int value)
Checks that value is strictly positive (i.e. value > 0).

Returns:
value, if it passes the check

positive

public long positive(long value)
Checks that value is strictly positive (i.e. value > 0).

Returns:
value, if it passes the check

positive

public float positive(float value)
Checks that value is strictly positive (i.e. value > 0). NaN fails this check.

Returns:
value, if it passes the check

positive

public double positive(double value)
Checks that value is strictly positive (i.e. value > 0). NaN fails this check.

Returns:
value, if it passes the check

notPositive

public byte notPositive(byte value)
Checks that value is not strictly positive (i.e. value <= 0).

Returns:
value, if it passes the check

notPositive

public short notPositive(short value)
Checks that value is not strictly positive (i.e. value <= 0).

Returns:
value, if it passes the check

notPositive

public int notPositive(int value)
Checks that value is not strictly positive (i.e. value <= 0).

Returns:
value, if it passes the check

notPositive

public long notPositive(long value)
Checks that value is not strictly positive (i.e. value <= 0).

Returns:
value, if it passes the check

notPositive

public float notPositive(float value)
Checks that value is not strictly positive (i.e. value <= 0). NaN fails this check.

Returns:
value, if it passes the check

notPositive

public double notPositive(double value)
Checks that value is not strictly positive (i.e. value <= 0). NaN fails this check.

Returns:
value, if it passes the check

naN

public float naN(float value)
Checks that value is NaN.

Returns:
value, if it passes the check

naN

public double naN(double value)
Checks that value is NaN.

Returns:
value, if it passes the check

notNaN

public float notNaN(float value)
Checks that value is not NaN.

Returns:
value, if it passes the check

notNaN

public double notNaN(double value)
Checks that value is not NaN.

Returns:
value, if it passes the check

infinite

public float infinite(float value)
Checks that value is infinite.

Returns:
value, if it passes the check

infinite

public double infinite(double value)
Checks that value is infinite.

Returns:
value, if it passes the check

notInfinite

public float notInfinite(float value)
Checks that value is not infinite.

Returns:
value, if it passes the check

notInfinite

public double notInfinite(double value)
Checks that value is not infinite.

Returns:
value, if it passes the check

normal

public float normal(float value)
Checks that value is "normal", which is defined as it passing all these tests:
  1. is not NaN
  2. is not infinite

Returns:
value, if it passes the check

normal

public double normal(double value)
Checks that value is "normal", which is defined as it passing all these tests:
  1. is not NaN
  2. is not infinite

Returns:
value, if it passes the check

normalNegative

public float normalNegative(float value)
Checks that value is normal and negative.

Returns:
value, if it passes the check

normalNegative

public double normalNegative(double value)
Checks that value is normal and negative.

Returns:
value, if it passes the check

normalNotNegative

public float normalNotNegative(float value)
Checks that value is normal and not negative.

Returns:
value, if it passes the check

normalNotNegative

public double normalNotNegative(double value)
Checks that value is normal and not negative.

Returns:
value, if it passes the check

normalPositive

public float normalPositive(float value)
Checks that value is normal and positive.

Returns:
value, if it passes the check

normalPositive

public double normalPositive(double value)
Checks that value is normal and positive.

Returns:
value, if it passes the check

normalNotPositive

public float normalNotPositive(float value)
Checks that value is normal and not positive.

Returns:
value, if it passes the check

normalNotPositive

public double normalNotPositive(double value)
Checks that value is normal and not positive.

Returns:
value, if it passes the check

validPort

public int validPort(int value)
Checks that value is a valid TCP or UDP port number.

Returns:
value, if it passes the check

validProbability

public double validProbability(double value)
Checks that value is a valid probability. The requirement is that value lies in the closed interval [0, 1]. See this probability article.

Returns:
value, if it passes the check

isNull

public Object isNull(Object object)
Checks that obj is null.

Returns:
obj, if it passes the check

notNull

public Object notNull(Object object)
Checks that obj is not null.

Returns:
obj, if it passes the check

empty

public <T> T[] empty(T[] array)
Checks that array is empty (i.e. either is null or array.length == 0).

This method was introduced for strict argument checking of main methods which do not use the supplied String[] parameter. Here, you want to crash if the user has supplied values, to inform them that they have misused the method.

An alternative to this method, if you do not want a null array to pass, is to call hasSize(array, 0) parameter.

Returns:
array, if it passes the check

notEmpty

public boolean[] notEmpty(boolean[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public byte[] notEmpty(byte[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public short[] notEmpty(short[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public char[] notEmpty(char[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public int[] notEmpty(int[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public long[] notEmpty(long[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public float[] notEmpty(float[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public double[] notEmpty(double[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public <T> T[] notEmpty(T[] array)
Checks that array is not empty (i.e. is not null and array.length > 0).

Returns:
array, if it passes the check

notEmpty

public <T> Collection<T> notEmpty(Collection<T> collection)
Checks that collection is not empty (i.e. is not null and collection.size() > 0).

Returns:
collection, if it passes the check

notEmpty

public <K,V> Map<K,V> notEmpty(Map<K,V> map)
Checks that map is not empty (i.e. is not null and map.size() > 0).

Returns:
map, if it passes the check

hasSize

public boolean[] hasSize(boolean[] array,
                         int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public byte[] hasSize(byte[] array,
                      int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public short[] hasSize(short[] array,
                       int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public char[] hasSize(char[] array,
                      int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public int[] hasSize(int[] array,
                     int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public long[] hasSize(long[] array,
                      int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public float[] hasSize(float[] array,
                       int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public double[] hasSize(double[] array,
                        int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public <T> T[] hasSize(T[] array,
                       int sizeRequired)
Checks that array is not null and has the required number of elements (i.e. array.length == sizeRequired).

Returns:
array, if it passes the check

hasSize

public <T> Collection<T> hasSize(Collection<T> collection,
                                 int sizeRequired)
Checks that collection is not null and has the required number of elements (i.e. collection.size() == sizeRequired).

Returns:
collection, if it passes the check

hasSize

public <K,V> Map<K,V> hasSize(Map<K,V> map,
                              int sizeRequired)
Checks that map is not null and has the required number of elements (i.e. map.size() == sizeRequired).

Returns:
map, if it passes the check

unmodifiable

public <T> Collection<T> unmodifiable(Collection<T> collection)
Checks that collection is unmodifiable (i.e. cannot be mutated).

The current algorithm is to call Collection.clear() and confirm that an UnsupportedOperationException is thrown. If said UnsupportedOperationException is caught, then it is otherwise ignored, however, if it is not raised at all then onFailure is called.

Warning: do not call this method with Collections that you expect may fail, because a side effect of failure is that collection will be cleared.

Unmodifiable Collections are conveniently generated by Collections.unmodifiableCollection, Collections.unmodifiableList Collections.unmodifiableSet, Collections.unmodifiableSortedSet. They may be used when exposing Collection type fields in order to maintain encapsulation.

Returns:
collection, if it passes the check

unmodifiable

public <K,V> Map<K,V> unmodifiable(Map<K,V> map)
Checks that map is unmodifiable (i.e. cannot be mutated).

The current algorithm is to call Map.clear() and confirm that an UnsupportedOperationException is thrown. If said UnsupportedOperationException is caught, then it is otherwise ignored, however, if it is not raised at all then onFailure is called.

Warning: do not call this method with Maps that you expect may fail, because a side effect of failure is that map will be cleared.

Unmodifiable Maps are conveniently generated by Collections.unmodifiableMap, Collections.unmodifiableSortedMap. They may be used when exposing Map type fields in order to maintain encapsulation.

Returns:
map, if it passes the check

validIndex

public int validIndex(int index,
                      boolean[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      byte[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      short[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      char[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      int[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      long[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      float[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public int validIndex(int index,
                      double[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public <T> int validIndex(int index,
                          T[] array)
Checks that index is valid for array (i.e. 0 <= index < array.length). The check necessarily fails if array is null, so this method simultaneously serves as a null check on array.

Returns:
index, if it passes the check

validIndex

public <T> int validIndex(int index,
                          Collection<T> collection)
Checks that index is valid for collection (i.e. 0 <= index < collection.size()). The check necessarily fails if collection is null, so this method simultaneously serves as a null check on collection.

Returns:
index, if it passes the check

validOffsetLength

public void validOffsetLength(int offset,
                              int length,
                              int lengthArray)
Checks that offset >= 0, length >= 0, and (offset + length) <= lengthArray.

Parameters:
offset - some proposed index offset into the array in question
length - some proposed number of array elements (e.g. to read into) of the array in question
lengthArray - should be the result of a call to a.length where a is the array in question

validDirectory

public File validDirectory(File directory)
Checks that directory is a valid filesystem directory, which is defined as it passing all these tests:
  1. is not null
  2. is a path that exists
  3. can be read by this application
  4. resolves to an actual directory, and not some other type of file (e.g. a normal file)

Returns:
directory, if it passes the check

validFile

public File validFile(File file)
Checks that file is a valid filesystem file, which is defined as it passing all these tests:
  1. is not null
  2. is a path that exists
  3. can be read by this application
  4. resolves to a normal filesystem file

Returns:
file, if it passes the check

notBlank

public String notBlank(String string)
Checks that s is not "blank".

Returns:
s, if it passes the check

edt

public Thread edt()
Checks that the current thread is EventQueue's dispatch thread (aka the "EDT").

The reason why this check is important is because typical Java gui code is not multithread safe. Most GUI code, including initialization, should only be called by EventQueue's dispatch thread. Some references that discuss this include:

  1. Lesson: Concurrency in Swing
  2. Multithreading In Swing
  3. More Multithreading In Swing
So, this method was written in order to support easy enforcement of that requirement.

Returns:
the current thread, if it passes the check

equals

public boolean equals(boolean value1,
                      boolean value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public byte equals(byte value1,
                   byte value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public short equals(short value1,
                    short value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public char equals(char value1,
                   char value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public int equals(int value1,
                  int value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public long equals(long value1,
                   long value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public float equals(float value1,
                    float value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public double equals(double value1,
                     double value2)
Checks that value1 == value2.

Returns:
value1, if the check is passed

equals

public Object equals(Object obj1,
                     Object obj2)
Checks that obj1.equals(obj2). Concerning nulls: passes check if obj1 == obj2 == null, but fails if one is null and the other is not.

Returns:
obj1, if the check is passed