Add utility class for method argument checking

Introduces the `Require` class which  provides a basic set of static
methods which are useful for validating method arguments. These methods
are:

 - `notNull`
 - `notNegative`
 - `validArrayIndex`
 - `validArraySlice`

All methods exist in two versions: one that outputs a default exception
message and second one which allows the caller to customize the
exception message.

Author: cboehme

src/main/java/org/culturegraph/mf/util/Require.java

@@ -0,0 +1,136 @@
+/*
+ *  Copyright 2014 Christoph Böhme
+ *
+ *  Licensed 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.culturegraph.mf.util;
+
+/**
+ * Defines static methods for method argument validation.
+ *
+ * @author Christoph Böhme
+ *
+ */
+public final class Require {
+
+	private Require() {
+		// No instances allowed
+	}
+
+	/**
+	 * Throws an {@link IllegalArgumentException} if {@code object} is
+	 * {@literal null}.
+	 *
+	 * @return {@code object}
+	 */
+	public static <T> T notNull(final T object) {
+		return notNull(object, "parameter must not be null");
+	}
+
+	/**
+	 * Throws an {@link IllegalArgumentException} if {@code object} is
+	 * {@literal null}.
+	 *
+	 * @param message
+	 *            exception message
+	 * @return {@code object}
+	 */
+	public static <T> T notNull(final T object, final String message) {
+		if (object == null) {
+			throw new IllegalArgumentException(message);
+		}
+		return object;
+	}
+
+	/**
+	 * Throws an {@link IllegalArgumentException} if {@code value} is negative.
+	 *
+	 * @return {@code value}
+	 */
+	public static int notNegative(final int value) {
+		return notNegative(value, "parameter must not be negative");
+	}
+
+	/**
+	 * Throws an {@link IllegalArgumentException} if {@code value} is negative.
+	 *
+	 * @param message
+	 *            exception message
+	 * @return {@code value}
+	 */
+	public static int notNegative(final int value, final String message) {
+		if (value < 0) {
+			throw new IllegalArgumentException(message);
+		}
+		return value;
+	}
+
+	/**
+	 * Throws an {@link IndexOutOfBoundsException} if {@code index} is negative
+	 * or equal to or greater than {@code arrayLength}.
+	 *
+	 * @return {@code index}
+	 */
+	public static int validArrayIndex(final int index, final int arrayLength) {
+		return validArrayIndex(index, arrayLength, "array index out of range");
+	}
+
+	/**
+	 * Throws an {@link IndexOutOfBoundsException} if {@code index} is negative
+	 * or equal to or greater than {@code arrayLength}.
+	 *
+	 * @param message
+	 *            exception message
+	 * @return {@code index}
+	 */
+	public static int validArrayIndex(final int index, final int arrayLength,
+			final String message) {
+		if (index < 0 || index >= arrayLength) {
+			throw new IndexOutOfBoundsException(message);
+		}
+		return index;
+	}
+
+	/**
+	 * Throws an {@link IndexOutOfBoundsException} if {@code sliceFrom} or
+	 * {@code sliceLength} is negative or the sum of both is greater than
+	 * {@code arrayLength}. Note that this means that a slice of length zero
+	 * starting at array length is a valid slice.
+	 */
+	public static void validArraySlice(final int sliceFrom,
+			final int sliceLength, final int arrayLength) {
+		validArraySlice(sliceFrom, sliceLength, arrayLength,
+				"array slice out of range");
+	}
+
+	/**
+	 * Throws an {@link IndexOutOfBoundsException} if {@code sliceFrom} or
+	 * {@code sliceLength} is negative or the sum of both is greater than
+	 * {@code arrayLength}. Note that this means that a slice of length zero
+	 * starting at array length is a valid slice.
+	 *
+	 *
+	 * @param message
+	 *            exception message
+	 */
+	public static void validArraySlice(final int sliceFrom,
+			final int sliceLength, final int arrayLength, final String message) {
+		if (sliceFrom < 0 || sliceLength < 0) {
+			throw new IndexOutOfBoundsException(message);
+		}
+		if (sliceFrom + sliceLength > arrayLength) {
+			throw new IndexOutOfBoundsException(message);
+		}
+	}
+
+}

src/test/java/org/culturegraph/mf/util/RequireTest.java

@@ -0,0 +1,87 @@
+/*
+ *  Copyright 2014 Christoph Böhme
+ *
+ *  Licensed 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.culturegraph.mf.util;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+
+import org.junit.Test;
+
+/**
+ * Tests for class {@link Require}.
+ *
+ * @author Christoph Böhme
+ *
+ */
+public final class RequireTest {
+
+	@Test(expected = IllegalArgumentException.class)
+	public void notNullShouldThrowIllegalArgumentExceptionIfArgIsNull() {
+		Require.notNull(null);
+	}
+
+	@Test
+	public void notNullShouldReturnArgIfArgIsNotNull() {
+		final Object obj = new Object();
+		assertSame(obj, Require.notNull(obj));
+	}
+
+	@Test(expected = IllegalArgumentException.class)
+	public void notNegativeShouldThrowIllegalArgumentExceptionIfArgIsNegative() {
+		Require.notNegative(-1);
+	}
+
+	@Test
+	public void notNegativeShouldReturnArgIfArgIsNotNegative() {
+		assertEquals(0, Require.notNegative(0));
+	}
+
+	@Test(expected = IndexOutOfBoundsException.class)
+	public void validArrayIndexShouldThrowIndexOutOfBoundsExceptionIfIndexIsNegative() {
+		Require.validArrayIndex(-1, 2);
+	}
+
+	@Test(expected = IndexOutOfBoundsException.class)
+	public void validArrayIndexShouldThrowIndexOutOfBoundsExceptionIfIndexIsGreaterThanArrayLength() {
+		Require.validArrayIndex(2, 2);
+	}
+
+	@Test
+	public void validArrayIndexShouldDoNothingIfIndexIsWithinArrayBounds() {
+		assertEquals(1, Require.validArrayIndex(1, 2));
+	}
+
+	@Test(expected = IndexOutOfBoundsException.class)
+	public void validArraySliceShouldThrowIndexOutOfBoundsExceptionIfIndexIsNegative() {
+		Require.validArraySlice(-1, 1, 2);
+	}
+
+	@Test(expected = IndexOutOfBoundsException.class)
+	public void validArraySliceShouldThrowIndexOutOfBoundsExceptionIfLengthIsNegative() {
+		Require.validArraySlice(0, -1, 2);
+	}
+
+	@Test(expected = IndexOutOfBoundsException.class)
+	public void validArraySliceShouldThrowIndexOutOfBoundsExceptionIfIndexPlusLengthIsGreaterThanArrayLength() {
+		Require.validArraySlice(1, 2, 2);
+	}
+
+	@Test
+	public void validArraySliceShouldDoNothingIfIndexAndLengthAreWithinArrayBounds() {
+		Require.validArraySlice(0, 1, 2);
+	}
+
+}