You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2012/09/16 17:42:49 UTC
svn commit: r1385286 - in
/incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis:
resources/Errors.java resources/Errors.properties
resources/Errors_fr.properties util/ArgumentChecks.java
Author: desruisseaux
Date: Sun Sep 16 15:42:49 2012
New Revision: 1385286
URL: http://svn.apache.org/viewvc?rev=1385286&view=rev
Log:
Added the ArgumentChecks utility methods.
Added:
incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java (with props)
Modified:
incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.java
incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.properties
incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors_fr.properties
Modified: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.java
URL: http://svn.apache.org/viewvc/incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.java?rev=1385286&r1=1385285&r2=1385286&view=diff
==============================================================================
--- incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.java (original)
+++ incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.java Sun Sep 16 15:42:49 2012
@@ -43,6 +43,57 @@ public final class Errors extends Indexe
public static final class Keys {
private Keys() {
}
+
+ /**
+ * Argument â{0}â shall not be empty.
+ */
+ public static final int EmptyArgument_1 = 1;
+
+ /**
+ * Argument â{0}â can not be an instance of â{1}â. Expected an instance of â{2}â or derived
+ * type.
+ */
+ public static final int IllegalArgumentClass_3 = 2;
+
+ /**
+ * Class â{0}â is illegal. It must be â{1}â or a derived class.
+ */
+ public static final int IllegalClass_2 = 3;
+
+ /**
+ * Index {0} is out of bounds.
+ */
+ public static final int IndexOutOfBounds_1 = 4;
+
+ /**
+ * Argument â{0}â shall not be negative. The given value was {1}.
+ */
+ public static final int NegativeArgument_2 = 8;
+
+ /**
+ * Argument '{0}' shall not be NaN (Not-a-Number).
+ */
+ public static final int NotANumber_1 = 9;
+
+ /**
+ * Argument â{0}â shall not be null.
+ */
+ public static final int NullArgument_1 = 0;
+
+ /**
+ * Argument â{0}â has {1} dimensions, while {2} was expected.
+ */
+ public static final int UnexpectedArgumentDimension_3 = 5;
+
+ /**
+ * Value â{0}â={1} is invalid. Expected a number greater than 0.
+ */
+ public static final int ValueNotGreaterThanZero_2 = 7;
+
+ /**
+ * Value â{0}â={1} is invalid. Expected a value in the [{2} ⦠{3}] range.
+ */
+ public static final int ValueOutOfRange_4 = 6;
}
/**
Modified: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.properties
URL: http://svn.apache.org/viewvc/incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.properties?rev=1385286&r1=1385285&r2=1385286&view=diff
==============================================================================
--- incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.properties (original)
+++ incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors.properties Sun Sep 16 15:42:49 2012
@@ -14,3 +14,13 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
+EmptyArgument_1=Argument \u2018{0}\u2019 shall not be empty.
+IllegalArgumentClass_3=Argument \u2018{0}\u2019 can not be an instance of \u2018{1}\u2019. Expected an instance of \u2018{2}\u2019 or derived type.
+IllegalClass_2=Class \u2018{0}\u2019 is illegal. It must be \u2018{1}\u2019 or a derived class.
+IndexOutOfBounds_1=Index {0} is out of bounds.
+NegativeArgument_2=Argument \u2018{0}\u2019 shall not be negative. The given value was {1}.
+NotANumber_1=Argument '{0}' shall not be NaN (Not-a-Number).
+NullArgument_1=Argument \u2018{0}\u2019 shall not be null.
+UnexpectedArgumentDimension_3=Argument \u2018{0}\u2019 has {1} dimensions, while {2} was expected.
+ValueNotGreaterThanZero_2=Value \u2018{0}\u2019={1} is invalid. Expected a number greater than 0.
+ValueOutOfRange_4=Value \u2018{0}\u2019={1} is invalid. Expected a value in the [{2} \u2026 {3}] range.
Modified: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors_fr.properties
URL: http://svn.apache.org/viewvc/incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors_fr.properties?rev=1385286&r1=1385285&r2=1385286&view=diff
==============================================================================
--- incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors_fr.properties (original)
+++ incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/Errors_fr.properties Sun Sep 16 15:42:49 2012
@@ -14,3 +14,13 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
+EmptyArgument_1=L\u2019argument \u2018{0}\u2019 ne doit pas \u00eatre vide.
+IllegalArgumentClass_3=L\u2019argument \u2018{0}\u2019 ne peut pas \u00eatre de type \u2018{1}\u2019. Une instance de \u2018{2}\u2019 ou d\u2019un type d\u00e9riv\u00e9 \u00e9tait attendue.
+IllegalClass_2=La classe \u2018{0}\u2019 est ill\u00e9gale. Il doit s\u2019agir d\u2019une classe \u2018{1}\u2019 ou d\u00e9riv\u00e9e.
+IndexOutOfBounds_1=L\u2019index {0} est en dehors des limites permises.
+NegativeArgument_2=L\u2019argument \u2018{0}\u2019 ne doit pas \u00eatre n\u00e9gatif. La valeur donn\u00e9e \u00e9tait {1}.
+NotANumber_1=L\u2019argument '{0}' ne doit pas \u00eatre NaN (Not-a-Number).
+NullArgument_1=L\u2019argument \u2018{0}\u2019 ne doit pas \u00eatre nul.
+UnexpectedArgumentDimension_3=L\u2019argument \u2018{0}\u2019 a {1} dimensions, alors qu\u2019on en attendait {2}.
+ValueNotGreaterThanZero_2=La valeur \u2018{0}\u2019={1} n\u2019est pas valide. On attendait un nombre positif non-nul.
+ValueOutOfRange_4=La valeur \u2018{0}\u2019={1} est invalide. Une valeur dans la plage [{2} \u2026 {3}] \u00e9tait attendue.
Added: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java
URL: http://svn.apache.org/viewvc/incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java?rev=1385286&view=auto
==============================================================================
--- incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java (added)
+++ incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java Sun Sep 16 15:42:49 2012
@@ -0,0 +1,403 @@
+/*
+ * 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.sis.util;
+
+import org.opengis.geometry.DirectPosition;
+import org.opengis.geometry.MismatchedDimensionException;
+
+import org.apache.sis.resources.Errors;
+
+
+/**
+ * Provides static methods for performing argument checks. The methods in this class throw
+ * one of the following exceptions (or a subclass of them) widely used in standard Java API:
+ * <p>
+ * <table>
+ * <tr><th>Exception</th></th>Thrown by</th></tr>
+ * <tr><td>{@link NullPointerException}</td>
+ * <td>{@link #ensureNonNull(String, Object) ensureNonNull}</td></tr>
+ *
+ * <tr><td>{@link IndexOutOfBoundsException}</td>
+ * <td>{@link #ensureValidIndex(int, int) ensureValidIndex}</td></tr>
+ *
+ * <tr><td>{@link IllegalArgumentException}</td>
+ * <td>{@link #ensurePositive(String, int) ensurePositive},
+ * {@link #ensureStrictlyPositive(String, int) ensureStrictlyPositive},
+ * {@link #ensureBetween(String, int, int, int) ensureBetween}</td></tr>
+ * </table>
+ *
+ * {@section Method Arguments}
+ * By convention, the value to check is always the last parameter given to every methods
+ * in this class. The other parameters may include the programmatic name of the argument
+ * being checked. This programmatic name is used for building an error message localized
+ * in the {@linkplain java.util.Locale#getDefault() default locale} if the check failed.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.3 (derived from geotk-3.17)
+ * @version 0.3
+ * @module
+ */
+public final class ArgumentChecks extends Static {
+ /**
+ * Forbid object creation.
+ */
+ private ArgumentChecks() {
+ }
+
+ /**
+ * Makes sure that an argument is non-null. If the given {@code object} is null, then a
+ * {@link NullArgumentException} is thrown with a localized message containing the given name.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param object The user argument to check against null value.
+ * @throws NullArgumentException if {@code object} is null.
+ */
+ public static void ensureNonNull(final String name, final Object object)
+ throws NullArgumentException
+ {
+ if (object == null) {
+ throw new NullArgumentException(Errors.format(Errors.Keys.NullArgument_1, name));
+ }
+ }
+
+ /**
+ * Makes sure that an array element is non-null. If {@code array[index]} is null, then a
+ * {@link NullArgumentException} is thrown with a localized message containing the given name.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param index Index of the element to check.
+ * @param array The user argument to check against null element.
+ * @throws NullArgumentException if {@code array} or {@code array[index]} is null.
+ */
+ public static void ensureNonNull(final String name, final int index, final Object[] array)
+ throws NullArgumentException
+ {
+ if (array == null) {
+ throw new NullArgumentException(Errors.format(Errors.Keys.NullArgument_1, name));
+ }
+ if (array[index] == null) {
+ throw new NullArgumentException(Errors.format(
+ Errors.Keys.NullArgument_1, name + '[' + index + ']'));
+ }
+ }
+
+ /**
+ * Makes sure that a character sequence is non-null and non-empty. If the given {@code text} is
+ * null, then a {@link NullArgumentException} is thrown. Otherwise if the given {@code text}Â has
+ * a {@linkplain CharSequence#length() length} equals to 0, then an {@link IllegalArgumentException}
+ * is thrown.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param text The user argument to check against null value and empty sequences.
+ * @throws NullArgumentException if {@code text} is null.
+ * @throws IllegalArgumentException if {@code text} is empty.
+ */
+ public static void ensureNonEmpty(final String name, final CharSequence text)
+ throws NullArgumentException, IllegalArgumentException
+ {
+ if (text == null) {
+ throw new NullArgumentException(Errors.format(Errors.Keys.NullArgument_1, name));
+ }
+ if (text.length() == 0) {
+ throw new IllegalArgumentException(Errors.format(Errors.Keys.EmptyArgument_1, name));
+ }
+ }
+
+ /**
+ * Ensures that the specified value is null or an instance assignable to the given type.
+ * If this method does not thrown an exception, then the value can be casted to the class
+ * represented by {@code expectedType} without throwing a {@link ClassCastException}.
+ *
+ * @param <T> The compile-time type of the value.
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * Can be {@code null} if the name is unknown.
+ * @param expectedType the expected type (class or interface).
+ * @param value The value to check, or {@code null}.
+ * @throws IllegalArgumentException if {@code value} is non-null and is not assignable
+ * to the given type.
+ */
+ public static <T> void ensureCanCast(final String name, final Class<? extends T> expectedType, final T value)
+ throws IllegalArgumentException
+ {
+ if (value != null) {
+ final Class<?> valueClass = value.getClass();
+ if (!expectedType.isAssignableFrom(valueClass)) {
+ final int key;
+ final Object[] args;
+ if (name != null) {
+ key = Errors.Keys.IllegalArgumentClass_3;
+ args = new Object[] {name, valueClass, expectedType};
+ } else {
+ key = Errors.Keys.IllegalClass_2;
+ args = new Object[] {valueClass, expectedType};
+ }
+ throw new IllegalArgumentException(Errors.format(key, args));
+ }
+ }
+ }
+
+ /**
+ * Ensures that the given index is equals or greater than zero and lower than the given
+ * upper value. This method is primarily designed for methods that expect only an index
+ * argument. For this reason, this method does not take the argument name.
+ *
+ * @param upper The maximal index value, exclusive.
+ * @param index The index to check.
+ * @throws IndexOutOfBoundsException If the given index is negative or not lower than the
+ * given upper value.
+ */
+ public static void ensureValidIndex(final int upper, final int index) throws IndexOutOfBoundsException {
+ if (index < 0 || index >= upper) {
+ throw new IndexOutOfBoundsException(Errors.format(Errors.Keys.IndexOutOfBounds_1, index));
+ }
+ }
+
+ /**
+ * Ensures that the given integer value is greater than or equals to zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is negative.
+ */
+ public static void ensurePositive(final String name, final int value)
+ throws IllegalArgumentException
+ {
+ if (value < 0) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.NegativeArgument_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given long value is greater than or equals to zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is negative.
+ */
+ public static void ensurePositive(final String name, final long value)
+ throws IllegalArgumentException
+ {
+ if (value < 0) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.NegativeArgument_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is greater than or equals to zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is {@linkplain Float#NaN NaN} or negative.
+ */
+ public static void ensurePositive(final String name, final float value)
+ throws IllegalArgumentException
+ {
+ if (!(value >= 0)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Float.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.NegativeArgument_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is greater than or equals to zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is {@linkplain Double#NaN NaN} or negative.
+ */
+ public static void ensurePositive(final String name, final double value)
+ throws IllegalArgumentException
+ {
+ if (!(value >= 0)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Double.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.NegativeArgument_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given integer value is greater than zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is negative or equals to zero.
+ */
+ public static void ensureStrictlyPositive(final String name, final int value)
+ throws IllegalArgumentException
+ {
+ if (value <= 0) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.ValueNotGreaterThanZero_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given long value is greater than zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is negative or equals to zero.
+ */
+ public static void ensureStrictlyPositive(final String name, final long value)
+ throws IllegalArgumentException
+ {
+ if (value <= 0) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.ValueNotGreaterThanZero_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is greater than zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is {@linkplain Float#NaN NaN},
+ * zero or negative.
+ */
+ public static void ensureStrictlyPositive(final String name, final float value)
+ throws IllegalArgumentException
+ {
+ if (!(value > 0)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Float.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.ValueNotGreaterThanZero_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is greater than zero.
+ *
+ * @param name The name of the argument to be checked, used only if an exception is thrown.
+ * @param value The user argument to check.
+ * @throws IllegalArgumentException if the given value is {@linkplain Double#NaN NaN},
+ * zero or negative.
+ */
+ public static void ensureStrictlyPositive(final String name, final double value)
+ throws IllegalArgumentException
+ {
+ if (!(value > 0)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Double.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.ValueNotGreaterThanZero_2, name, value));
+ }
+ }
+
+ /**
+ * Ensures that the given integer value is between the given bounds, inclusive.
+ * This method is used for checking values that are <strong>not</strong> index.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param min The minimal value, inclusive.
+ * @param max The maximal value, inclusive.
+ * @param value The value to be tested.
+ * @throws IllegalArgumentException if the given value is not in the given range.
+ *
+ * @see #ensureValidIndex(int, int)
+ */
+ public static void ensureBetween(final String name, final int min, final int max, final int value)
+ throws IllegalArgumentException
+ {
+ if (value < min || value > max) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.ValueOutOfRange_4, name, value, min, max));
+ }
+ }
+
+ /**
+ * Ensures that the given long value is between the given bounds, inclusive.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param min The minimal value, inclusive.
+ * @param max The maximal value, inclusive.
+ * @param value The value to be tested.
+ * @throws IllegalArgumentException if the given value is not in the given range.
+ */
+ public static void ensureBetween(final String name, final long min, final long max, final long value)
+ throws IllegalArgumentException
+ {
+ if (value < min || value > max) {
+ throw new IllegalArgumentException(Errors.format(
+ Errors.Keys.ValueOutOfRange_4, name, value, min, max));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is between the given bounds, inclusive.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param min The minimal value, inclusive.
+ * @param max The maximal value, inclusive.
+ * @param value The value to be tested.
+ * @throws IllegalArgumentException if the given value is {@linkplain Float#NaN NaN}
+ * or not in the given range.
+ */
+ public static void ensureBetween(final String name, final float min, final float max, final float value)
+ throws IllegalArgumentException
+ {
+ if (!(value >= min && value <= max)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Float.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.ValueOutOfRange_4, name, value, min, max));
+ }
+ }
+
+ /**
+ * Ensures that the given floating point value is between the given bounds, inclusive.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param min The minimal value, inclusive.
+ * @param max The maximal value, inclusive.
+ * @param value The value to be tested.
+ * @throws IllegalArgumentException if the given value is {@linkplain Float#NaN NaN}
+ * or not in the given range.
+ */
+ public static void ensureBetween(final String name, final double min, final double max, final double value)
+ throws IllegalArgumentException
+ {
+ if (!(value >= min && value <= max)) { // Use '!' for catching NaN.
+ throw new IllegalArgumentException(Double.isNaN(value) ?
+ Errors.format(Errors.Keys.NotANumber_1, name) :
+ Errors.format(Errors.Keys.ValueOutOfRange_4, name, value, min, max));
+ }
+ }
+
+ /**
+ * Ensures that the given direct position has the expected number of dimensions.
+ * This method does nothing if the direct position is null.
+ *
+ * @param name The name of the argument to be checked. Used only in case an exception is thrown.
+ * @param position The direct position to check for its dimension.
+ * @param expected The expected number of dimensions.
+ * @throws MismatchedDimensionException If the given direct position is non-null and does
+ * not have the expected number of dimensions.
+ */
+ public static void ensureDimensionMatches(final String name, final DirectPosition position, final int expected)
+ throws MismatchedDimensionException
+ {
+ if (position != null) {
+ final int dimension = position.getDimension();
+ if (dimension != expected) {
+ throw new MismatchedDimensionException(Errors.format(
+ Errors.Keys.UnexpectedArgumentDimension_3, name, dimension, expected));
+ }
+ }
+ }
+}
Propchange: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: incubator/sis/trunk/sis-utility/src/main/java/org/apache/sis/util/ArgumentChecks.java
------------------------------------------------------------------------------
svn:mime-type = text/plain