|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectbb.util.Check
public abstract class Check
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
Every checking method has some constraint stated in its name that the variable is expected to pass.
For instance,
means "check that object is not null".
notNull
(object)
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).
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 . |
|
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"). |
|
|
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). |
|
|
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). |
|
|
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). |
|
|
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). |
|
|
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). |
|
|
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). |
|
|
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. |
|
|
unmodifiable(Collection<T> collection)
Checks that collection is unmodifiable (i.e. cannot be mutated). |
|
|
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). |
|
|
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). |
|
|
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 |
---|
private static final Check.Arg argInstance
private static final Check.State stateInstance
private static final Check.Assert assertInstance
private final boolean doCheck
Check.Assert
may choose to suppress checks.
Constructor Detail |
---|
public Check()
this
(true)
.
public Check(boolean doCheck)
Method Detail |
---|
public static Check.Arg arg()
Check.Arg
instance. The same instance is always returned.
public static Check.State state()
Check.State
instance. The same instance is always returned.
public static Check.Assert azzert()
Check.Assert
instance. The same instance is always returned. This method should be named "assert", but that is now a Java keyword.
public abstract void onFailure(String errMsg)
public abstract void onFailure(String errMsg, Throwable throwable)
public boolean isTrue(boolean value)
public boolean isFalse(boolean value)
public byte zero(byte value)
public short zero(short value)
public int zero(int value)
public long zero(long value)
public float zero(float value)
public double zero(double value)
public byte notZero(byte value)
public short notZero(short value)
public int notZero(int value)
public long notZero(long value)
public float notZero(float value)
public double notZero(double value)
public byte negative(byte value)
public short negative(short value)
public int negative(int value)
public long negative(long value)
public float negative(float value)
public double negative(double value)
public byte notNegative(byte value)
public short notNegative(short value)
public int notNegative(int value)
public long notNegative(long value)
public float notNegative(float value)
public double notNegative(double value)
public byte positive(byte value)
public short positive(short value)
public int positive(int value)
public long positive(long value)
public float positive(float value)
public double positive(double value)
public byte notPositive(byte value)
public short notPositive(short value)
public int notPositive(int value)
public long notPositive(long value)
public float notPositive(float value)
public double notPositive(double value)
public float naN(float value)
public double naN(double value)
public float notNaN(float value)
public double notNaN(double value)
public float infinite(float value)
public double infinite(double value)
public float notInfinite(float value)
public double notInfinite(double value)
public float normal(float value)
public double normal(double value)
public float normalNegative(float value)
normal
and negative
.
public double normalNegative(double value)
normal
and negative
.
public float normalNotNegative(float value)
normal
and not negative
.
public double normalNotNegative(double value)
normal
and not negative
.
public float normalPositive(float value)
normal
and positive
.
public double normalPositive(double value)
normal
and positive
.
public float normalNotPositive(float value)
normal
and not positive
.
public double normalNotPositive(double value)
normal
and not positive
.
public int validPort(int value)
valid TCP or UDP port number
.
public double validProbability(double value)
public Object isNull(Object object)
public Object notNull(Object object)
public <T> T[] empty(T[] array)
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
parameter.
hasSize
(array, 0)
public boolean[] notEmpty(boolean[] array)
public byte[] notEmpty(byte[] array)
public short[] notEmpty(short[] array)
public char[] notEmpty(char[] array)
public int[] notEmpty(int[] array)
public long[] notEmpty(long[] array)
public float[] notEmpty(float[] array)
public double[] notEmpty(double[] array)
public <T> T[] notEmpty(T[] array)
public <T> Collection<T> notEmpty(Collection<T> collection)
public <K,V> Map<K,V> notEmpty(Map<K,V> map)
public boolean[] hasSize(boolean[] array, int sizeRequired)
public byte[] hasSize(byte[] array, int sizeRequired)
public short[] hasSize(short[] array, int sizeRequired)
public char[] hasSize(char[] array, int sizeRequired)
public int[] hasSize(int[] array, int sizeRequired)
public long[] hasSize(long[] array, int sizeRequired)
public float[] hasSize(float[] array, int sizeRequired)
public double[] hasSize(double[] array, int sizeRequired)
public <T> T[] hasSize(T[] array, int sizeRequired)
public <T> Collection<T> hasSize(Collection<T> collection, int sizeRequired)
public <K,V> Map<K,V> hasSize(Map<K,V> map, int sizeRequired)
public <T> Collection<T> unmodifiable(Collection<T> collection)
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.
public <K,V> Map<K,V> unmodifiable(Map<K,V> map)
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.
public int validIndex(int index, boolean[] array)
public int validIndex(int index, byte[] array)
public int validIndex(int index, short[] array)
public int validIndex(int index, char[] array)
public int validIndex(int index, int[] array)
public int validIndex(int index, long[] array)
public int validIndex(int index, float[] array)
public int validIndex(int index, double[] array)
public <T> int validIndex(int index, T[] array)
public <T> int validIndex(int index, Collection<T> collection)
public void validOffsetLength(int offset, int length, int lengthArray)
offset
- some proposed index offset into the array in questionlength
- some proposed number of array elements (e.g. to read into) of the array in questionlengthArray
- should be the result of a call to a.length where a is the array in questionpublic File validDirectory(File directory)
public File validFile(File file)
public String notBlank(String string)
"blank"
.
public Thread edt()
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:
So, this method was written in order to support easy enforcement of that requirement.
public boolean equals(boolean value1, boolean value2)
public byte equals(byte value1, byte value2)
public short equals(short value1, short value2)
public char equals(char value1, char value2)
public int equals(int value1, int value2)
public long equals(long value1, long value2)
public float equals(float value1, float value2)
public double equals(double value1, double value2)
public Object equals(Object obj1, Object obj2)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |