001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2023 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
020import java.util.List;
021import org.opengis.metadata.Identifier;
022import org.opengis.annotation.UML;
023
024import static org.opengis.annotation.Obligation.*;
025import static org.opengis.annotation.Specification.*;
026
027
028/**
029 * The definition of a group of related parameters used by an operation method.
030 *
031 * @departure rename
032 *   GeoAPI uses a name which contains the "{@code Descriptor}" word for consistency with other
033 *   libraries in Java (e.g. {@code ParameterListDescriptor} in Java Advanced Imaging).
034 *
035 * @author  OGC Topic 2 (for abstract model and documentation)
036 * @author  Martin Desruisseaux (IRD, Geomatys)
037 * @author  Jody Garnett (Refractions Research)
038 * @version 3.1
039 * @since   2.0
040 *
041 * @see ParameterValueGroup
042 * @see ParameterDescriptor
043 */
044@UML(identifier="OperationParameterGroup", specification=ISO_19111)
045public interface ParameterDescriptorGroup extends GeneralParameterDescriptor {
046    /**
047     * Returns the parameters in this group.
048     *
049     * @return the parameter descriptors in this group.
050     */
051    @UML(identifier="parameter", obligation=MANDATORY, specification=ISO_19111)
052    List<GeneralParameterDescriptor> descriptors();
053
054    /**
055     * Returns the parameter descriptor in this group for the specified identifier code.
056     *
057     * @param  name  the case insensitive identifier code of the parameter to search for.
058     * @return the parameter for the given identifier code.
059     * @throws ParameterNotFoundException if there is no parameter for the given identifier code.
060     *
061     * @see Identifier#getCode()
062     *
063     * @departure easeOfUse
064     *   This method is not part of the ISO specification.
065     *   It has been added in an attempt to make this interface easier to use.
066     */
067    GeneralParameterDescriptor descriptor(String name) throws ParameterNotFoundException;
068
069    /**
070     * Creates a new instance of parameter value group initialized with the default values.
071     * While not a requirement, the {@linkplain ParameterValueGroup#getDescriptor() parameter
072     * value descriptor} for the created group will typically be {@code this} descriptor instance.
073     *
074     * <p>The number of {@link ParameterValue} objects included must be between the
075     * {@linkplain ParameterDescriptor#getMinimumOccurs() minimum} and
076     * {@linkplain ParameterDescriptor#getMaximumOccurs() maximum occurrences} required.
077     * For example:</p>
078     *
079     * <ul>
080     *   <li>For {@link ParameterDescriptor} with multiplicity 1:* a {@code ParameterValue} will
081     *       be included with the default value (even if this default value is null).</li>
082     *   <li>For {@code ParameterDescriptor} with multiplicity 0:* no entry is required.
083     *       {@code ParameterValue} entries may be created only as needed.</li>
084     * </ul>
085     *
086     * @return a new parameter instance initialized to the default value.
087     *
088     * @see ParameterDescriptor#getDefaultValue()
089     *
090     * @departure extension
091     *   This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
092     *   factory method.
093     */
094    @Override
095    ParameterValueGroup createValue();
096}