Class DefaultParameterValue<T>
- Type Parameters:
T
- the type of the value stored in this parameter.
- All Implemented Interfaces:
Serializable
,Cloneable
,LenientComparable
,org.opengis.parameter.GeneralParameterValue
,org.opengis.parameter.ParameterValue<T>
- Direct Known Subclasses:
ContextualParameter
,MapProjectionParameters.EarthRadius
,MapProjectionParameters.InverseFlattening
,MapProjectionParameters.IsIvfDefinitive
,MapProjectionParameters.StandardParallel
,UnmodifiableParameterValue
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) |
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
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate org.opengis.parameter.ParameterDescriptor
<T> The definition of this parameter.private static final long
Serial number for inter-operability with different versions.protected javax.measure.Unit
<?> The unit of measure for the value, ornull
if it does not apply.protected T
The value, ornull
if undefined. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Default constructor for JAXB only.DefaultParameterValue
(org.opengis.parameter.ParameterDescriptor<T> descriptor) Creates a parameter value from the specified descriptor.DefaultParameterValue
(org.opengis.parameter.ParameterValue<T> parameter) Creates a new instance initialized with the values from the specified parameter object. -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returns the boolean value of this parameter.private static Number
Converts the given number to the expected type, with a special case for conversion from float to double type.clone()
Returns a clone of this parameter value.double
Returns the numeric value of this parameter.double
doubleValue
(javax.measure.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
(javax.measure.Unit<?> unit) Returns an ordered sequence of numeric values in the specified unit of measure.final boolean
Compares the specified object with this parameter for equality.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this parameter for equality.protected String
Formats this parameter as a Well Known TextParameter[…]
element.private String
Formats an error message for illegal method call for the current value type.private javax.measure.UnitConverter
getConverterTo
(javax.measure.Unit<?> unit) Returns the converter to be used bydoubleValue(Unit)
anddoubleValueList(Unit)
.org.opengis.parameter.ParameterDescriptor
<T> Returns the definition of this parameter.javax.measure.Unit
<?> getUnit()
Returns the unit of measure of the parameter value.getValue()
Returns the parameter value as an object.private Object
Invoked by JAXB for obtaining the object to marshal.private static boolean
hasContextualUnit
(Formatter formatter) Returnstrue
if the given formatter has contextual units, in which case the WKT format can omit the unit of measurement.int
hashCode()
Returns a hash value for this parameter.int
intValue()
Returns 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.private static boolean
Returnstrue
if the given value is an instance of one of the types documented invalueFile()
.private boolean
isOrNeedFile
(Object newValue) Same asisFile(Object)
, but accepts also aString
if the type specified in the parameter descriptor is one of the types documented invalueFile()
.private IllegalStateException
missingOrIncompatibleValue
(Object newValue) Returns the exception to throw when an incompatible method is invoked for the value type.(package private) final void
setDescriptor
(org.opengis.parameter.ParameterDescriptor<T> descriptor) Invoked by JAXB at unmarshalling time.void
setValue
(boolean newValue) Sets the parameter value as a boolean.void
setValue
(double newValue) Sets the parameter value as a floating point.void
setValue
(double[] newValues, javax.measure.Unit<?> unit) Sets the parameter value as an array of floating point and their associated unit.void
setValue
(double newValue, javax.measure.Unit<?> unit) Sets the parameter value as a floating point and its associated unit.void
setValue
(int newValue) Sets the parameter value as an integer.void
Sets the parameter value as an object.protected void
Sets the parameter value and its associated unit.private void
setXmlValue
(Object xmlValue) Invoked by JAXB at unmarshalling time.Returns the string value of this parameter.static <T> DefaultParameterValue
<T> unmodifiable
(org.opengis.parameter.ParameterValue<T> parameter) Returns an unmodifiable implementation of the given parameter value.protected void
Invoked 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.private static Number
Wraps the given value in a type compatible with the expected value class, if possible.Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
descriptor
The definition of this parameter.Consider this field as final! This field is modified only at unmarshalling time by
setDescriptor(ParameterDescriptor)
- See Also:
-
value
The value, ornull
if 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
protected javax.measure.Unit<?> unitThe unit of measure for the value, ornull
if 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:
-
DefaultParameterValue
private DefaultParameterValue()Default constructor for JAXB only. The descriptor is initialized tonull
, but will be assigned a value after XML unmarshalling.
-
-
Method Details
-
getDescriptor
Returns the definition of this parameter.- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.GeneralParameterValue
- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the definition of this parameter.
-
getUnit
public javax.measure.Unit<?> getUnit()Returns the unit of measure of the parameter value. If the parameter value has no unit (for example because it is aString
type), 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:
getUnit
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the unit of measure, or
null
if 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:
getValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the parameter value as an object, or
null
if 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:
booleanValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the boolean value represented by this parameter.
- Throws:
org.opengis.parameter.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:
intValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the numeric value represented by this parameter after conversion to type
int
. - Throws:
org.opengis.parameter.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:
intValueList
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- a copy of the sequence of values represented by this parameter.
- Throws:
org.opengis.parameter.InvalidParameterTypeException
- if the value is not an array ofint
s.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:
doubleValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the numeric value represented by this parameter after conversion to type
double
. This method returnsDouble.NaN
only if such "value" has been explicitly set. - Throws:
org.opengis.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
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:
doubleValueList
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- a copy of the sequence of values represented by this parameter.
- Throws:
org.opengis.parameter.InvalidParameterTypeException
- if the value is not an array ofdouble
s.IllegalStateException
- if the value is not defined and there is no default value.- See Also:
-
getConverterTo
private javax.measure.UnitConverter getConverterTo(javax.measure.Unit<?> unit) Returns the converter to be used bydoubleValue(Unit)
anddoubleValueList(Unit)
. -
doubleValue
public double doubleValue(javax.measure.Unit<?> unit) throws IllegalArgumentException, IllegalStateException 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:
doubleValue
in interfaceorg.opengis.parameter.ParameterValue<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
double
and conversion tounit
. - Throws:
IllegalArgumentException
- if the specified unit is invalid for this parameter.org.opengis.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(javax.measure.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:
doubleValueList
in interfaceorg.opengis.parameter.ParameterValue<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
double
and conversion tounit
. - Throws:
IllegalArgumentException
- if the specified unit is invalid for this parameter.org.opengis.parameter.InvalidParameterTypeException
- if the value is not an array ofdouble
s.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:
stringValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the string value represented by this parameter.
- Throws:
org.opengis.parameter.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:
valueFile
in interfaceorg.opengis.parameter.ParameterValue<T>
- Returns:
- the reference to a file containing parameter values.
- Throws:
org.opengis.parameter.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:
-
isFile
Returnstrue
if the given value is an instance of one of the types documented invalueFile()
. -
isOrNeedFile
Same asisFile(Object)
, but accepts also aString
if the type specified in the parameter descriptor is one of the types documented invalueFile()
. -
missingOrIncompatibleValue
Returns the exception to throw when an incompatible method is invoked for the value type. -
getClassTypeError
Formats an error message for illegal method call for the current value type. -
cast
Converts the given number to the expected type, with a special case for conversion from float to double type. Widening conversions are aimed to be exact in base 10 instead of base 2. IfexpectedClass
is not aNumber
subtype, then this method does nothing. If the cast would result in information lost, than this method returns the given value unchanged for allowing a more accurate error message to happen later.- Parameters:
value
- the value to cast (can benull
).expectedClass
- the desired class as a wrapper class (not a primitive type).- Returns:
- value converted to the desired class, or
value
if no cast is needed or can be done.
-
setValue
Sets the parameter value as an object. The object type is typically (but not limited to)Double
,double[]
,Integer
,int[]
,Boolean
,String
orURI
. 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 fromFloat
toDouble
or fromPath
toURI
) if such conversion can be done without information lost.- Specified by:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValue
- the parameter value, ornull
to restore the default.- Throws:
org.opengis.parameter.InvalidParameterValueException
- if the type ofvalue
is 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
public void setValue(boolean newValue) throws org.opengis.parameter.InvalidParameterValueException Sets the parameter value as a boolean.- Specified by:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValue
- the parameter value.- Throws:
org.opengis.parameter.InvalidParameterValueException
- if the boolean type is inappropriate for this parameter.- See Also:
-
setValue
public void setValue(int newValue) throws org.opengis.parameter.InvalidParameterValueException 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:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValue
- the parameter value.- Throws:
org.opengis.parameter.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:
-
wrap
Wraps the given value in a type compatible with the expected value class, if possible. If the value cannot be wrapped, then this method fallbacks on theDouble
class consistently with this method being invoked only bysetValue(double, …)
methods.- Throws:
IllegalArgumentException
- if the given value cannot be converted to the given type.
-
setValue
public void setValue(double newValue) throws org.opengis.parameter.InvalidParameterValueException 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:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValue
- the parameter value.- Throws:
org.opengis.parameter.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
public void setValue(double newValue, javax.measure.Unit<?> unit) throws org.opengis.parameter.InvalidParameterValueException 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:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValue
- the parameter value.unit
- the unit for the specified value.- Throws:
org.opengis.parameter.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
public void setValue(double[] newValues, javax.measure.Unit<?> unit) throws org.opengis.parameter.InvalidParameterValueException Sets the parameter value as an array of floating point and their associated unit.- Specified by:
setValue
in interfaceorg.opengis.parameter.ParameterValue<T>
- Parameters:
newValues
- the parameter values.unit
- the unit for the specified value.- Throws:
org.opengis.parameter.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
protected void setValue(Object newValue, javax.measure.Unit<?> unit) throws org.opengis.parameter.InvalidParameterValueException 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, ornull
to restore the default.unit
- the unit associated to the new parameter value, ornull
.- Throws:
org.opengis.parameter.InvalidParameterValueException
- if the type ofvalue
is 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:
org.opengis.parameter.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:
equals
in interfaceLenientComparable
- Parameters:
object
- the object to compare tothis
.mode
- the strictness level of the comparison.- Returns:
true
if 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 overrideequals(Object, ComparisonMode)
instead of this method.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classObject
- Parameters:
object
- the object to compare tothis
.- Returns:
true
if 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. -
unmodifiable
public static <T> DefaultParameterValue<T> unmodifiable(org.opengis.parameter.ParameterValue<T> parameter) 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.
Cloneable
interface 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 givenparameter
instance 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 sameDefaultParameterValue
instance on a best effort basis.Rational: 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 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
null
if the given parameter was null. - Since:
- 0.6
- See Also:
-
formatTo
Formats this parameter as a Well Known TextParameter[…]
element. Example: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:
WKT 2:
- Specified by:
formatTo
in classFormattableObject
- Parameters:
formatter
- the formatter where to format the inner content of this WKT element.- Returns:
"Parameter"
or"ParameterFile"
.- See Also:
-
hasContextualUnit
Returnstrue
if the given formatter has contextual units, in which case the WKT format can omit the unit of measurement. The contextual units may be defined either in the direct parent or in the parent of the parent, depending if we are formatting WKT1 or WKT2 respectively. This is because WKT2 wraps the parameters in an additionalCONVERSION[…]
element which is not present in WKT1.Taking the example documented in
formatTo(Formatter)
:- in WKT 1,
PROJCS[…]
is the immediate parent ofPARAMETER[…]
, but - in WKT 2,
ProjectedCRS[…]
is the parent ofConversion[…]
, which is the parent ofParameter[…]
.
- in WKT 1,
-
setDescriptor
Invoked by JAXB at unmarshalling time. May also be invoked byDefaultParameterValueGroup
if the descriptor has been completed with additional information provided in the<gml:group>
element of a descriptor group.- See Also:
-
getXmlValue
Invoked by JAXB for obtaining the object to marshal. The property name depends on its type after conversion by this method. -
setXmlValue
Invoked by JAXB at unmarshalling time.
-