Package org.apache.sis.parameter

## Class DefaultParameterDescriptor<T>

- Object
- - FormattableObject
  - - AbstractIdentifiedObject
    - - AbstractParameterDescriptor
      - - DefaultParameterDescriptor<T>

- Type Parameters:
    `T` - the type of elements to be returned by `DefaultParameterValue​.getValue()`.
  All Implemented Interfaces:
    `Serializable`, `Deprecable`, `LenientComparable`, `GeneralParameterDescriptor`, `ParameterDescriptor<T>`, `IdentifiedObject`

      public class DefaultParameterDescriptor<T>
      extends AbstractParameterDescriptor
      implements ParameterDescriptor<T>

  The definition of a single parameter used by an operation method. For Coordinate Reference Systems most parameter values are numeric, but other types of parameter values are possible.

  A parameter descriptor contains the following properties:

  - The parameter name.
  - The class of values. This is usually `Double`, `double[]`, `Integer`, `int[]`, `Boolean`, `String` or `URI`, but other types are allowed as well.
  - Whether this parameter is optional or mandatory. This is specified by the minimum occurences number, which can be 0 or 1 respectively.
  - The domain of values, as a minimum value, maximum value or an enumeration of valid values.
  - The default value.
  - The unit of measurement.
  Since:
    0.4
  See Also:
    `DefaultParameterValue`, `DefaultParameterDescriptorGroup`, Serialized Form

  Defined in the `sis-referencing` module

- - ### Field Summary

    - ### Fields inherited from class AbstractIdentifiedObject

      `DEPRECATED_KEY, LOCALE_KEY`

    - ### Fields inherited from interface IdentifiedObject

      `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `DefaultParameterDescriptor​(Map<String,​?> properties, int minimumOccurs, int maximumOccurs, Class<T> valueClass, Range<?> valueDomain, T[] validValues, T defaultValue)` | Constructs a descriptor from the given properties.
    `protected` | `DefaultParameterDescriptor​(ParameterDescriptor<T> descriptor)` | Creates a new descriptor with the same values than the specified one.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static <T> DefaultParameterDescriptor<T>` | `castOrCopy​(ParameterDescriptor<T> object)` | Returns a SIS parameter implementation with the same values than the given arbitrary implementation.
    `protected long` | `computeHashCode()` | Invoked by `AbstractIdentifiedObject​.hashCode()` for computing the hash code when first needed.
    `ParameterValue<T>` | `createValue()` | Creates a new parameter value instance initialized with the default value.
    `boolean` | `equals​(Object object, ComparisonMode mode)` | Compares the specified object with this parameter for equality.
    `T` | `getDefaultValue()` | Returns the default value for the parameter.
    `Class<? extends ParameterDescriptor<T>>` | `getInterface()` | Returns the GeoAPI interface implemented by this class.
    `Comparable<T>` | `getMaximumValue()` | Returns the maximum parameter value.
    `Comparable<T>` | `getMinimumValue()` | Returns the minimum parameter value.
    `Unit<?>` | `getUnit()` | Returns the unit of measurement for the minimum, maximum and default values.
    `Set<T>` | `getValidValues()` | If this parameter allows only a finite set of values, returns that set.
    `Class<T>` | `getValueClass()` | Returns the class that describe the type of the parameter.
    `Range<?>` | `getValueDomain()` | Returns the domain of values with their unit of measurement (if any), or `null` if none.

    - ### Methods inherited from class AbstractParameterDescriptor

      `formatTo, getMaximumOccurs, getMinimumOccurs, print, toString`

    - ### Methods inherited from class AbstractIdentifiedObject

      `castOrCopy, equals, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName`

    - ### Methods inherited from class FormattableObject

      `toString, toWKT`

    - ### Methods inherited from class Object

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

    - ### Methods inherited from interface GeneralParameterDescriptor

      `getMaximumOccurs, getMinimumOccurs`

    - ### Methods inherited from interface IdentifiedObject

      `getAlias, getIdentifiers, getName, getRemarks, toWKT`

- - ### Constructor Detail

    - #### DefaultParameterDescriptor

          public DefaultParameterDescriptor​(Map<String,​?> properties,
                                            int minimumOccurs,
                                            int maximumOccurs,
                                            Class<T> valueClass,
                                            Range<?> valueDomain,
                                            T[] validValues,
                                            T defaultValue)

      Constructs a descriptor from the given properties. The properties map is given unchanged to the super-class constructor. The following table is a reminder of main (not all) properties:

      Recognized properties (non exhaustive list)
      Property name | Value type | Returned by
      --- | --- | ---
      "name" | `ReferenceIdentifier` or `String` | `AbstractIdentifiedObject.getName()`
      "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
      "identifiers" | `ReferenceIdentifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
      "description" | `InternationalString` or `String` | `AbstractIdentifiedObject.getDescription()`
      "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`

      The `valueDomain` argument combines the minimum value, maximum value, unit of measurement (if any) and information about whether the bounds are inclusive or exclusive. If this argument is non-null, then it shall comply to the following conditions:
      - The range shall be non-empty.
      - `valueDomain.getElementType()` shall be equals to one of the following:
        - to `valueClass` if the later is not an array,
        - or to `primitiveToWrapper(valueClass.getComponentType())` if `valueClass` is an array.
      If both `valueDomain` and `validValues` are non-null, then all valid values shall be contained in the value domain.
      Parameters:
        `properties` - the properties to be given to the identified object.
        `minimumOccurs` - the minimum number of times that values for this parameter group are required, or 0 if no restriction.
        `maximumOccurs` - the maximum number of times that values for this parameter group are required, or `Integer​.MAX_VALUE` if no restriction.
        `valueClass` - the class that describes the type of the parameter value.
        `valueDomain` - the minimum value, maximum value and unit of measurement, or `null` if none.
        `validValues` - the list of valid values, or `null` if there is no restriction. This 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.
        `defaultValue` - the default value for the parameter, or `null` if none.

    - #### DefaultParameterDescriptor

          protected DefaultParameterDescriptor​(ParameterDescriptor<T> descriptor)

      Creates a new descriptor with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.

      This constructor performs a shallow copy, i.e. the properties are not cloned.

      Parameters:
        `descriptor` - the descriptor to shallow copy.
      See Also:
        `castOrCopy(ParameterDescriptor)`

  - ### Method Detail

    - #### castOrCopy

          public static <T> DefaultParameterDescriptor<T> castOrCopy​(ParameterDescriptor<T> object)

      Returns a SIS parameter implementation with the same values than the given arbitrary implementation. If the given object is `null`, then this method returns `null`. Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged. Otherwise a new SIS implementation is created and initialized to the values of the given object.
      Type Parameters:
        `T` - the type of values.
      Parameters:
        `object` - the object to get as a SIS implementation, or `null` if none.
      Returns:
        a SIS implementation containing the values of the given object (may be the given object itself), or `null` if the argument was null.

    - #### getInterface

          public Class<? extends ParameterDescriptor<T>> getInterface()

      Returns the GeoAPI interface implemented by this class. The SIS implementation returns `ParameterDescriptor​.class`.
      Note for implementers: Subclasses usually do not need to override this method since GeoAPI does not define `ParameterDescriptor` sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.
      Overrides:
        `getInterface` in class `AbstractParameterDescriptor`
      Returns:
        `ParameterDescriptor​.class` or a user-defined sub-interface.

    - #### getValueClass

          public final Class<T> getValueClass()

      Returns the class that describe the type of the parameter.
      Specified by:
        `getValueClass` in interface `ParameterDescriptor<T>`
      Returns:
        the parameter value class.

    - #### getValidValues

          public Set<T> getValidValues()

      If this parameter allows only a finite set of values, returns that set. The set of valid values is usually a code list or enumeration. This method returns `null` if this parameter does not limit values to a finite set.
      Specified by:
        `getValidValues` in interface `ParameterDescriptor<T>`
      Returns:
        a finite set of valid values (usually from a code list), or `null` if it does not apply or if there is no restriction.

    - #### getValueDomain

          public final Range<?> getValueDomain()

      Returns the domain of values with their unit of measurement (if any), or `null` if none. The `Range` object combines the value class, minimum value, maximum value and whether these values are inclusive or inclusive. If the range is an instance of `MeasurementRange`, then it contains also the unit of measurement.
      API note: If this method returns a non-null value, then its type is either exactly `Range<T>`, or `Range<E>` where `<E>` is the component type of `<T>` (using wrapper classes for primitive types).
      Returns:
        the domain of values, or `null`.
      See Also:
        `Parameters​.getValueDomain(ParameterDescriptor)`

    - #### getMinimumValue

          public Comparable<T> getMinimumValue()

      Returns the minimum parameter value. If there is no minimum value, or if minimum value is inappropriate for the value class, then this method returns `null`.

      This is a convenience method for `getValueDomain().getMinValue()`. Note that this method said nothing about whether the value is inclusive.

      Specified by:
        `getMinimumValue` in interface `ParameterDescriptor<T>`
      Returns:
        the minimum parameter value (often an instance of `Double`), or `null` if unbounded.

    - #### getMaximumValue

          public Comparable<T> getMaximumValue()

      Returns the maximum parameter value. If there is no maximum value, or if maximum value is inappropriate for the value type, then this method returns `null`.

      This is a convenience method for `getValueDomain().getMaxValue()`. Note that this method said nothing about whether the value is inclusive.

      Specified by:
        `getMaximumValue` in interface `ParameterDescriptor<T>`
      Returns:
        the minimum parameter value (often an instance of `Double`), or `null` if unbounded.

    - #### getDefaultValue

          public T getDefaultValue()

      Returns the default value for the parameter. The return type can be any type including a `Number` or a `String`. If there is no default value, then this method returns `null`.
      Specified by:
        `getDefaultValue` in interface `ParameterDescriptor<T>`
      Returns:
        the default value, or `null` in none.

    - #### getUnit

          public Unit<?> getUnit()

      Returns the unit of measurement for the minimum, maximum and default values. This attribute apply only if the values is of numeric type (usually an instance of `Double`).

      This is a convenience method for `getValueDomain().unit()`.

      Specified by:
        `getUnit` in interface `ParameterDescriptor<T>`
      Returns:
        the unit for numeric value, or `null` if it doesn't apply to the value type.

    - #### createValue

          public ParameterValue<T> createValue()

      Creates a new parameter value instance initialized with the default value. The parameter descriptor for the created parameter value will be `this` object.
      Specified by:
        `createValue` in interface `GeneralParameterDescriptor`
      Specified by:
        `createValue` in interface `ParameterDescriptor<T>`
      Returns:
        a parameter initialized to the default value.

    - #### 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. This method compares the following properties in every cases:
      - `AbstractIdentifiedObject​.getName()`, compared heuristically in `IGNORE_METADATA` or less strict mode.
      - `getValueClass()`
      - `getDefaultValue()`
      - `getUnit()`
      All other properties (minimum and maximum occurrences, minimum, maximum and valid values) are compared only for modes stricter than `ComparisonMode​.IGNORE_METADATA`.
      Specified by:
        `equals` in interface `LenientComparable`
      Overrides:
        `equals` in class `AbstractParameterDescriptor`
      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:
        `AbstractIdentifiedObject​.computeHashCode()`, `Utilities​.deepEquals(Object, Object, ComparisonMode)`

    - #### computeHashCode

          protected long computeHashCode()

      Invoked by `AbstractIdentifiedObject​.hashCode()` for computing the hash code when first needed.
      Overrides:
        `computeHashCode` in class `AbstractIdentifiedObject`
      Returns:
        the hash code value. This value may change in any future Apache SIS version.