org.opends.server.util
Class Validator

java.lang.Object
  extended by org.opends.server.util.Validator

@PublicAPI(stability=UNCOMMITTED,
           mayInstantiate=false,
           mayExtend=false,
           mayInvoke=true)
public class Validator
extends java.lang.Object

This utility class provides static methods that make parameter checking easier (e.g. in constructors and setters). In particular the ensureNotNull methods provide an easy way to validate that certain parameters are not null, and the ensureTrue methods provide the ability to check arbitrary boolean conditions.

Invocation of these methods should be limited to situations where the only way that they should fail is if there is a defect somewhere in the system (including 3rd-party plugins).

You can think of these methods as being similar to assert, but there are some additional advantages:

In general, you should not worry about the performance impact of calling these methods. Some micro-benchmarking has shown that ensureNotNull can be called 200M times per second on a single CPU laptop. The value of catching defects early will almost always out-weigh any overhead that is introduced. There are a couple of exceptions to this. Any execution overhead that happens before the method is invoked cannot be eliminated, e.g. Validator.ensureTrue(someExpensiveCheck()) will always invoke someExpensiveCheck(). When this code is on the critical path, and we do not expect the validation to fail, you can guard the call with an assert because each method returns true, and this code will only be executed when asserts are enabled.

These methods are provided primarily to check parameter values for constructors, setters, etc, and when they are used in this way, the javadoc for the method must be updated to reflect what constraints are placed on the parameters (e.g. attributeType cannot be null).

Feel free to add any method to this class that makes sense. Be sure to ensure that they don't violate the spirit of this class in that performance is second only to correctness.

There are a few issues open for remaining tasks:


Field Summary
static boolean ENABLE_CHECKS
          This static final variable theoretically allows us to compile out all of these checks.
 
Constructor Summary
Validator()
           
 
Method Summary
static boolean ensureNotNull(java.lang.Object param)
          This method validates that the specified parameter is not null.
static boolean ensureNotNull(java.lang.Object param1, java.lang.Object param2)
          This method validates that the specified parameters are not null.
static boolean ensureNotNull(java.lang.Object param1, java.lang.Object param2, java.lang.Object param3)
          This method validates that the specified parameters are not null.
static boolean ensureNotNull(java.lang.Object param1, java.lang.Object param2, java.lang.Object param3, java.lang.Object param4)
          This method validates that the specified parameters are not null.
static boolean ensureTrue(boolean condition)
          This method validates that the specified parameter is true.
static boolean ensureTrue(boolean condition, java.lang.String message)
          This method validates that the specified parameter is true.
static long getErrorCount()
          Returns the number of errors that this class has detected since the system started or the last time that resetErrorCount() was called.
static void resetErrorCount()
          Resets the error count to zero.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ENABLE_CHECKS

public static final boolean ENABLE_CHECKS
This static final variable theoretically allows us to compile out all of these checks. Since all of the code below is guarded with this check, the compiler should eliminate it if ENABLE_CHECKS is false. From doing a little bit of micro-benchmarking, it appears that setting ENABLE_CHECKS=false speeds the code up by about a factor of four, but it's still not the same as not having the invocation in the first place. On a single CPU laptop, I was able to get 200M invocations per second with ENABLE_CHECKS=true, and 350M with ENABLE_CHECKS=false.

Setting this to false, will not eliminate any expensive computation done in a parameter list (e.g. some self-check that returns true).

See Also:
Constant Field Values
Constructor Detail

Validator

public Validator()
Method Detail

ensureNotNull

public static boolean ensureNotNull(java.lang.Object param)
                             throws java.lang.AssertionError
This method validates that the specified parameter is not null. It throws an AssertionError if it is null after logging this error.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null.

Parameters:
param - the parameter to validate as non-null.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if and only if param is null if assertions are enabled

ensureNotNull

public static boolean ensureNotNull(java.lang.Object param1,
                                    java.lang.Object param2)
                             throws java.lang.AssertionError
This method validates that the specified parameters are not null. It throws an AssertionError if one of them are null after logging this error. It's similar to the ensureNotNull(Object) call except it provides the convenience of checking two parameters at once.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null.

See the class level javadoc for why we did not use varargs to implement this method.

Parameters:
param1 - the first parameter to validate as non-null.
param2 - the second parameter to validate as non-null.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if and only if any of the parameters is null

ensureNotNull

public static boolean ensureNotNull(java.lang.Object param1,
                                    java.lang.Object param2,
                                    java.lang.Object param3)
                             throws java.lang.AssertionError
This method validates that the specified parameters are not null. It throws an AssertionError if one of them are null after logging this error. It's similar to the ensureNotNull(Object) call except it provides the convenience of checking three parameters at once.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null.

See the class level javadoc for why we did not use varargs to implement this method.

Parameters:
param1 - the first parameter to validate as non-null.
param2 - the second parameter to validate as non-null.
param3 - the third parameter to validate as non-null.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if and only if one of the parameters is null

ensureNotNull

public static boolean ensureNotNull(java.lang.Object param1,
                                    java.lang.Object param2,
                                    java.lang.Object param3,
                                    java.lang.Object param4)
                             throws java.lang.AssertionError
This method validates that the specified parameters are not null. It throws an AssertionError if one of them are null after logging this error. It's similar to the ensureNotNull(Object) call except it provides the convenience of checking four parameters at once.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null.

See the class level javadoc for why we did not use varargs to implement this method.

Parameters:
param1 - the first parameter to validate as non-null.
param2 - the second parameter to validate as non-null.
param3 - the third parameter to validate as non-null.
param4 - the fourth parameter to validate as non-null.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if and only if one of the parameters is null

ensureTrue

public static boolean ensureTrue(boolean condition)
                          throws java.lang.AssertionError
This method validates that the specified parameter is true. It throws an AssertionError if it is not true.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null. The other advantage of using this method instead of an assert is that it logs the error to the debug and error logs.

Parameters:
condition - the condition that must be true.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if condition is false

ensureTrue

public static boolean ensureTrue(boolean condition,
                                 java.lang.String message)
                          throws java.lang.AssertionError
This method validates that the specified parameter is true. It throws an AssertionError if it is not true. The supplied message is included in the error message.

This should be used like an assert, except it is not turned off at runtime. That is, it should only be used in situations where there is a bug in someone's code if param is null. The other advantage of using this method instead of an assert is that it logs the error to the debug and error logs.

Parameters:
condition - the condition that must be true.
message - the textual message to include in the error message.
Returns:
true always. This allows this call to be used in an assert statement, which can skip this check and remove all overhead from the calling code. This idiom should only be used when performance testing proves that it is necessary.
Throws:
java.lang.AssertionError - if condition is false

getErrorCount

public static long getErrorCount()
Returns the number of errors that this class has detected since the system started or the last time that resetErrorCount() was called.

This could be useful in the unit tests to validate that no background errors occurred during a test. It could also be exposed by the monitoring framekwork.

Returns:
the number of errors detected by this class since the error count was last reset.

resetErrorCount

public static void resetErrorCount()
Resets the error count to zero.