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.net.URI;
35 import javax.measure.unit.Unit;
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  * A parameter value used by an operation method. Most parameter values are numeric and can be
44  * obtained by the {@link #intValue()} or {@link #doubleValue()} methods. But other types of
45  * parameter values are possible and can be handled by the more generic {@link #getValue()} and
46  * {@link #setValue(Object)} methods. The type and constraints on parameter values are given
47  * by the {@linkplain #getDescriptor() descriptor}.
48  * <p>
49  * Instances of {@code ParameterValue} are created by the {@link ParameterDescriptor#createValue()}
50  * method.
51  *
52  * @param <T> The type of parameter values.
53  *
54  * @author  Martin Desruisseaux (IRD)
55  * @author  Jody Garnett (Refractions Research)
56  * @version 3.0
57  * @since   1.0
58  *
59  * @see ParameterDescriptor
60  * @see ParameterValueGroup
61  */
62 @UML(identifier="CC_ParameterValue", specification=ISO_19111)
63 public interface ParameterValue<T> extends GeneralParameterValue {
64     /**
65      * Returns the abstract definition of this parameter value.
66      *
67      * @return The abstract definition of this parameter value.
68      */
getDescriptor()69     ParameterDescriptor<T> getDescriptor();
70 
71     /**
72      * Returns the unit of measure of the {@linkplain #doubleValue() parameter value}.
73      * If the parameter value has no unit (for example because it is a {@link String} type),
74      * then this method returns {@code null}. Note that "no unit" doesn't means
75      * "dimensionless".
76      *
77      * @return The unit of measure of the parameter value.
78      *
79      * @see #doubleValue()
80      * @see #doubleValueList()
81      * @see #getValue()
82      */
getUnit()83     Unit<?> getUnit();
84 
85     /**
86      * Returns the numeric value of the coordinate operation parameter in the specified unit
87      * of measure. This convenience method applies unit conversion on the fly as needed.
88      *
89      * @param  unit The unit of measure for the value to be returned.
90      * @return The numeric value represented by this parameter after conversion to type
91      *         {@code double} and conversion to {@code unit}.
92      * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
93      * @throws InvalidParameterTypeException if the value is not a numeric type.
94      * @throws IllegalStateException if the value can not be returned for an other raison.
95      *
96      * @see #getUnit()
97      * @see #setValue(double,Unit)
98      * @see #doubleValueList(Unit)
99      */
doubleValue(Unit<?> unit)100     double doubleValue(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
101 
102     /**
103      * Returns the numeric value of the coordinate operation parameter with its
104      * associated {@linkplain #getUnit unit of measure}.
105      *
106      * @return The numeric value represented by this parameter after conversion to type {@code double}.
107      * @throws InvalidParameterTypeException if the value is not a numeric type.
108      * @throws IllegalStateException if the value can not be returned for an other raison.
109      * @unitof Measure
110      *
111      * @departure rename
112      *   Renamed the method from "<code>value</code>" to "<code>doubleValue</code>" for consistency
113      *   with <code>Number.doubleValue()</code> and the other "<code>*Value</code>" methods defined
114      *   in this interface.
115      *
116      * @see #getUnit()
117      * @see #setValue(double)
118      * @see #doubleValueList()
119      */
doubleValue()120     double doubleValue() throws IllegalStateException;
121 
122     /**
123      * Returns the positive integer value of an operation parameter, usually used
124      * for a count. An integer value does not have an associated unit of measure.
125      *
126      * @return The numeric value represented by this parameter after conversion to type {@code int}.
127      * @throws InvalidParameterTypeException if the value is not an integer type.
128      * @throws IllegalStateException if the value can not be returned for an other raison.
129      *
130      * @departure rename
131      *   Renamed the method from "<code>integerValue</code>" to "<code>intValue</code>" for
132      *   consistency with <code>Number.intValue()</code> and the <code>int</code> Java primitive type.
133      *
134      * @see #setValue(int)
135      * @see #intValueList()
136      */
137     @UML(identifier="integerValue", obligation=CONDITIONAL, specification=ISO_19111)
intValue()138     int intValue() throws IllegalStateException;
139 
140     /**
141      * Returns the boolean value of an operation parameter
142      * A boolean value does not have an associated unit of measure.
143      *
144      * @return The boolean value represented by this parameter.
145      * @throws InvalidParameterTypeException if the value is not a boolean type.
146      * @throws IllegalStateException if the value can not be returned for an other raison.
147      *
148      * @see #setValue(boolean)
149      */
150     @UML(identifier="booleanValue", obligation=CONDITIONAL, specification=ISO_19111)
booleanValue()151     boolean booleanValue() throws IllegalStateException;
152 
153     /**
154      * Returns the string value of an operation parameter.
155      * A string value does not have an associated unit of measure.
156      *
157      * @return The string value represented by this parameter.
158      * @throws InvalidParameterTypeException if the value is not a string.
159      * @throws IllegalStateException if the value can not be returned for an other raison.
160      *
161      * @see #getValue()
162      * @see #setValue(Object)
163      */
164     @UML(identifier="stringValue", obligation=CONDITIONAL, specification=ISO_19111)
stringValue()165     String stringValue() throws IllegalStateException;
166 
167     /**
168      * Returns an ordered sequence of numeric values in the specified unit of measure.
169      * This convenience method applies unit conversions on the fly as needed.
170      *
171      * @param  unit The unit of measure for the value to be returned.
172      * @return The sequence of values represented by this parameter after conversion to type
173      *         {@code double} and conversion to {@code unit}.
174      * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
175      * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
176      * @throws IllegalStateException if the value can not be returned for an other raison.
177      *
178      * @see #getUnit()
179      * @see #setValue(double[],Unit)
180      * @see #doubleValue(Unit)
181      */
doubleValueList(Unit<?> unit)182     double[] doubleValueList(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
183 
184     /**
185      * Returns an ordered sequence of two or more numeric values of an operation parameter
186      * list, where each value has the same associated {@linkplain Unit unit of measure}.
187      *
188      * @return The sequence of values represented by this parameter.
189      * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
190      * @throws IllegalStateException if the value can not be returned for an other raison.
191      * @unitof Measure
192      *
193      * @departure rename
194      *   Renamed the method from "<code>valueList</code>" to "<code>doubleValueList</code>" both for
195      *   consistency with <code>doubleValue()</code> and also because, like <code>doubleValue()</code>,
196      *   this method returns an array of <code>double</code> values rather than a <code>Measure</code>
197      *   object.
198      *
199      * @see #getUnit()
200      * @see #setValue(Object)
201      * @see #doubleValue()
202      */
203     @UML(identifier="valueList", obligation=CONDITIONAL, specification=ISO_19111)
doubleValueList()204     double[] doubleValueList() throws IllegalStateException;
205 
206     /**
207      * Returns an ordered sequence of two or more integer values of an operation parameter list,
208      * usually used for counts. These integer values do not have an associated unit of measure.
209      *
210      * @return The sequence of values represented by this parameter.
211      * @throws InvalidParameterTypeException if the value is not an array of {@code int}s.
212      * @throws IllegalStateException if the value can not be returned for an other raison.
213      *
214      * @departure rename
215      *   Renamed the attribute from "<code>integerValueList</code>" to "<code>intValueList</code>"
216      *   for consistency with <code>intValue()</code>.
217      *
218      * @see #setValue(Object)
219      * @see #intValue()
220      */
221     @UML(identifier="integerValueList", obligation=CONDITIONAL, specification=ISO_19111)
intValueList()222     int[] intValueList() throws IllegalStateException;
223 
224     /**
225      * Returns a reference to a file or a part of a file containing one or more parameter
226      * values. When referencing a part of a file, that file must contain multiple identified
227      * parts, such as an XML encoded document. Furthermore, the referenced file or part of a
228      * file can reference another part of the same or different files, as allowed in XML documents.
229      *
230      * @return The reference to a file containing parameter values.
231      * @throws InvalidParameterTypeException if the value is not a reference to a file or an URI.
232      * @throws IllegalStateException if the value can not be returned for an other raison.
233      *
234      * @see #getValue()
235      * @see #setValue(Object)
236      */
237     @UML(identifier="valueFile", obligation=CONDITIONAL, specification=ISO_19111)
valueFile()238     URI valueFile() throws IllegalStateException;
239 
240     /**
241      * Returns the parameter value as an object. The object type is typically a {@link Double},
242      * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]} or
243      * {@code int[]}. If no value has been set, then this method returns the
244      * {@linkplain ParameterDescriptor#getDefaultValue() default value} (which may be null).
245      *
246      * @return The parameter value as an object, or {@code null} if no value has been set and
247      *         there is no default value.
248      *
249      * @see #setValue(Object)
250      */
251     @UML(identifier="value", obligation=CONDITIONAL, specification=ISO_19111)
getValue()252     T getValue();
253 
254     /**
255      * Sets the parameter value as an array of floating point and their associated unit.
256      *
257      * @param  values The parameter values.
258      * @param  unit The unit for the specified value.
259      * @throws InvalidParameterValueException if the floating point type is inappropriate for this
260      *         parameter, or if the value is illegal for some other reason (for example a value out
261      *         of range).
262      */
setValue(double[] values, Unit<?> unit)263     void setValue(double[] values, Unit<?> unit) throws InvalidParameterValueException;
264 
265     /**
266      * Sets the parameter value as a floating point and its associated unit.
267      *
268      * @param  value The parameter value.
269      * @param  unit The unit for the specified value.
270      * @throws InvalidParameterValueException if the floating point type is inappropriate for this
271      *         parameter, or if the value is illegal for some other reason (for example a value out
272      *         of range).
273      *
274      * @see #setValue(double)
275      * @see #doubleValue(Unit)
276      */
setValue(double value, Unit<?> unit)277     void setValue(double value, Unit<?> unit) throws InvalidParameterValueException;
278 
279     /**
280      * Sets the parameter value as a floating point.
281      *
282      * @param  value The parameter value.
283      * @throws InvalidParameterValueException if the floating point type is inappropriate for this
284      *         parameter, or if the value is illegal for some other reason (for example a value out
285      *         of range).
286      *
287      * @see #setValue(double,Unit)
288      * @see #doubleValue()
289      */
setValue(double value)290     void setValue(double value) throws InvalidParameterValueException;
291 
292     /**
293      * Set the parameter value as an integer.
294      *
295      * @param  value The parameter value.
296      * @throws InvalidParameterValueException if the integer type is inappropriate for this parameter,
297      *         or if the value is illegal for some other reason (for example a value out of range).
298      *
299      * @see #intValue()
300      */
setValue(int value)301     void setValue(int value) throws InvalidParameterValueException;
302 
303     /**
304      * Set the parameter value as a boolean.
305      *
306      * @param  value The parameter value.
307      * @throws InvalidParameterValueException if the boolean type is inappropriate for this parameter.
308      *
309      * @see #booleanValue()
310      */
setValue(boolean value)311     void setValue(boolean value) throws InvalidParameterValueException;
312 
313     /**
314      * Set the parameter value as an object. The object type is typically a {@link Double},
315      * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]}
316      * or {@code int[]}.
317      * <p>
318      * The argument is not restricted to the parameterized type {@code T} because the type
319      * is typically unknown (as in <code>group.{@linkplain ParameterValueGroup#parameter
320      * parameter}("<var>name</var>").setValue(<var>value</var>)</code>) and
321      * because some implementations may choose to convert a wider range of types.
322      *
323      * @param  value The parameter value.
324      * @throws InvalidParameterValueException if the type of {@code value} is inappropriate
325      *         for this parameter, or if the value is illegal for some other reason (for example
326      *         the value is numeric and out of range).
327      *
328      * @see #getValue()
329      */
setValue(Object value)330     void setValue(Object value) throws InvalidParameterValueException;
331 
332     /**
333      * Returns a copy of this parameter value.
334      *
335      * @return A copy of this parameter value.
336      */
clone()337     ParameterValue<T> clone();
338 }
339