org.geotools.parameter
Class Parameters

java.lang.Object
  org.geotools.parameter.Parameters

public class Parameters

extends java.lang.Object

Utility class for methods helping implementing, and working with the parameter API from org.opengis.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 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 axis length using the Geotools's descriptor for this parameter, we will fail to find this parameter in any alternative ParameterValueGroup 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

Version:

$Id: Parameters.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Jody Garnett (Refractions Research), Martin Desruisseaux

Field Summary

static org.opengis.parameter.ParameterDescriptorGroup

EMPTY_GROUP An empty parameter group.

Constructor Summary

Parameters()

Method Summary

static void	copy(org.opengis.parameter.ParameterValueGroup source, org.opengis.parameter.ParameterValueGroup target) Copies all parameter values from to .
static boolean	ensureSet(org.opengis.parameter.ParameterValueGroup parameters, java.lang.String name, double value, javax.units.Unit unit, boolean force) Ensures that the specified parameter is set.
static boolean	isValid(org.opengis.parameter.ParameterValue parameter) Checks a parameter value against its parameter descriptor.
static java.util.List	search(org.opengis.parameter.GeneralParameterValue param, java.lang.String name, int maxDepth) Searchs all parameters with the specified name.
static java.util.Map	toNameValueMap(org.opengis.parameter.GeneralParameterValue parameters, java.util.Map destination) Gets a flat view of name-value pairs.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_GROUP

public static org.opengis.parameter.ParameterDescriptorGroup EMPTY_GROUP

An empty parameter group. This group contains no parameters.

Constructor Detail

Parameters

public Parameters()

Method Detail

isValid

public static boolean isValid(org.opengis.parameter.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 ) or a collection (like ), 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.opengis.parameter.ParameterDescriptor, java.lang.Object)

search

public static java.util.List search(org.opengis.parameter.GeneralParameterValue param,
                                    java.lang.String name,
                                    int maxDepth)

Searchs all parameters with the specified name. The given is compared against parameter name and alias. This method search recursively in subgroups up to the specified depth:

• If is equals to 0, then this method returns if and only if it matches the specified name.
• If is equals to 1 and is an instance of ParameterDescriptorGroup, then this method checks all elements in this group but not in subgroups.
• ...
• If 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, 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.

Returns:

The set (possibly empty) of parameters with the given name.

copy

public static void copy(org.opengis.parameter.ParameterValueGroup source,
                        org.opengis.parameter.ParameterValueGroup target)

Copies all parameter values from to . 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 a ParameterBlock for image processing operations).

Since:

2.2

toNameValueMap

public static java.util.Map toNameValueMap(org.opengis.parameter.GeneralParameterValue parameters,
                                           java.util.Map destination)

Gets a flat view of name-value pairs. This method copies all parameter values into the supplied map. Keys are parameter names as String 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, or for a default one.

Returns:

, or a new map if was null.

ensureSet

public static boolean ensureSet(org.opengis.parameter.ParameterValueGroup parameters,
                                java.lang.String name,
                                double value,
                                javax.units.Unit unit,
                                boolean force)

Ensures that the specified parameter is set. The is set if and only if no value were already set by the user for the given .

The 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 and is , then the parameter is overriden with the specified . Otherwise, the parameter is left unchanged but a warning is logged with the FINE 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 - for forcing the parameter to the specified is case of mismatch.

Returns:

if the were a mismatch, or if the parameters can be used with no change.