Module org.apache.sis.referencing
Package org.apache.sis.parameter
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 cannot be removed from the group. They can be left to their default value however.
- Group may contain other groups.
Usage
When using thisorg.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 aParameterDescriptorGroup
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.
Exceptions
Calls toparameter(…)
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
-
ClassDescriptionAbstract definition of a parameter or group of parameters used by a coordinate operation or a process.The definition of a single parameter used by an operation method.The definition of a group of related parameters used by an operation method.A single parameter value used by an operation method.A group of related parameter values.Helper class for parameter descriptor instantiations.Formats parameter descriptors or parameter values in a tabular format.The amount of information to include in the table formatted by
ParameterFormat
.An object which can supply its parameters in aParameterValueGroup
.Convenience methods for fetching parameter values despite the variations in parameter names, value types and units.Creates parameter groups for tensors (usually matrices).