Class ParameterBuilder

java.lang.Object
org.apache.sis.referencing.Builder<ParameterBuilder>
org.apache.sis.parameter.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 number 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 number 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.
Since:
0.4
Version:
0.6
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private boolean
    true if the parameter is mandatory, or false if optional.

    Fields inherited from class org.apache.sis.referencing.Builder

    properties
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new builder.
    ParameterBuilder(org.opengis.parameter.GeneralParameterDescriptor descriptor)
    Creates a new builder initialized to properties of the given object.
  • Method Summary

    Modifier and Type
    Method
    Description
    org.opengis.parameter.ParameterDescriptor<Double>
    create(double defaultValue, javax.measure.Unit<?> unit)
    Creates a descriptor for floating point values without domain restriction.
    private <T> org.opengis.parameter.ParameterDescriptor<T>
    create(Class<T> valueClass, Range<?> valueDomain, T[] validValues, T defaultValue)
    Invoked by all createXXX(…) methods for creating the descriptor from the properties currently set in this builder.
    <T> org.opengis.parameter.ParameterDescriptor<T>
    create(Class<T> valueClass, T defaultValue)
    Creates a descriptor for values of the given type without domain restriction.
    org.opengis.parameter.ParameterDescriptor<Double>
    createBounded(double minimumValue, double maximumValue, double defaultValue, javax.measure.Unit<?> unit)
    Creates a descriptor for floating point values restricted to the given domain.
    org.opengis.parameter.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>>
    org.opengis.parameter.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>>
    org.opengis.parameter.ParameterDescriptor<T>
    createBounded(Range<T> valueDomain, T defaultValue)
    Creates a descriptor for values in the domain represented by the given Range object.
    <T> org.opengis.parameter.ParameterDescriptor<T>
    createEnumerated(Class<T> valueClass, T[] validValues, T defaultValue)
    Creates a descriptor for a parameter restricted to a set of valid values.
    org.opengis.parameter.ParameterDescriptorGroup
    createGroup(int minimumOccurs, int maximumOccurs, org.opengis.parameter.GeneralParameterDescriptor... parameters)
    Creates a descriptor group for the given multiplicity and parameters.
    org.opengis.parameter.ParameterDescriptorGroup
    createGroup(org.opengis.parameter.GeneralParameterDescriptor... parameters)
    Creates a descriptor group for the given parameters.
    org.opengis.parameter.ParameterDescriptorGroup
    createGroupForMapProjection(org.opengis.parameter.ParameterDescriptor<?>... parameters)
    Creates a descriptor group for a map projection.
    org.opengis.parameter.ParameterDescriptorGroup
    createGroupWithSameParameters(org.opengis.parameter.ParameterDescriptorGroup parameters)
    Creates a descriptor group with the same parameters than another group.
    org.opengis.parameter.ParameterDescriptor<Double>
    createStrictlyPositive(double defaultValue, javax.measure.Unit<?> unit)
    Creates a descriptor for floating point values greater than zero.
    setRequired(boolean required)
    Sets whether the parameter is mandatory or optional.
    private static Double
    valueOf(double value)
    Boxes the given value if non-NaN, or returns null if the value is NaN.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • required

      private boolean required
      true if the parameter is mandatory, or false if optional.
      See Also:
  • Constructor Details

    • ParameterBuilder

      public ParameterBuilder()
      Creates a new builder.
    • ParameterBuilder

      public ParameterBuilder(org.opengis.parameter.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 Details

    • 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 cannot 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.
    • valueOf

      private static Double valueOf(double value)
      Boxes the given value if non-NaN, or returns null if the value is NaN.
    • create

      public <T> org.opengis.parameter.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 org.opengis.parameter.ParameterDescriptor<Double> create(double defaultValue, javax.measure.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 org.opengis.parameter.ParameterDescriptor<Double> createStrictlyPositive(double defaultValue, javax.measure.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 org.opengis.parameter.ParameterDescriptor<Double> createBounded(double minimumValue, double maximumValue, double defaultValue, javax.measure.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 org.opengis.parameter.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>> org.opengis.parameter.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>> org.opengis.parameter.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> org.opengis.parameter.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.
    • create

      private <T> org.opengis.parameter.ParameterDescriptor<T> create(Class<T> valueClass, Range<?> valueDomain, T[] validValues, T defaultValue)
      Invoked by all createXXX(…) methods for creating the descriptor from the properties currently set in this builder. Identification information are cleared after this method call.
    • createGroup

      public org.opengis.parameter.ParameterDescriptorGroup createGroup(int minimumOccurs, int maximumOccurs, org.opengis.parameter.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 org.opengis.parameter.ParameterDescriptorGroup createGroup(org.opengis.parameter.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 org.opengis.parameter.ParameterDescriptorGroup createGroupWithSameParameters(org.opengis.parameter.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 org.opengis.parameter.ParameterDescriptorGroup createGroupForMapProjection(org.opengis.parameter.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".
      Notes:
      • The "standard_parallel" parameter descriptor is added only if the parameters argument contains "standard_parallel_1" and "standard_parallel_2" descriptors.
      • 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