org.apache.sis.parameter

Class Parameters

Object

Parameters

All Implemented Interfaces:

Cloneable, GeneralParameterValue, ParameterValueGroup

Direct Known Subclasses:

ContextualParameters, DefaultParameterValueGroup

public abstract class Parameters
extends Object
implements ParameterValueGroup, Cloneable

Convenience methods for fetching parameter values despite the variations in parameter names, value types and units. See DefaultParameterValueGroup javadoc for a description of the standard way to get and set a particular parameter in a group. The remaining of this javadoc is specific to Apache SIS.

Convenience static methods

This class provides the following convenience static methods:

• cast(…, Class) for type safety with parameterized types.
• getMemberName(ParameterDescriptor) for inter-operability between ISO 19111 and ISO 19115.
• getValueDomain(ParameterDescriptor) for information purpose.
• copy(ParameterValueGroup, ParameterValueGroup) for copying values into an existing instance.

Fetching parameter values despite different names, types or units

The common way to get a parameter is to invoke the ParameterValueGroup.parameter(String) method. This Parameters class provides an alternative way, using a ParameterDescriptor argument instead than a String. The methods in this class use the additional information provided by the descriptor for choosing a String argument that the above-cited parameter(String) method is more likely to know (by giving preference to a name or alias defined by a common authority), and for applying type and unit conversions.

Example: The same parameter may be known under different names. For example the length of the semi-major axis of the ellipsoid is commonly known as "semi_major". But that parameter can also be named "semi_major_axis", "earth_radius" or simply "a" in other libraries. When fetching parameter values, we do not always know in advance which of the above-cited names is recognized by an arbitrary ParameterValueGroup implementation.

This uncertainty is mitigated with the Apache SIS implementation since DefaultParameterValueGroup.parameter(String) compares the given String argument against all parameter's aliases in addition to the name. However we do not have the guarantee that all implementations do that.

The method names in this class follow the names of methods provided by the ParameterValue interface. Those methods are themselves inspired by JDK methods:

Methods fetching parameter value

Parameters method	ParameterValue method	JDK methods
getValue(ParameterDescriptor)	getValue()
booleanValue(ParameterDescriptor)	booleanValue()	Boolean.booleanValue()
intValue(ParameterDescriptor)	intValue()	Number.intValue()
intValueList(ParameterDescriptor)	intValueList()
doubleValue(ParameterDescriptor)	doubleValue()	Number.doubleValue()
doubleValueList(ParameterDescriptor)	doubleValueList()
stringValue(ParameterDescriptor)	stringValue()

Note for subclass implementors

All methods in this class get their information from the ParameterValueGroup methods. In addition, each method in this class is isolated from all others: overriding one method has no impact on other methods.

Note on this class name: Despite implementing the ParameterValueGroup interface, this class is not named AbstractParameterValueGroup because it does not implement any method from the interface. Extending this class or extending Object make almost no difference for implementors. The intend of this Parameters class is rather to extend the API with methods that are convenient for the way Apache SIS uses parameters. In other words, this class is intended for users rather than implementors.

Since:

0.4

Defined in the sis-referencing module

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Parameters() For subclass constructors only.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	booleanValue(ParameterDescriptor<Boolean> parameter) Returns the boolean value of the parameter identified by the given descriptor.
static <T> ParameterDescriptor<T>	cast(ParameterDescriptor<?> descriptor, Class<T> valueClass) Casts the given parameter descriptor to the given type.
static <T> ParameterValue<T>	cast(ParameterValue<?> parameter, Class<T> valueClass) Casts the given parameter value to the given type.
static Parameters	castOrWrap(ParameterValueGroup parameters) Returns the given parameter value group as a Parameters instance.
Parameters	clone() Returns a copy of this group of parameter values.
static void	copy(ParameterValueGroup values, ParameterValueGroup destination) Copies the values of a parameter group into another parameter group.
double	doubleValue(ParameterDescriptor<? extends Number> parameter) Returns the floating point value of the parameter identified by the given descriptor.
double[]	doubleValueList(ParameterDescriptor<double[]> parameter) Returns the floating point values of the parameter identified by the given descriptor.
static GeneralParameterDescriptor[]	getDescriptors(GeneralParameterValue... parameters) Returns the descriptors of the given parameters, in the same order.
static MemberName	getMemberName(ParameterDescriptor<?> parameter) Gets the parameter name as an instance of MemberName.
<T> ParameterValue<T>	getOrCreate(ParameterDescriptor<T> parameter) Returns the parameter identified by the given descriptor.
<T> T	getValue(ParameterDescriptor<T> parameter) Returns the value of the parameter identified by the given descriptor.
static Range<?>	getValueDomain(ParameterDescriptor<?> descriptor) Returns the domain of valid values defined by the given descriptor, or null if none.
int	intValue(ParameterDescriptor<? extends Number> parameter) Returns the integer value of the parameter identified by the given descriptor.
int[]	intValueList(ParameterDescriptor<int[]> parameter) Returns the integer values of the parameter identified by the given descriptor.
String	stringValue(ParameterDescriptor<? extends CharSequence> parameter) Returns the string value of the parameter identified by the given descriptor.

Methods inherited from class Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ParameterValueGroup

addGroup, getDescriptor, groups, parameter, values

Constructor Detail

Parameters

protected Parameters()

For subclass constructors only.

Method Detail

castOrWrap

public static Parameters castOrWrap(ParameterValueGroup parameters)

Returns the given parameter value group as a Parameters instance. If the given parameters is already an instance of Parameters, then it is returned as-is. Otherwise this method returns a wrapper which delegate all method invocations to the given instance.

This method provides a way to get access to the non-static Parameters methods, like getValue(ParameterDescriptor), for an arbitrary ParameterValueGroup instance.

Parameters:

parameters - The object to cast or wrap, or null.

Returns:

The given argument as an instance of Parameters (may be the same reference), or null if the given argument was null.

cast

public static <T> ParameterDescriptor<T> cast(ParameterDescriptor<?> descriptor,
                              Class<T> valueClass)
                                   throws ClassCastException

Casts the given parameter descriptor to the given type. An exception is thrown immediately if the parameter does not have the expected value class.

Type Parameters:

T - The expected value class.

Parameters:

descriptor - The descriptor to cast, or null.

valueClass - The expected value class.

Returns:

The descriptor casted to the given value class, or null if the given descriptor was null.

Throws:

ClassCastException - if the given descriptor does not have the expected value class.

See Also:

Class.cast(Object)

cast

public static <T> ParameterValue<T> cast(ParameterValue<?> parameter,
                         Class<T> valueClass)
                              throws ClassCastException

Casts the given parameter value to the given type. An exception is thrown immediately if the parameter does not have the expected value class.

Type Parameters:

T - The expected value class.

Parameters:

parameter - The parameter to cast, or null.

valueClass - The expected value class.

Returns:

The value casted to the given type, or null if the given value was null.

Throws:

ClassCastException - if the given value doesn't have the expected value class.

See Also:

Class.cast(Object)

getDescriptors

public static GeneralParameterDescriptor[] getDescriptors(GeneralParameterValue... parameters)

Returns the descriptors of the given parameters, in the same order. Special cases:

• If the given array is null, then this method returns null.
• If an element of the given array is null, then the corresponding element of the returned array is also null.

Parameters:

parameters - The parameter values from which to get the descriptors, or null.

Returns:

The descriptors of the given parameter values, or null if the parameters argument was null.

Since:

0.6

getMemberName

public static MemberName getMemberName(ParameterDescriptor<?> parameter)

Gets the parameter name as an instance of MemberName. This method performs the following checks:

• If the primary name is an instance of MemberName, returns that primary name.
• Otherwise this method searches for the first alias which is an instance of MemberName. If found, that alias is returned.
• If no alias is found, then this method tries to build a member name from the primary name and the value class, using the mapping defined in DefaultTypeName javadoc.

This method can be used as a bridge between the parameter object defined by ISO 19111 (namely CC_OperationParameter) and the one defined by ISO 19115 (namely SV_Parameter).

Parameters:

parameter - The parameter from which to get the name (may be null).

Returns:

The member name, or null if none.

Since:

0.5

See Also:

Names.createMemberName(CharSequence, String, CharSequence, Class)

getValueDomain

public static Range<?> getValueDomain(ParameterDescriptor<?> descriptor)

Returns the domain of valid values defined by the given descriptor, or null if none. This method performs the following operations:

• If the given parameter is an instance of DefaultParameterDescriptor, delegate to DefaultParameterDescriptor.getValueDomain().
• Otherwise builds the range from the minimum value, maximum value and, if the values are numeric, from the unit.

Parameters:

descriptor - The parameter descriptor, or null.

Returns:

The domain of valid values, or null if none.

See Also:

DefaultParameterDescriptor.getValueDomain()

getValue

public <T> T getValue(ParameterDescriptor<T> parameter)
           throws ParameterNotFoundException

Returns the value of the parameter identified by the given descriptor. This method uses the following information from the given parameter descriptor:

• The most appropriate name or alias to use for searching in this ParameterValueGroup, chosen as below:
  • a name or alias defined by the same authority, if any;
  • an arbitrary name or alias otherwise.
• The default value to return if there is no value associated to the above-cited name or alias.
• The unit of measurement (if any) of numerical value to return.
• The type of value to return.

This method can be useful when the ParameterDescriptor are known in advance, for example in the implementation of some coordinate operation method. If the caller has no such ParameterDescriptor at hand, then the parameter(String) method is probably more convenient.

Type Parameters:

T - The type of the parameter value.

Parameters:

parameter - The name or alias of the parameter to look for, together with the desired type and unit of value.

Returns:

The requested parameter value if it exists, or the default value otherwise (which may be null).

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

Since:

0.6

See Also:

DefaultParameterValueGroup.parameter(String), DefaultParameterValue.getValue()

booleanValue

public boolean booleanValue(ParameterDescriptor<Boolean> parameter)
                     throws ParameterNotFoundException

Returns the boolean value of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter value if it exists, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.booleanValue()

intValue

public int intValue(ParameterDescriptor<? extends Number> parameter)
             throws ParameterNotFoundException

Returns the integer value of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter value if it exists, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.intValue()

intValueList

public int[] intValueList(ParameterDescriptor<int[]> parameter)
                   throws ParameterNotFoundException

Returns the integer values of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter values if they exist, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.intValueList()

doubleValue

public double doubleValue(ParameterDescriptor<? extends Number> parameter)
                   throws ParameterNotFoundException

Returns the floating point value of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

If the given descriptor supplies a unit of measurement, then the returned value will be converted into that unit.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter value if it exists, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.doubleValue(Unit)

doubleValueList

public double[] doubleValueList(ParameterDescriptor<double[]> parameter)
                         throws ParameterNotFoundException

Returns the floating point values of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

If the given descriptor supplies a unit of measurement, then the returned values will be converted into that unit.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter values if they exists, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.doubleValueList(Unit)

stringValue

public String stringValue(ParameterDescriptor<? extends CharSequence> parameter)
                   throws ParameterNotFoundException

Returns the string value of the parameter identified by the given descriptor. See getValue(ParameterDescriptor) for more information about how this method uses the given parameter argument.

Parameters:

parameter - The name or alias of the parameter to look for.

Returns:

The requested parameter value if it exists, or the non-null default value otherwise.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

IllegalStateException - if the value is not defined and there is no default value.

Since:

0.6

See Also:

DefaultParameterValue.stringValue()

getOrCreate

public <T> ParameterValue<T> getOrCreate(ParameterDescriptor<T> parameter)
                              throws ParameterNotFoundException

Returns the parameter identified by the given descriptor. If the identified parameter is optional and not yet created, then it will be created now.

The default implementation is equivalent to:

return cast(parameter(name), parameter.getValueClass());

where name is a parameter name or alias chosen by the same algorithm than getValue(ParameterDescriptor).

Type Parameters:

T - The type of the parameter value.

Parameters:

parameter - The parameter to look for.

Returns:

The requested parameter instance.

Throws:

ParameterNotFoundException - if the given parameter name or alias is not legal for this group.

Since:

0.6

See Also:

DefaultParameterValueGroup.parameter(String)

clone

public Parameters clone()

Returns a copy of this group of parameter values. The default implementation performs a shallow copy, but subclasses are encouraged to perform a deep copy.

Specified by:

clone in interface GeneralParameterValue

Specified by:

clone in interface ParameterValueGroup

Overrides:

clone in class Object

Returns:

A copy of this group of parameter values.

See Also:

copy(ParameterValueGroup, ParameterValueGroup)

copy

public static void copy(ParameterValueGroup values,
        ParameterValueGroup destination)
                 throws InvalidParameterNameException,
                        InvalidParameterValueException

Copies the values of a parameter group into another parameter group. All values in the source group shall be valid for the destination group, but the destination may have more parameters. Sub-groups are copied recursively.

A typical usage of this method is for transferring values from an arbitrary implementation to some specific implementation, or to a parameter group using a different but compatible descriptor.

Parameters:

values - The parameters values to copy.

destination - Where to copy the values.

Throws:

InvalidParameterNameException - if a source parameter name is unknown to the destination.

InvalidParameterValueException - if the value of a source parameter is invalid for the destination.

Since:

0.5

See Also:

clone()