HADOOP-17126. implement non-guava Precondition checkNotNull
This adds a new class org.apache.hadoop.util.Preconditions which is * @Private/@Unstable * Intended to allow us to move off Google Guava * Is designed to be trivially backportable (i.e contains no references to guava classes internally) Please use this instead of the guava equivalents, where possible. Contributed by: Ahmed Hussein Change-Id: Ic392451bcfe7d446184b7c995734bcca8c07286e
This commit is contained in:
parent
103ef9c711
commit
9188fa8cce
|
@ -0,0 +1,163 @@
|
|||
/*
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
* or more contributor license agreements. See the NOTICE file
|
||||
* distributed with this work for additional information
|
||||
* regarding copyright ownership. The ASF licenses this file
|
||||
* to you under the Apache License, Version 2.0 (the
|
||||
* "License"); you may not use this file except in compliance
|
||||
* with the License. You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
package org.apache.hadoop.util;
|
||||
|
||||
import java.util.function.Supplier;
|
||||
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import org.apache.hadoop.classification.InterfaceAudience;
|
||||
import org.apache.hadoop.classification.InterfaceStability;
|
||||
|
||||
/**
|
||||
* <p>This class replaces {@code guava.Preconditions} which provides helpers
|
||||
* to validate the following conditions:
|
||||
* <ul>
|
||||
* <li>An invalid {@code null} obj causes a {@link NullPointerException}.</li>
|
||||
* <li>An invalid argument causes an {@link IllegalArgumentException}.</li>
|
||||
* <li>An invalid state causes an {@link IllegalStateException}.</li>
|
||||
* <li>An invalid index causes an {@link IndexOutOfBoundsException}.</li>
|
||||
* </ul>
|
||||
*/
|
||||
@InterfaceAudience.Private
|
||||
@InterfaceStability.Unstable
|
||||
public final class Preconditions {
|
||||
private static final Logger LOG =
|
||||
LoggerFactory.getLogger(Preconditions.class);
|
||||
|
||||
private static final String VALIDATE_IS_NOT_NULL_EX_MESSAGE =
|
||||
"The argument object is NULL";
|
||||
|
||||
private Preconditions() {
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Preconditions that the specified argument is not {@code null},
|
||||
* throwing a NPE exception otherwise.
|
||||
*
|
||||
* <p>The message of the exception is
|
||||
* "The validated object is null".</p>
|
||||
*
|
||||
* @param <T> the object type
|
||||
* @param obj the object to check
|
||||
* @return the validated object
|
||||
* @throws NullPointerException if the object is {@code null}
|
||||
* @see #checkNotNull(Object, Object)
|
||||
*/
|
||||
public static <T> T checkNotNull(final T obj) {
|
||||
return checkNotNull(obj, VALIDATE_IS_NOT_NULL_EX_MESSAGE);
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Preconditions that the specified argument is not {@code null},
|
||||
* throwing a NPE exception otherwise.
|
||||
*
|
||||
* <p>The message of the exception is {@code errorMessage}.</p>
|
||||
*
|
||||
* @param <T> the object type
|
||||
* @param obj the object to check
|
||||
* @param errorMessage the message associated with the NPE
|
||||
* @return the validated object
|
||||
* @throws NullPointerException if the object is {@code null}
|
||||
* @see #checkNotNull(Object, String, Object...)
|
||||
*/
|
||||
public static <T> T checkNotNull(final T obj,
|
||||
final Object errorMessage) {
|
||||
if (obj == null) {
|
||||
throw new NullPointerException(String.valueOf(errorMessage));
|
||||
}
|
||||
return obj;
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Preconditions that the specified argument is not {@code null},
|
||||
* throwing a NPE exception otherwise.
|
||||
*
|
||||
* <p>The message of the exception is {@code String.format(f, m)}.</p>
|
||||
*
|
||||
* @param <T> the object type
|
||||
* @param obj the object to check
|
||||
* @param message the {@link String#format(String, Object...)}
|
||||
* exception message if valid. Otherwise,
|
||||
* the message is {@link #VALIDATE_IS_NOT_NULL_EX_MESSAGE}
|
||||
* @param values the optional values for the formatted exception message
|
||||
* @return the validated object
|
||||
* @throws NullPointerException if the object is {@code null}
|
||||
* @see #checkNotNull(Object, Supplier)
|
||||
*/
|
||||
public static <T> T checkNotNull(final T obj, final String message,
|
||||
final Object... values) {
|
||||
// Deferring the evaluation of the message is a tradeoff between the cost
|
||||
// of constructing lambda Vs constructing a string object.
|
||||
// Using lambda would allocate an object on every call:
|
||||
// return checkNotNull(obj, () -> String.format(message, values));
|
||||
if (obj == null) {
|
||||
String msg;
|
||||
try {
|
||||
msg = String.format(message, values);
|
||||
} catch (Exception e) {
|
||||
LOG.debug("Error formatting message", e);
|
||||
msg = VALIDATE_IS_NOT_NULL_EX_MESSAGE;
|
||||
}
|
||||
throw new NullPointerException(msg);
|
||||
}
|
||||
return obj;
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Preconditions that the specified argument is not {@code null},
|
||||
* throwing a NPE exception otherwise.
|
||||
*
|
||||
* <p>The message of the exception is {@code msgSupplier.get()}.</p>
|
||||
*
|
||||
* @param <T> the object type
|
||||
* @param obj the object to check
|
||||
* @param msgSupplier the {@link Supplier#get()} set the
|
||||
* exception message if valid. Otherwise,
|
||||
* the message is {@link #VALIDATE_IS_NOT_NULL_EX_MESSAGE}
|
||||
* @return the validated object (never {@code null} for method chaining)
|
||||
* @throws NullPointerException if the object is {@code null}
|
||||
*/
|
||||
public static <T> T checkNotNull(final T obj,
|
||||
final Supplier<String> msgSupplier) {
|
||||
if (obj == null) {
|
||||
String msg;
|
||||
try {
|
||||
// note that we can get NPE evaluating the message itself;
|
||||
// but we do not want this to override the actual NPE.
|
||||
msg = msgSupplier.get();
|
||||
} catch (Exception e) {
|
||||
// ideally we want to log the error to capture. This may cause log files
|
||||
// to bloat. On the other hand, swallowing the exception may hide a bug
|
||||
// in the caller. Debug level is a good compromise between the two
|
||||
// concerns.
|
||||
LOG.debug("Error formatting message", e);
|
||||
msg = VALIDATE_IS_NOT_NULL_EX_MESSAGE;
|
||||
}
|
||||
throw new NullPointerException(msg);
|
||||
}
|
||||
return obj;
|
||||
}
|
||||
|
||||
/* @VisibleForTesting */
|
||||
static String getDefaultNullMSG() {
|
||||
return VALIDATE_IS_NOT_NULL_EX_MESSAGE;
|
||||
}
|
||||
}
|
|
@ -0,0 +1,122 @@
|
|||
/*
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
* or more contributor license agreements. See the NOTICE file
|
||||
* distributed with this work for additional information
|
||||
* regarding copyright ownership. The ASF licenses this file
|
||||
* to you under the Apache License, Version 2.0 (the
|
||||
* "License"); you may not use this file except in compliance
|
||||
* with the License. You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
package org.apache.hadoop.util;
|
||||
|
||||
import org.junit.Test;
|
||||
|
||||
import org.apache.hadoop.test.LambdaTestUtils;
|
||||
|
||||
public class TestPreconditions {
|
||||
private static final String NON_NULL_STRING = "NON_NULL_OBJECT";
|
||||
private static final String NON_INT_STRING = "NOT_INT";
|
||||
private static final String EXPECTED_ERROR_MSG = "Expected-Error-MSG";
|
||||
private static final String EXPECTED_ERROR_MSG_ARGS =
|
||||
EXPECTED_ERROR_MSG + " %s number %d";
|
||||
private static final String NULL_FORMATTER = null;
|
||||
|
||||
private String errorMessage;
|
||||
|
||||
@Test
|
||||
public void testCheckNotNullSuccess() {
|
||||
Preconditions.checkNotNull(NON_NULL_STRING);
|
||||
// null supplier
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, null);
|
||||
// ill-formated string supplier
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, ()-> String.format("%d",
|
||||
NON_INT_STRING));
|
||||
// null pattern to string formatter
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, NULL_FORMATTER, null, 1);
|
||||
// null arguments to string formatter
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, EXPECTED_ERROR_MSG_ARGS,
|
||||
null, null);
|
||||
// illegal format exception
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, "message %d %d",
|
||||
NON_INT_STRING, 1);
|
||||
// insufficient arguments
|
||||
Preconditions.checkNotNull(NON_NULL_STRING, EXPECTED_ERROR_MSG_ARGS,
|
||||
NON_INT_STRING);
|
||||
// null format in string supplier
|
||||
Preconditions.checkNotNull(NON_NULL_STRING,
|
||||
() -> String.format(NULL_FORMATTER, NON_INT_STRING));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testCheckNotNullFailure() throws Exception {
|
||||
// failure without message
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null));
|
||||
|
||||
// failure with message
|
||||
errorMessage = EXPECTED_ERROR_MSG;
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
errorMessage,
|
||||
() -> Preconditions.checkNotNull(null, errorMessage));
|
||||
|
||||
// failure with Null message
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
null,
|
||||
() -> Preconditions.checkNotNull(null, errorMessage));
|
||||
|
||||
// failure with message format
|
||||
errorMessage = EXPECTED_ERROR_MSG + " %s";
|
||||
String arg = "NPE";
|
||||
String expectedMSG = String.format(errorMessage, arg);
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
expectedMSG,
|
||||
() -> Preconditions.checkNotNull(null, errorMessage, arg));
|
||||
|
||||
// failure with multiple arg message format
|
||||
errorMessage = EXPECTED_ERROR_MSG_ARGS;
|
||||
expectedMSG =
|
||||
String.format(errorMessage, arg, 1);
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
expectedMSG,
|
||||
() -> Preconditions.checkNotNull(null, errorMessage, arg, 1));
|
||||
|
||||
// illegal format will be thrown if the case is not handled correctly
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null,
|
||||
errorMessage, 1, NON_INT_STRING));
|
||||
|
||||
// illegal format will be thrown for insufficient Insufficient Args
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null, errorMessage, NON_NULL_STRING));
|
||||
|
||||
// illegal format in supplier
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null,
|
||||
() -> String.format(errorMessage, 1, NON_INT_STRING)));
|
||||
|
||||
// insufficient arguments in string Supplier
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null,
|
||||
() -> String.format(errorMessage, NON_NULL_STRING)));
|
||||
|
||||
// null formatter
|
||||
LambdaTestUtils.intercept(NullPointerException.class,
|
||||
Preconditions.getDefaultNullMSG(),
|
||||
() -> Preconditions.checkNotNull(null,
|
||||
() -> String.format(NULL_FORMATTER, NON_NULL_STRING)));
|
||||
}
|
||||
}
|
Loading…
Reference in New Issue