001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.parameter;
019
020
021/**
022 * Thrown if adding or removing a {@linkplain ParameterValue parameter value} in a
023 * {@linkplain ParameterValueGroup group} would result in more or less parameters than the expected range.
024 * The minimum and maximum occurrences are defined by the {@link ParameterDescriptorGroup}
025 * instance associated with the {@code ParameterValueGroup}.
026 *
027 * <p>This exception may be thrown directly by the {@link ParameterValueGroup#addGroup(String)}
028 * method, or indirectly during the add or remove operations applied on the list returned by
029 * {@link ParameterValueGroup#values()}.</p>
030 *
031 * <div class="note"><b>Note 1:</b>
032 * the <dfn>cardinality</dfn> is the number of elements in a set. Contrast with <dfn>multiplicity</dfn>,
033 * which is the range of possible cardinalities a set can hold.</div>
034 *
035 * <div class="note"><b>Note 2:</b>
036 * this exception is of kind {@code IllegalStateException} instead of {@code IllegalArgumentException}
037 * because it is not caused by a bad argument. It is rather a consequence of an {@link ParameterValueGroup}
038 * being "full".</div>
039 *
040 * @author  Martin Desruisseaux (IRD)
041 * @version 3.0
042 * @since   2.0
043 */
044public class InvalidParameterCardinalityException extends IllegalStateException {
045    /**
046     * Serial number for inter-operability with different versions.
047     */
048    private static final long serialVersionUID = 4030549323541812311L;
049
050    /**
051     * The name of the parameter with invalid cardinality.
052     */
053    private final String parameterName;
054
055    /**
056     * Creates an exception with the specified message and parameter name.
057     *
058     * @param message        the detail message, saved for later retrieval by the {@link #getMessage()} method.
059     * @param parameterName  the name of the parameter with invalid cardinality.
060     */
061    public InvalidParameterCardinalityException(String message, String parameterName) {
062        super(message);
063        this.parameterName = parameterName;
064    }
065
066    /**
067     * Creates an exception with the specified message, cause and parameter name.
068     *
069     * @param message        the detail message, saved for later retrieval by the {@link #getMessage()} method.
070     * @param cause          the cause, saved for later retrieval by the {@link #getCause()} method.
071     * @param parameterName  the name of the parameter with invalid cardinality.
072     *
073     * @since 3.1
074     */
075    public InvalidParameterCardinalityException(String message, Throwable cause, String parameterName) {
076        super(message, cause);
077        this.parameterName = parameterName;
078    }
079
080    /**
081     * Returns the name of the parameter with invalid cardinality.
082     *
083     * @return the name of the parameter with invalid cardinality.
084     */
085    public String getParameterName() {
086        return parameterName;
087    }
088}