Class Parameters
- All Implemented Interfaces:
- Cloneable,- GeneralParameterValue,- ParameterValueGroup
- Direct Known Subclasses:
- ContextualParameters,- DefaultParameterValueGroup
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 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.
ParameterValue interface.
 Those methods are themselves inspired by JDK methods:
 | Parametersmethod | ParameterValuemethod | 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() | 
Fetching parameter values despite different names, types or units
The common way to get a parameter is to invoke theParameterValueGroup.parameter(String) method.
 This Parameters class provides alternative ways, using a ParameterDescriptor argument
 instead of a String argument. Those descriptors provide additional information like the various
 aliases under which the same parameter may be known.
 By using this information, Parameters can choose the most appropriate parameter name or alias
 (by searching for a common authority)
 when it delegates its work to the parameter(String) method.
 "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 instance.Parameters uses also the descriptor information for applying type and unit conversions
 (i.e. returned values are converted to the units of measurement specified by the given parameter descriptor).
 Note for subclass implementers
This class does not implement any method from theParameterValueGroup interface
 (this class is not named “AbstractParameterValueGroup” for that reason).
 Extending this class or extending Object make almost no difference for implementers;
 Parameters purpose is mostly to extend the API for users convenience.
 All methods in this class get their information from the ParameterValueGroup methods.
 In addition, unless otherwise specified, methods in this class is isolated from all others:
 overriding one method has no impact on other methods.- Since:
- 0.4
Defined in the sis-referencing module
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionbooleanbooleanValue(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 ParameterscastOrWrap(ParameterValueGroup parameters) Returns the given parameter value group as aParametersinstance.clone()Returns a copy of this group of parameter values.static voidcopy(ParameterValueGroup values, ParameterValueGroup destination) Copies the values of a parameter group into another parameter group.doubledoubleValue(ParameterDescriptor<? extends Number> parameter) Returns the floating point value of the parameter identified by the given descriptor.doubledoubleValue(ParameterDescriptor<? extends Number> parameter, Unit<?> unit) Returns the floating point value of the parameter identified by the given descriptor, converted to the given unit of measurement.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.<T> TgetMandatoryValue(ParameterDescriptor<T> parameter) Returns the value of the parameter identified by the given descriptor, or throws an exception if none.static MemberNamegetMemberName(ParameterDescriptor<?> parameter) Gets the parameter name as an instance ofMemberName.<T> ParameterValue<T>getOrCreate(ParameterDescriptor<T> parameter) Returns the parameter identified by the given descriptor.<T> TgetValue(ParameterDescriptor<T> parameter) Returns the value of the parameter identified by the given descriptor, ornullif none.static Range<?>getValueDomain(ParameterDescriptor<?> descriptor) Returns the domain of valid values defined by the given descriptor, ornullif none.intintValue(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.static booleanisUnmodifiable(ParameterValueGroup parameters) Returnstrueif the given parameter group is a non-null instance created byunmodifiable(…).voidprint()Prints a string representation of this group to the standard output stream.stringValue(ParameterDescriptor<? extends CharSequence> parameter) Returns the string value of the parameter identified by the given descriptor.Returns a string representation of this group.static Parametersunmodifiable(ParameterValueGroup parameters) Returns the given parameter value group as an unmodifiableParametersinstance.static Parametersunmodifiable(ParameterValueGroup parameters, Predicate<? super GeneralParameterDescriptor> filter) Returns the given parameter value group as an unmodifiableParametersinstance with some parameters hidden.Methods inherited from class Objectequals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface ParameterValueGroupaddGroup, getDescriptor, groups, parameter, values
- 
Constructor Details- 
Parametersprotected Parameters()For subclass constructors only.
 
- 
- 
Method Details- 
isUnmodifiableReturnstrueif the given parameter group is a non-null instance created byunmodifiable(…).- Parameters:
- parameters- the parameter group to test. Can be- null.
- Returns:
- whether the given parameters are non-null and unmodifiable.
- Since:
- 1.3
 
- 
unmodifiableReturns the given parameter value group as an unmodifiableParametersinstance. If the given parameters is already an unmodifiable instance ofParameters, then it is returned as-is. Otherwise this method copies all parameter values in a new, unmodifiable, parameter group instance.- Parameters:
- parameters- the parameters to make unmodifiable, or- null.
- Returns:
- an unmodifiable group with the same parameters than the given group,
         or nullif the given argument was null.
- Since:
- 0.7
- See Also:
 
- 
unmodifiablepublic static Parameters unmodifiable(ParameterValueGroup parameters, Predicate<? super GeneralParameterDescriptor> filter) Returns the given parameter value group as an unmodifiableParametersinstance with some parameters hidden. The hidden parameters are excluded from the list returned byParameterValueGroup.values(), but are otherwise still accessible when the hidden parameters is explicitly named in a call toParameterValueGroup.parameter(String).Use case: this method is used for hiding parameters that should be inferred from the context. For example, the"semi_major"and"semi_minor"parameters are included in the list ofMathTransformparameters because that class has no way to know the values if they are not explicitly provided. But those semi-axis length parameters should not be included in the list ofCoordinateOperationparameters because they are inferred from the context (the source and target CRS).- Parameters:
- parameters- the parameters to make unmodifiable, or- null.
- filter- specifies which source parameters to keep visible, or- nullif no filtering.
- Returns:
- an unmodifiable group with the parameters of the given group to keep visible,
         or nullif theparametersargument was null.
- Since:
- 1.3
 
- 
castOrWrapReturns the given parameter value group as aParametersinstance. If the given parameters is already an instance ofParameters, 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 Parametersmethods, likegetValue(ParameterDescriptor), for an arbitraryParameterValueGroupinstance.- Parameters:
- parameters- the object to cast or wrap, or- null.
- Returns:
- the given argument as an instance of Parameters(may be the same reference), ornullif the given argument was null.
 
- 
castpublic 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 nullif the given descriptor was null.
- Throws:
- ClassCastException- if the given descriptor does not have the expected value class.
- See Also:
 
- 
castpublic 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 nullif the given value was null.
- Throws:
- ClassCastException- if the given value doesn't have the expected value class.
- See Also:
 
- 
getDescriptorsReturns the descriptors of the given parameters, in the same order. Special cases:- If the given array is null, then this method returnsnull.
- If an element of the given array is null, then the corresponding element of the returned array is alsonull.
 - Parameters:
- parameters- the parameter values from which to get the descriptors, or- null.
- Returns:
- the descriptors of the given parameter values, or nullif theparametersargument was null.
- Since:
- 0.6
 
- If the given array is 
- 
getMemberNameGets the parameter name as an instance ofMemberName. This method performs the following checks:- If the primary name is an instance of MemberName(for example aNamedIdentifiersubclass), returns that primary name.
- Otherwise this method searches for the first alias
       which is an instance of MemberName(a subtype of aliases type). If found, that alias is returned.
- If no alias is found, then this method tries to build a MemberNamefrom the primary name and the value class, using the mapping defined inDefaultTypeNamejavadoc.
 CC_OperationParameter) and the one defined by ISO 19115 (namelySV_Parameter).- Parameters:
- parameter- the parameter from which to get the name (may be- null).
- Returns:
- the member name, or nullif none.
- Since:
- 0.5
- See Also:
 
- If the primary name is an instance of 
- 
getValueDomainReturns the domain of valid values defined by the given descriptor, ornullif none. This method performs the following operations:- If the given parameter is an instance of DefaultParameterDescriptor, delegate toDefaultParameterDescriptor.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 nullif none.
- See Also:
 
- If the given parameter is an instance of 
- 
getValueReturns the value of the parameter identified by the given descriptor, ornullif none. This method uses the following information from the givenparameterdescriptor:- 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.
 ParameterDescriptorare known in advance, for example in the implementation of some coordinate operation method. If the caller has no suchParameterDescriptorat hand, then theparameter(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- parametername or alias is not legal for this group.
- UnconvertibleObjectException- if the parameter value cannot be converted to the expected type.
- Since:
- 0.6
- See Also:
 
- The most appropriate name or
       alias to use for searching
       in this 
- 
getMandatoryValueReturns the value of the parameter identified by the given descriptor, or throws an exception if none. The default implementation performs the same work thangetValue(ParameterDescriptor)and verifies that the returned value is non-null.- 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 provided that it is not null.
- Throws:
- ParameterNotFoundException- if the given- parametername or alias is not legal for this group.
- IllegalStateException- if the value is not defined and there is no default value.
- Since:
- 0.7
- See Also:
 
- 
booleanValuepublic boolean booleanValue(ParameterDescriptor<Boolean> parameter) throws ParameterNotFoundException Returns the boolean value of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.- 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- parametername 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:
 
- 
intValuepublic int intValue(ParameterDescriptor<? extends Number> parameter) throws ParameterNotFoundException Returns the integer value of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.- 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- parametername 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:
 
- 
intValueListReturns the integer values of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.- 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- parametername 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:
 
- 
doubleValuepublic double doubleValue(ParameterDescriptor<? extends Number> parameter) throws ParameterNotFoundException Returns the floating point value of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.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- parametername 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:
 
- 
doubleValuepublic double doubleValue(ParameterDescriptor<? extends Number> parameter, Unit<?> unit) throws ParameterNotFoundException Returns the floating point value of the parameter identified by the given descriptor, converted to the given unit of measurement. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.- Parameters:
- parameter- the name or alias of the parameter to look for.
- unit- the desired unit of measurement.
- Returns:
- the requested parameter value if it exists, or the non-null default value otherwise.
- Throws:
- ParameterNotFoundException- if the given- parametername or alias is not legal for this group.
- IllegalStateException- if the value is not defined and there is no default value.
- IllegalArgumentException- if the specified unit is invalid for the parameter.
- Since:
- 1.3
- See Also:
 
- 
doubleValueListpublic double[] doubleValueList(ParameterDescriptor<double[]> parameter) throws ParameterNotFoundException Returns the floating point values of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.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- parametername 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:
 
- 
stringValuepublic String stringValue(ParameterDescriptor<? extends CharSequence> parameter) throws ParameterNotFoundException Returns the string value of the parameter identified by the given descriptor. SeegetValue(ParameterDescriptor)for more information about how this method uses the givenparameterargument.- 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- parametername 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:
 
- 
getOrCreatepublic <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: 
 wherereturn cast(parameter(name), parameter.getValueClass()); nameis aparametername or alias chosen by the same algorithm thangetValue(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- parametername or alias is not legal for this group.
- Since:
- 0.6
- See Also:
 
- 
cloneReturns 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:
- clonein interface- GeneralParameterValue
- Specified by:
- clonein interface- ParameterValueGroup
- Overrides:
- clonein class- Object
- Returns:
- a copy of this group of parameter values.
- See Also:
 
- 
copypublic static void copy(ParameterValueGroup values, ParameterValueGroup destination) throws InvalidParameterNameException, InvalidParameterValueException Copies the values of a parameter group into another parameter group. All values in thesourcegroup shall be valid for thedestinationgroup, but thedestinationmay 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 parameter values to copy.
- destination- where to copy the values.
- Throws:
- InvalidParameterNameException- if a- sourceparameter name is unknown to the- destination.
- InvalidParameterValueException- if the value of a- sourceparameter is invalid for the- destination.
- Since:
- 0.5
- See Also:
 
- 
toStringReturns a string representation of this group. The default implementation delegates toParameterFormat.This method is for information purpose only and may change in future SIS version. 
- 
printPrints a string representation of this group to the standard output stream. If a console is attached to the running JVM (i.e. if the application is run from the command-line and the output is not redirected to a file) and if Apache SIS thinks that the console supports the ANSI escape codes (a.k.a. X3.64), then a syntax coloring will be applied.This is a convenience method for debugging purpose and for console applications. - Since:
- 0.7
 
 
-