Author: desruisseaux
Date: Sun Mar 9 22:14:10 2014
New Revision: 1575777
URL: http://svn.apache.org/r1575777
Log:
Implemented the clear() method and added javadoc.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterValueList.java
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DefaultParameterValueGroupTest.java
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java?rev=1575777&r1=1575776&r2=1575777&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
[UTF-8] Sun Mar 9 22:14:10 2014
@@ -44,11 +44,14 @@ import static org.apache.sis.util.Utilit
*
* {@section Instantiation}
* Map projection or process <em>implementors</em> may use the {@link
ParameterBuilder} class for making
- * their task easier. The following example creates a <cite>Mercator (variant
A)</cite> projection valid
+ * their task easier.
+ *
+ * <div class="note"><b>Example:</b>
+ * The following example creates a <cite>Mercator (variant A)</cite>
projection valid
* from 80°S to 84°N on all the longitude range (±180°).
*
* {@preformat java
- * public class MercatorProjection {
+ * public class Mercator {
* public static final ParameterDescriptorGroup PARAMETERS;
* static {
* ParameterBuilder builder = new ParameterBuilder();
@@ -72,9 +75,10 @@ import static org.apache.sis.util.Utilit
* Users can simply reference the descriptor provided par projection or
process providers like below:
*
* {@preformat java
- * ParameterValueGroup parameters =
MercatorProjection.PARAMETERS.createValue();
- * // See DefaultParameterValueGroup for more information on 'parameters'
usage.
+ * ParameterValueGroup parameters = Mercator.PARAMETERS.createValue();
+ * // See DefaultParameterValueGroup for examples on 'parameters' usage.
* }
+ * </div>
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Johann Sorel (Geomatys)
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java?rev=1575777&r1=1575776&r2=1575777&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
[UTF-8] Sun Mar 9 22:14:10 2014
@@ -37,34 +37,49 @@ import java.util.Objects;
/**
- * A group of related parameter values.
- *
- * <p>This class defines the following convenience methods:</p>
- * <ul>
- * <li>{@link #parameter(String)} searches for a single parameter value of
the given name.</li>
- * <li>{@link #groups(String)} searches for all groups of the given
name.</li>
- * <li>{@link #addGroup(String)} for creating a new subgroup and adding it
to the list of subgroups.</li>
- * </ul>
- *
- * {@section Instantiation}
- * {@code ParameterValueGroup} are usually not instantiated directly. Instead,
new instances are created by calling
+ * A group of related parameter values. {@code ParameterValueGroup} instances
are typically created by calls to
* <code>descriptor.{@linkplain DefaultParameterDescriptorGroup#createValue()
createValue()}</code> on a descriptor
- * supplied by a map projection or process provider. After a {@code
ParameterValueGroup} instance has been created,
- * the parameter values can be set by chaining calls to {@link
#parameter(String)} with one of the {@code setValue(…)}
- * methods defined in the {@linkplain DefaultParameterValue parameter value}
class.
+ * supplied by a map projection or process provider. New instances are
initialized with a {@linkplain #values() list
+ * of values} containing all mandatory parameters, and no optional parameter.
The values list is modifiable, but all
+ * operations will first ensure that the modification would not violate the
cardinality constraints (i.e. the minimum
+ * and maximum occurrences of that parameter allowed by the descriptor). If a
cardinality constraint is violated, then
+ * an {@link InvalidParameterCardinalityException} will be thrown.
+ *
+ * <p>After a new {@code ParameterValueGroup} instance has been created, the
parameter values can be set by chaining
+ * calls to {@link #parameter(String)} with one of the {@code setValue(…)}
methods defined in the returned object
+ * (see the {@linkplain DefaultParameterValue table of setter methods}). The
{@code parameter(String)} method can
+ * be invoked regardless of whether the parameter is mandatory or optional: if
the parameter was optional and not
+ * yet present in this group, it will be created.</p>
*
* <div class="note"><b>Example:</b>
- * Assuming a descriptor defined as in the {@link
DefaultParameterDescriptorGroup} javadoc,
+ * Assuming the descriptor defined in the {@link
DefaultParameterDescriptorGroup} example,
* one can set <cite>Mercator (variant A)</cite> projection parameters as
below:
*
* {@preformat java
- * ParameterValueGroup mercator =
MercatorProjection.PARAMETERS.createValue();
+ * ParameterValueGroup mercator = Mercator.PARAMETERS.createValue();
* mercator.parameter("Longitude of natural origin").setValue(-60,
NonSI.DEGREE_ANGLE); // 60°W
* mercator.parameter("Latitude of natural origin") .setValue( 40,
NonSI.DEGREE_ANGLE); // 40°N
* // Keep default values for other parameters.
* }
* </div>
*
+ * Alternatively, if all parameters were created elsewhere and the user wants
to copy them in a new
+ * parameter group, the {@link List#addAll(Collection)} method can been
invoked on the values list.
+ *
+ * <div class="note"><b>Example:</b>
+ * {@preformat java
+ * ParameterValue<?>[] parameter = ...; // Defined elsewhere.
+ * ParameterValueGroup mercator = Mercator.PARAMETERS.createValue();
+ * mercator.values().addAll(Arrays.asList(parameters));
+ * }
+ * </div>
+ *
+ * Optional parameters can be removed by the usual {@link List#remove(int)} or
{@link List#remove(Object)}
+ * operations on the values list. But attempts to remove a mandatory parameter
will cause an
+ * {@link InvalidParameterCardinalityException} to be thrown.
+ *
+ * <p>Calls to {@code values().clear()} restore this {@code
DefaultParameterValueGroup} to its initial state.</p>
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @since 0.4 (derived from geotk-2.0)
* @version 0.4
@@ -89,17 +104,15 @@ public class DefaultParameterValueGroup
/**
* Constructs a parameter group from the specified descriptor.
*
+ * <p><b>Usage note:</b> {@code ParameterValueGroup} are usually not
instantiated directly. Instead, consider
+ * invoking <code>descriptor.{@linkplain
DefaultParameterDescriptorGroup#createValue() createValue()}</code>
+ * on a descriptor supplied by a map projection or process provider.</p>
+ *
* @param descriptor The descriptor for this group.
*/
public DefaultParameterValueGroup(final ParameterDescriptorGroup
descriptor) {
ArgumentChecks.ensureNonNull("descriptor", descriptor);
- final List<GeneralParameterDescriptor> elements =
descriptor.descriptors();
- values = new ParameterValueList(descriptor, elements.size());
- for (final GeneralParameterDescriptor child : elements) {
- for (int count=child.getMinimumOccurs(); --count>=0;) {
- values.addUnchecked(new UninitializedParameter(child));
- }
- }
+ values = new ParameterValueList(descriptor);
}
/**
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterValueList.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterValueList.java?rev=1575777&r1=1575776&r2=1575777&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterValueList.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterValueList.java
[UTF-8] Sun Mar 9 22:14:10 2014
@@ -79,11 +79,12 @@ final class ParameterValueList extends A
* Constructs an initially empty parameter list.
*
* @param descriptor The descriptor for this list.
- * @param capacity The initial capacity.
*/
- ParameterValueList(final ParameterDescriptorGroup descriptor, final int
capacity) {
+ ParameterValueList(final ParameterDescriptorGroup descriptor) {
this.descriptor = descriptor;
- values = new GeneralParameterValue[capacity];
+ final List<GeneralParameterDescriptor> elements =
descriptor.descriptors();
+ values = new GeneralParameterValue[elements.size()];
+ initialize(elements);
}
/**
@@ -98,6 +99,28 @@ final class ParameterValueList extends A
}
/**
+ * Adds all mandatory parameters to this list. This method can been
invoked only after
+ * construction or after a call to {@link #clear()}.
+ */
+ private void initialize(final List<GeneralParameterDescriptor> elements) {
+ for (final GeneralParameterDescriptor child : elements) {
+ for (int count=child.getMinimumOccurs(); --count>=0;) {
+ addUnchecked(new UninitializedParameter(child));
+ }
+ }
+ }
+
+ /**
+ * Clears this list, then recreate the mandatory parameters.
+ */
+ @Override
+ public void clear() {
+ Arrays.fill(values, 0, size, null);
+ size = 0;
+ initialize(descriptor.descriptors());
+ }
+
+ /**
* Returns the number of parameters in this list.
*/
@Override
Modified:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DefaultParameterValueGroupTest.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DefaultParameterValueGroupTest.java?rev=1575777&r1=1575776&r2=1575777&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DefaultParameterValueGroupTest.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DefaultParameterValueGroupTest.java
[UTF-8] Sun Mar 9 22:14:10 2014
@@ -132,6 +132,22 @@ public final strictfp class DefaultParam
}
/**
+ * Tests {@code DefaultParameterValueGroup.values().clear()}.
+ */
+ @Test
+ @DependsOnMethod("testParameter")
+ public void testValuesClear() {
+ final DefaultParameterValueGroup group = createGroup(10);
+ final List<GeneralParameterValue> values = group.values();
+ assertEquals("size", 4, values.size());
+ assertEquals("parameter(“Mandatory 2”)", 20,
group.parameter("Mandatory 2").intValue());
+ values.clear();
+ assertEquals("size", 2, values.size());
+ assertEquals("parameter(“Mandatory 2”)", 10,
group.parameter("Mandatory 2").intValue());
+ // The above 10 is the default value specified by the descriptor.
+ }
+
+ /**
* Tests {@code DefaultParameterValueGroup.values().get(…)} on a group
expected to be pre-filled
* with mandatory parameters.
*/
