You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2014/03/09 23:14:10 UTC
svn commit: r1575777 - in /sis/branches/JDK7/core/sis-referencing/src:
main/java/org/apache/sis/parameter/ test/java/org/apache/sis/parameter/
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.
*/