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