Reject.java
/*
* The contents of this file are subject to the terms of the Common Development and
* Distribution License (the License). You may not use this file except in compliance with the
* License.
*
* You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
* specific language governing permission and limitations under the License.
*
* When distributing Covered Software, include this CDDL Header Notice in each file and include
* the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
* Header, with the fields enclosed by brackets [] replaced by your own identifying
* information: "Portions copyright [year] [name of copyright owner]".
*
* Copyright 2015-2016 ForgeRock AS.
*/
package org.forgerock.util;
/**
* A input parameter-validating utility class using fluent invocation:
*
* <pre>
* public int divide(int dividend, int divisor) {
* Reject.ifTrue(divisor == 0, "Division by zero not supported");
* return dividend / divisor;
* }
* </pre>
*
* The example above will cause an {@code IllegalArgumentException} to be thrown
* with the message given.
* <p>
* Another use case is validating constructor parameters:
*
* <pre>
* public TokenManager(final TokenFactory factory) {
* Reject.ifNull(factory, "Cannot instantiate TokenManager with null TokenFactory");
* }
* </pre>
*
* Sometimes, constructor parameters are passed to ancestor constructors which
* must be called first--thus, the {@code checkNotNull} syntax is available:
*
* <pre>
* import static org.forgerock.util.Reject.checkNotNull;
*
* public TokenManager(final TokenFactory factory) {
* super(checkNotNull(factory));
* }
* </pre>
*
* Note that the methods herein throw generic RuntimeExceptions as opposed to
* custom, application-specific error Exceptions. This class is intended for
* wide use among multiple projects whose Exception frameworks may differ. The
* implementer is encouraged to catch the generic exceptions thrown by this
* class and rethrow exceptions appropriate to the target application.
*/
public final class Reject {
/**
* Throws a {@code NullPointerException} if the <tt>object</tt> parameter is
* null, returns the object otherwise.
*
* @param <T>
* The type of object to test.
* @param object
* the object to test
* @return the object
* @throws NullPointerException
* if {@code object} is null
*/
public static <T> T checkNotNull(final T object) {
return checkNotNull(object, null);
}
/**
* Throws a {@code NullPointerException} if the <tt>object</tt> parameter is
* null, returns the object otherwise.
*
* @param <T>
* The type of object to test.
* @param object
* the object to test
* @param message
* a custom exception message to use
* @return the object
* @throws NullPointerException
* if {@code object} is null
*/
public static <T> T checkNotNull(final T object, final String message) {
if (object == null) {
throw new NullPointerException(message);
}
return object;
}
/**
* Throws an {@code IllegalArgumentException} if the <tt>condition</tt>
* parameter is false.
*
* @param condition
* the condition to test
* @throws IllegalArgumentException
* if {@code condition} is false
*/
public static void ifFalse(final boolean condition) {
ifFalse(condition, "Expected condition was true, found false");
}
/**
* Throws an {@code IllegalArgumentException} with a custom {@code message}
* if the <tt>condition</tt> parameter is false.
*
* @param condition
* the condition to test
* @param message
* a custom exception message to use
* @throws IllegalArgumentException
* if {@code condition} is false
*/
public static void ifFalse(final boolean condition, final String message) {
if (!condition) {
throw new IllegalArgumentException(message);
}
}
/**
* Alias for {@code checkNotNull} to be used in fluent {@code Reject.ifNull}
* syntax. Throws a {@code NullPointerException} if the <tt>object</tt>
* parameter is null.
*
* @param object
* the object to test
* @throws NullPointerException
* if {@code object} is null
*/
public static void ifNull(final Object object) {
ifNull(object, null);
}
/**
* Throws a {@code NullPointerException} if any of the provided arguments
* are {@code null}.
*
* @param <T>
* The type of object to test.
* @param objects
* The objects to test.
* @throws NullPointerException
* If any of the provided arguments are {@code null}.
*/
@SafeVarargs
public static <T> void ifNull(final T... objects) {
/*
* This method is generic in order to play better with varargs.
* Otherwise invoking this method with an array of Strings will be
* flagged with a warning because of the potential ambiguity. See
* org.forgerock.util.RejectTest.ifNullVarArgsStrings().
*/
for (final Object o : objects) {
if (o == null) {
throw new NullPointerException();
}
}
}
/**
* Alias for {@code checkNotNull} to be used in fluent {@code Reject.ifNull}
* syntax. Throws a {@code NullPointerException} if the <tt>object</tt>
* parameter is null.
*
* @param object
* the object to test
* @param message
* a custom exception message to use
* @throws NullPointerException
* if {@code object} is null
*/
public static void ifNull(final Object object, final String message) {
checkNotNull(object, message);
}
/**
* Throws an {@code IllegalArgumentException} if the <tt>condition</tt>
* parameter is true.
*
* @param condition
* the condition to test
* @throws IllegalArgumentException
* if {@code condition} is true
*/
public static void ifTrue(final boolean condition) {
ifTrue(condition, "Expected condition was false, found true");
}
/**
* Throws an {@code IllegalArgumentException} with a custom {@code message}
* if the <tt>condition</tt> parameter is true.
*
* @param condition
* the condition to test
* @param message
* a custom exception message to use
* @throws IllegalArgumentException
* if {@code condition} is true
*/
public static void ifTrue(final boolean condition, final String message) {
if (condition) {
throw new IllegalArgumentException(message);
}
}
/**
* Throws an {@code IllegalStateException} with a custom {@code message}
* if the <tt>condition</tt> parameter is true.
*
* @param condition
* the condition to test
* @param message
* a custom exception message to use
* @throws IllegalStateException
* if {@code condition} is true
*/
public static void rejectStateIfTrue(final boolean condition, final String message) {
if (condition) {
throw new IllegalStateException(message);
}
}
// Prevent instantiation
private Reject() {
// nothing to do
}
}