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 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 cannot 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 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 implementer 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.

Exceptions

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