Package org.apache.sis.parameter
Class DefaultParameterValueGroup
- Object
-
- Parameters
-
- DefaultParameterValueGroup
-
- All Implemented Interfaces:
Serializable
,Cloneable
,LenientComparable
,GeneralParameterValue
,ParameterValueGroup
public class DefaultParameterValueGroup extends Parameters implements LenientComparable, Serializable
A group of related parameter values. Parameter groups have some similarities withjava.util.Map
:parameter(String)
is similar in purpose toMap.get(Object)
, with an additional level of indirection in both the argument and the return value.values()
is similar in purpose toMap.entrySet()
, withParameterValue
playing a role similar toMap.Entry
.
Instantiation and validity constraintsParameterValueGroup
instances are typically created by calls todescriptor.createValue()
on a descriptor supplied by a coordinate operation or process provider. New instances are initialized with a list of values containing all mandatory parameters, and no optional parameter. The values list is modifiable, but all methods will first ensure that the modification would not violate the cardinality constraints (i.e. the minimum and maximum occurrences of that parameter allowed by the descriptor). If a cardinality constraint is violated, then anInvalidParameterCardinalityException
will be thrown.Setting the parameter valuesAfter a newParameterValueGroup
instance has been created, the parameter values can be set by chaining calls toparameter(String)
with one of thesetValue(…)
methods defined in the returned object (see the table of setter methods). Theparameter(String)
method can be invoked regardless of whether the parameter is mandatory or optional: if the parameter was optional and not yet present in this group, it will be created.Example: Assuming the descriptor defined in theAlternatively, if all parameters were created elsewhere and the user wants to copy them in a new parameter group, theDefaultParameterDescriptorGroup
example, one can set Mercator (variant A) projection parameters as below:ParameterValueGroup mercator = Mercator.PARAMETERS.createValue(); mercator.parameter("Longitude of natural origin").setValue(-60, Units.DEGREE); // 60°W mercator.parameter("Latitude of natural origin") .setValue( 40, Units.DEGREE); // 40°N // Keep default values for other parameters.
List.addAll(Collection)
method can been invoked on the values list.Example:Optional parameters can be removed by the usualParameterValue<?>[] parameter = ...; // Defined elsewhere. ParameterValueGroup mercator = Mercator.PARAMETERS.createValue(); mercator.values().addAll(Arrays.asList(parameters));
List.remove(int)
orList.remove(Object)
operations on the values list. But attempts to remove a mandatory parameter will cause anInvalidParameterCardinalityException
to be thrown.Calls to
values().clear()
restore thisDefaultParameterValueGroup
to its initial state.- Since:
- 0.4
- See Also:
DefaultParameterDescriptorGroup
,DefaultParameterValue
, Serialized Form
Defined in the
sis-referencing
module
-
-
Constructor Summary
Constructors Constructor Description DefaultParameterValueGroup(ParameterDescriptorGroup descriptor)
Creates a parameter group from the specified descriptor.DefaultParameterValueGroup(ParameterValueGroup parameters)
Creates a new instance initialized with all values from the specified parameter group.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ParameterValueGroup
addGroup(String name)
Creates a new subgroup of the specified name, and adds it to the list of subgroups.DefaultParameterValueGroup
clone()
Returns a deep copy of this group of parameter values.boolean
equals(Object object)
Compares the specified object with this parameter for equality.boolean
equals(Object object, ComparisonMode mode)
Compares the specified object with this parameter for equality.ParameterDescriptorGroup
getDescriptor()
Returns the abstract definition of this group of parameters.List<ParameterValueGroup>
groups(String name)
Returns all subgroups with the specified name.int
hashCode()
Returns a hash value for this parameter.ParameterValue<?>
parameter(String name)
Returns the value in this group for the specified name.List<GeneralParameterValue>
values()
Returns the values in this group.-
Methods inherited from class Parameters
booleanValue, cast, cast, castOrWrap, copy, doubleValue, doubleValueList, getDescriptors, getMandatoryValue, getMemberName, getOrCreate, getValue, getValueDomain, intValue, intValueList, print, stringValue, toString, unmodifiable
-
-
-
-
Constructor Detail
-
DefaultParameterValueGroup
public DefaultParameterValueGroup(ParameterDescriptorGroup descriptor)
Creates a parameter group from the specified descriptor.Usage note:
ParameterValueGroup
are usually not instantiated directly. Instead, consider invokingdescriptor.createValue()
on a descriptor supplied by a map projection or process provider.- Parameters:
descriptor
- the descriptor for this group.
-
DefaultParameterValueGroup
public DefaultParameterValueGroup(ParameterValueGroup parameters)
Creates a new instance initialized with all values from the specified parameter group. This is a shallow copy constructor, since the values contained in the given group is not cloned.- Parameters:
parameters
- The parameters to copy values from.- Since:
- 0.6
- See Also:
clone()
-
-
Method Detail
-
getDescriptor
public ParameterDescriptorGroup getDescriptor()
Returns the abstract definition of this group of parameters.- Specified by:
getDescriptor
in interfaceGeneralParameterValue
- Specified by:
getDescriptor
in interfaceParameterValueGroup
- Returns:
- the abstract definition of this group of parameters.
-
values
public List<GeneralParameterValue> values()
Returns the values in this group. The returned list is live: changes in this list are reflected on thisParameterValueGroup
, and conversely.RestrictionsAll write operations must comply to the following conditions:- Parameters added to the list shall have one of the descriptors listed by
getDescriptor()
. - Adding or removing parameters shall not violate the parameter cardinality constraints.
InvalidParameterNameException
,InvalidParameterCardinalityException
or other runtime exceptions if a condition is not met.- Specified by:
values
in interfaceParameterValueGroup
- Returns:
- the values in this group.
- Parameters added to the list shall have one of the descriptors listed by
-
parameter
public ParameterValue<?> parameter(String name) throws ParameterNotFoundException
Returns the value in this group for the specified name. This method performs the first applicable action in the following choices:- If this group contains a parameter value of the given name, then that parameter is returned.
- Otherwise if a descriptor of the
given name exists, then a new
ParameterValue
instance is created, added to this group and returned. - Otherwise a
ParameterNotFoundException
is thrown.
double easting = parameter("False easting" ).doubleValue(); double northing = parameter("False northing").doubleValue(); parameter("False easting").setValue(500000.0);
API note: there is noparameters(String)
method returning a list of parameter values because the ISO 19111 standard fixes theParameterValue
maximum occurrence to 1.Parameters subgroupsThis method does not search recursively in subgroups. This is because more than one subgroup may exist for the same descriptor. The user have to query all subgroups and select explicitly the appropriate one.- Specified by:
parameter
in interfaceParameterValueGroup
- Parameters:
name
- the name of the parameter to search for.- Returns:
- the parameter value for the given name.
- Throws:
ParameterNotFoundException
- if there is no parameter value for the given name.- See Also:
Parameters.getValue(ParameterDescriptor)
-
groups
public List<ParameterValueGroup> groups(String name) throws ParameterNotFoundException
Returns all subgroups with the specified name.This method do not create new groups: if the requested group is optional (i.e.
minimumOccurs == 0
) and no value were defined previously, then this method returns an empty set.- Specified by:
groups
in interfaceParameterValueGroup
- Parameters:
name
- the name of the parameter to search for.- Returns:
- the set of all parameter group for the given name.
- Throws:
ParameterNotFoundException
- if no descriptor was found for the given name.
-
addGroup
public ParameterValueGroup addGroup(String name) throws ParameterNotFoundException, InvalidParameterCardinalityException
Creates a new subgroup of the specified name, and adds it to the list of subgroups. The argument shall be the name of a descriptor group which is a child of this group.API note: There is noremoveGroup(String)
method. To remove a group, users shall inspect thevalues()
list, decide which occurrences to remove if there is many of them for the same name, and whether to iterate recursively into sub-groups or not.- Specified by:
addGroup
in interfaceParameterValueGroup
- Parameters:
name
- the name of the parameter group to create.- Returns:
- a newly created parameter group for the given name.
- Throws:
ParameterNotFoundException
- if no descriptor was found for the given name.InvalidParameterCardinalityException
- if this parameter group already contains the maximum number of occurrences of subgroups of the given name.
-
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:ComparisonMode.STRICT
andBY_CONTRACT
take in account the parameter order.ComparisonMode.IGNORE_METADATA
andAPPROXIMATE
ignore the order of parameter values (but not necessarily the order of parameter descriptors).
- 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:
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:
equals
in interfaceLenientComparable
- Overrides:
equals
in classObject
- Parameters:
object
- the object to compare tothis
.- Returns:
true
if both objects are equal.- See Also:
ComparisonMode.STRICT
-
hashCode
public int hashCode()
Returns a hash value for this parameter.
-
clone
public DefaultParameterValueGroup clone()
Returns a deep copy of this group of parameter values. Included parameter values and subgroups are cloned recursively.- Specified by:
clone
in interfaceGeneralParameterValue
- Specified by:
clone
in interfaceParameterValueGroup
- Overrides:
clone
in classParameters
- Returns:
- a copy of this group of parameter values.
- See Also:
Parameters.copy(ParameterValueGroup, ParameterValueGroup)
-
-