001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2013 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 import org.opengis.annotation.Classifier;
038 import org.opengis.annotation.Stereotype;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * A parameter value used by an operation method. Most parameter values are numeric and can be
046 * obtained by the {@link #intValue()} or {@link #doubleValue()} methods. But other types of
047 * parameter values are possible and can be handled by the more generic {@link #getValue()} and
048 * {@link #setValue(Object)} methods. The type and constraints on parameter values are given
049 * by the {@linkplain #getDescriptor() descriptor}.
050 *
051 * <p>Instances of {@code ParameterValue} are created by the {@link ParameterDescriptor#createValue()}
052 * method.</p>
053 *
054 * @param <T> The type of parameter values.
055 *
056 * @author Martin Desruisseaux (IRD)
057 * @author Jody Garnett (Refractions Research)
058 * @version 3.1
059 * @since 1.0
060 *
061 * @see ParameterDescriptor
062 * @see ParameterValueGroup
063 */
064 @Classifier(Stereotype.UNION)
065 @UML(identifier="CC_ParameterValue", specification=ISO_19111)
066 public interface ParameterValue<T> extends GeneralParameterValue {
067 /**
068 * Returns the abstract definition of this parameter value.
069 *
070 * @return The abstract definition of this parameter value.
071 */
072 @Override
073 ParameterDescriptor<T> getDescriptor();
074
075 /**
076 * Returns the unit of measure of the {@linkplain #doubleValue() parameter value}.
077 * If the parameter value has no unit (for example because it is a {@link String} type),
078 * then this method returns {@code null}. Note that "no unit" doesn't means
079 * "dimensionless".
080 *
081 * @return The unit of measure of the parameter value.
082 *
083 * @see #doubleValue()
084 * @see #doubleValueList()
085 * @see #getValue()
086 */
087 Unit<?> getUnit();
088
089 /**
090 * Returns the numeric value of the operation parameter in the specified unit
091 * of measure. This convenience method applies unit conversion on the fly as needed.
092 *
093 * @param unit The unit of measure for the value to be returned.
094 * @return The numeric value represented by this parameter after conversion to type
095 * {@code double} and conversion to {@code unit}.
096 * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
097 * @throws InvalidParameterTypeException if the value is not a numeric type.
098 * @throws IllegalStateException if the value can not be returned for an other raison.
099 *
100 * @see #getUnit()
101 * @see #setValue(double,Unit)
102 * @see #doubleValueList(Unit)
103 */
104 double doubleValue(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
105
106 /**
107 * Returns the numeric value represented by this operation parameter.
108 * The units of measurement are specified by {@link #getUnit()}.
109 *
110 * @return The numeric value represented by this parameter after conversion to type {@code double}.
111 * @throws InvalidParameterTypeException if the value is not a numeric type.
112 * @throws IllegalStateException if the value can not be returned for an other raison.
113 * @unitof Measure
114 *
115 * @departure rename
116 * Renamed the method from "<code>value</code>" to "<code>doubleValue</code>" for consistency
117 * with <code>Number.doubleValue()</code> and the other "<code>*Value</code>" methods defined
118 * in this interface.
119 *
120 * @see #getUnit()
121 * @see #setValue(double)
122 * @see #doubleValueList()
123 */
124 double doubleValue() throws IllegalStateException;
125
126 /**
127 * Returns the positive integer value of an operation parameter, usually used
128 * for a count. An integer value does not have an associated unit of measure.
129 *
130 * @return The numeric value represented by this parameter after conversion to type {@code int}.
131 * @throws InvalidParameterTypeException if the value is not an integer type.
132 * @throws IllegalStateException if the value can not be returned for an other raison.
133 *
134 * @departure rename
135 * Renamed the method from "<code>integerValue</code>" to "<code>intValue</code>" for
136 * consistency with <code>Number.intValue()</code> and the <code>int</code> Java primitive type.
137 *
138 * @see #setValue(int)
139 * @see #intValueList()
140 */
141 @UML(identifier="integerValue", obligation=CONDITIONAL, specification=ISO_19111)
142 int intValue() throws IllegalStateException;
143
144 /**
145 * Returns the boolean value of an operation parameter.
146 * A boolean value does not have an associated unit of measure.
147 *
148 * @return The boolean value represented by this parameter.
149 * @throws InvalidParameterTypeException if the value is not a boolean type.
150 * @throws IllegalStateException if the value can not be returned for an other raison.
151 *
152 * @see #setValue(boolean)
153 */
154 @UML(identifier="booleanValue", obligation=CONDITIONAL, specification=ISO_19111)
155 boolean booleanValue() throws IllegalStateException;
156
157 /**
158 * Returns the string value of an operation parameter.
159 * A string value does not have an associated unit of measure.
160 *
161 * @return The string value represented by this parameter.
162 * @throws InvalidParameterTypeException if the value is not a string.
163 * @throws IllegalStateException if the value can not be returned for an other raison.
164 *
165 * @see #getValue()
166 * @see #setValue(Object)
167 */
168 @UML(identifier="stringValue", obligation=CONDITIONAL, specification=ISO_19111)
169 String stringValue() throws IllegalStateException;
170
171 /**
172 * Returns an ordered sequence of numeric values in the specified unit of measure.
173 * This convenience method applies unit conversions on the fly as needed.
174 *
175 * @param unit The unit of measure for the value to be returned.
176 * @return The sequence of values represented by this parameter after conversion to type
177 * {@code double} and conversion to {@code unit}.
178 * @throws IllegalArgumentException if the specified unit is invalid for this parameter.
179 * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
180 * @throws IllegalStateException if the value can not be returned for an other raison.
181 *
182 * @see #getUnit()
183 * @see #setValue(double[],Unit)
184 * @see #doubleValue(Unit)
185 */
186 double[] doubleValueList(Unit<?> unit) throws IllegalArgumentException, IllegalStateException;
187
188 /**
189 * Returns an ordered sequence of two or more numeric values of an operation parameter
190 * list, where each value has the same associated {@linkplain Unit unit of measure}.
191 *
192 * @return The sequence of values represented by this parameter.
193 * @throws InvalidParameterTypeException if the value is not an array of {@code double}s.
194 * @throws IllegalStateException if the value can not be returned for an other raison.
195 * @unitof Measure
196 *
197 * @departure rename
198 * Renamed the method from "<code>valueList</code>" to "<code>doubleValueList</code>" both for
199 * consistency with <code>doubleValue()</code> and also because, like <code>doubleValue()</code>,
200 * this method returns an array of <code>double</code> values rather than a <code>Measure</code>
201 * object.
202 *
203 * @see #getUnit()
204 * @see #setValue(Object)
205 * @see #doubleValue()
206 */
207 @UML(identifier="valueList", obligation=CONDITIONAL, specification=ISO_19111)
208 double[] doubleValueList() throws IllegalStateException;
209
210 /**
211 * Returns an ordered sequence of two or more integer values of an operation parameter list,
212 * usually used for counts. These integer values do not have an associated unit of measure.
213 *
214 * @return The sequence of values represented by this parameter.
215 * @throws InvalidParameterTypeException if the value is not an array of {@code int}s.
216 * @throws IllegalStateException if the value can not be returned for an other raison.
217 *
218 * @departure rename
219 * Renamed the attribute from "<code>integerValueList</code>" to "<code>intValueList</code>"
220 * for consistency with <code>intValue()</code>.
221 *
222 * @see #setValue(Object)
223 * @see #intValue()
224 */
225 @UML(identifier="integerValueList", obligation=CONDITIONAL, specification=ISO_19111)
226 int[] intValueList() throws IllegalStateException;
227
228 /**
229 * Returns a reference to a file or a part of a file containing one or more parameter
230 * values. When referencing a part of a file, that file must contain multiple identified
231 * parts, such as an XML encoded document. Furthermore, the referenced file or part of a
232 * file can reference another part of the same or different files, as allowed in XML documents.
233 *
234 * @return The reference to a file containing parameter values.
235 * @throws InvalidParameterTypeException if the value is not a reference to a file or an URI.
236 * @throws IllegalStateException if the value can not be returned for an other raison.
237 *
238 * @see #getValue()
239 * @see #setValue(Object)
240 */
241 @UML(identifier="valueFile", obligation=CONDITIONAL, specification=ISO_19111)
242 URI valueFile() throws IllegalStateException;
243
244 /**
245 * Returns the parameter value as an object. The object type is typically a {@link Double},
246 * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]} or
247 * {@code int[]}. If no value has been set, then this method returns the
248 * {@linkplain ParameterDescriptor#getDefaultValue() default value} (which may be null).
249 *
250 * @return The parameter value as an object, or {@code null} if no value has been set and
251 * there is no default value.
252 *
253 * @see #setValue(Object)
254 */
255 @UML(identifier="value", obligation=CONDITIONAL, specification=ISO_19111)
256 T getValue();
257
258 /**
259 * Sets the parameter value as an array of floating point and their associated unit.
260 *
261 * @param values The parameter values.
262 * @param unit The unit for the specified value.
263 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
264 * parameter, or if the value is illegal for some other reason (for example a value out
265 * of range).
266 */
267 void setValue(double[] values, Unit<?> unit) throws InvalidParameterValueException;
268
269 /**
270 * Sets the parameter value as a floating point and its associated unit.
271 *
272 * @param value The parameter value.
273 * @param unit The unit for the specified values.
274 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
275 * parameter, or if the value is illegal for some other reason (for example a value out
276 * of range).
277 *
278 * @see #setValue(double)
279 * @see #doubleValue(Unit)
280 */
281 void setValue(double value, Unit<?> unit) throws InvalidParameterValueException;
282
283 /**
284 * Sets the parameter value as a floating point.
285 *
286 * @param value The parameter value.
287 * @throws InvalidParameterValueException if the floating point type is inappropriate for this
288 * parameter, or if the value is illegal for some other reason (for example a value out
289 * of range).
290 *
291 * @see #setValue(double,Unit)
292 * @see #doubleValue()
293 */
294 void setValue(double value) throws InvalidParameterValueException;
295
296 /**
297 * Sets the parameter value as an integer.
298 *
299 * @param value The parameter value.
300 * @throws InvalidParameterValueException if the integer type is inappropriate for this parameter,
301 * or if the value is illegal for some other reason (for example a value out of range).
302 *
303 * @see #intValue()
304 */
305 void setValue(int value) throws InvalidParameterValueException;
306
307 /**
308 * Sets the parameter value as a boolean.
309 *
310 * @param value The parameter value.
311 * @throws InvalidParameterValueException if the boolean type is inappropriate for this parameter.
312 *
313 * @see #booleanValue()
314 */
315 void setValue(boolean value) throws InvalidParameterValueException;
316
317 /**
318 * Sets the parameter value as an object. The object type is typically a {@link Double},
319 * {@link Integer}, {@link Boolean}, {@link String}, {@link URI}, {@code double[]}
320 * or {@code int[]}.
321 *
322 * <p>The argument is not restricted to the parameterized type {@code T} because the type
323 * is typically unknown (as in <code>group.{@linkplain ParameterValueGroup#parameter(String)
324 * parameter}("<var>name</var>").setValue(<var>value</var>)</code>) and
325 * because some implementations may choose to convert a wider range of types.</p>
326 *
327 * @param value The parameter value.
328 * @throws InvalidParameterValueException if the type of {@code value} is inappropriate
329 * for this parameter, or if the value is illegal for some other reason (for example
330 * the value is numeric and out of range).
331 *
332 * @see #getValue()
333 */
334 void setValue(Object value) throws InvalidParameterValueException;
335
336 /**
337 * Returns a copy of this parameter value.
338 *
339 * @return A copy of this parameter value.
340 */
341 @Override
342 ParameterValue<T> clone();
343 }