From sis-commits-return-503-apmail-incubator-sis-commits-archive=incubator.apache.org@incubator.apache.org Sun Sep 16 15:43:39 2012 Return-Path: X-Original-To: apmail-incubator-sis-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-sis-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 9D839D612 for ; Sun, 16 Sep 2012 15:43:39 +0000 (UTC) Received: (qmail 2702 invoked by uid 500); 16 Sep 2012 15:43:39 -0000 Delivered-To: apmail-incubator-sis-commits-archive@incubator.apache.org Received: (qmail 2673 invoked by uid 500); 16 Sep 2012 15:43:39 -0000 Mailing-List: contact sis-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: sis-dev@incubator.apache.org Delivered-To: mailing list sis-commits@incubator.apache.org Received: (qmail 2663 invoked by uid 99); 16 Sep 2012 15:43:39 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 16 Sep 2012 15:43:39 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 16 Sep 2012 15:43:34 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id F3A9D23889D7; Sun, 16 Sep 2012 15:42:49 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: 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 Date: Sun, 16 Sep 2012 15:42:49 -0000 To: sis-commits@incubator.apache.org From: desruisseaux@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120916154249.F3A9D23889D7@eris.apache.org> 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: + *

+ * + * Thrown by + * + * + * + * + * + * + * + * + *
Exception
{@link NullPointerException}{@link #ensureNonNull(String, Object) ensureNonNull}
{@link IndexOutOfBoundsException}{@link #ensureValidIndex(int, int) ensureValidIndex}
{@link IllegalArgumentException}{@link #ensurePositive(String, int) ensurePositive}, + * {@link #ensureStrictlyPositive(String, int) ensureStrictlyPositive}, + * {@link #ensureBetween(String, int, int, int) ensureBetween}
+ * + * {@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 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 void ensureCanCast(final String name, final Class 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 not 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