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.Set;
35 import javax.measure.unit.Unit;
36 import org.opengis.util.CodeList;
37 import org.opengis.annotation.UML;
38 
39 import static org.opengis.annotation.Obligation.*;
40 import static org.opengis.annotation.Specification.*;
41 
42 
43 /**
44  * The definition of a parameter used by an operation method. Most parameter values are
45  * numeric, but other types of parameter values are possible.
46  *
47  * @param <T> The type of parameter values.
48  *
49  * @departure rename
50  *   GeoAPI uses a name which contains the "<code>Descriptor</code>" word for consistency with other
51  *   libraries in Java (e.g. <code>ParameterListDescriptor</code> in Java Advanced Imaging).
52  *
53  * @author  Martin Desruisseaux (IRD)
54  * @author  Jody Garnett (Refractions Research)
55  * @version 3.0
56  * @since   2.0
57  *
58  * @see ParameterValue
59  * @see ParameterDescriptorGroup
60  */
61 @UML(identifier="CC_OperationParameter", specification=ISO_19111)
62 public interface ParameterDescriptor<T> extends GeneralParameterDescriptor {
63     /**
64      * Creates a new instance of {@linkplain ParameterValue parameter value} initialized with the
65      * {@linkplain #getDefaultValue default value}. The {@linkplain ParameterValue#getDescriptor
66      * parameter value descriptor} for the created parameter value will be {@code this} object.
67      *
68      * @departure extension
69      *   This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
70      *   factory method.
71      */
createValue()72     ParameterValue<T> createValue();
73 
74     /**
75      * Returns the class that describe the type of the parameter.
76      *
77      * @return The type of parameter values.
78      */
79     @UML(identifier="GC_ParameterInfo.type", obligation=MANDATORY, specification=ISO_19111)
getValueClass()80     Class<T> getValueClass();
81 
82     /**
83      * Returns the set of allowed values when these are restricted to some finite set or returns
84      * {@code null} otherwise. The returned set usually contains {@linkplain CodeList code list}
85      * or enumeration elements.
86      *
87      * @return A finite set of valid values (usually from a {@linkplain CodeList code list}),
88      *         or {@code null} if it doesn't apply.
89      *
90      * @departure extension
91      *   This method is not part of ISO specification. It is provided as a complement of information.
92      */
getValidValues()93     Set<T> getValidValues();
94 
95     /**
96      * Returns the default value for the parameter. The return type can be any type
97      * including a {@link Number} or a {@link String}. If there is no default value,
98      * then this method returns {@code null}.
99      *
100      * @return The default value, or {@code null} in none.
101      */
102     @UML(identifier="GC_ParameterInfo.defaultValue", obligation=OPTIONAL, specification=ISO_19111)
getDefaultValue()103     T getDefaultValue();
104 
105     /**
106      * Returns the minimum parameter value.
107      *
108      * If there is no minimum value, or if minimum
109      * value is inappropriate for the {@linkplain #getValueClass parameter type}, then
110      * this method returns {@code null}.
111      * <p>
112      * When the getValueClass() is an array or Collection getMinimumValue
113      * may be used to constrain the contained elements.
114      * </p>
115      * @return The minimum parameter value (often an instance of {@link Double}), or {@code null}.
116      */
117     @UML(identifier="GC_ParameterInfo.minimumValue", obligation=OPTIONAL, specification=ISO_19111)
getMinimumValue()118     Comparable<T> getMinimumValue();
119 
120     /**
121      * Returns the maximum parameter value.
122      *
123      * If there is no maximum value, or if maximum
124      * value is inappropriate for the {@linkplain #getValueClass parameter type}, then
125      * this method returns {@code null}.
126      * <p>
127      * When the getValueClass() is an array or Collection getMaximumValue
128      * may be used to constraint the contained elements.
129      *
130      * @return The minimum parameter value (often an instance of {@link Double}), or {@code null}.
131      */
132     @UML(identifier="GC_ParameterInfo.maximumValue", obligation=OPTIONAL, specification=ISO_19111)
getMaximumValue()133     Comparable<T> getMaximumValue();
134 
135     /**
136      * Returns the unit for
137      * {@linkplain #getDefaultValue default},
138      * {@linkplain #getMinimumValue minimum} and
139      * {@linkplain #getMaximumValue maximum} values.
140      * This attribute apply only if the values is of numeric type (usually an instance
141      * of {@link Double}).
142      *
143      * @return The unit for numeric value, or {@code null} if it doesn't apply to the value type.
144      *
145      * @departure extension
146      *   This method is not part of ISO specification. It is provided as a complement of information.
147      */
getUnit()148     Unit<?> getUnit();
149 }
150