Class DefaultParameterValue<T>
- Object
-
- FormattableObject
-
- DefaultParameterValue<T>
-
- Type Parameters:
T- the type of the value stored in this parameter.
- All Implemented Interfaces:
Serializable,Cloneable,LenientComparable,GeneralParameterValue,ParameterValue<T>
public class DefaultParameterValue<T> extends FormattableObject implements ParameterValue<T>, LenientComparable, Serializable, Cloneable
A single parameter value used by an operation method.ParameterValueinstances are elements in a parameter value group, in a way similar toMap.Entryinstances in ajava.util.Map.In the context of coordinate operations, most parameter values are numeric and can be obtained by the
intValue()ordoubleValue()methods. But other types of parameter values are possible and can be handled by the more genericgetValue()andsetValue(Object)methods. AllxxxValue()methods in this class are convenience methods converting the value fromObjectto 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:
The type and constraints on parameter values are given by the descriptor, which is specified at construction time. The parameter type can be fetch with the following idiom:Mapping from ISO attributes to getters and setters ISO attribute Java type Getter method Setter method ObjectgetValue()setValue(Object)stringValue StringstringValue()setValue(Object)value doubledoubleValue()setValue(double)doubledoubleValue(Unit)setValue(double, Unit)valueList double[]doubleValueList()setValue(Object)double[]doubleValueList(Unit)setValue(double[], Unit)integerValue intintValue()setValue(int)integerValueList int[]intValueList()setValue(Object)booleanValue booleanbooleanValue()setValue(boolean)valueFile URIvalueFile()setValue(Object)valueFileCitation CitationgetValue()setValue(Object)Class<T> valueClass = parameter.getDescriptor().getValueClass();
InstantiationA parameter descriptor must be defined before parameter value can be created. Descriptors are usually pre-defined 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 theParameterDescriptor.createValue()method. The later is recommended since it allows descriptors to return specialized implementations.Implementation note for subclassesAll read and write operations (except constructors,equals(Object)andhashCode()) 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:
DefaultParameterDescriptor,DefaultParameterValueGroup, Serialized Form
Defined in the
sis-referencingmodule
-
-
Constructor Summary
Constructors Constructor Description DefaultParameterValue(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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description booleanbooleanValue()Returns the boolean value of this parameter.DefaultParameterValue<T>clone()Returns a clone of this parameter value.doubledoubleValue()Returns the numeric value of this parameter.doubledoubleValue(Unit<?> unit)Returns the numeric value of this parameter in the given unit of measure.double[]doubleValueList()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.booleanequals(Object object)Compares the specified object with this parameter for equality.booleanequals(Object object, ComparisonMode mode)Compares the specified object with this parameter for equality.protected StringformatTo(Formatter formatter)Formats this parameter as a Well Known TextParameter[…]element.ParameterDescriptor<T>getDescriptor()Returns the definition of this parameter.Unit<?>getUnit()Returns the unit of measure of the parameter value.TgetValue()Returns the parameter value as an object.inthashCode()Returns a hash value for this parameter.intintValue()Returns the integer value of this parameter, usually used for a count.int[]intValueList()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.voidsetValue(double[] newValues, Unit<?> unit)Sets the parameter value as an array of floating point and their associated unit.voidsetValue(double newValue, Unit<?> unit)Sets the parameter value as a floating point and its associated unit.voidsetValue(int newValue)Sets the parameter value as an integer.voidsetValue(Object newValue)Sets the parameter value as an object.protected voidsetValue(Object newValue, Unit<?> unit)Sets the parameter value and its associated unit.StringstringValue()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 voidvalidate(T newValue)Invoked bysetValue(Object, Unit)after the basic verifications have been done and before the value is stored.URIvalueFile()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 Detail
-
value
protected T 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
protected Unit<?> 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 Detail
-
DefaultParameterValue
public DefaultParameterValue(ParameterDescriptor<T> descriptor)
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
public DefaultParameterValue(ParameterValue<T> parameter)
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:
clone(),unmodifiable(ParameterValue)
-
-
Method Detail
-
getDescriptor
public ParameterDescriptor<T> getDescriptor()
Returns the definition of this parameter.- Specified by:
getDescriptorin interfaceGeneralParameterValue- Specified by:
getDescriptorin interfaceParameterValue<T>- Returns:
- the definition of this parameter.
-
getUnit
public Unit<?> 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 subclassesAll 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:
doubleValue(),doubleValueList(),getValue()
-
getValue
public T 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 subclassesAll 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:
setValue(Object),Parameters.getValue(ParameterDescriptor)
-
booleanValue
public boolean booleanValue() throws IllegalStateExceptionReturns 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:
setValue(boolean),Parameters.booleanValue(ParameterDescriptor)
-
intValue
public int intValue() throws IllegalStateExceptionReturns 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:
setValue(int),intValueList(),Parameters.intValue(ParameterDescriptor)
-
intValueList
public int[] intValueList() throws IllegalStateExceptionReturns 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:
setValue(Object),intValue(),Parameters.intValueList(ParameterDescriptor)
-
doubleValue
public double doubleValue() throws IllegalStateExceptionReturns 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:
getUnit(),setValue(double),doubleValueList(),Parameters.doubleValue(ParameterDescriptor)
-
doubleValueList
public double[] doubleValueList() throws IllegalStateExceptionReturns 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:
getUnit(),setValue(Object),doubleValue()
-
doubleValue
public double doubleValue(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:
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:
getUnit(),setValue(double,Unit),doubleValueList(Unit),Parameters.doubleValue(ParameterDescriptor)
-
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:
getUnit(),setValue(double[],Unit),doubleValue(Unit),Parameters.doubleValueList(ParameterDescriptor)
-
stringValue
public String stringValue() throws IllegalStateException
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:
getValue(),setValue(Object),Parameters.stringValue(ParameterDescriptor)
-
valueFile
public URI valueFile() throws IllegalStateException
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:
getValue(),setValue(Object)
-
setValue
public void setValue(Object newValue) throws InvalidParameterValueException
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:
getValue()
-
setValue
public void setValue(boolean newValue) throws InvalidParameterValueExceptionSets 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:
booleanValue()
-
setValue
public void setValue(int newValue) throws InvalidParameterValueExceptionSets 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:
intValue()
-
setValue
public void setValue(double newValue) throws InvalidParameterValueExceptionSets 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(double,Unit),doubleValue()
-
setValue
public void setValue(double newValue, Unit<?> unit) throws InvalidParameterValueExceptionSets 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(double),doubleValue(Unit)
-
setValue
public void setValue(double[] newValues, Unit<?> unit) throws InvalidParameterValueExceptionSets 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
protected void setValue(Object newValue, Unit<?> unit) throws 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 subclassesThis 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:
validate(Object)
- This method does not perform any type conversion. Type conversion, if desired, should be
applied by the public
-
validate
protected void validate(T newValue) throws InvalidParameterValueException
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 measurementIf 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 later value will be stored in the unit specified by the user.Standard validationsThe 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
public boolean equals(Object object, ComparisonMode mode)
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:
Utilities.deepEquals(Object, Object, ComparisonMode)
-
equals
public final boolean equals(Object object)
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 than this method.- Specified by:
equalsin interfaceLenientComparable- Overrides:
equalsin classObject- Parameters:
object- the object to compare tothis.- Returns:
trueif both objects are equal.- See Also:
ComparisonMode.STRICT
-
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
public DefaultParameterValue<T> clone()
Returns a clone of this parameter value.- Specified by:
clonein interfaceGeneralParameterValue- Specified by:
clonein interfaceParameterValue<T>- Overrides:
clonein classObject- See Also:
DefaultParameterValue(ParameterValue),unmodifiable(ParameterValue)
-
unmodifiable
public static <T> DefaultParameterValue<T> unmodifiable(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.
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 sharingIf 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.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
nullif the given parameter was null. - Since:
- 0.6
- See Also:
Parameters.unmodifiable(ParameterValueGroup)
-
formatTo
protected String formatTo(Formatter formatter)
Formats this parameter as a Well Known TextParameter[…]element. Example:Parameter["False easting", 0.0, LengthUnit["metre", 1]]
Unit of measurementThe 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:
- WKT 2 specification §17.2.4
-
-