Module org.apache.sis.referencing

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 Parameter­Descriptor.create­Value() on the descriptor provided by the implementer.

Identification properties

The following properties are cleared after a call to any create­XXX(…) 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 add­Name(…) methods. Parameters can optionally have an arbitrary number of aliases, which are also specified by the add­Name(…) 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 add­Identifier(…) 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 set­Remarks(…) method.

Usage example

Parameter descriptors are typically grouped in a Parameter­Descriptor­Group. 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.

public class MyOperation {
    public static final ParameterDescriptorGroup PARAMETERS;
    static {
        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 cannot 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.
        PARAMETERS = 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

Field Summary

Fields inherited from class Builder

properties

Constructor Summary

Constructors

Constructor	Description
Parameter­Builder()	Creates a new builder.
Parameter­Builder(General­Parameter­Descriptor descriptor)	Creates a new builder initialized to properties of the given object.

Method Summary

Modifier and Type	Method	Description
Parameter­Descriptor<Double>	create(double default­Value, Unit<?> unit)	Creates a descriptor for floating point values without domain restriction.
<T> Parameter­Descriptor<T>	create(Class<T> value­Class, T default­Value)	Creates a descriptor for values of the given type without domain restriction.
Parameter­Descriptor<Double>	create­Bounded(double minimum­Value, double maximum­Value, double default­Value, Unit<?> unit)	Creates a descriptor for floating point values restricted to the given domain.
Parameter­Descriptor<Integer>	create­Bounded(int minimum­Value, int maximum­Value, int default­Value)	Creates a descriptor for integer values restricted to the given domain.
<T extends Comparable<? super T>> Parameter­Descriptor<T>	create­Bounded(Class<T> value­Class, T minimum­Value, T maximum­Value, T default­Value)	Creates a descriptor for values of the given type restricted to the given domain.
<T extends Comparable<? super T>> Parameter­Descriptor<T>	create­Bounded(Range<T> value­Domain, T default­Value)	Creates a descriptor for values in the domain represented by the given Range object.
<T> Parameter­Descriptor<T>	create­Enumerated(Class<T> value­Class, T[] valid­Values, T default­Value)	Creates a descriptor for a parameter restricted to a set of valid values.
Parameter­Descriptor­Group	create­Group(int minimum­Occurs, int maximum­Occurs, General­Parameter­Descriptor... parameters)	Creates a descriptor group for the given multiplicity and parameters.
Parameter­Descriptor­Group	create­Group(General­Parameter­Descriptor... parameters)	Creates a descriptor group for the given parameters.
Parameter­Descriptor­Group	create­Group­For­Map­Projection(Parameter­Descriptor<?>... parameters)	Creates a descriptor group for a map projection.
Parameter­Descriptor­Group	create­Group­With­Same­Parameters(Parameter­Descriptor­Group parameters)	Creates a descriptor group with the same parameters than another group.
Parameter­Descriptor<Double>	create­Strictly­Positive(double default­Value, Unit<?> unit)	Creates a descriptor for floating point values greater than zero.
Parameter­Builder	set­Required(boolean required)	Sets whether the parameter is mandatory or optional.

Methods inherited from class Builder

add­Identifier, add­Identifier, add­Identifier, add­Name, add­Name, add­Name, add­Name, add­Name­And­Identifier, add­Names­And­Identifiers, on­Create, reidentify, rename, set­Code­Space, set­Deprecated, set­Description, set­Remarks, set­Version

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Details

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 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 set­Required(…) 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 Default­Parameter­Value­Group.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 Default­Parameter­Descriptor 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 value­Class argument.

Parameters:

value­Class - the class that describe the type of the parameter values.

default­Value - 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:

default­Value - the default value for the parameter, or Double.Na­N 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:

default­Value - the default value for the parameter, or Double.Na­N 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:

minimum­Value - the minimum parameter value (inclusive), or Double.NEGATIVE_INFINITY if none.

maximum­Value - the maximum parameter value (inclusive), or Double.POSITIVE_INFINITY if none.

default­Value - the default value for the parameter, or Double.Na­N 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:

minimum­Value - the minimum parameter value (inclusive).

maximum­Value - the maximum parameter value (inclusive).

default­Value - 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 value­Class argument.

Parameters:

value­Class - the class that describe the type of the parameter values.

minimum­Value - the minimum parameter value (inclusive), or null if none.

maximum­Value - the maximum parameter value (inclusive), or null if none.

default­Value - 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:

value­Domain - the minimum value, maximum value and unit of measurement.

default­Value - 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 valid­Values 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 value­Class argument.

Parameters:

value­Class - the class that describe the type of the parameter values.

valid­Values - a finite set of valid values (usually from a code list or enumeration) or null if it doesn't apply.

default­Value - 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:

minimum­Occurs - the minimum number of times that values for this parameter group are required.

maximum­Occurs - 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 create­Group(int, int, General­Parameter­Descriptor[]) with a multiplicity of [0 … 1] or [1 … 1] depending on the value given to the last call to set­Required(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, Default­Math­Transform­Factory 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 set­Required(boolean).

Parameters:

parameters - the parameter descriptors for the group to create.

Returns:

the parameter descriptor group for a map projection.

Since:

0.6