# Interface ParameterValueGroup

All Superinterfaces:
  `GeneralParameterValue`

All Known Implementing Classes:
  `ContextualParameters, DefaultParameterValueGroup, Parameters`

@UML(identifier="CC_ParameterValueGroup", specification=ISO_19111) public interface ParameterValueGroup extends GeneralParameterValue
A group of related parameter values. The same group can be repeated more than once in an coordinate operation or higher level `ParameterValueGroup`, if those instances contain different values of one or more `ParameterValue`s which suitably distinquish among those groups.

Since:
  1.0
See Also:
  - `ParameterDescriptorGroup`
  - `ParameterValue`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ParameterValueGroup`
  `addGroup(String name)`
  Creates a new group of the specified name.
  `ParameterValueGroup`
  `clone()`
  Returns a copy of this group of parameter values.
  `ParameterDescriptorGroup`
  `getDescriptor()`
  The abstract definition of this group of parameters.
  `List<ParameterValueGroup>`
  `groups(String name)`
  Returns all subgroups with the specified name.
  `ParameterValue<?>`
  `parameter(String name)`
  Returns the value in this group for the specified identifier code.
  `List<GeneralParameterValue>`
  `values()`
  Returns the values in this group.

- ## Method Details

  - ### getDescriptor

    @UML(identifier="group", obligation=MANDATORY, specification=ISO_19111) ParameterDescriptorGroup getDescriptor()
    The abstract definition of this group of parameters.
    Specified by:
      `getDescriptor` in interface `GeneralParameterValue`
    Returns:
      The abstract definition of this parameter or group of parameters.

  - ### values

    @UML(identifier="parameterValue", obligation=MANDATORY, specification=ISO_19111) List<GeneralParameterValue> values()
    Returns the values in this group. The returned list may or may not be unmodifiable; this is implementation-dependent. However, if some aspects of this list are modifiable, then any modification shall be reflected back into this `ParameterValueGroup`. More specifically:

    - If the list supports the `add` operation, then it should ensure that the added general parameter value is valid and can be added to this group. An `InvalidParameterCardinalityException` (or any other appropriate exception) shall be thrown if it is not the case.

    - The list may also supports the `remove` operation as a way to remove parameter created by the `parameter(String)` method.

    Returns:
      The values in this group.

  - ### parameter

    ParameterValue<?> parameter(String name) throws ParameterNotFoundException
    Returns the value in this group for the specified identifier code. If no parameter value is found but a parameter descriptor is found (which may occurs if the parameter is optional, i.e. `minimumOccurs == 0`), then a parameter value is automatically created and initialized to its default value (if any).

    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"` parameter:

    > `double value = parameter("false_easting").doubleValue();`

    This method do not search recursively in subgroups. This is because more than one subgroup may exist for the same descriptor. The user must query all subgroups and select explicitly the appropriate one to use.
    Parameters:
      `name` - The case insensitive identifier code of the parameter to search for.
    Returns:
      The parameter value for the given identifier code.
    Throws:
      `ParameterNotFoundException` - if there is no parameter value for the given identifier code.

  - ### groups

    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.
    Parameters:
      `name` - The case insensitive identifier code of the parameter group to search for.
    Returns:
      The set of all parameter group for the given identifier code.
    Throws:
      `ParameterNotFoundException` - if no descriptor was found for the given name.

  - ### addGroup

    ParameterValueGroup addGroup(String name) throws ParameterNotFoundException, IllegalStateException
    Creates a new group of the specified name. The specified name must be the identifier code of a descriptor group.
    Parameters:
      `name` - The case insensitive identifier code of the parameter group to create.
    Returns:
      A newly created parameter group for the given identifier code.
    Throws:
      `ParameterNotFoundException` - if no descriptor was found for the given name.
      `InvalidParameterCardinalityException` - If this parameter group already contains the maximum number of occurences of subgroups of the given name.
      `IllegalStateException` - If the group cannot be added for another reason.

  - ### clone

    ParameterValueGroup clone()
    Returns a copy of this group of parameter values. Included parameter values and subgroups are cloned recursively.
    Specified by:
      `clone` in interface `GeneralParameterValue`
    Returns:
      A copy of this group of parameter values.