Package org.apache.sis.parameter

Descriptions and values of parameters used by a coordinate operation or a process.

See: Description

Interface Summary

Interface	Description
Parameterized	An object which can supply its parameters in a Parameter­Value­Group.

Class Summary

Class	Description
AbstractParameterDescriptor	Abstract definition of a parameter or group of parameters used by a coordinate operation or a process.
DefaultParameterDescriptor<T>	The definition of a single parameter used by an operation method.
DefaultParameterDescriptorGroup	The definition of a group of related parameters used by an operation method.
DefaultParameterValue<T>	A single parameter value used by an operation method.
DefaultParameterValueGroup	A group of related parameter values.
ParameterBuilder	Helper class for parameter descriptor instantiations.
ParameterFormat	Formats parameter descriptors or parameter values in a tabular format.
Parameters	Convenience methods for fetching parameter values despite the variations in parameter names, value types and units.
TensorParameters<E>	Creates parameter groups for tensors (usually matrices).

Enum Summary

Enum	Description
ParameterFormat.ContentLevel	The amount of information to include in the table formatted by Parameter­Format.

Package org.apache.sis.parameter Description

Descriptions and values of parameters used by a coordinate operation or a process. An explanation for this package is provided in the OpenGIS® javadoc. The remaining discussion on this page is specific to the SIS implementation.

There is three categories of classes in this package:

• Parameter descriptors are immutable types that describes the parameters needed by an operation or a process. Descriptors contain information like parameter name, optionality, repeatability and value type, but do not contain the actual parameter value.
• Parameter values are (descriptor, value) tuples, together with convenience methods for performing unit conversions and getting the values as instances of some commonly used types.
• Builders, formatters and search methods aim to simplify the creation of Parameter­Descriptors, the search for parameter values and visualizing them in a tabular format.

Parameters are organized in groups. A group may be for example the set of all parameters needed for the definition of a Mercator projection. Parameter groups have some similarities with java.util.Map where:

• Keys are (indirectly) parameter names.
• Values are (indirectly) typically of type int, int[], double, double[], boolean, String, URI or Citation.
• Each parameter (equivalent to map entry) constraints the values to a base value class, and optionally to a value domain (i.e. minimum and maximum valid values) or an enumeration of valid values.
• Each parameter can have a default value and a unit of measurement.
• Some parameters are mandatory (minimum occurrence = 1), meaning that they can not be removed from the group. They can be left to their default value however.
• Group may contain other groups.

Usage

When using this org.apache.sis.parameter package, the starting point is usually to obtain a parameter group descriptor for the operation of interest. Those groups are provided by the operation implementors, so users do not need to create their own.

Given a group descriptor, users can obtain a new instance of parameter values by a call to the create­Value() method. New value groups initially contain all mandatory parameters with their default values and no optional parameter. A parameter(String) convenience method is provided for fetching a parameter regardless of whether it was present or not — optional parameters are created when first needed.

Example: the following code snippet assumes that the implementor of a Mercator projection provides a Parameter­Descriptor­Group instance in a PARAMETERS static constant:

ParameterValueGroup group = Mercator.PARAMETERS.createValue();
group.parameter("Longitude of natural origin").setValue(-60);        // Using default units (e.g. degrees).
group.parameter("False easting").setValue(200.0, Units.KILOMETRE);   // Using explicit units.

Calls to parameter(…) throw a Parameter­Not­Found­Exception if the given name is unknown to the group. Calls to set­Value(…) throw a Invalid­Parameter­Value­Exception if the given value is not assignable to the expected class or is not inside the value domain.

Since:

0.4

Defined in the sis-referencing module