391N/A * The contents of this file are subject to the terms of the 391N/A * Common Development and Distribution License, Version 1.0 only 391N/A * (the "License"). You may not use this file except in compliance 391N/A * You can obtain a copy of the license at 391N/A * See the License for the specific language governing permissions 391N/A * and limitations under the License. 391N/A * When distributing Covered Code, include this CDDL HEADER in each 391N/A * file and include the License file at 391N/A * add the following below this CDDL HEADER, with the fields enclosed 873N/A * by brackets "[]" replaced with your own identifying information: 391N/A * Portions Copyright [yyyy] [name of copyright owner] 3215N/A * Copyright 2006-2008 Sun Microsystems, Inc. 391N/A * This utility class provides static methods that make parameter checking 391N/A * easier (e.g. in constructors and setters). 391N/A * In particular the ensureNotNull methods provide an easy way to validate that 391N/A * certain parameters are not null, and the ensureTrue methods provide the 391N/A * ability to check arbitrary boolean conditions. 391N/A * Invocation of these methods should be limited to situations where the only 391N/A * way that they should fail is if there is a defect somewhere in the 391N/A * system (including 3rd-party plugins). 391N/A * You can think of these methods as being similar to <code>assert</code>, 391N/A * but there are some additional advantages: 391N/A * <li>All failures are logged to the debug and error logs</li> 391N/A * <li>Checks are always enabled (even if asserts are off)</li> 391N/A * <li>This class tracks the number of failures, allowing it to 391N/A * be exposed via monitoring, etc.<li> 391N/A * <li>The unit tests can track unnoticed internal failures and 391N/A * <li>Developers can catch all Validator failures with a single 391N/A * In general, you should not worry about the performance impact of calling 391N/A * these methods. Some micro-benchmarking has shown that ensureNotNull can be 391N/A * called 200M times per second on a single CPU laptop. The value of catching 391N/A * defects early will almost always out-weigh any overhead that is introduced. 391N/A * There are a couple of exceptions to this. Any execution overhead that 391N/A * happens before the method is invoked cannot be eliminated, e.g. 391N/A * <code>Validator.ensureTrue(someExpensiveCheck())</code> will always invoke 391N/A * <code>someExpensiveCheck()</code>. When this code is on the critical path, 699N/A * and we do not expect the validation to fail, you can guard the call with 391N/A * an <code>assert</code> because each method returns true, and this code will 391N/A * only be executed when asserts are enabled. 391N/A * These methods are provided primarily to check parameter values for 391N/A * constructors, setters, etc, and when they are used in this way, the javadoc 391N/A * for the method must be updated to reflect what constraints are placed on the 391N/A * parameters (e.g. attributeType cannot be null). 391N/A * Feel free to add any method to this class that makes sense. Be sure to 391N/A * ensure that they don't violate the spirit of this class in that performance 391N/A * is second only to correctness. 391N/A * There are a few issues open for remaining tasks: 391N/A * <li>757 Validator should expose a way to turn it off</li> 391N/A * <li>758 Validator should provide a way to throttle it's error messages</li> 391N/A * <li>759 Unit tests should always check that no unexpected Validator checks 1400N/A * The tracer object for the debug logger. 391N/A /** This static final variable theoretically allows us to compile out all of 391N/A * these checks. Since all of the code below is guarded with this check, 391N/A * the compiler should eliminate it if ENABLE_CHECKS is false. 391N/A * From doing a little bit of micro-benchmarking, it appears that setting 391N/A * ENABLE_CHECKS=false speeds the code up by about a factor of four, but 391N/A * it's still not the same as not having the invocation in the first place. 391N/A * On a single CPU laptop, I was able to get 200M 391N/A * invocations per second with ENABLE_CHECKS=true, and 350M with 391N/A * Setting this to false, will not eliminate any expensive computation 391N/A * done in a parameter list (e.g. some self-check that returns true).*/ 391N/A /** A one-based array for parameter descriptions. */ 391N/A {
"** A ZERO-BASED INDEX IS INVALID **",
391N/A /** A count of the errors detected by the methods in this class since the 391N/A * last time that resetErrorCount was called. */ 391N/A * This method validates that the specified parameter is not null. It 533N/A * throws an AssertionError if it is null after logging this error. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. 391N/A * @param param the parameter to validate as non-null. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if and only if param is null 391N/A * if assertions are enabled 391N/A * This method validates that the specified parameters are not null. It 533N/A * throws an AssertionError if one of them are null after logging this error. 533N/A * It's similar to the ensureNotNull(Object) call except it provides the 533N/A * convenience of checking two parameters at once. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. 391N/A * See the class level javadoc for why we did not use varargs to 391N/A * implement this method. 391N/A * @param param1 the first parameter to validate as non-null. 391N/A * @param param2 the second parameter to validate as non-null. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if and only if any of the parameters is null 391N/A * This method validates that the specified parameters are not null. It 533N/A * throws an AssertionError if one of them are null after logging this error. 533N/A * It's similar to the ensureNotNull(Object) call except it provides the 533N/A * convenience of checking three parameters at once. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. 391N/A * See the class level javadoc for why we did not use varargs to 391N/A * implement this method. 391N/A * @param param1 the first parameter to validate as non-null. 391N/A * @param param2 the second parameter to validate as non-null. 391N/A * @param param3 the third parameter to validate as non-null. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if and only if one of the parameters is null 391N/A * This method validates that the specified parameters are not null. It 533N/A * throws an AssertionError if one of them are null after logging this error. 533N/A * It's similar to the ensureNotNull(Object) call except it provides the 533N/A * convenience of checking four parameters at once. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. 391N/A * See the class level javadoc for why we did not use varargs to 391N/A * implement this method. 391N/A * @param param1 the first parameter to validate as non-null. 391N/A * @param param2 the second parameter to validate as non-null. 391N/A * @param param3 the third parameter to validate as non-null. 391N/A * @param param4 the fourth parameter to validate as non-null. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if and only if one of the parameters is null 391N/A * This method validates that the specified parameter is true. It 533N/A * throws an AssertionError if it is not true. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. The other advantage of 391N/A * using this method instead of an assert is that it logs the error to the 391N/A * debug and error logs. 391N/A * @param condition the condition that must be true. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if condition is false 391N/A * This method validates that the specified parameter is true. It 533N/A * throws an AssertionError if it is not true. The supplied message is 533N/A * included in the error message. 391N/A * This should be used like an assert, except it is not turned 391N/A * off at runtime. That is, it should only be used in situations where 391N/A * there is a bug in someone's code if param is null. The other advantage of 391N/A * using this method instead of an assert is that it logs the error to the 391N/A * debug and error logs. 391N/A * @param condition the condition that must be true. 391N/A * @param message the textual message to include in the error message. 391N/A * @return true always. This allows this call to be used in an assert 391N/A * statement, which can skip this check and remove all 391N/A * overhead from the calling code. This idiom should only be used when 391N/A * performance testing proves that it is necessary. 533N/A * @throws AssertionError if condition is false 391N/A //////////////////////////////////////////////////////////////////////////// 391N/A //////////////////////////////////////////////////////////////////////////// 391N/A * Returns the number of errors that this class has detected since the 391N/A * system started or the last time that resetErrorCount() was called. 391N/A * This could be useful in the unit tests to validate that no background 391N/A * errors occurred during a test. It could also be exposed by the monitoring 391N/A * @return the number of errors detected by this class since the error count 391N/A * Resets the error count to zero. 391N/A //////////////////////////////////////////////////////////////////////////// 391N/A //////////////////////////////////////////////////////////////////////////// 391N/A // Log to the debug log. 391N/A // Log to the error log. 391N/A * @return a String representation of the line that called the 391N/A * @return a stack trace rooted at the line that called the first 391N/A * @return the index in the supplied stack trace of the first non-Validator 391N/A // Go up the stack until we find who called the first Validator method. 391N/A // The stack trace of this thread looks like 391N/A // java.lang.Thread.dumpThreads(Native Method) 391N/A // org.opends.server.util.Validator.getOriginalCallerLineInfo... 391N/A // original caller <---- this is what we want to return