1 /*
2  *    GeoAPI - Java interfaces for OGC/ISO standards
3  *    http://www.geoapi.org
4  *
5  *    Copyright (C) 2004-2011 Open Geospatial Consortium, Inc.
6  *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
7  *
8  *    Permission to use, copy, and modify this software and its documentation, with
9  *    or without modification, for any purpose and without fee or royalty is hereby
10  *    granted, provided that you include the following on ALL copies of the software
11  *    and documentation or portions thereof, including modifications, that you make:
12  *
13  *    1. The full text of this NOTICE in a location viewable to users of the
14  *       redistributed or derivative work.
15  *    2. Notice of any changes or modifications to the OGC files, including the
16  *       date changes were made.
17  *
18  *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
19  *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
20  *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
21  *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
22  *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
23  *
24  *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
25  *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
26  *
27  *    The name and trademarks of copyright holders may NOT be used in advertising or
28  *    publicity pertaining to the software without specific, written prior permission.
29  *    Title to copyright in this software and any associated documentation will at all
30  *    times remain with copyright holders.
31  */
32 package org.opengis.parameter;
33 
34 import java.util.List;
35 import org.opengis.metadata.Identifier;
36 import org.opengis.annotation.UML;
37 
38 import static org.opengis.annotation.Obligation.*;
39 import static org.opengis.annotation.Specification.*;
40 
41 
42 /**
43  * The definition of a group of related parameters used by an operation method.
44  *
45  * @departure rename
46  *   GeoAPI uses a name which contains the "<code>Descriptor</code>" word for consistency with other
47  *   libraries in Java (e.g. <code>ParameterListDescriptor</code> in Java Advanced Imaging).
48  *
49  * @author  Martin Desruisseaux (IRD)
50  * @author  Jody Garnett (Refractions Research)
51  * @version 3.0
52  * @since   2.0
53  *
54  * @see ParameterValueGroup
55  * @see ParameterDescriptor
56  *
57  * @navassoc - - - GeneralParameterDescriptor
58  */
59 @UML(identifier="CC_OperationParameterGroup", specification=ISO_19111)
60 public interface ParameterDescriptorGroup extends GeneralParameterDescriptor {
61     /**
62      * Creates a new instance of {@linkplain ParameterValueGroup parameter value group}
63      * initialized with the {@linkplain ParameterDescriptor#getDefaultValue default values}.
64      * The {@linkplain ParameterValueGroup#getDescriptor parameter value descriptor}
65      * for the created group will be {@code this} object.
66      *
67      * The number of {@link ParameterValue} objects included must be between the
68      * {@linkplain ParameterDescriptor#getMinimumOccurs minimum} and
69      * {@linkplain ParameterDescriptor#getMaximumOccurs maximum occurences} required.
70      * For example:
71      * <ul>
72      * <li>For {@link ParameterDescriptor} with cardinality 1:* a {@link ParameterValue} will
73      *     be included with the {@linkplain ParameterDescriptor#getDefaultValue default value}
74      *     (even if this default value is null).</li>
75      * <li>For {@link ParameterDescriptor} with cardinality 0:* no entry is required.
76      *     {@link ParameterValue} entries may be created only as needed.</li>
77      * </ul>
78      *
79      * @return A new parameter instance initialized to the default value.
80      *
81      * @departure extension
82      *   This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
83      *   factory method.
84      */
createValue()85     ParameterValueGroup createValue();
86 
87     /**
88      * Returns the parameters in this group.
89      *
90      * @return The descriptor of this group.
91      */
92     @UML(identifier="parameter", obligation=MANDATORY, specification=ISO_19111)
descriptors()93     List<GeneralParameterDescriptor> descriptors();
94 
95     /**
96      * Returns the parameter descriptor in this group for the specified
97      * {@linkplain Identifier#getCode identifier code}.
98      *
99      * @param  name The case insensitive {@linkplain Identifier#getCode identifier code} of the
100      *              parameter to search for.
101      * @return The parameter for the given identifier code.
102      * @throws ParameterNotFoundException if there is no parameter for the given identifier code.
103      *
104      * @departure easeOfUse
105      *   This method is not part of the ISO specification. It has been added in an attempt to make
106      *   this interface easier to use.
107      */
descriptor(String name)108     GeneralParameterDescriptor descriptor(String name) throws ParameterNotFoundException;
109 }
110