Package org.apache.sis.parameter
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
ParameterDescriptor
s, 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
orCitation
. - 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 implementers, 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
createValue()
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 implementer of a Mercator projection
provides a
Calls to ParameterDescriptorGroup
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.
parameter(…)
throw a ParameterNotFoundException
if the given name is unknown to the group.
Calls to setValue(…)
throw a InvalidParameterValueException
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
-
Interface Summary Interface Description Parameterized An object which can supply its parameters in aParameterValueGroup
. -
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 byParameterFormat
.