sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1567019 - in /sis/branches/JDK7/core: sis-referencing/src/main/java/org/apache/sis/parameter/ sis-referencing/src/main/java/org/apache/sis/referencing/ sis-referencing/src/main/java/org/apache/sis/referencing/cs/ sis-utility/src/main/java/...
Date Tue, 11 Feb 2014 09:53:12 GMT
Author: desruisseaux
Date: Tue Feb 11 09:53:12 2014
New Revision: 1567019

URL: http://svn.apache.org/r1567019
Log:
Simplification: removed an abstract base class which doesn't implement enough services.
Various javadoc fixes.

Removed:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/AbstractParameterDescriptor.java
Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java?rev=1567019&r1=1567018&r2=1567019&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
[UTF-8] Tue Feb 11 09:53:12 2014
@@ -36,6 +36,7 @@ import org.apache.sis.util.collection.Co
 import org.apache.sis.internal.util.Numerics;
 import org.apache.sis.referencing.IdentifiedObjects;
 import org.apache.sis.referencing.AbstractIdentifiedObject;
+import org.apache.sis.io.wkt.Formatter;
 
 import static org.apache.sis.util.ArgumentChecks.ensureNonNull;
 import static org.apache.sis.util.ArgumentChecks.ensureCanCast;
@@ -50,8 +51,19 @@ import java.util.Objects;
  * The definition of a parameter used by an operation method.
  * For {@linkplain org.apache.sis.referencing.crs.AbstractCRS Coordinate Reference Systems}
  * most parameter values are numeric, but other types of parameter values are possible.
- * The {@linkplain #getValueClass() value class} for such numeric parameters is usually
- * {@link Double} or {@link Integer}, but other number types are accepted as well.
+ *
+ * <p>A parameter descriptor contains the following properties:</p>
+ * <ul>
+ *   <li>The parameter {@linkplain #getName() name}.</li>
+ *   <li>The {@linkplain #getValueClass() class of values}. This is usually {@link
Double}, {@code double[]},
+ *       {@link Integer}, {@code int[]}, {@link Boolean}, {@link String} or {@link java.net.URI},
+ *       but other types are allowed as well.</li>
+ *   <li>Whether this parameter is optional or mandatory. This is specified by the
{@linkplain #getMinimumOccurs()
+ *       minimum occurences} number, which can be 0 or 1 respectively.</li>
+ *   <li>The {@linkplain #getDefaultValue() default value} and its {@linkplain #getUnit()
unit of measurement}.</li>
+ *   <li>The domain of values, as a {@linkplain #getMinimumValue() minimum value},
{@linkplain #getMaximumValue()
+ *       maximum value} or an enumeration of {@linkplain #getValidValues() valid values}.</li>
+ * </ul>
  *
  * @param <T> The type of elements to be returned by {@link DefaultParameterValue#getValue()}.
  *
@@ -64,31 +76,36 @@ import java.util.Objects;
  * @see Parameter
  * @see DefaultParameterDescriptorGroup
  */
-public class DefaultParameterDescriptor<T> extends AbstractParameterDescriptor implements
ParameterDescriptor<T> {
+public class DefaultParameterDescriptor<T> extends AbstractIdentifiedObject implements
ParameterDescriptor<T> {
     /**
      * Serial number for inter-operability with different versions.
      */
     private static final long serialVersionUID = -295668622297737705L;
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getMinimumValue()}.
      */
     public static final String MINIMUM_VALUE_KEY = "minimumValue";
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getMaximumValue()}.
      */
     public static final String MAXIMUM_VALUE_KEY = "maximumValue";
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getValidValues()}.
      */
     public static final String VALID_VALUES_KEY = "validValues";
 
     /**
+     * {@code true} if this parameter is mandatory, or {@code false} if it is optional.
+     */
+    private final boolean required;
+
+    /**
      * The class that describe the type of parameter values.
      */
     private final Class<T> valueClass;
@@ -187,13 +204,14 @@ public class DefaultParameterDescriptor<
                                       final Unit<?>       unit,
                                       final boolean       required)
     {
-        super(properties, required ? 1 : 0, 1);
+        super(properties);
         final Comparable<T> minimumValue = Containers.property(properties, MINIMUM_VALUE_KEY,
Comparable.class);
         final Comparable<T> maximumValue = Containers.property(properties, MAXIMUM_VALUE_KEY,
Comparable.class);
         ensureNonNull("valueClass",      valueClass);
         ensureCanCast("defaultValue",    valueClass, defaultValue);
         ensureCanCast(MINIMUM_VALUE_KEY, valueClass, minimumValue);
         ensureCanCast(MAXIMUM_VALUE_KEY, valueClass, maximumValue);
+        this.required     = required;
         this.valueClass   = valueClass;
         this.defaultValue = Numerics.cached(defaultValue);
         this.minimumValue = Numerics.cached(minimumValue);
@@ -276,6 +294,7 @@ public class DefaultParameterDescriptor<
      */
     public DefaultParameterDescriptor(final ParameterDescriptor<T> descriptor) {
         super(descriptor);
+        required     = descriptor.getMinimumOccurs() != 0;
         valueClass   = descriptor.getValueClass();
         validValues  = descriptor.getValidValues();
         defaultValue = descriptor.getDefaultValue();
@@ -301,8 +320,19 @@ public class DefaultParameterDescriptor<
     }
 
     /**
+     * The minimum number of times that values for this parameter group or parameter are
required.
+     * A value of 0 means an optional parameter and a value of 1 means a mandatory parameter.
+     *
+     * @see #getMaximumOccurs()
+     */
+    @Override
+    public int getMinimumOccurs() {
+        return required ? 1 : 0;
+    }
+
+    /**
      * The maximum number of times that values for this parameter group or parameter can
be included.
-     * For a {@linkplain DefaultParameterDescriptor single parameter}, the value is always
1.
+     * For a {@code ParameterDescriptor}, the value is always 1.
      *
      * @return The maximum occurrence.
      *
@@ -404,16 +434,15 @@ public class DefaultParameterDescriptor<
      * This method compares the following properties in every cases:
      *
      * <ul>
-     *   <li>{@link #getName()}</li>
-     *   <li>{@link #getMinimumOccurs()}</li>
-     *   <li>{@link #getMaximumOccurs()}</li>
+     *   <li>{@link #getName()}, compared {@linkplain #isHeuristicMatchForName(String)
heuristically}
+     *       in {@code IGNORE_METADATA} or less strict mode.</li>
      *   <li>{@link #getValueClass()}</li>
      *   <li>{@link #getDefaultValue()}</li>
      *   <li>{@link #getUnit()}</li>
      * </ul>
      *
-     * All other properties (minimum, maximum and valid values) are compared only
-     * for modes stricter than {@link ComparisonMode#IGNORE_METADATA}.
+     * All other properties (minimum and maximum occurrences, minimum, maximum and valid
values)
+     * are compared only for modes stricter than {@link ComparisonMode#IGNORE_METADATA}.
      *
      * @return {@inheritDoc}
      */
@@ -440,7 +469,9 @@ public class DefaultParameterDescriptor<
                 }
                 case BY_CONTRACT: {
                     final ParameterDescriptor<?> that = (ParameterDescriptor<?>)
object;
-                    return                    getValueClass() == that.getValueClass()   
&&
+                    return getMinimumOccurs() == that.getMinimumOccurs() &&
+                           getMaximumOccurs() == that.getMaximumOccurs() &&
+                           getValueClass()    == that.getValueClass()    &&
                            Objects.    equals(getValidValues(),  that.getValidValues()) 
&&
                            Objects.deepEquals(getDefaultValue(), that.getDefaultValue())
&&
                            Objects.    equals(getMinimumValue(), that.getMinimumValue())
&&
@@ -449,11 +480,12 @@ public class DefaultParameterDescriptor<
                 }
                 case STRICT: {
                     final DefaultParameterDescriptor<?> that = (DefaultParameterDescriptor<?>)
object;
-                    return                    this.valueClass == that.valueClass    &&
+                    return                    this.required   == that.required      &&
+                                              this.valueClass == that.valueClass    &&
                            Objects.    equals(this.validValues,  that.validValues)  &&
                            Objects.deepEquals(this.defaultValue, that.defaultValue) &&
-                           Objects.    equals(this.minimumValue, that.minimumValue)     
&&
-                           Objects.    equals(this.maximumValue, that.maximumValue)     
&&
+                           Objects.    equals(this.minimumValue, that.minimumValue) &&
+                           Objects.    equals(this.maximumValue, that.maximumValue) &&
                            Objects.    equals(this.unit,         that.unit);
                 }
             }
@@ -468,11 +500,24 @@ public class DefaultParameterDescriptor<
      */
     @Override
     protected long computeHashCode() {
-        return Arrays.deepHashCode(new Object[] {valueClass, defaultValue, minimumValue,
maximumValue, unit})
+        return Arrays.deepHashCode(new Object[] {required, valueClass, defaultValue, minimumValue,
maximumValue, unit})
                 + super.computeHashCode();
     }
 
     /**
+     * Formats the inner part of a <cite>Well Known Text</cite> (WKT) element.
+     *
+     * @param  formatter The formatter to use.
+     * @return The WKT element name.
+     *
+     * @todo Not yet implemented.
+     */
+    @Override
+    protected String formatTo(final Formatter formatter) {
+        return null;
+    }
+
+    /**
      * Returns a string representation of this descriptor. The string returned by this
      * method is for information purpose only and may change in future SIS version.
      */

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java?rev=1567019&r1=1567018&r2=1567019&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] Tue Feb 11 09:53:12 2014
@@ -210,7 +210,7 @@ public class AbstractIdentifiedObject ex
      * Constructs an object from the given properties. Keys are strings from the table below.
      * The map given in argument shall contain an entry at least for the
      * {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} or
-     * {@value org.opengis.referencing.ReferenceIdentifier#CODE_KEY} key.
+     * {@value org.opengis.metadata.Identifier#CODE_KEY} key.
      * Other properties listed in the table below are optional.
      * In particular, {@code "authority"}, {@code "code"}, {@code "codespace"} and {@code
"version"}
      * are convenience properties for building a name, and are ignored if the {@code "name"}
property
@@ -714,7 +714,7 @@ public class AbstractIdentifiedObject ex
      * two objects that can be differentiated only by some identifier (name or alias), like
      * {@linkplain org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis coordinate system
axes},
      * {@linkplain org.apache.sis.referencing.datum.AbstractDatum datum},
-     * {@linkplain org.apache.sis.parameter.AbstractParameterDescriptor parameters} and
+     * {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor parameters} and
      * {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod operation
methods}.
      * See {@link #equals(Object, ComparisonMode)} for more information.
      *
@@ -753,34 +753,37 @@ public class AbstractIdentifiedObject ex
      * The strictness level is controlled by the second argument,
      * from stricter to more permissive values:
      *
-     * <table class="compact">
+     * <p><table class="compact">
      *   <tr><td>{@link ComparisonMode#STRICT STRICT}:</td>
      *        <td>Verifies if the two objects are of the same {@linkplain #getClass()
class}
      *            and compares all public properties, including SIS-specific (non standard)
properties.</td></tr>
      *   <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}:</td>
      *       <td>Verifies if the two objects implement the same {@linkplain #getInterface()
GeoAPI interface}
-     *           and compares all properties defined by that interface: {@linkplain #getName()
name},
-     *           {@linkplain #getRemarks() remarks}, {@linkplain #getIdentifiers() identifiers},
<i>etc</i>.</td></tr>
+     *           and compares all properties defined by that interface ({@linkplain #getName()
name},
+     *           {@linkplain #getIdentifiers() identifiers}, {@linkplain #getRemarks() remarks},
<i>etc</i>).
+     *           The two objects do not need to be instances of the same implementation class
+     *           and SIS-specific properties are ignored.</td></tr>
      *   <tr><td>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}:</td>
      *       <td>Compares only the properties relevant to coordinate transformations.
Generally speaking, the content
      *           of the {@code properties} map given at {@linkplain #AbstractIdentifiedObject(Map)
construction time}
      *           is considered ignorable metadata while the explicit arguments given to the
constructor (if any) are
-     *           considered non-ignorable.</td></tr>
+     *           considered non-ignorable. Note that there is some exceptions to this rule
of thumb — see
+     *           <cite>When object name matter</cite> below.</td></tr>
      *   <tr><td>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}:</td>
      *       <td>Same as {@code IGNORE_METADATA}, with some tolerance threshold on
numerical values.</td></tr>
      *   <tr><td>{@link ComparisonMode#DEBUG DEBUG}:</td>
      *        <td>Special mode for figuring out why two objects expected to be equal
are not.</td></tr>
-     * </table>
+     * </table></p>
      *
      * The main guideline is that if {@code sourceCRS.equals(targetCRS, IGNORE_METADATA)}
returns {@code true},
      * then the transformation from {@code sourceCRS} to {@code targetCRS} should be the
identity transform
-     * no matter what {@link #getName()} said.
+     * even if the two CRS do not have the same name.
      *
-     * {@section Exceptions to the above rules}
+     * {@section When object name matter}
      * Some subclasses (especially
      * {@link org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis},
      * {@link org.apache.sis.referencing.datum.AbstractDatum} and
-     * {@link org.apache.sis.parameter.AbstractParameterDescriptor}) will compare the
+     * {@link org.apache.sis.parameter.DefaultParameterDescriptor}) will compare the
      * {@linkplain #getName() name} even in {@code IGNORE_METADATA} mode,
      * because objects of those types with different names have completely different meaning.
      * For example nothing differentiate the {@code "semi_major"} and {@code "semi_minor"}
parameters except the name.

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java?rev=1567019&r1=1567018&r2=1567019&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java
[UTF-8] Tue Feb 11 09:53:12 2014
@@ -97,19 +97,19 @@ public class DefaultCoordinateSystemAxis
     private static final long serialVersionUID = -7883614853277827689L;
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getMinimumValue()}.
      */
     public static final String MINIMUM_VALUE_KEY = "minimumValue";
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getMaximumValue()}.
      */
     public static final String MAXIMUM_VALUE_KEY = "maximumValue";
 
     /**
-     * Key for the {@value} property to be given to the constructor.
+     * Key for the <code>{@value}</code> property to be given to the constructor.
      * This is used for setting the value to be returned by {@link #getRangeMeaning()}.
      */
     public static final String RANGE_MEANING_KEY = "rangeMeaning";

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java?rev=1567019&r1=1567018&r2=1567019&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
[UTF-8] Tue Feb 11 09:53:12 2014
@@ -110,7 +110,7 @@ public interface LenientComparable {
      * The strictness level is controlled by the second argument,
      * from stricter to more permissive values:
      *
-     * <table class="compact" >
+     * <p><table class="compact" >
      *   <tr><td>{@link ComparisonMode#STRICT STRICT}:</td>
      *        <td>All attributes of the compared objects shall be strictly equal.</td></tr>
      *   <tr><td>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}:</td>
@@ -122,7 +122,7 @@ public interface LenientComparable {
      *           with some tolerance threshold on numerical values.</td></tr>
      *   <tr><td>{@link ComparisonMode#DEBUG DEBUG}:</td>
      *        <td>Special mode for figuring out why two objects expected to be equal
are not.</td></tr>
-     * </table>
+     * </table></p>
      *
      * {@section Conformance to the <code>equals(Object)</code> method contract}
      * {@link ComparisonMode#STRICT} is the only mode compliant with the {@link Object#equals(Object)}
contract.



Mime
View raw message