Module org.apache.sis.referencing
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 with `java​.util​.Map`:

- `parameter(String)` is similar in purpose to `Map​.get(Object)`, with an additional level of indirection in both the argument and the return value.
- `values()` is similar in purpose to `Map​.entrySet()`, with `ParameterValue` playing a role similar to `Map​.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 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 1

Assuming the descriptor defined in the `DefaultParameterDescriptorGroup` 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.

### Example 2

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.

    ParameterValue<?>[] parameter = ...;        // Defined elsewhere.
    ParameterValueGroup mercator = Mercator.PARAMETERS.createValue();
    Collections.addAll(mercator.values(), parameters);

## Removing elements

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
See Also:
  - `DefaultParameterDescriptorGroup`
  - `DefaultParameterValue`
  - Serialized Form

- ## 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

  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.
  `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.
  `ParameterDescriptorGroup`
  `getDescriptor()`
  Returns the abstract definition of this group of parameters.
  `<T> ParameterValue<T>`
  `getOrCreate(ParameterDescriptor<T> parameter)`
  Returns the parameter identified by the given descriptor.
  `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, doubleValue, doubleValueList, getDescriptors, getMandatoryValue, getMemberName, getValue, getValueDomain, intValue, intValueList, isUnmodifiable, print, stringValue, toString, unmodifiable, unmodifiable`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DefaultParameterValueGroup

    public DefaultParameterValueGroup(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(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 Details

  - ### getDescriptor

    public ParameterDescriptorGroup getDescriptor()
    Returns the abstract definition of this group of parameters.
    Specified by:
      `getDescriptor` in interface `GeneralParameterValue`
    Specified by:
      `getDescriptor` in interface `ParameterValueGroup`
    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 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 `ParameterValueGroup`
    Returns:
      the values in this group.

  - ### getOrCreate

    public <T> ParameterValue<T> getOrCreate(ParameterDescriptor<T> parameter) throws 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:
      `ParameterNotFoundException` - if the given `parameter` name or alias is not legal for this group.
    See Also:
      - `Parameters​.getValue(ParameterDescriptor)`
      - `Parameters​.getMandatoryValue(ParameterDescriptor)`
      - `parameter(String)`

  - ### 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.
    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:

        double easting  = parameter("False easting" ).doubleValue();
        double northing = parameter("False northing").doubleValue();
        parameter("False easting").setValue(500000.0);

    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 `ParameterValueGroup`
    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. 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 `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:
      `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.

    #### Group removal

    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 `ParameterValueGroup`
    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` and `BY_CONTRACT` take in account the parameter order.
    - `ComparisonMode​.IGNORE_METADATA` and `APPROXIMATE` ignore the order of parameter values (but not necessarily the order of parameter descriptors).
    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:
      - `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:

        return equals(other, ComparisonMode.STRICT);

    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:
      - `ComparisonMode​.STRICT`

  - ### 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 `GeneralParameterValue`
    Specified by:
      `clone` in interface `ParameterValueGroup`
    Overrides:
      `clone` in class `Parameters`
    Returns:
      a copy of this group of parameter values.
    See Also:
      - `Parameters​.copy(ParameterValueGroup, ParameterValueGroup)`