sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1452127 - in /sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata: AbstractMetadata.java MetadataStandard.java PropertyAccessor.java
Date Sun, 03 Mar 2013 21:23:47 GMT
Author: desruisseaux
Date: Sun Mar  3 21:23:47 2013
New Revision: 1452127

URL: http://svn.apache.org/r1452127
Log:
Minor clarifications in javadoc and method names.

Modified:
    sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
    sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
    sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java

Modified: sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] Sun Mar  3 21:23:47 2013
@@ -113,10 +113,6 @@ public abstract class AbstractMetadata i
      * for better performances, or for comparing "hidden" attributes not specified
      * by the GeoAPI (or other standard) interface.
      *
-     * <p>This method performs a <cite>deep</cite> comparison: if this
metadata contains
-     * other metadata, then the comparison will invoke the {@link Object#equals(Object)}
-     * method on those children as well.</p>
-     *
      * @param  object The object to compare with this metadata.
      * @param  mode The strictness level of the comparison.
      * @return {@code true} if the given object is equal to this metadata.
@@ -151,7 +147,7 @@ public abstract class AbstractMetadata i
          * Edit: actually, even if we could synchronize the two objects atomically, a deadlock
          *       risk would still exists for the reason documented in this class's javadoc.
          */
-        return standard.shallowEquals(this, object, mode, false);
+        return standard.equals(this, object, mode);
     }
 
     /**
@@ -177,8 +173,8 @@ public abstract class AbstractMetadata i
 
     /**
      * Computes a hash code value for this metadata using Java reflection. The hash code
-     * is defined as the sum of hash code values of all non-null properties. This is the
-     * same contract than {@link java.util.Set#hashCode()} and ensure that the hash code
+     * is defined as the sum of hash code values of all non-empty properties. This is a
+     * similar contract than {@link java.util.Set#hashCode()} and ensures that the hash code
      * value is insensitive to the ordering of properties.
      *
      * {@section Performance note}

Modified: sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] Sun Mar  3 21:23:47 2013
@@ -93,7 +93,7 @@ public class MetadataStandard {
     private static final MetadataStandard[] INSTANCES;
 
     /**
-     * An instance working on ISO 19123 standard as defined by GeoAPI interfaces
+     * An instance working on ISO 19111 standard as defined by GeoAPI interfaces
      * in the {@link org.opengis.referencing} package and sub-packages.
      */
     public static final MetadataStandard ISO_19111;
@@ -234,6 +234,8 @@ public class MetadataStandard {
      * </ul>
      *
      * @param  implementation The implementation class.
+     * @param  mandatory Whether this method shall throw an exception or return {@code null}
+     *         if no accessor is found for the given implementation class.
      * @return The accessor for the given implementation, or {@code null} if the given class
does
      *         not implement a metadata interface of the expected package and {@code mandatory}
      *         is {@code false}.
@@ -448,30 +450,25 @@ public class MetadataStandard {
      * this {@code MetadataStandard}, otherwise an exception will be thrown. However the
two
      * arguments do not need to be the same implementation class.
      *
-     * <p>This method can optionally excludes null values from the comparison. In metadata,
-     * null value often means "don't know", so in some occasions we want to consider two
-     * metadata as different only if a property value is know for sure to be different.</p>
-     *
      * {@section Shallow or deep comparisons}
      * This method implements a <cite>shallow</cite> comparison in that properties
are compared by
      * invoking their {@code properties.equals(…)} method without <em>explicit</em>
recursive call
-     * to this {@code shallowEquals(…)} method for children metadata. However the comparison
will
+     * to this {@code standard.equals(…)} method for children metadata. However the comparison
will
      * do <em>implicit</em> recursive calls if the {@code properties.equals(…)}
implementations
-     * invoke this {@code shallowEquals(…)} method. In the later case, the final result
is a deep
-     * comparison.
+     * delegate their work to this {@code standard.equals(…)} method, as {@link AbstractMetadata}
does.
+     * In the later case, the final result is a deep comparison.
      *
      * @param metadata1 The first metadata object to compare.
      * @param metadata2 The second metadata object to compare.
      * @param mode      The strictness level of the comparison.
-     * @param skipNulls If {@code true}, only non-null values will be compared.
      * @return {@code true} if the given metadata objects are equals.
      * @throws ClassCastException if at least one metadata object don't
      *         implements a metadata interface of the expected package.
      *
      * @see AbstractMetadata#equals(Object, ComparisonMode)
      */
-    public boolean shallowEquals(final Object metadata1, final Object metadata2,
-            final ComparisonMode mode, final boolean skipNulls) throws ClassCastException
+    public boolean equals(final Object metadata1, final Object metadata2,
+            final ComparisonMode mode) throws ClassCastException
     {
         if (metadata1 == metadata2) {
             return true;
@@ -483,14 +480,14 @@ public class MetadataStandard {
         if (accessor.type != findInterface(metadata2.getClass())) {
             return false;
         }
-        return accessor.shallowEquals(metadata1, metadata2, mode, skipNulls);
+        return accessor.equals(metadata1, metadata2, mode, false);
     }
 
     /**
      * Computes a hash code for the specified metadata. The hash code is defined as the
-     * sum of hash code values of all non-null properties. This is the same contract than
-     * {@link java.util.Set#hashCode} and ensure that the hash code value is insensitive
-     * to the ordering of properties.
+     * sum of hash code values of all non-empty properties. This is a similar contract
+     * than {@link java.util.Set#hashCode()} and ensures that the hash code value is
+     * insensitive to the ordering of properties.
      *
      * @param  metadata The metadata object to compute hash code.
      * @return A hash code value for the specified metadata.

Modified: sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] Sun Mar  3 21:23:47 2013
@@ -62,7 +62,7 @@ import static org.apache.sis.internal.ut
  * <ul>
  *   <li>The standard properties defined by the GeoAPI (or other standard) interfaces.
  *       Those properties are the only one accessible by most methods in this class,
- *       except {@link #shallowEquals(Object, Object, ComparisonMode, boolean)},
+ *       except {@link #equals(Object, Object, ComparisonMode, boolean)},
  *       {@link #shallowCopy(Object, Object, boolean)} and {@link #freeze(Object)}.</li>
  *
  *   <li>Extra properties defined by the {@link IdentifiedObject} interface. Those
properties
@@ -508,10 +508,13 @@ final class PropertyAccessor {
      * Returns the index of the specified property, or -1 if none.
      * The search is case-insensitive.
      *
-     * @param  key The property to search.
-     * @return The index of the given key, or -1 if none.
+     * @param  name The name of the property to search.
+     * @param  mandatory Whether this method shall throw an exception or return {@code -1}
+     *         if the given name is not found.
+     * @return The index of the given name, or -1 if none and {@code mandatory} is {@code
false}.
+     * @throws IllegalArgumentException if the name is not found and {@code mandatory} is
{@code true}.
      */
-    final int indexOf(final String name) {
+    final int indexOf(final String name, final boolean mandatory) {
         Integer index = mapping.get(name);
         if (index == null) {
             /*
@@ -521,29 +524,16 @@ final class PropertyAccessor {
              */
             final String key = CharSequences.trimWhitespaces(name.replace(" ", "").toLowerCase(Locale.ROOT));
             if (key == name || (index = mapping.get(key)) == null) { // Identity comparison
is okay here.
-                return -1;
+                if (!mandatory) {
+                    return -1;
+                }
+                throw new IllegalArgumentException(Errors.format(Errors.Keys.NoSuchProperty_2,
name, type));
             }
         }
         return index;
     }
 
     /**
-     * Always returns the index of the specified property (never -1).
-     * The search is case-insensitive.
-     *
-     * @param  key The property to search.
-     * @return The index of the given key.
-     * @throws IllegalArgumentException if the given key is not found.
-     */
-    final int requiredIndexOf(final String key) throws IllegalArgumentException {
-        final int index = indexOf(key);
-        if (index >= 0) {
-            return index;
-        }
-        throw new IllegalArgumentException(Errors.format(Errors.Keys.NoSuchProperty_2, key,
type));
-    }
-
-    /**
      * Returns the declaring class of the getter at the given index.
      *
      * @param  index The index of the property for which to get the declaring class.
@@ -958,12 +948,13 @@ final class PropertyAccessor {
     }
 
     /**
-     * Compares the two specified metadata objects. The comparison is <cite>shallow</cite>,
-     * i.e. all metadata properties are compared using their {@code properties.equals(…)}
-     * method without explicit calls to this {@code shallowEquals} method for children.
+     * Compares the two specified metadata objects. This method implements a <cite>shallow</cite>
+     * comparison, i.e. all metadata properties are compared using their {@code properties.equals(…)}
+     * method without explicit calls to this {@code accessor.equals(…)} method for children.
+     * However the final result may still be a deep comparison.
      *
      * <p>This method can optionally excludes null values from the comparison. In metadata,
-     * null value often means "don't know", so in some occasion we want to consider two
+     * null value often means "don't know", so in some occasions we want to consider two
      * metadata as different only if a property value is know for sure to be different.</p>
      *
      * @param  metadata1 The first metadata object to compare. This object determines the
accessor.
@@ -972,9 +963,12 @@ final class PropertyAccessor {
      * @param  skipNulls If {@code true}, only non-null values will be compared.
      * @throws BackingStoreException If the implementation threw a checked exception.
      *
-     * @see MetadataStandard#shallowEquals(Object, Object, ComparisonMode, boolean)
+     * @see MetadataStandard#equals(Object, Object, ComparisonMode, boolean)
+     *
+     * @todo The semantic of the <code>skipNulls</code> argument should be revisited
+     *       in order to provide a behavior more like a <code>contains(Object)</code>
method.
      */
-    public boolean shallowEquals(final Object metadata1, final Object metadata2,
+    public boolean equals(final Object metadata1, final Object metadata2,
             final ComparisonMode mode, final boolean skipNulls) throws BackingStoreException
     {
         assert type.isInstance(metadata1) : metadata1;
@@ -985,13 +979,13 @@ final class PropertyAccessor {
             final Method  method = getters[i];
             final Object  value1 = get(method, metadata1);
             final Object  value2 = get(method, metadata2);
-            final boolean empty1 = isEmpty(value1);
-            final boolean empty2 = isEmpty(value2);
+            final boolean empty1 = isNullOrEmpty(value1);
+            final boolean empty2 = isNullOrEmpty(value2);
             if (empty1 && empty2) {
                 continue;
             }
             if (!Utilities.deepEquals(value1, value2, mode)) {
-                if (mode.ordinal() < ComparisonMode.APPROXIMATIVE.ordinal() &&
floatEpsilonEqual(value1, value2)) {
+                if (mode.ordinal() >= ComparisonMode.APPROXIMATIVE.ordinal() &&
floatEpsilonEqual(value1, value2)) {
                     continue; // Accept this slight difference.
                 }
                 if (!skipNulls || (!empty1 && !empty2)) {
@@ -1003,9 +997,12 @@ final class PropertyAccessor {
     }
 
     /**
-     * Copies all metadata from source to target. The source can be any implementation of
-     * the metadata interface, but the target must be the implementation expected by this
-     * class.
+     * Copies all non-empty metadata from source to target. The source can be any implementation
+     * of the metadata interface, but the target must be the implementation expected by this
class.
+     *
+     * <p>If {@code skipNulls} is {@code true} and the source contains any null or
empty properties,
+     * then those properties will <strong>not</strong> overwrite the corresponding
properties in the
+     * destination metadata.</p>
      *
      * @param  source The metadata to copy.
      * @param  target The target metadata.
@@ -1027,7 +1024,7 @@ final class PropertyAccessor {
         for (int i=0; i<standardCount; i++) {
             final Method getter = getters[i];
             arguments[0] = get(getter, source);
-            if (!skipNulls || !isEmpty(arguments[0])) {
+            if (!skipNulls || !isNullOrEmpty(arguments[0])) {
                 if (setters == null) {
                     return false;
                 }
@@ -1079,10 +1076,10 @@ final class PropertyAccessor {
     }
 
     /**
-     * Returns a hash code for the specified metadata. The hash code is defined as the
-     * sum of hash code values of all non-null properties. This is the same contract than
-     * {@link java.util.Set#hashCode} and ensure that the hash code value is insensitive
-     * to the ordering of properties.
+     * Computes a hash code for the specified metadata. The hash code is defined as the
+     * sum of hash code values of all non-empty properties. This is a similar contract
+     * than {@link java.util.Set#hashCode()} and ensures that the hash code value is
+     * insensitive to the ordering of properties.
      *
      * @throws BackingStoreException If the implementation threw a checked exception.
      */
@@ -1091,7 +1088,7 @@ final class PropertyAccessor {
         int code = 0;
         for (int i=0; i<standardCount; i++) {
             final Object value = get(getters[i], metadata);
-            if (!isEmpty(value)) {
+            if (!isNullOrEmpty(value)) {
                 code += value.hashCode();
             }
         }
@@ -1099,7 +1096,7 @@ final class PropertyAccessor {
     }
 
     /**
-     * Counts the number of non-null properties.
+     * Counts the number of non-empty properties.
      *
      * @throws BackingStoreException If the implementation threw a checked exception.
      */
@@ -1107,7 +1104,7 @@ final class PropertyAccessor {
         assert type.isInstance(metadata) : metadata;
         int count = 0;
         for (int i=0; i<standardCount; i++) {
-            if (!isEmpty(get(getters[i], metadata))) {
+            if (!isNullOrEmpty(get(getters[i], metadata))) {
                 if (++count >= max) {
                     break;
                 }
@@ -1123,7 +1120,7 @@ final class PropertyAccessor {
      * is invoked from methods doing shallow copy or comparison. If we were inspecting elements,
      * we would need to add a check against infinite recursivity.</p>
      */
-    static boolean isEmpty(final Object value) {
+    static boolean isNullOrEmpty(final Object value) {
         return value == null
                 || ((value instanceof CharSequence) && CharSequences.trimWhitespaces((CharSequence)
value).length() == 0)
                 || ((value instanceof Collection<?>) && ((Collection<?>)
value).isEmpty())



Mime
View raw message