You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by se...@apache.org on 2016/04/13 10:31:05 UTC

[07/14] flink git commit: [FLINK-3700] [core] Add 'Preconditions' utility class.

[FLINK-3700] [core] Add 'Preconditions' utility class.


Project: http://git-wip-us.apache.org/repos/asf/flink/repo
Commit: http://git-wip-us.apache.org/repos/asf/flink/commit/885d543b
Tree: http://git-wip-us.apache.org/repos/asf/flink/tree/885d543b
Diff: http://git-wip-us.apache.org/repos/asf/flink/diff/885d543b

Branch: refs/heads/master
Commit: 885d543be8a8c0d1acdffa0003e394347d5376ef
Parents: 272fd12
Author: Stephan Ewen <se...@apache.org>
Authored: Tue Apr 5 13:23:14 2016 +0200
Committer: Stephan Ewen <se...@apache.org>
Committed: Wed Apr 13 01:10:54 2016 +0200

----------------------------------------------------------------------
 .../org/apache/flink/util/Preconditions.java    | 213 +++++++++++++++++++
 1 file changed, 213 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/flink/blob/885d543b/flink-core/src/main/java/org/apache/flink/util/Preconditions.java
----------------------------------------------------------------------
diff --git a/flink-core/src/main/java/org/apache/flink/util/Preconditions.java b/flink-core/src/main/java/org/apache/flink/util/Preconditions.java
new file mode 100644
index 0000000..135038b
--- /dev/null
+++ b/flink-core/src/main/java/org/apache/flink/util/Preconditions.java
@@ -0,0 +1,213 @@
+/*
+ * 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.
+ */
+
+// ----------------------------------------------------------------------------
+//  This class is largely adapted from "com.google.common.base.Preconditions",
+//  which is part of the "Guava" library.
+//
+//  Because of frequent issues with dependency conflicts, this class was
+//  added to the Flink code base to reduce dependency on Guava.
+// ----------------------------------------------------------------------------
+
+package org.apache.flink.util;
+
+import org.apache.flink.annotation.Internal;
+
+import javax.annotation.Nullable;
+
+/**
+ * A collection of static utility methods to validate input.
+ * 
+ * <p>This class is modelled after Google Guava's Preconditions class, and partly takes code
+ * from that class. We add this code to the Flink code base in order to reduce external
+ * dependencies.
+ */
+@Internal
+public final class Preconditions {
+
+	// ------------------------------------------------------------------------
+	//  Null checks
+	// ------------------------------------------------------------------------
+	
+	/**
+	 * Ensures that the given object reference is not null.
+	 * Upon violation, a {@code NullPointerException} with no message is thrown.
+	 * 
+	 * @param reference The object reference
+	 * @return The object reference itself (generically typed).
+	 * 
+	 * @throws NullPointerException Thrown, if the passed reference was null.
+	 */
+	public static <T> T checkNotNull(T reference) {
+		if (reference == null) {
+			throw new NullPointerException();
+		}
+		return reference;
+	}
+	
+	/**
+	 * Ensures that the given object reference is not null.
+	 * Upon violation, a {@code NullPointerException} with the given message is thrown.
+	 * 
+	 * @param reference The object reference
+	 * @param errorMessage The message for the {@code NullPointerException} that is thrown if the check fails.
+	 * @return The object reference itself (generically typed).
+	 *
+	 * @throws NullPointerException Thrown, if the passed reference was null.
+	 */
+	public static <T> T checkNotNull(T reference, @Nullable String errorMessage) {
+		if (reference == null) {
+			throw new NullPointerException(String.valueOf(errorMessage));
+		}
+		return reference;
+	}
+
+	/**
+	 * Ensures that the given object reference is not null.
+	 * Upon violation, a {@code NullPointerException} with the given message is thrown.
+	 * 
+	 * <p>The error message is constructed from a template and an arguments array, after
+	 * a similar fashion as {@link String#format(String, Object...)}, but supporting only
+	 * {@code %s} as a placeholder.
+	 *
+	 * @param reference The object reference
+	 * @param errorMessageTemplate The message template for the {@code NullPointerException}
+	 *                             that is thrown if the check fails. The template substitutes its
+	 *                             {@code %s} placeholders with the error message arguments.
+	 * @param errorMessageArgs The arguments for the error message, to be inserted into the
+	 *                         message template for the {@code %s} placeholders.
+	 *                         
+	 * @return The object reference itself (generically typed).
+	 *
+	 * @throws NullPointerException Thrown, if the passed reference was null.
+	 */
+	public static <T> T checkNotNull(T reference,
+				@Nullable String errorMessageTemplate,
+				@Nullable Object... errorMessageArgs) {
+		
+		if (reference == null) {
+			throw new NullPointerException(format(errorMessageTemplate, errorMessageArgs));
+		}
+		return reference;
+	}
+
+	// ------------------------------------------------------------------------
+	//  Boolean Condition Checking
+	// ------------------------------------------------------------------------
+	
+	/**
+	 * Checks the given boolean condition, and throws an {@code IllegalArgumentException} if
+	 * the condition is not met (evaluates to {@code false}).
+	 *
+	 * @param condition The condition to check
+	 *                     
+	 * @throws IllegalArgumentException Thrown, if the condition is violated.
+	 */
+	public static void checkArgument(boolean condition) {
+		if (!condition) {
+			throw new IllegalArgumentException();
+		}
+	}
+
+	/**
+	 * Checks the given boolean condition, and throws an {@code IllegalArgumentException} if
+	 * the condition is not met (evaluates to {@code false}). The exception will have the
+	 * given error message.
+	 *
+	 * @param condition The condition to check
+	 * @param errorMessage The message for the {@code IllegalArgumentException} that is thrown if the check fails.
+	 * 
+	 * @throws IllegalArgumentException Thrown, if the condition is violated.
+	 */
+	public static void checkArgument(boolean condition, @Nullable Object errorMessage) {
+		if (!condition) {
+			throw new IllegalArgumentException(String.valueOf(errorMessage));
+		}
+	}
+
+	/**
+	 * Checks the given boolean condition, and throws an {@code IllegalArgumentException} if
+	 * the condition is not met (evaluates to {@code false}).
+	 *
+	 * @param condition The condition to check
+	 * @param errorMessageTemplate The message template for the {@code IllegalArgumentException}
+	 *                             that is thrown if the check fails. The template substitutes its
+	 *                             {@code %s} placeholders with the error message arguments.
+	 * @param errorMessageArgs The arguments for the error message, to be inserted into the
+	 *                         message template for the {@code %s} placeholders.
+	 * 
+	 * @throws IllegalArgumentException Thrown, if the condition is violated.
+	 */
+	public static void checkArgument(boolean condition,
+			@Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		
+		if (!condition) {
+			throw new IllegalArgumentException(format(errorMessageTemplate, errorMessageArgs));
+		}
+	}
+
+
+	// ------------------------------------------------------------------------
+	//  Utilities
+	// ------------------------------------------------------------------------
+
+	/**
+	 * A simplified formatting method. Similar to {@link String#format(String, Object...)}, but
+	 * with lower overhead (only String parameters, no locale, no format validation).
+	 * 
+	 * <p>This method is taken quasi verbatim from the Guava Preconditions class.
+	 */
+	private static String format(@Nullable String template, @Nullable Object... args) {
+		final int numArgs = args == null ? 0 : args.length;
+		template = String.valueOf(template); // null -> "null"
+		
+		// start substituting the arguments into the '%s' placeholders
+		StringBuilder builder = new StringBuilder(template.length() + 16 * numArgs);
+		int templateStart = 0;
+		int i = 0;
+		while (i < numArgs) {
+			int placeholderStart = template.indexOf("%s", templateStart);
+			if (placeholderStart == -1) {
+				break;
+			}
+			builder.append(template.substring(templateStart, placeholderStart));
+			builder.append(args[i++]);
+			templateStart = placeholderStart + 2;
+		}
+		builder.append(template.substring(templateStart));
+
+		// if we run out of placeholders, append the extra args in square braces
+		if (i < numArgs) {
+			builder.append(" [");
+			builder.append(args[i++]);
+			while (i < numArgs) {
+				builder.append(", ");
+				builder.append(args[i++]);
+			}
+			builder.append(']');
+		}
+
+		return builder.toString();
+	}
+	
+	// ------------------------------------------------------------------------
+
+	/** Private constructor to prevent instantiation */
+	private Preconditions() {}
+}
\ No newline at end of file