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:

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 new ParameterValueGroup 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 DefaultParameterDescriptorGroup example, one can set Mercator (variant A) projection parameters as below:
Alternatively, if all parameters were created elsewhere and the user wants to copy them in a new parameter group, the 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

    Fields
    Modifier and Type
    Field
    Description
    private static final long
    serialVersionUID
    Serial number for inter-operability with different versions.
    private ParameterValueList
    values
    Contains the descriptor and the parameter values for this group.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    DefaultParameterValueGroup()
    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 Type
    Method
    Description
    org.opengis.parameter.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.
    final 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.
    (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
    getDescriptor()
    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[]
    getValues()
    Invoked by JAXB for getting the parameters to marshal.
    List<org.opengis.parameter.ParameterValueGroup>
    groups(String name)
    Returns all subgroups with the specified name.
    int
    hashCode()
    Returns a hash value for this parameter.
    (package private) boolean
    isKnownImplementation()
    Conservatively returns false if this instance is for a subclass, because we do not know if the subclass overrides parameter(String) in a way incompatible with parameterIfExist(String).
    org.opengis.parameter.ParameterValue<?>
    parameter(String name)
    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, or null 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

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

  • 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 invoking descriptor.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 to null, but will be assigned a value after XML unmarshalling.

  • Method Details

    • isKnownImplementation

      boolean isKnownImplementation()
      Conservatively returns false if this instance is for a subclass, because we do not know if the subclass overrides parameter(String) in a way incompatible with parameterIfExist(String). (note: using Class.getMethod(…).getDeclaringClass() is presumed not worth the cost.
      Overrides:
      isKnownImplementation in class Parameters

    • getDescriptor

      public org.opengis.parameter.ParameterDescriptorGroup getDescriptor()
      Returns the abstract definition of this group of parameters.
      Specified by:
      getDescriptor in interface org.opengis.parameter.GeneralParameterValue
      Specified by:
      getDescriptor in interface org.opengis.parameter.ParameterValueGroup
      Returns:
      the abstract definition of this group of parameters.

    • values

      public List<org.opengis.parameter.GeneralParameterValue> values()
      Returns the values in this group. The returned list is live: changes in this list are reflected on this ParameterValueGroup, 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.
      The list will verify those conditions and throws InvalidParameterNameException, InvalidParameterCardinalityException or other runtime exceptions if a condition is not met.
      Specified by:
      values in interface org.opengis.parameter.ParameterValueGroup
      Returns:
      the values in this group.

    • 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 class Parameters
      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 given parameter 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 all org.apache.sis.referencing.operation.projection class initializations.
      Overrides:
      getParameter in class Parameters
      Parameters:
      parameter - the parameter to search.
      Returns:
      the requested parameter value, or null if none.
      Throws:
      org.opengis.parameter.ParameterNotFoundException - if the given parameter 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.
      This convenience method provides a way to get and set parameter values by name. For example, the following idiom fetches a floating point value for the False easting and False northing parameters and set a new value for the False easting one:
      API note: there is no parameters(String) method returning a list of parameter values because the ISO 19111 standard fixes the ParameterValue 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 interface org.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, or null if none. This method avoid creating new ParameterValue instance when no value exists for the given parameter name.
      Overrides:
      parameterIfExist in class Parameters
      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 to addGroup(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 interface org.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 no removeGroup(String) method. To remove a group, users can inspect the groups(String) or values() 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 interface org.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

      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:
      equals in interface LenientComparable
      Parameters:
      object - the object to compare to this.
      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

      public final boolean equals(Object object)
      Compares the specified object with this parameter for equality. This method is implemented as below: Subclasses shall override equals(Object, ComparisonMode) instead of this method.
      Specified by:
      equals in interface LenientComparable
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare to this.
      Returns:
      true if both objects are equal.
      See Also:

    • hashCode

      public int hashCode()
      Returns a hash value for this parameter.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value. This value does not need to be the same in past or future versions of this class.

    • 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 interface org.opengis.parameter.GeneralParameterValue
      Specified by:
      clone in interface org.opengis.parameter.ParameterValueGroup
      Overrides:
      clone in class Parameters
      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 to setValues(GeneralParameterValue[]), except for the group identification (name, etc.) and for any optional parameters which were not present in the above GeneralParameterValue 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 (after setDescriptor(ParameterDescriptorGroup)) even if the parameterValue 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 in CC_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, or null for values.
      replacements - the replacements to apply in the GeneralParameterValue instances.
      addTo - where to store the new values.