- Type Parameters:
T- the type of the value stored in this parameter.
- All Implemented Interfaces:
Serializable,Cloneable,LenientComparable,GeneralParameterValue,ParameterValue<T>
ParameterValue instances are elements in
a parameter value group, in a way similar to Map.Entry
instances in a java.util.Map.
In the context of coordinate operations, most parameter values are numeric and can be obtained by the
intValue() or doubleValue() methods. But other types of parameter values are possible
and can be handled by the more generic getValue() and setValue(Object) methods.
All xxxValue() methods in this class are convenience methods converting the value from Object
to some commonly used types. Those types are specified in ISO 19111 as an union of attributes, listed below with
the corresponding getter and setter methods:
| ISO attribute | Java type | Getter method | Setter method |
|---|---|---|---|
Object | getValue() | setValue(Object) | |
| stringValue | String | stringValue() | setValue(Object) |
| value | double | doubleValue() | setValue(double) |
double | doubleValue(Unit) | setValue(double, Unit) | |
| valueList | double[] | doubleValueList() | setValue(Object) |
double[] | doubleValueList(Unit) | setValue(double[], Unit) | |
| integerValue | int | intValue() | setValue(int) |
| integerValueList | int[] | intValueList() | setValue(Object) |
| booleanValue | boolean | booleanValue() | setValue(boolean) |
| valueFile | URI | valueFile() | setValue(Object) |
| valueFileCitation | Citation | getValue() | setValue(Object) |
Class<T> valueClass = parameter.getDescriptor().getValueClass();
Instantiation
A parameter descriptor must be defined before parameter value can be created. Descriptors are usually predefined by map projection or process providers. Given a descriptor, a parameter value can be created by a call to theDefaultParameterValue(ParameterDescriptor) constructor or by a call to the
ParameterDescriptor.createValue() method. The latter is recommended since it allows descriptors to return
specialized implementations.
Implementation note for subclasses
All read and write operations (except constructors,equals(Object) and hashCode())
ultimately delegates to the following methods:
- All getter methods will invoke
getValue()andgetUnit()(if needed), then perform their processing on the values returned by those methods. - All setter methods delegate to the
setValue(Object, Unit)method.
- Since:
- 0.4
- See Also:
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionDefaultParameterValue(ParameterDescriptor<T> descriptor) Creates a parameter value from the specified descriptor.DefaultParameterValue(ParameterValue<T> parameter) Creates a new instance initialized with the values from the specified parameter object. -
Method Summary
Modifier and TypeMethodDescriptionbooleanReturns the boolean value of this parameter.clone()Returns a clone of this parameter value.doubleReturns the numeric value of this parameter.doubledoubleValue(Unit<?> unit) Returns the numeric value of this parameter in the given unit of measure.double[]Returns an ordered sequence of two or more numeric values of this parameter, where each value has the same associated unit of measure.double[]doubleValueList(Unit<?> unit) Returns an ordered sequence of numeric values in the specified unit of measure.final booleanCompares the specified object with this parameter for equality.booleanequals(Object object, ComparisonMode mode) Compares the specified object with this parameter for equality.protected StringFormats this parameter as a Well Known TextParameter[…]element.Returns the definition of this parameter.Unit<?> getUnit()Returns the unit of measure of the parameter value.Returns the parameter value as an object.intReturns a hash value for this parameter.intReturns the integer value of this parameter, usually used for a count.int[]Returns an ordered sequence of two or more integer values of this parameter, usually used for counts.voidsetValue(boolean newValue) Sets the parameter value as a boolean.voidsetValue(double newValue) Sets the parameter value as a floating point.voidSets the parameter value as an array of floating point and their associated unit.voidSets the parameter value as a floating point and its associated unit.voidsetValue(int newValue) Sets the parameter value as an integer.voidSets the parameter value as an object.protected voidSets the parameter value and its associated unit.Returns the string value of this parameter.static <T> DefaultParameterValue<T> unmodifiable(ParameterValue<T> parameter) Returns an unmodifiable implementation of the given parameter value.protected voidInvoked bysetValue(Object, Unit)after the basic verifications have been done and before the value is stored.Returns a reference to a file or a part of a file containing one or more parameter values.Methods inherited from class FormattableObject
print, toString, toString, toWKT
-
Field Details
-
value
The value, ornullif undefined. Except for the constructors, theequals(Object)and thehashCode()methods, this field should be read only bygetValue()and written only bysetValue(Object, Unit).- Since:
- 0.7
-
unit
The unit of measure for the value, ornullif it does not apply. Except for the constructors, theequals(Object)and thehashCode()methods, this field should be read only bygetUnit()and written only bysetValue(Object, Unit).- Since:
- 0.7
-
-
Constructor Details
-
DefaultParameterValue
Creates a parameter value from the specified descriptor. The value will be initialized to the default value, if any.- Parameters:
descriptor- the abstract definition of this parameter.
-
DefaultParameterValue
Creates a new instance initialized with the values from the specified parameter object. This is a shallow copy constructor, since the value contained in the given object is not cloned.- Parameters:
parameter- the parameter to copy values from.- See Also:
-
-
Method Details
-
getDescriptor
Returns the definition of this parameter.- Specified by:
getDescriptorin interfaceGeneralParameterValue- Specified by:
getDescriptorin interfaceParameterValue<T>- Returns:
- the definition of this parameter.
-
getUnit
Returns the unit of measure of the parameter value. If the parameter value has no unit (for example because it is aStringtype), then this method returnsnull. Note that "no unit" does not mean "dimensionless".Implementation note for subclasses
All getter methods which need unit information will invoke thisgetUnit()method. Subclasses can override this method if they need to compute the unit dynamically.- Specified by:
getUnitin interfaceParameterValue<T>- Returns:
- the unit of measure, or
nullif none. - See Also:
-
getValue
Returns the parameter value as an object. If no value has been set, then this method returns the default value (which may be null).Implementation note for subclasses
All getter methods will invoke thisgetValue()method. Subclasses can override this method if they need to compute the value dynamically.- Specified by:
getValuein interfaceParameterValue<T>- Returns:
- the parameter value as an object, or
nullif no value has been set and there is no default value. - See Also:
-
booleanValue
Returns the boolean value of this parameter. A boolean value does not have an associated unit of measure.The default implementation invokes
getValue()and casts the result if possible, or throws an exception otherwise.- Specified by:
booleanValuein interfaceParameterValue<T>- Returns:
- the boolean value represented by this parameter.
- Throws:
InvalidParameterTypeException- if the value is not a boolean type.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
intValue
Returns the integer value of this parameter, usually used for a count. An integer value does not have an associated unit of measure.The default implementation invokes
getValue()and casts the result if possible, or throws an exception otherwise.- Specified by:
intValuein interfaceParameterValue<T>- Returns:
- the numeric value represented by this parameter after conversion to type
int. - Throws:
InvalidParameterTypeException- if the value is not an integer type.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
intValueList
Returns an ordered sequence of two or more integer values of this parameter, usually used for counts.The default implementation invokes
getValue()and casts the result if possible, or throws an exception otherwise. If the value can be casted, then the array is cloned before to be returned.- Specified by:
intValueListin interfaceParameterValue<T>- Returns:
- a copy of the sequence of values represented by this parameter.
- Throws:
InvalidParameterTypeException- if the value is not an array ofints.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
doubleValue
Returns the numeric value of this parameter. The units of measurement are specified bygetUnit().The default implementation invokes
getValue()and casts the result if possible, or throws an exception otherwise.- Specified by:
doubleValuein interfaceParameterValue<T>- Returns:
- the numeric value represented by this parameter after conversion to type
double. This method returnsDouble.NaNonly if such "value" has been explicitly set. - Throws:
InvalidParameterTypeException- if the value is not a numeric type.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
doubleValueList
Returns an ordered sequence of two or more numeric values of this parameter, where each value has the same associated unit of measure.The default implementation invokes
getValue()and casts the result if possible, or throws an exception otherwise. If the value can be casted, then the array is cloned before to be returned.- Specified by:
doubleValueListin interfaceParameterValue<T>- Returns:
- a copy of the sequence of values represented by this parameter.
- Throws:
InvalidParameterTypeException- if the value is not an array ofdoubles.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
doubleValue
Returns the numeric value of this parameter in the given unit of measure. This convenience method applies unit conversions on the fly as needed.The default implementation invokes
doubleValue()andgetUnit(), then converts the values to the given unit of measurement.- Specified by:
doubleValuein interfaceParameterValue<T>- Parameters:
unit- the unit of measure for the value to be returned.- Returns:
- the numeric value represented by this parameter after conversion to type
doubleand conversion tounit. - Throws:
IllegalArgumentException- if the specified unit is invalid for this parameter.InvalidParameterTypeException- if the value is not a numeric type.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
doubleValueList
public double[] doubleValueList(Unit<?> unit) throws IllegalArgumentException, IllegalStateException Returns an ordered sequence of numeric values in the specified unit of measure. This convenience method applies unit conversions on the fly as needed.The default implementation invokes
doubleValueList()andgetUnit(), then converts the values to the given unit of measurement.- Specified by:
doubleValueListin interfaceParameterValue<T>- Parameters:
unit- the unit of measure for the value to be returned.- Returns:
- the sequence of values represented by this parameter after conversion to type
doubleand conversion tounit. - Throws:
IllegalArgumentException- if the specified unit is invalid for this parameter.InvalidParameterTypeException- if the value is not an array ofdoubles.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
stringValue
Returns the string value of this parameter. A string value does not have an associated unit of measure.- Specified by:
stringValuein interfaceParameterValue<T>- Returns:
- the string value represented by this parameter.
- Throws:
InvalidParameterTypeException- if the value is not a string.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
valueFile
Returns a reference to a file or a part of a file containing one or more parameter values. The default implementation can convert the following value types:URI,URL,Path,File.- Specified by:
valueFilein interfaceParameterValue<T>- Returns:
- the reference to a file containing parameter values.
- Throws:
InvalidParameterTypeException- if the value is not a reference to a file or a URI.IllegalStateException- if the value is not defined and there is no default value.- See Also:
-
setValue
Sets the parameter value as an object. The object type is typically (but not limited to)Double,double[],Integer,int[],Boolean,StringorURI. If the given value isnull, then this parameter is set to the default value. If the given value is not an instance of the expected type, then this method may perform automatically a type conversion (for example fromFloattoDoubleor fromPathtoURI) if such conversion can be done without information lost.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValue- the parameter value, ornullto restore the default.- Throws:
InvalidParameterValueException- if the type ofvalueis inappropriate for this parameter, or if the value is illegal for some other reason (for example the value is numeric and out of range).- See Also:
-
setValue
Sets the parameter value as a boolean.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValue- the parameter value.- Throws:
InvalidParameterValueException- if the boolean type is inappropriate for this parameter.- See Also:
-
setValue
Sets the parameter value as an integer. This method automatically wraps the given integer in an object of the type specified by the descriptor if that conversion can be done without information lost.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValue- the parameter value.- Throws:
InvalidParameterValueException- if the integer type is inappropriate for this parameter, or if the value is illegal for some other reason (for example a value out of range).- See Also:
-
setValue
Sets the parameter value as a floating point. The unit, if any, stay unchanged. This method automatically wraps the given number in an object of the type specified by the descriptor.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValue- the parameter value.- Throws:
InvalidParameterValueException- if the floating point type is inappropriate for this parameter, or if the value is illegal for some other reason (for example a value out of range).- See Also:
-
setValue
Sets the parameter value as a floating point and its associated unit. This method automatically wraps the given number in an object of the type specified by the descriptor.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValue- the parameter value.unit- the unit for the specified value.- Throws:
InvalidParameterValueException- if the floating point type is inappropriate for this parameter, or if the value is illegal for some other reason (for example a value out of range).- See Also:
-
setValue
Sets the parameter value as an array of floating point and their associated unit.- Specified by:
setValuein interfaceParameterValue<T>- Parameters:
newValues- the parameter values.unit- the unit for the specified value.- Throws:
InvalidParameterValueException- if the floating point array type is inappropriate for this parameter, or if the value is illegal for some other reason (for example a value out of range).
-
setValue
Sets the parameter value and its associated unit. If the given value isnull, then this parameter is set to the default value. Otherwise the given value shall be an instance of the class expected by the descriptor.- This method does not perform any type conversion. Type conversion, if desired, should be
applied by the public
setValue(…)methods before to invoke this protected method. - This method does not clone the given value. In particular, references to
int[]anddouble[]arrays are stored as-is.
Implementation note for subclasses
This method is invoked by all setter methods in this class, thus providing a single point that subclasses can override if they want to perform more processing on the value before its storage, or to be notified about value changes.- Parameters:
newValue- the parameter value, ornullto restore the default.unit- the unit associated to the new parameter value, ornull.- Throws:
InvalidParameterValueException- if the type ofvalueis inappropriate for this parameter, or if the value is illegal for some other reason (for example the value is numeric and out of range).- See Also:
- This method does not perform any type conversion. Type conversion, if desired, should be
applied by the public
-
validate
Invoked bysetValue(Object, Unit)after the basic verifications have been done and before the value is stored. Subclasses can override this method for performing additional verifications.Unit of measurement
If the user specified a unit of measurement, then the value given to this method has been converted to the unit specified by the descriptor, for easier comparisons against standardized values. This converted value may be different than the value to be stored in thisParameterValue, since the latter value will be stored in the unit specified by the user.Standard validations
The checks for value class, for value domain and for valid values are performed before this method is invoked. The default implementation of this method does nothing.- Parameters:
newValue- the value converted to the unit of measurement specified by the descriptor.- Throws:
InvalidParameterValueException- if the given value is invalid for implementation-specific reasons.
-
equals
Compares the specified object with this parameter for equality. The strictness level is controlled by the second argument.- Specified by:
equalsin interfaceLenientComparable- Parameters:
object- the object to compare tothis.mode- the strictness level of the comparison.- Returns:
trueif both objects are equal according the given comparison mode.- See Also:
-
equals
Compares the specified object with this parameter for equality. This method is implemented as below:Subclasses shall overridereturn equals(other, ComparisonMode.STRICT);equals(Object, ComparisonMode)instead of this method.- Specified by:
equalsin interfaceLenientComparable- Overrides:
equalsin classObject- Parameters:
object- the object to compare tothis.- Returns:
trueif both objects are equal.- See Also:
-
hashCode
public int hashCode()Returns a hash value for this parameter. This value does not need to be the same in past or future versions of this class. -
clone
Returns a clone of this parameter value.- Specified by:
clonein interfaceGeneralParameterValue- Specified by:
clonein interfaceParameterValue<T>- Overrides:
clonein classObject- See Also:
-
unmodifiable
Returns an unmodifiable implementation of the given parameter value. This method shall be used only with:- immutable descriptor,
- immutable or null unit, and
- immutable or cloneable parameter value.
Cloneableinterface and has a publicclone()method, then that value will be cloned every time thegetValue()method is invoked. The value is not cloned by this method however; it is caller's responsibility to not modify the value of the givenparameterinstance after this method call.Instances sharing
If this method is invoked more than once with equal descriptor, value and unit, then this method will return the sameDefaultParameterValueinstance on a best effort basis. The rational for sharing is because the same parameter value is often used in many different coordinate operations. For example, all Universal Transverse Mercator (UTM) projections use the same scale factor (0.9996) and the same false easting (500000 metres).- Type Parameters:
T- the type of the value stored in the given parameter.- Parameters:
parameter- the parameter to make unmodifiable, ornull.- Returns:
- a unmodifiable implementation of the given parameter, or
nullif the given parameter was null. - Since:
- 0.6
- See Also:
-
formatTo
Formats this parameter as a Well Known TextParameter[…]element. Example:Parameter["False easting", 0.0, LengthUnit["metre", 1]]Unit of measurement
The units of measurement were never specified in WKT 1 format, and are optional in WKT 2 format. If the units are not specified, then they are inferred from the context. Typically, parameter values that are lengths are given in the unit for the projected CRS axes while parameter values that are angles are given in the unit for the base geographic CRS.Example
The snippet below show WKT representations of the map projection parameters of a projected CRS (most other elements are omitted). The map projection uses a "Latitude of natural origin" parameters which is set to 52 grads, as defined in theUNIT[…]element of the enclosing CRS. A similar rule applies to “False easting” and “False northing” parameters, which are in kilometres in this example.WKT 1:
PROJCS[…, GEOGCS[…, UNIT[“grad”, 0.015707963267948967]], // Unit for all angles PROJECTION[“Lambert_Conformal_Conic_1SP”] PARAMETER[“latitude_of_origin”, 52.0], // In grads PARAMETER[“scale_factor”, 0.99987742], PARAMETER[“false_easting”, 600.0], // In kilometres PARAMETER[“false_northing”, 2200.0], // In kilometres UNIT[“kilometre”, 1000]] // Unit for all lengthsWKT 2:
ProjectedCRS[… BaseGeodCRS[… AngleUnit[“grad”, 0.015707963267948967]], Conversion[“Lambert zone II”, Method[“Lambert Conic Conformal (1SP)”], Parameter[“Latitude of natural origin”, 52.0], Parameter[“Scale factor at natural origin”, 0.99987742], Parameter[“False easting”, 600.0], Parameter[“False northing”, 2200.0]], CS[“Cartesian”, 2], LengthUnit[“kilometre”, 1000]]- Specified by:
formatToin classFormattableObject- Parameters:
formatter- the formatter where to format the inner content of this WKT element.- Returns:
"Parameter"or"ParameterFile".- See Also:
-