Package org.apache.sis.parameter

## Class ParameterBuilder

- Object
- - Builder<ParameterBuilder>
  - - ParameterBuilder

-     public class ParameterBuilder
      extends Builder<ParameterBuilder>

  Helper class for parameter descriptor instantiations. This builder can be helpful to operation or process providers (e.g. map projection implementers). Operation users do not need this builder since they can invoke `ParameterDescriptor​.createValue()` on the descriptor provided by the implementer.
  Identification properties
  The following properties are cleared after a call to any `createXXX(…)` method, since those properties are specific to the each parameter. Other properties like codespace, version and multiplicity are left unchanged because they may be shared by many parameters.
  - Names: each parameter must have a name, which can be specified by any of the `addName(…)` methods. Parameters can optionally have an arbitrary amount of aliases, which are also specified by the `addName(…)` methods. Each call after the first one adds an alias.
  - Identifiers: parameters can also have an arbitrary amount of identifiers, which are specified by any of the `addIdentifier(…)` methods. Like names, more than one identifier can be added by invoking the method many time.
  - Remarks: parameters can have at most one remark, which is specified by the `setRemarks(…)` method.
  Usage example
  Parameter descriptors are typically grouped in a `ParameterDescriptorGroup`. All parameters usually have the same namespace, which can be declared only once. The following example creates parameters for "Mercator (variant A)" projection method (EPSG:9804), previously known as "Mercator (1SP)", centered by default on (0°,0°) with no scale factor and no false easting/northing. The projection is valid from 80°S to 84°N and on all the longitude range (±180°). In this example, the "Longitude of natural origin" parameter is giving different aliases for illustrating the case of different software libraries or standards using different conventions.

  >     ParameterBuilder builder = new ParameterBuilder();
  >     builder.setCodeSpace(Citations.EPSG, "EPSG")                   // The default namespace to be used below.
  >            .setRequired(true);                                     // All parameters will be considered mandatory.

  >     // Constructs the list of parameters.
  >     ParameterDescriptor<?>[] parameters = {
  >         builder.addName("Latitude of natural origin")              // Name in the default namespace ("EPSG" in this example).
  >                .createBounded( -80,  +84, 0, Units.DEGREE),        // Latitude of Mercator projection can not go to the poles.

  >         builder.addIdentifier("8802")                              // Primary key in default namespace ("EPSG" in this example).
  >                .addName("Longitude of natural origin")             // Primary name in default namespace ("EPSG" in this example).
  >                .addName(Citations.OGC, "central_meridian")         // First alias in "OGC" namespace.
  >                .addName(Citations.GEOTIFF, "NatOriginLong")        // Second alias in "GeoTIFF" namespace.
  >                .createBounded(-180, +180, 0, Units.DEGREE),        // Projection is valid on all the longitude range (±180°).

  >         builder.addName("Scale factor at natural origin")
  >                .createStrictlyPositive(1, Units.UNITY),

  >         builder.addName("False easting")
  >                .create(0, Units.METRE),

  >         builder.addName("False northing")
  >                .create(0, Units.METRE)
  >     };

  >     // Put all above parameters in a group.
  >     ParameterDescriptorGroup group = builder
  >             .addIdentifier("9804")                                 // Defined in implicit "EPSG" namespace.
  >             .addName      ("Mercator (variant A)")                 // Defined in implicit "EPSG" namespace.
  >             .addName      ("Mercator (1SP)")                       // Defined in implicit "EPSG" namespace.
  >             .addName      (Citations.OGC, "Mercator_1SP")          // "OGC" namespace explicitly shown by toString().
  >             .addName      (Citations.GEOTIFF, "CT_Mercator")       // "GeoTIFF" namespace explicitly shown by toString().
  >             .addIdentifier(Citations.GEOTIFF, "7")
  >             .setRemarks   ("The “Mercator (1SP)” method name was used prior to October 2010.")
  >             .createGroupForMapProjection(parameters);

  Since:
    0.4

  Defined in the `sis-referencing` module

- - ### Field Summary

    - ### Fields inherited from class Builder

      `properties`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ParameterBuilder()` | Creates a new builder.
    `ParameterBuilder​(GeneralParameterDescriptor descriptor)` | Creates a new builder initialized to properties of the given object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ParameterDescriptor<Double>` | `create​(double defaultValue, Unit<?> unit)` | Creates a descriptor for floating point values without domain restriction.
    `<T> ParameterDescriptor<T>` | `create​(Class<T> valueClass, T defaultValue)` | Creates a descriptor for values of the given type without domain restriction.
    `ParameterDescriptor<Double>` | `createBounded​(double minimumValue, double maximumValue, double defaultValue, Unit<?> unit)` | Creates a descriptor for floating point values restricted to the given domain.
    `ParameterDescriptor<Integer>` | `createBounded​(int minimumValue, int maximumValue, int defaultValue)` | Creates a descriptor for integer values restricted to the given domain.
    `<T extends Comparable<? super T>> ParameterDescriptor<T>` | `createBounded​(Class<T> valueClass, T minimumValue, T maximumValue, T defaultValue)` | Creates a descriptor for values of the given type restricted to the given domain.
    `<T extends Comparable<? super T>> ParameterDescriptor<T>` | `createBounded​(Range<T> valueDomain, T defaultValue)` | Creates a descriptor for values in the domain represented by the given `Range` object.
    `<T> ParameterDescriptor<T>` | `createEnumerated​(Class<T> valueClass, T[] validValues, T defaultValue)` | Creates a descriptor for a parameter restricted to a set of valid values.
    `ParameterDescriptorGroup` | `createGroup​(int minimumOccurs, int maximumOccurs, GeneralParameterDescriptor... parameters)` | Creates a descriptor group for the given multiplicity and parameters.
    `ParameterDescriptorGroup` | `createGroup​(GeneralParameterDescriptor... parameters)` | Creates a descriptor group for the given parameters.
    `ParameterDescriptorGroup` | `createGroupForMapProjection​(ParameterDescriptor<?>... parameters)` | Creates a descriptor group for a map projection.
    `ParameterDescriptorGroup` | `createGroupWithSameParameters​(ParameterDescriptorGroup parameters)` | Creates a descriptor group with the same parameters than another group.
    `ParameterDescriptor<Double>` | `createStrictlyPositive​(double defaultValue, Unit<?> unit)` | Creates a descriptor for floating point values greater than zero.
    `ParameterBuilder` | `setRequired​(boolean required)` | Sets whether the parameter is mandatory or optional.

    - ### Methods inherited from class Builder

      `addIdentifier, addIdentifier, addIdentifier, addName, addName, addName, addName, addNamesAndIdentifiers, onCreate, reidentify, rename, setCodeSpace, setDeprecated, setDescription, setRemarks, setVersion`

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ParameterBuilder

          public ParameterBuilder()

      Creates a new builder.

    - #### ParameterBuilder

          public ParameterBuilder​(GeneralParameterDescriptor descriptor)

      Creates a new builder initialized to properties of the given object.
      Parameters:
        `descriptor` - the descriptor from which to inherit properties, or `null`.
      Since:
        0.6

  - ### Method Detail

    - #### setRequired

          public ParameterBuilder setRequired​(boolean required)

      Sets whether the parameter is mandatory or optional. This property determines the minimum number of times that values are required, which will be 0 for an optional parameter and 1 for a mandatory one.

      Default value: If this method is never invoked, then the default value is `false`.

      Lifetime: this property is kept unchanged until this `setRequired(…)` method is invoked again.

      API note: the `maximum number of occurrences` is fixed to 1 and can not be changed with this builder (except for parameters group) because `DefaultParameterValueGroup​.parameter(String)` can return only one value. Allowing to return more than one value would complicate the API for an uncommon case. If nevertheless a maximum number of occurrences greater than 1 is really desired, Apache SIS supports this feature but users have to create the `DefaultParameterDescriptor` instance themselves.
      Parameters:
        `required` - `true` for a mandatory parameter, or `false` for an optional one.
      Returns:
        `this`, for method call chaining.

    - #### create

          public <T> ParameterDescriptor<T> create​(Class<T> valueClass,
                                                   T defaultValue)

      Creates a descriptor for values of the given type without domain restriction.
      Type Parameters:
        `T` - the compile-time type of the `valueClass` argument.
      Parameters:
        `valueClass` - the class that describe the type of the parameter values.
        `defaultValue` - the default value for the parameter, or `null` if none.
      Returns:
        the parameter descriptor for the given default value and unit.

    - #### create

          public ParameterDescriptor<Double> create​(double defaultValue,
                                                    Unit<?> unit)

      Creates a descriptor for floating point values without domain restriction. All `double` values are considered valid.
      Parameters:
        `defaultValue` - the default value for the parameter, or `Double​.NaN` if none.
        `unit` - the default unit, or `null` if none.
      Returns:
        the parameter descriptor for the given default value and unit.

    - #### createStrictlyPositive

          public ParameterDescriptor<Double> createStrictlyPositive​(double defaultValue,
                                                                    Unit<?> unit)

      Creates a descriptor for floating point values greater than zero. The zero value is not considered valid. There is no maximal value.
      Parameters:
        `defaultValue` - the default value for the parameter, or `Double​.NaN` if none.
        `unit` - the default unit, or `null` if none.
      Returns:
        the parameter descriptor for the given default value and unit.

    - #### createBounded

          public ParameterDescriptor<Double> createBounded​(double minimumValue,
                                                           double maximumValue,
                                                           double defaultValue,
                                                           Unit<?> unit)

      Creates a descriptor for floating point values restricted to the given domain.
      Parameters:
        `minimumValue` - the minimum parameter value (inclusive), or `Double​.NEGATIVE_INFINITY` if none.
        `maximumValue` - the maximum parameter value (inclusive), or `Double​.POSITIVE_INFINITY` if none.
        `defaultValue` - the default value for the parameter, or `Double​.NaN` if none.
        `unit` - the unit for default, minimum and maximum values, or `null` if none.
      Returns:
        the parameter descriptor for the given domain of values.

    - #### createBounded

          public ParameterDescriptor<Integer> createBounded​(int minimumValue,
                                                            int maximumValue,
                                                            int defaultValue)

      Creates a descriptor for integer values restricted to the given domain.
      Parameters:
        `minimumValue` - the minimum parameter value (inclusive).
        `maximumValue` - the maximum parameter value (inclusive).
        `defaultValue` - the default value for the parameter.
      Returns:
        the parameter descriptor for the given domain of values.

    - #### createBounded

          public <T extends Comparable<? super T>> ParameterDescriptor<T> createBounded​(Class<T> valueClass,
                                                                                        T minimumValue,
                                                                                        T maximumValue,
                                                                                        T defaultValue)

      Creates a descriptor for values of the given type restricted to the given domain.
      Type Parameters:
        `T` - the compile-time type of the `valueClass` argument.
      Parameters:
        `valueClass` - the class that describe the type of the parameter values.
        `minimumValue` - the minimum parameter value (inclusive), or `null` if none.
        `maximumValue` - the maximum parameter value (inclusive), or `null` if none.
        `defaultValue` - the default value for the parameter, or `null` if none.
      Returns:
        the parameter descriptor for the given domain of values.

    - #### createBounded

          public <T extends Comparable<? super T>> ParameterDescriptor<T> createBounded​(Range<T> valueDomain,
                                                                                        T defaultValue)

      Creates a descriptor for values in the domain represented by the given `Range` object. This method allows to specify whether the minimum and maximum values are inclusive or not.
      Type Parameters:
        `T` - the type of the parameter values.
      Parameters:
        `valueDomain` - the minimum value, maximum value and unit of measurement.
        `defaultValue` - the default value for the parameter, or `null` if none.
      Returns:
        the parameter descriptor for the given domain of values.

    - #### createEnumerated

          public <T> ParameterDescriptor<T> createEnumerated​(Class<T> valueClass,
                                                             T[] validValues,
                                                             T defaultValue)

      Creates a descriptor for a parameter restricted to a set of valid values. The descriptor has no minimal or maximal value and no unit.

      The `validValues` property is mostly for restricting values to a code list or enumeration subset. It is not necessary to provide this property when all values from the code list or enumeration are valid.

      Type Parameters:
        `T` - the compile-time type of the `valueClass` argument.
      Parameters:
        `valueClass` - the class that describe the type of the parameter values.
        `validValues` - a finite set of valid values (usually from a code list or enumeration) or `null` if it doesn't apply.
        `defaultValue` - the default value for the parameter, or `null` if none.
      Returns:
        the parameter descriptor for the given set of valid values.

    - #### createGroup

          public ParameterDescriptorGroup createGroup​(int minimumOccurs,
                                                      int maximumOccurs,
                                                      GeneralParameterDescriptor... parameters)

      Creates a descriptor group for the given multiplicity and parameters.
      Parameters:
        `minimumOccurs` - the minimum number of times that values for this parameter group are required.
        `maximumOccurs` - the maximum number of times that values for this parameter group are required.
        `parameters` - the parameter descriptors for the group to create.
      Returns:
        the parameter descriptor group.

    - #### createGroup

          public ParameterDescriptorGroup createGroup​(GeneralParameterDescriptor... parameters)

      Creates a descriptor group for the given parameters. This is a convenience method for `createGroup(int, int, GeneralParameterDescriptor[])` with a multiplicity of [0 … 1] or [1 … 1] depending on the value given to the last call to `setRequired(boolean)`.
      Parameters:
        `parameters` - the parameter descriptors for the group to create.
      Returns:
        the parameter descriptor group.

    - #### createGroupWithSameParameters

          public ParameterDescriptorGroup createGroupWithSameParameters​(ParameterDescriptorGroup parameters)

      Creates a descriptor group with the same parameters than another group. This is a convenience constructor for operations that expect the same parameters than another operation, but perform a different process.
      Example: the various "Coordinate Frame Rotation" variants (EPSG codes 1032, 1038 and 9607) expect the same parameters than their "Position Vector transformation" counterpart (EPSG codes 1033, 1037 and 9606) but perform the rotation in the opposite direction.
      Parameters:
        `parameters` - the existing group from which to copy the parameters.
      Returns:
        the parameter descriptor group.
      Since:
        0.7

    - #### createGroupForMapProjection

          public ParameterDescriptorGroup createGroupForMapProjection​(ParameterDescriptor<?>... parameters)

      Creates a descriptor group for a map projection. This method automatically adds mandatory parameters for the semi-major and semi-minor axis length. Those parameters are usually not explicitly included in parameter definitions since the axis lengths can be inferred from the ellipsoid. However `DefaultMathTransformFactory` needs them.

      In addition, this method adds hidden parameters for alternative ways to express some standard parameters. Those hidden parameters never appear in the list of parameters. However when one of those parameters is read or written, the work will be delegated to the standard parameters.

      Parameters automatically added by this method
      Name | Visibility | Comment
      --- | --- | ---
      `"semi_major"` | Always | Standard parameter defined by WKT 1.
      `"semi_minor"` | Always | Standard parameter defined by WKT 1.
      `"earth_radius"` | Hidden | Mapped to `"semi_major"` and `"semi_minor"` parameters.
      `"inverse_flattening"` | Hidden | Computed from the `"semi_major"` and `"semi_minor"` parameters.
      `"standard_parallel"` | Hidden | Array of 1 or 2 elements mapped to `"standard_parallel_1"` and `"standard_parallel_2"`.

      Note: When the `"earth_radius"` parameter is read, its value is the authalic radius computed from the semi-major and semi-minor axis lengths.
      Map projection parameter groups always have a minimum and maximum occurrence of 1, regardless the value given to `setRequired(boolean)`.
      Parameters:
        `parameters` - the parameter descriptors for the group to create.
      Returns:
        the parameter descriptor group for a map projection.
      Since:
        0.6