Class Parameters
- Object
-
- Parameters
-
public final class Parameters extends Object
Utility class for methods helping implementing, and working with the parameter API fromorg.geotools.api.parameter
package.Design note
This class contains some methods working on a specific parameter in a group (e.g. searching, setting a value, etc.). Parameters are identified by their name instead of their full descriptor object, because:- The parameter descriptor may not be always available. For example a user may looks for the
"semi_major"
axis length (because it is documented in OGC specification under that name) but doesn't know and doesn't care about who is providing the implementation. In such case, he doesn't have the parameter's descriptor. He only have the parameter's name, and creating a descriptor from that name (a descriptor independent of any implementation) is tedious.. - Parameter descriptors are implementation-dependent. For example if a user searchs for the
above-cited
"semi_major"
axis length using the Geotools's descriptor for this parameter, we will fail to find this parameter in any alternativeParameterValueGroup
implementations. This is against GeoAPI's inter-operability goal.
The above doesn't mean that parameter's descriptor should not be used. They are used for inspecting meta-data about parameters, not as a key for searching parameters in a group. Since each parameter's name should be unique in a given parameter group (because maximum occurs is always 1 for single parameter), the parameter name is a suffisient key.
- Since:
- 2.1
- Author:
- Jody Garnett (Refractions Research), Martin Desruisseaux
- The parameter descriptor may not be always available. For example a user may looks for the
-
-
Field Summary
Fields Modifier and Type Field Description static ParameterDescriptorGroup
EMPTY_GROUP
An empty parameter group.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> ParameterDescriptor<T>
cast(ParameterDescriptor<?> descriptor, Class<T> type)
Casts the given parameter descriptor to the given type.static <T> ParameterValue<T>
cast(ParameterValue<?> value, Class<T> type)
Casts the given parameter value to the given type.static void
copy(ParameterValueGroup source, ParameterValueGroup target)
Copies all parameter values fromsource
totarget
.static boolean
ensureSet(ParameterValueGroup parameters, String name, double value, Unit<?> unit, boolean force)
Ensures that the specified parameter is set.static boolean
isValid(ParameterValue<?> parameter)
Checks a parameter value against its parameter descriptor.static List<Object>
search(GeneralParameterValue param, String name, int maxDepth)
Searchs all parameters with the specified name.static Map<String,Object>
toNameValueMap(GeneralParameterValue parameters, Map<String,Object> destination)
-
-
-
Field Detail
-
EMPTY_GROUP
public static ParameterDescriptorGroup EMPTY_GROUP
An empty parameter group. This group contains no parameters.
-
-
Method Detail
-
cast
public static <T> ParameterDescriptor<T> cast(ParameterDescriptor<?> descriptor, Class<T> type) 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. This is a helper method for type safety when using Java 5 parameterized types.- Type Parameters:
T
- The expected value class.- Parameters:
descriptor
- The descriptor to cast.type
- The expected value class.- Returns:
- The descriptor casted to the given type.
- Throws:
ClassCastException
- if the given descriptor doesn't have the expected value class.- Since:
- 2.5
-
cast
public static <T> ParameterValue<T> cast(ParameterValue<?> value, Class<T> type) 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. This is a helper method for type safety when using Java 5 parameterized types.- Type Parameters:
T
- The expected value class.- Parameters:
value
- The value to cast.type
- The expected value class.- Returns:
- The value casted to the given type.
- Throws:
ClassCastException
- if the given value doesn't have the expected value class.- Since:
- 2.5
-
isValid
public static boolean isValid(ParameterValue<?> parameter)
Checks a parameter value against its parameter descriptor. This method takes care of handling checking arrays and collections against parameter descriptor.When the value class is an array (like
double[].class
) or a collection (likeList.class
), the descriptor minimum value, maximum value and valid values will be used to check the elements.- Parameters:
parameter
- The parameter to test.- Returns:
- true if parameter is valid.
- See Also:
Parameter.ensureValidValue(org.geotools.api.parameter.ParameterDescriptor<T>, java.lang.Object)
-
search
public static List<Object> search(GeneralParameterValue param, String name, int maxDepth)
Searchs all parameters with the specified name. The givenname
is compared against parametername
andalias
. This method search recursively in subgroups up to the specified depth:- If
maxDepth
is equals to 0, then this method returnsparam
if and only if it matches the specified name. - If
maxDepth
is equals to 1 andparam
is an instance ofParameterDescriptorGroup
, then this method checks all elements in this group but not in subgroups. - ...
- If
maxDepth
is a high number (e.g. 100), then this method checks all elements in all subgroups up to the specified depth, which is likely to be never reached. In this case,maxDepth
can be seen as a safeguard against never ending loops, for example if parameters graph contains cyclic entries.
- Parameters:
param
- The parameter to inspect.name
- The name of the parameter to search for. See the class javadoc for a rational about the usage of name as a key instead of descriptor.maxDepth
- The maximal depth while descending down the parameter tree.- Returns:
- The set (possibly empty) of parameters with the given name.
- If
-
copy
public static void copy(ParameterValueGroup source, ParameterValueGroup target)
Copies all parameter values fromsource
totarget
. A typical usage of this method is for transfering values from an arbitrary implementation to some specific implementation (e.g. a parameter group implementation backed by aParameterBlock
for image processing operations).- Parameters:
source
- The parameters to copy.target
- Where to copy the source parameters.- Since:
- 2.2
-
toNameValueMap
public static Map<String,Object> toNameValueMap(GeneralParameterValue parameters, Map<String,Object> destination)
Gets a flat view of name-value pairs. This method copies all parameter values into the supplieddestination
map. Keys are parameter names asString
objects, and values are parameter values as arbitrary objects. All subgroups (if any) are extracted recursively.- Parameters:
parameters
- The parameters to extract values from.destination
- The destination map, ornull
for a default one.- Returns:
destination
, or a new map ifdestination
was null.
-
ensureSet
public static boolean ensureSet(ParameterValueGroup parameters, String name, double value, Unit<?> unit, boolean force)
Ensures that the specified parameter is set. Thevalue
is set if and only if no value were already set by the user for the givenname
.The
force
argument said what to do if the named parameter is already set. If the value matches, nothing is done in all case. If there is a mismatch andforce
istrue
, then the parameter is overridden with the specifiedvalue
. Otherwise, the parameter is left unchanged but a warning is logged with theFINE
level.- Parameters:
parameters
- The set of projection parameters.name
- The parameter name to set.value
- The value to set, or to expect if the parameter is already set.unit
- The value unit.force
-true
for forcing the parameter to the specifiedvalue
is case of mismatch.- Returns:
true
if the were a mismatch, orfalse
if the parameters can be used with no change.
-
-