# 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 are 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` 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 `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 `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.

## Exceptions

Calls to `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

- 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.
  MatrixParameters<E>
  Builder of parameter groups for matrices or mathematical objects of higher dimensions.
  ParameterBuilder
  Helper class for parameter descriptor instantiations.
  ParameterFormat
  Formats parameter descriptors or parameter values in a tabular format.
  ParameterFormat.ContentLevel
  The amount of information to include in the table formatted by `ParameterFormat`.
  Parameterized
  An object which can supply its parameters in a `ParameterValueGroup`.
  Parameters
  Convenience methods for fetching parameter values despite the variations in parameter names, value types and units.