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
020import java.util.Optional;
021import org.opengis.annotation.UML;
022import org.opengis.annotation.Classifier;
023import org.opengis.annotation.Stereotype;
024import org.opengis.annotation.Specification;
025import org.opengis.util.MemberName;                     // For javadoc
026import org.opengis.util.InternationalString;
027import org.opengis.metadata.Identifier;
028import org.opengis.referencing.IdentifiedObject;
029import org.opengis.referencing.ReferenceIdentifier;
030
031import static org.opengis.annotation.Obligation.*;
032import static org.opengis.annotation.Specification.*;
033
034
035/**
036 * Abstract definition of a parameter or group of parameters used by an operation method.
037 * This interface combines information provided by Referencing by Coordinates (ISO 19111),
038 * Service Metadata (ISO 19115), Data Quality (ISO 19157), filter encoding (ISO 19143)
039 * and Web Processing Services (WPS) standards.
040 * The main information are:
041 *
042 * <table class="ogc">
043 *   <caption>Main parameter properties and their mapping to other standards</caption>
044 *   <tr>
045 *     <th>Getter method</th>
046 *     <th class="sep">ISO 19111</th>
047 *     <th class="sep">ISO 19115</th>
048 *     <th class="sep">ISO 19157</th>
049 *     <th class="sep">ISO 19143</th>
050 *     <th class="sep">WPS</th>
051 *     <th class="sep">Remarks</th>
052 *   </tr><tr>
053 *     <td>{@link #getName()}</td>
054 *     <td class="sep">{@code name}</td>
055 *     <td class="sep">{@code name}</td>
056 *     <td class="sep">{@code name}</td>
057 *     <td class="sep">{@code name}</td>
058 *     <td class="sep">{@code Identifier}</td>
059 *     <td class="sep">See {@linkplain #getName() method javadoc} for {@code MemberName} ↔ {@code Identifier} mapping.</td>
060 *   </tr><tr>
061 *     <td>{@link #getAlias() getAlias()}</td>
062 *     <td class="sep">{@code alias}</td>
063 *     <td class="sep"></td>
064 *     <td class="sep"></td>
065 *     <td class="sep"></td>
066 *     <td class="sep"></td>
067 *     <td class="sep"></td>
068 *   </tr><tr>
069 *     <td>{@link #getIdentifiers() getIdentifiers()}</td>
070 *     <td class="sep">{@code identifier}</td>
071 *     <td class="sep"></td>
072 *     <td class="sep"></td>
073 *     <td class="sep"></td>
074 *     <td class="sep"></td>
075 *     <td class="sep">Optional, contrarily to name which is mandatory.</td>
076 *   </tr><tr>
077 *     <td><code>{@linkplain #getName()}.{@linkplain Identifier#getDescription() getDescription()}</code></td>
078 *     <td class="sep"></td>
079 *     <td class="sep"></td>
080 *     <td class="sep">{@code definition}</td>
081 *     <td class="sep"></td>
082 *     <td class="sep"></td>
083 *     <td class="sep">Should be a short sentence.</td>
084 *   </tr>
085 *   <!-- "Title" (WPS) equivalent to "designation" (Feature), but not yet provided. -->
086 *   <tr>
087 *     <td>{@link #getDescription()}</td>
088 *     <td class="sep"></td>
089 *     <td class="sep">{@code description}</td>
090 *     <td class="sep">{@code description}</td>
091 *     <td class="sep"></td>
092 *     <td class="sep">{@code Abstract}</td>
093 *     <td class="sep">Explanation more detailed than the definition.</td>
094 *   </tr><tr>
095 *     <td>{@link #getRemarks() getRemarks()}</td>
096 *     <td class="sep">{@code remarks}</td>
097 *     <td class="sep"></td>
098 *     <td class="sep"></td>
099 *     <td class="sep"></td>
100 *     <td class="sep"></td>
101 *     <td class="sep"></td>
102 *   </tr><tr>
103 *     <td>{@link ParameterDescriptor#getValueType() getValueType()}</td>
104 *     <td class="sep"></td>
105 *     <td class="sep"></td>
106 *     <td class="sep">{@code valueType}</td>
107 *     <td class="sep">{@code type}</td>
108 *     <td class="sep"></td>
109 *     <td class="sep">Name that describes the type of parameter values.</td>
110 *   </tr><tr>
111 *     <td>{@link #getDirection()}</td>
112 *     <td class="sep"></td>
113 *     <td class="sep">{@code direction}</td>
114 *     <td class="sep"></td>
115 *     <td class="sep"></td>
116 *     <td class="sep"></td>
117 *     <td class="sep">Tells if the parameter is a WPS {@code Input} or {@code Output} structure.</td>
118 *   </tr><tr>
119 *     <td>{@link #getMinimumOccurs()}</td>
120 *     <td class="sep">{@code minimumOccurs}</td>
121 *     <td class="sep">{@code optionality}</td>
122 *     <td class="sep"></td>
123 *     <td class="sep"></td>
124 *     <td class="sep">{@code MinOccurs}</td>
125 *     <td class="sep">{@code optionality   = (minimumOccurs > 0)}</td>
126 *   </tr><tr>
127 *     <td>{@link #getMaximumOccurs()}</td>
128 *     <td class="sep">{@code maximumOccurs}</td>
129 *     <td class="sep">{@code repeatability}</td>
130 *     <td class="sep"></td>
131 *     <td class="sep"></td>
132 *     <td class="sep">{@code MaxOccurs}</td>
133 *     <td class="sep">{@code repeatability = (maximumOccurs > 1)}</td>
134 *   </tr>
135 * </table>
136 *
137 * @departure rename
138 *   GeoAPI uses a name which contains the "{@code Descriptor}" word for consistency with other
139 *   libraries in Java (e.g. {@code ParameterListDescriptor} in Java Advanced Imaging).
140 *
141 * @author  OGC Topic 2 (for abstract model and documentation)
142 * @author  Martin Desruisseaux (IRD, Geomatys)
143 * @author  Jody Garnett (Refractions Research)
144 * @version 3.1
145 * @since   2.0
146 *
147 * @see GeneralParameterValue
148 */
149@Classifier(Stereotype.ABSTRACT)
150@UML(identifier="GeneralOperationParameter", specification=ISO_19111)
151public interface GeneralParameterDescriptor extends IdentifiedObject {
152    /**
153     * Returns the name, as used by the service or operation for this parameter.
154     *
155     * <h4>Unified parameter API</h4>
156     * The metadata standard ({@linkplain Specification#ISO_19115 ISO 19115}) defines the
157     * {@code name} property as of type {@link MemberName} instead of {@code Identifier},
158     * while the data quality standard ({@linkplain Specification#ISO_19157 ISO 19157})
159     * defines equivalent properties directly in its parameter class.
160     * The following table provides the suggested mapping from ISO models to parameter descriptor.
161     *
162     * <table class="ogc">
163     *   <caption>Mapping from ISO abstract models to unified parameter API</caption>
164     *   <tr>
165     *     <th>Name used by ISO 19115</th>
166     *     <th>Property in ISO 19157</th>
167     *     <th>Property in unified parameter API</th>
168     *   </tr><tr>
169     *     <td><code>{@linkplain MemberName#scope() MemberName.scope()}.name().toString()</code></td>
170     *     <td></td>
171     *     <td>{@link Identifier#getCodeSpace()}</td>
172     *   </tr><tr>
173     *     <td>{@link MemberName#toString()}</td>
174     *     <td>{@code DQM_Parameter.name}</td>
175     *     <td>{@link Identifier#getCode()}</td>
176     *   </tr><tr>
177     *     <td>{@link MemberName#getAttributeType()}</td>
178     *     <td>{@code DQM_Parameter.valueType}</td>
179     *     <td>{@link ParameterDescriptor#getValueType()}</td>
180     *   </tr><tr>
181     *     <td></td>
182     *     <td>{@code DQM_Parameter.definition}</td>
183     *     <td>{@link Identifier#getDescription()}</td>
184     *   </tr>
185     * </table>
186     *
187     * <div class="warning"><b>Upcoming API change — generalization</b><br>
188     * As of ISO 19115:2014, {@code ReferenceIdentifier} has been merged with its {@link Identifier} parent interface.
189     * Consequently this method return type will be changed to {@code Identifier} in GeoAPI 4.0.
190     * </div>
191     *
192     * @return the name, as used by the service or operation for this parameter.
193     */
194    @Override
195    @UML(identifier="name", obligation=MANDATORY, specification=ISO_19111)
196    ReferenceIdentifier getName();
197
198    /**
199     * Returns whether the parameter is an input to the service, an output or both.
200     * This information applies mostly to <i>service metadata</i>.
201     * The default value is {@link ParameterDirection#IN}.
202     *
203     * @return indication if the parameter is an input to the service, an output or both.
204     *
205     * @since 3.1
206     */
207    @UML(identifier="SV_Parameter.direction", obligation=MANDATORY, specification=ISO_19115)
208    default ParameterDirection getDirection() {
209        return ParameterDirection.IN;
210    }
211
212    /**
213     * Returns a narrative explanation of the role of this parameter.
214     *
215     * @return a narrative explanation of the role of this parameter.
216     *
217     * @see #getName()
218     * @see #getRemarks()
219     *
220     * @since 3.1
221     */
222    @UML(identifier="SV_Parameter.description", obligation=OPTIONAL, specification=ISO_19115)
223    default Optional<InternationalString> getDescription() {
224        return Optional.empty();
225    }
226
227    /**
228     * Returns the minimum number of times that values for this parameter or parameter group are required.
229     * The default value is 1. A value of 0 means an optional parameter.
230     *
231     * @return the minimum occurrence.
232     *
233     * @see #getMaximumOccurs()
234     */
235    @UML(identifier="OperationParameterGroup.minimumOccurs", obligation=OPTIONAL, specification=ISO_19111)
236    default int getMinimumOccurs() {
237        return 1;
238    }
239
240    /**
241     * Returns the maximum number of times that values for this parameter or parameter group can be included.
242     * The default value is 1. A value greater than 1 means a repeatable parameter.
243     *
244     * <p>If this parameter is an instance of {@link ParameterDescriptor} used for the description of
245     * {@link org.opengis.referencing.operation.OperationMethod} parameters, then the value shall be 1.
246     * If this parameter is an instance of {@link ParameterDescriptorGroup}, or if this parameter is used
247     * {@linkplain org.opengis.metadata.identification.OperationMetadata#getParameters() in the context of
248     * service metadata}, then {@code maximumOccurs} value may vary.</p>
249     *
250     * @departure generalization
251     *   Moved up (in the interface hierarchy) the {@code maximumOccurs} method from
252     *   {@code ParameterDescriptorGroup} into this super-interface, for parallelism
253     *   with the {@code minimumOccurs} method.
254     *
255     * @return the maximum occurrence, or {@link Integer#MAX_VALUE} if there is no limit.
256     *
257     * @see #getMinimumOccurs()
258     */
259    @UML(identifier="OperationParameterGroup.maximumOccurs", obligation=OPTIONAL, specification=ISO_19111)
260    default int getMaximumOccurs() {
261        return 1;
262    }
263
264    /**
265     * Creates a new instance of {@linkplain GeneralParameterValue parameter value or group}
266     * initialized with the {@linkplain ParameterDescriptor#getDefaultValue default value(s)}.
267     * The {@linkplain GeneralParameterValue#getDescriptor parameter value descriptor} for
268     * the created parameter value(s) will be {@code this} object.
269     *
270     * @return a new parameter initialized to its default value.
271     *
272     * @departure extension
273     *   This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
274     *   factory method.
275     */
276    GeneralParameterValue createValue();
277}