sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1575777 - in /sis/branches/JDK7/core/sis-referencing/src: main/java/org/apache/sis/parameter/ test/java/org/apache/sis/parameter/
Date Sun, 09 Mar 2014 22:14:10 GMT
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.
      */



Mime
View raw message