Package org.apache.sis.parameter
Class DefaultParameterValueGroup
java.lang.Object
org.apache.sis.parameter.Parameters
org.apache.sis.parameter.DefaultParameterValueGroup
- All Implemented Interfaces:
Serializable
,Cloneable
,LenientComparable
,org.opengis.parameter.GeneralParameterValue
,org.opengis.parameter.ParameterValueGroup
- Direct Known Subclasses:
MapProjectionParameters
public class DefaultParameterValueGroup
extends Parameters
implements LenientComparable, Serializable
A group of related parameter values. Parameter groups have some similarities with
java.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 constraints
ParameterValueGroup
instances are typically created by calls to
descriptor.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
an InvalidParameterCardinalityException
will be thrown.
Setting the parameter values
After a newParameterValueGroup
instance has been created, the parameter values can be set by chaining
calls to parameter(String)
with one of the setValue(…)
methods defined in the returned object
(see the table of setter methods). The parameter(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 the
Alternatively, if all parameters were created elsewhere and the user wants to copy them in a new
parameter group, the DefaultParameterDescriptorGroup
example,
one can set Mercator (variant A) projection parameters as below:
List.addAll(Collection)
method can be invoked on the values list.
Example:
Optional parameters can be removed by the usual List.remove(int)
or List.remove(Object)
operations on the values list. But attempts to remove a mandatory parameter will cause an
InvalidParameterCardinalityException
to be thrown.
Calls to values().clear()
restore this DefaultParameterValueGroup
to its initial state.
- Since:
- 0.4
- Version:
- 1.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
Serial number for inter-operability with different versions.private ParameterValueList
Contains the descriptor and the parameter values for this group. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Default constructor for JAXB only.DefaultParameterValueGroup
(org.opengis.parameter.ParameterDescriptorGroup descriptor) Creates a parameter group from the specified descriptor.DefaultParameterValueGroup
(org.opengis.parameter.ParameterValueGroup parameters) Creates a new instance initialized with all values from the specified parameter group. -
Method Summary
Modifier and TypeMethodDescriptionorg.opengis.parameter.ParameterValueGroup
Creates a new subgroup of the specified name, and adds it to the list of subgroups.clone()
Returns a deep copy of this group of parameter values.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.(package private) static boolean
equals
(Parameters expected, org.opengis.parameter.ParameterValueGroup actual, ComparisonMode mode) Compares the given objects for equality, ignoring parameter order in "ignore metadata" mode.org.opengis.parameter.ParameterDescriptorGroup
Returns the abstract definition of this group of parameters.<T> org.opengis.parameter.ParameterValue
<T> getOrCreate
(org.opengis.parameter.ParameterDescriptor<T> parameter) Returns the parameter identified by the given descriptor.(package private) final org.opengis.parameter.ParameterValue
<?> getParameter
(org.opengis.parameter.ParameterDescriptor<?> parameter) Returns the parameter value for the specified operation parameter, overridden for performance reasons.private org.opengis.parameter.GeneralParameterValue[]
Invoked by JAXB for getting the parameters to marshal.List
<org.opengis.parameter.ParameterValueGroup> Returns all subgroups with the specified name.int
hashCode()
Returns a hash value for this parameter.(package private) boolean
Conservatively returnsfalse
if this instance is for a subclass, because we do not know if the subclass overridesparameter(String)
in a way incompatible withparameterIfExist(String)
.org.opengis.parameter.ParameterValue
<?> Returns the value in this group for the specified name.(package private) org.opengis.parameter.ParameterValue
<?> parameterIfExist
(String name) Returns the value in this group for the specified name if it exists, ornull
if none.private void
setDescriptor
(org.opengis.parameter.ParameterDescriptorGroup descriptor) Invoked by JAXB for setting the group parameter descriptor.private void
setValues
(org.opengis.parameter.GeneralParameterValue[] parameters) Invoked by JAXB for setting the unmarshalled parameters.private void
setValues
(org.opengis.parameter.GeneralParameterValue[] parameters, Map<org.opengis.parameter.GeneralParameterDescriptor, org.opengis.parameter.GeneralParameterDescriptor> replacements, ParameterValueList addTo) Appends all parameter values.List
<org.opengis.parameter.GeneralParameterValue> values()
Returns the values in this group.Methods inherited from class org.apache.sis.parameter.Parameters
booleanValue, cast, cast, castOrWrap, copy, doubleValue, doubleValue, doubleValueList, getDescriptors, getMandatoryValue, getMemberName, getValue, getValueDomain, intValue, intValueList, isUnmodifiable, print, stringValue, toString, unmodifiable, unmodifiable
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
values
Contains the descriptor and the parameter values for this group.Consider this field as final! This field is modified only by the
clone()
method and at unmarshalling time bysetValues(GeneralParameterValue[])
- See Also:
-
-
Constructor Details
-
DefaultParameterValueGroup
public DefaultParameterValueGroup(org.opengis.parameter.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(org.opengis.parameter.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:
-
DefaultParameterValueGroup
private DefaultParameterValueGroup()Default constructor for JAXB only. The values list is initialized tonull
, but will be assigned a value after XML unmarshalling.
-
-
Method Details
-
isKnownImplementation
boolean isKnownImplementation()Conservatively returnsfalse
if this instance is for a subclass, because we do not know if the subclass overridesparameter(String)
in a way incompatible withparameterIfExist(String)
. (note: usingClass.getMethod(…).getDeclaringClass()
is presumed not worth the cost.- Overrides:
isKnownImplementation
in classParameters
-
getDescriptor
public org.opengis.parameter.ParameterDescriptorGroup getDescriptor()Returns the abstract definition of this group of parameters.- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.GeneralParameterValue
- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.ParameterValueGroup
- Returns:
- the abstract definition of this group of parameters.
-
values
Returns the values in this group. The returned list is live: changes in this list are reflected on thisParameterValueGroup
, and conversely.Restrictions
All 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 interfaceorg.opengis.parameter.ParameterValueGroup
- Returns:
- the values in this group.
- Parameters added to the list shall have one of the descriptors listed by
-
getOrCreate
public <T> org.opengis.parameter.ParameterValue<T> getOrCreate(org.opengis.parameter.ParameterDescriptor<T> parameter) throws org.opengis.parameter.ParameterNotFoundException Returns the parameter identified by the given descriptor. If the identified parameter is optional and not yet created, then it will be created now.- Overrides:
getOrCreate
in classParameters
- Type Parameters:
T
- the type of the parameter value.- Parameters:
parameter
- the parameter to look for.- Returns:
- the requested parameter instance.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if the givenparameter
name or alias is not legal for this group.- See Also:
-
getParameter
final org.opengis.parameter.ParameterValue<?> getParameter(org.opengis.parameter.ParameterDescriptor<?> parameter) throws org.opengis.parameter.ParameterNotFoundException Returns the parameter value for the specified operation parameter, overridden for performance reasons. This implementation first compares descriptor references. If this quick search finds no result, then the more costly search implemented in parent class is used as a fallback. The quick search implemented here is should cover at least the cases of allorg.apache.sis.referencing.operation.projection
class initializations.- Overrides:
getParameter
in classParameters
- Parameters:
parameter
- the parameter to search.- Returns:
- the requested parameter value, or
null
if none. - Throws:
org.opengis.parameter.ParameterNotFoundException
- if the givenparameter
name or alias is not legal for this group.
-
parameter
public org.opengis.parameter.ParameterValue<?> parameter(String name) throws org.opengis.parameter.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.
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 subgroups
This 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 interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- the name of the parameter to search for.- Returns:
- the parameter value for the given name.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if there is no parameter value for the given name.- See Also:
-
parameterIfExist
org.opengis.parameter.ParameterValue<?> parameterIfExist(String name) throws org.opengis.parameter.ParameterNotFoundException Returns the value in this group for the specified name if it exists, ornull
if none. This method avoid creating newParameterValue
instance when no value exists for the given parameter name.- Overrides:
parameterIfExist
in classParameters
- Throws:
org.opengis.parameter.ParameterNotFoundException
- See Also:
-
groups
public List<org.opengis.parameter.ParameterValueGroup> groups(String name) throws org.opengis.parameter.ParameterNotFoundException Returns all subgroups with the specified name. Groups are listed in the order they were added by calls toaddGroup(String)
.This method does 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 interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- the name of the parameter to search for.- Returns:
- the list of all parameter group for the given name, in insertion order.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if no descriptor was found for the given name.
-
addGroup
public org.opengis.parameter.ParameterValueGroup addGroup(String name) throws org.opengis.parameter.ParameterNotFoundException, org.opengis.parameter.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 can inspect thegroups(String)
orvalues()
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 interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- the name of the parameter group to create.- Returns:
- a newly created parameter group for the given name.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if no descriptor was found for the given name.org.opengis.parameter.InvalidParameterCardinalityException
- if this parameter group already contains the maximum number of occurrences of subgroups of the given name.
-
equals
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:
-
equals
static boolean equals(Parameters expected, org.opengis.parameter.ParameterValueGroup actual, ComparisonMode mode) Compares the given objects for equality, ignoring parameter order in "ignore metadata" mode. -
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. -
clone
Returns a deep copy of this group of parameter values. Included parameter values and subgroups are cloned recursively.- Specified by:
clone
in interfaceorg.opengis.parameter.GeneralParameterValue
- Specified by:
clone
in interfaceorg.opengis.parameter.ParameterValueGroup
- Overrides:
clone
in classParameters
- Returns:
- a copy of this group of parameter values.
- See Also:
-
setDescriptor
private void setDescriptor(org.opengis.parameter.ParameterDescriptorGroup descriptor) Invoked by JAXB for setting the group parameter descriptor. Those parameter are redundant with the parameters associated to the values given tosetValues(GeneralParameterValue[])
, except for the group identification (name, etc.) and for any optional parameters which were not present in the aboveGeneralParameterValue
array.- See Also:
-
getValues
private org.opengis.parameter.GeneralParameterValue[] getValues()Invoked by JAXB for getting the parameters to marshal. -
setValues
private void setValues(org.opengis.parameter.GeneralParameterValue[] parameters) Invoked by JAXB for setting the unmarshalled parameters. This method should be invoked last (aftersetDescriptor(ParameterDescriptorGroup)
) even if theparameterValue
elements were first in the XML document. This is the case at least with the JAXB reference implementation, because the property type is an array (it would not work with a list).Maintenance note: the
"setValues"
method name is also hard-coded inCC_GeneralOperationParameter
for logging purpose. -
setValues
private void setValues(org.opengis.parameter.GeneralParameterValue[] parameters, Map<org.opengis.parameter.GeneralParameterDescriptor, org.opengis.parameter.GeneralParameterDescriptor> replacements, ParameterValueList addTo) Appends all parameter values. In this process, we may need to update the descriptor of some values if those descriptors changed as a result of the above merge process.- Parameters:
parameters
- the parameters to add, ornull
forvalues
.replacements
- the replacements to apply in theGeneralParameterValue
instances.addTo
- where to store the new values.
-