001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.parameter;
033
034 import java.net.URI;
035 import javax.measure.unit.Unit;
036 import org.opengis.annotation.UML;
037
038 import static org.opengis.annotation.Obligation.*;
039 import static org.opengis.annotation.Specification.*;
040
041
042 /**
043 * A parameter value used by an operation method. Most parameter values are numeric and can be
044 * obtained by the {@link #intValue()} or {@link #doubleValue()} methods. But other types of
045 * parameter values are possible and can be handled by the more generic {@link #getValue()} and
046 * {@link #setValue(Object)} methods. The type and constraints on parameter values are given
047 * by the {@linkplain #getDescriptor() descriptor}.
048 * <p>
049 * Instances of {@code ParameterValue} are created by the {@link ParameterDescriptor#createValue()}
050 * method.
051 *
052 * @param <T> The type of parameter values.
053 *
054 * @author Martin Desruisseaux (IRD)
055 * @author Jody Garnett (Refractions Research)
056 * @version 3.0
057 * @since 1.0
058 *
059 * @see ParameterDescriptor
060 * @see ParameterValueGroup
061 */
062 @UML(identifier="CC_ParameterValue", specification=ISO_19111)
063 public interface ParameterValue<T> extends GeneralParameterValue {
064 /**
065 * Returns the abstract definition of this parameter value.
066 *
067 * @return The abstract definition of this parameter value.
068 */
069 @Override
070 ParameterDescriptor<T> getDescriptor();
071
072 /**
073 * Returns the unit of measure of the {@linkplain #doubleValue() parameter value}.
074 * If the parameter value has no unit (for example because it is a {@link String} type),
075 * then this method returns {@code null}. Note that "no unit" doesn't means
076 * "dimensionless".
077 *
078 * @return The unit of measure of the parameter value.
079 *
080 * @see #doubleValue()
081 * @see #doubleValueList()
082 * @see #getValue()
083 */
084 Unit<?> getUnit();
085
086 /**
087 * Returns the numeric value of the operation parameter in the specified unit
088 * of measure. This convenience method applies unit conversion on the fly as needed.
089 *
090 * @param unit The unit of measure for the value to be returned.
091 * @return The numeric value represented by this parameter after conversion to type
092 * {@code double} and conversion to {@code unit}.
093 * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
094 * @throws InvalidParameterTypeException if the value is not a numeric type.
095 * @throws IllegalStateException if the value can not be returned for an other raison.
096 *
097 * @see #getUnit()
098 * @see #setValue(double,Unit)
099 * @see #doubleValueList(Unit)
100 */
101 double doubleValue(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
102
103 /**
104 * Returns the numeric value represented by this operation parameter.
105 * The units of measurement are specified by {@link #getUnit()}.
106 *
107 * @return The numeric value represented by this parameter after conversion to type {@code double}.
108 * @throws InvalidParameterTypeException if the value is not a numeric type.
109 * @throws IllegalStateException if the value can not be returned for an other raison.
110 * @unitof Measure
111 *
112 * @departure rename
113 * Renamed the method from "<code>value</code>" to "<code>doubleValue</code>" for consistency
114 * with <code>Number.doubleValue()</code> and the other "<code>*Value</code>" methods defined
115 * in this interface.
116 *
117 * @see #getUnit()
118 * @see #setValue(double)
119 * @see #doubleValueList()
120 */
121 double doubleValue() throws IllegalStateException;
122
123 /**
124 * Returns the positive integer value of an operation parameter, usually used
125 * for a count. An integer value does not have an associated unit of measure.
126 *
127 * @return The numeric value represented by this parameter after conversion to type {@code int}.
128 * @throws InvalidParameterTypeException if the value is not an integer type.
129 * @throws IllegalStateException if the value can not be returned for an other raison.
130 *
131 * @departure rename
132 * Renamed the method from "<code>integerValue</code>" to "<code>intValue</code>" for
133 * consistency with <code>Number.intValue()</code> and the <code>int</code> Java primitive type.
134 *
135 * @see #setValue(int)
136 * @see #intValueList()
137 */
138 @UML(identifier="integerValue", obligation=CONDITIONAL, specification=ISO_19111)
139 int intValue() throws IllegalStateException;
140
141 /**
142 * Returns the boolean value of an operation parameter.
143 * A boolean value does not have an associated unit of measure.
144 *
145 * @return The boolean value represented by this parameter.
146 * @throws InvalidParameterTypeException if the value is not a boolean type.
147 * @throws IllegalStateException if the value can not be returned for an other raison.
148 *
149 * @see #setValue(boolean)
150 */
151 @UML(identifier="booleanValue", obligation=CONDITIONAL, specification=ISO_19111)
152 boolean booleanValue() throws IllegalStateException;
153
154 /**
155 * Returns the string value of an operation parameter.
156 * A string value does not have an associated unit of measure.
157 *
158 * @return The string value represented by this parameter.
159 * @throws InvalidParameterTypeException if the value is not a string.
160 * @throws IllegalStateException if the value can not be returned for an other raison.
161 *
162 * @see #getValue()
163 * @see #setValue(Object)
164 */
165 @UML(identifier="stringValue", obligation=CONDITIONAL, specification=ISO_19111)
166 String stringValue() throws IllegalStateException;
167
168 /**
169 * Returns an ordered sequence of numeric values in the specified unit of measure.
170 * This convenience method applies unit conversions on the fly as needed.
171 *
172 * @param unit The unit of measure for the value to be returned.
173 * @return The sequence of values represented by this parameter after conversion to type
174 * {@code double} and conversion to {@code unit}.
175 * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
176 * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
177 * @throws IllegalStateException if the value can not be returned for an other raison.
178 *
179 * @see #getUnit()
180 * @see #setValue(double[],Unit)
181 * @see #doubleValue(Unit)
182 */
183 double[] doubleValueList(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
184
185 /**
186 * Returns an ordered sequence of two or more numeric values of an operation parameter
187 * list, where each value has the same associated {@linkplain Unit unit of measure}.
188 *
189 * @return The sequence of values represented by this parameter.
190 * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
191 * @throws IllegalStateException if the value can not be returned for an other raison.
192 * @unitof Measure
193 *
194 * @departure rename
195 * Renamed the method from "<code>valueList</code>" to "<code>doubleValueList</code>" both for
196 * consistency with <code>doubleValue()</code> and also because, like <code>doubleValue()</code>,
197 * this method returns an array of <code>double</code> values rather than a <code>Measure</code>
198 * object.
199 *
200 * @see #getUnit()
201 * @see #setValue(Object)
202 * @see #doubleValue()
203 */
204 @UML(identifier="valueList", obligation=CONDITIONAL, specification=ISO_19111)
205 double[] doubleValueList() throws IllegalStateException;
206
207 /**
208 * Returns an ordered sequence of two or more integer values of an operation parameter list,
209 * usually used for counts. These integer values do not have an associated unit of measure.
210 *
211 * @return The sequence of values represented by this parameter.
212 * @throws InvalidParameterTypeException if the value is not an array of {@code int}s.
213 * @throws IllegalStateException if the value can not be returned for an other raison.
214 *
215 * @departure rename
216 * Renamed the attribute from "<code>integerValueList</code>" to "<code>intValueList</code>"
217 * for consistency with <code>intValue()</code>.
218 *
219 * @see #setValue(Object)
220 * @see #intValue()
221 */
222 @UML(identifier="integerValueList", obligation=CONDITIONAL, specification=ISO_19111)
223 int[] intValueList() throws IllegalStateException;
224
225 /**
226 * Returns a reference to a file or a part of a file containing one or more parameter
227 * values. When referencing a part of a file, that file must contain multiple identified
228 * parts, such as an XML encoded document. Furthermore, the referenced file or part of a
229 * file can reference another part of the same or different files, as allowed in XML documents.
230 *
231 * @return The reference to a file containing parameter values.
232 * @throws InvalidParameterTypeException if the value is not a reference to a file or an URI.
233 * @throws IllegalStateException if the value can not be returned for an other raison.
234 *
235 * @see #getValue()
236 * @see #setValue(Object)
237 */
238 @UML(identifier="valueFile", obligation=CONDITIONAL, specification=ISO_19111)
239 URI valueFile() throws IllegalStateException;
240
241 /**
242 * Returns the parameter value as an object. The object type is typically a {@link Double},
243 * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]} or
244 * {@code int[]}. If no value has been set, then this method returns the
245 * {@linkplain ParameterDescriptor#getDefaultValue() default value} (which may be null).
246 *
247 * @return The parameter value as an object, or {@code null} if no value has been set and
248 * there is no default value.
249 *
250 * @see #setValue(Object)
251 */
252 @UML(identifier="value", obligation=CONDITIONAL, specification=ISO_19111)
253 T getValue();
254
255 /**
256 * Sets the parameter value as an array of floating point and their associated unit.
257 *
258 * @param values The parameter values.
259 * @param unit The unit for the specified value.
260 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
261 * parameter, or if the value is illegal for some other reason (for example a value out
262 * of range).
263 */
264 void setValue(double[] values, Unit<?> unit) throws InvalidParameterValueException;
265
266 /**
267 * Sets the parameter value as a floating point and its associated unit.
268 *
269 * @param value The parameter value.
270 * @param unit The unit for the specified values.
271 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
272 * parameter, or if the value is illegal for some other reason (for example a value out
273 * of range).
274 *
275 * @see #setValue(double)
276 * @see #doubleValue(Unit)
277 */
278 void setValue(double value, Unit<?> unit) throws InvalidParameterValueException;
279
280 /**
281 * Sets the parameter value as a floating point.
282 *
283 * @param value The parameter value.
284 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
285 * parameter, or if the value is illegal for some other reason (for example a value out
286 * of range).
287 *
288 * @see #setValue(double,Unit)
289 * @see #doubleValue()
290 */
291 void setValue(double value) throws InvalidParameterValueException;
292
293 /**
294 * Sets the parameter value as an integer.
295 *
296 * @param value The parameter value.
297 * @throws InvalidParameterValueException if the integer type is inappropriate for this parameter,
298 * or if the value is illegal for some other reason (for example a value out of range).
299 *
300 * @see #intValue()
301 */
302 void setValue(int value) throws InvalidParameterValueException;
303
304 /**
305 * Sets the parameter value as a boolean.
306 *
307 * @param value The parameter value.
308 * @throws InvalidParameterValueException if the boolean type is inappropriate for this parameter.
309 *
310 * @see #booleanValue()
311 */
312 void setValue(boolean value) throws InvalidParameterValueException;
313
314 /**
315 * Sets the parameter value as an object. The object type is typically a {@link Double},
316 * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]}
317 * or {@code int[]}.
318 * <p>
319 * The argument is not restricted to the parameterized type {@code T} because the type
320 * is typically unknown (as in <code>group.{@linkplain ParameterValueGroup#parameter
321 * parameter}("<var>name</var>").setValue(<var>value</var>)</code>) and
322 * because some implementations may choose to convert a wider range of types.
323 *
324 * @param value The parameter value.
325 * @throws InvalidParameterValueException if the type of {@code value} is inappropriate
326 * for this parameter, or if the value is illegal for some other reason (for example
327 * the value is numeric and out of range).
328 *
329 * @see #getValue()
330 */
331 void setValue(Object value) throws InvalidParameterValueException;
332
333 /**
334 * Returns a copy of this parameter value.
335 *
336 * @return A copy of this parameter value.
337 */
338 @Override
339 ParameterValue<T> clone();
340 }