sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1545748 - in /sis/branches/JDK7/core: sis-referencing/src/main/java/org/apache/sis/referencing/ sis-referencing/src/main/java/org/apache/sis/referencing/cs/ sis-referencing/src/main/java/org/apache/sis/referencing/datum/ sis-referencing/sr...
Date Tue, 26 Nov 2013 17:43:01 GMT
Author: desruisseaux
Date: Tue Nov 26 17:43:00 2013
New Revision: 1545748

URL: http://svn.apache.org/r1545748
Log:
Javadoc clarification, trying to emphase on the heuristic nature of 'nameMatches(String)'
method.
Also put the implementation in-line with what javadoc said regarding diacritical signs.

Modified:
    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/IdentifiedObjects.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCoordinateSystemAxis.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
    sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/IdentifiedObjectsTest.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/StringBuilders.java

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=1545748&r1=1545747&r2=1545748&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 Nov 26 17:43:00 2013
@@ -479,9 +479,9 @@ public class AbstractIdentifiedObject ex
 
     /**
      * Returns {@code true} if either the {@linkplain #getName() primary name} or at least
-     * one {@linkplain #getAlias() alias} "ends" with the specified string. More specifically
-     * this method returns {@code true} if the given {@code name} is equal, ignoring aspects
-     * documented below, to one of the following names:
+     * one {@linkplain #getAlias() alias} matches the given string according heuristic rules.
+     * The default implementation returns {@code true} if the given {@code name} is equal,
+     * ignoring aspects documented below, to one of the following names:
      *
      * <ul>
      *   <li>The {@linkplain #getName() primary name}'s {@linkplain NamedIdentifier#getCode()
code}
@@ -490,17 +490,25 @@ public class AbstractIdentifiedObject ex
      *       (ignoring {@linkplain NamedIdentifier#scope() scope} and namespace).</li>
      * </ul>
      *
+     * {@note Namespaces or scopes are ignored because this method is typically invoked with
either the value of an
+     *        other <code>IdentifiedObject.getName().getCode()</code>, or with
the <cite>Well Known Text</cite> (WKT)
+     *        projection or parameter name.}
+     *
      * The comparison ignores the following aspects:
      * <ul>
-     *   <li>Lower/Upper cases</li>
+     *   <li>Lower/upper cases.</li>
      *   <li>Some Latin diacritical signs (e.g. {@code "Réunion"} and {@code "Reunion"}
are considered equal).</li>
      *   <li>All characters that are not {@linkplain Character#isLetterOrDigit(int)
letters or digits}
      *       (e.g. {@code "Mercator (1SP)"} and {@code "Mercator_1SP"} are considered equal).</li>
      * </ul>
      *
      * {@section Usage}
-     * This method is invoked by SIS when comparing in {@code IGNORE_METADATA} mode two objects
that can be
-     * differentiated only by their name, like coordinate system axes, datum, parameters
and operation methods.
+     * This method is invoked by SIS when comparing in {@link ComparisonMode#IGNORE_METADATA
IGNORE_METADATA} mode
+     * 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.referencing.operation.DefaultOperationMethod operation
methods}.
      * See {@link #equals(Object, ComparisonMode)} for more information.
      *
      * <p>This method is also invoked when searching a parameter or operation method
for a given name.
@@ -509,16 +517,21 @@ public class AbstractIdentifiedObject ex
      * accepts it as an alias of the <cite>Mercator (variant A)</cite> projection.</p>
      *
      * {@section Overriding by subclasses}
-     * Some subclasses relax further the comparison criterion:
+     * Some subclasses add more flexibility to the comparisons:
      * <ul>
-     *   <li>{@linkplain org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#nameMatches(String)
Comparisons
-     *       of coordinate system axis names} consider “Lat”, “Latitude” and “Geodetic
latitude” as synonymous, and
-     *       likewise for longitude.</li>
+     *   <li>{@linkplain org.apache.sis.referencing.cs.DefaultCoordinateSystemAxis#nameMatches(String)
Comparisons of
+     *       coordinate system axis names} consider {@code "Lat"}, {@code "Latitude"} and
{@code "Geodetic latitude"}
+     *       as synonymous, and likewise for longitude.</li>
      *   <li>{@linkplain org.apache.sis.referencing.datum.DefaultGeodeticDatum#nameMatches(String)
Comparisons
      *       of geodetic datum} ignore the {@code "D_"} prefix, if any. This prefix appears
in ESRI datum name
      *       (e.g. {@code "D_WGS_1984"}).</li>
      * </ul>
      *
+     * {@section Future evolutions}
+     * This method implements heuristic rules learned from experience while trying to provide
inter-operability
+     * with different data producers. Those rules may be adjusted in any future SIS version
according experience
+     * gained while working with more data producers.
+     *
      * @param  name The name to compare with the object name or aliases.
      * @return {@code true} if the primary name of at least one alias matches the specified
{@code name}.
      *

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -30,11 +30,11 @@ import org.opengis.referencing.Identifie
 import org.opengis.referencing.ReferenceIdentifier;
 
 import org.apache.sis.util.Static;
+import org.apache.sis.util.CharSequences;
 import org.apache.sis.util.iso.DefaultNameSpace;
 import org.apache.sis.metadata.iso.citation.Citations;
 
 import static org.apache.sis.util.ArgumentChecks.ensureNonNull;
-import static org.apache.sis.util.CharSequences.equalsFiltered;
 import static org.apache.sis.util.Characters.Filter.LETTERS_AND_DIGITS;
 import static org.apache.sis.internal.util.Citations.iterator;
 import static org.apache.sis.internal.util.Citations.identifierMatches;
@@ -288,10 +288,12 @@ public final class IdentifiedObjects ext
     }
 
     /**
-     * Returns {@code true} if either the {@linkplain AbstractIdentifiedObject#getName()
primary name} or
-     * at least one {@linkplain AbstractIdentifiedObject#getAlias() alias} "ends" with the
specified string.
-     * More specifically this method returns {@code true} if the given {@code name} is equal,
-     * ignoring aspects documented below, to one of the following names:
+     * Returns {@code true} if either the {@linkplain AbstractIdentifiedObject#getName()
primary name} or at least
+     * one {@linkplain AbstractIdentifiedObject#getAlias() alias} matches the given string
according heuristic rules.
+     * If the given object is an instance of {@link AbstractIdentifiedObject}, then this
method delegates to its
+     * {@link AbstractIdentifiedObject#nameMatches(String) nameMatches(String)} method in
order to leverage the
+     * additional rules implemented by sub-classes. Otherwise the fallback implementation
returns {@code true}
+     * if the given {@code name} is equal, ignoring aspects documented below, to one of the
following names:
      *
      * <ul>
      *   <li>The {@linkplain AbstractIdentifiedObject#getName() primary name}'s {@linkplain
NamedIdentifier#getCode() code}
@@ -302,15 +304,12 @@ public final class IdentifiedObjects ext
      *
      * The comparison ignores the following aspects:
      * <ul>
-     *   <li>Lower/Upper cases</li>
+     *   <li>Lower/upper cases.</li>
      *   <li>Some Latin diacritical signs (e.g. {@code "Réunion"} and {@code "Reunion"}
are considered equal).</li>
      *   <li>All characters that are not {@linkplain Character#isLetterOrDigit(int)
letters or digits}
      *       (e.g. {@code "Mercator (1SP)"} and {@code "Mercator_1SP"} are considered equal).</li>
      * </ul>
      *
-     * If the given object is an instance of {@link AbstractIdentifiedObject}, then this
method delegates
-     * to its {@code nameMatches(String)} method. Otherwise this method fallbacks on a generic
algorithm.
-     *
      * @param  object The object for which to check the name or alias.
      * @param  name The name to compare with the object name or aliases.
      * @return {@code true} if the primary name of at least one alias matches the specified
{@code name}.
@@ -330,33 +329,40 @@ public final class IdentifiedObjects ext
 
     /**
      * Returns {@code true} if the {@linkplain AbstractIdentifiedObject#getName() primary
name} of the given object
-     * or one of the given alias matches the given name. The comparison ignores case, Some
Latin diacritical signs
+     * or one of the given alias matches the given name. The comparison ignores case, some
Latin diacritical signs
      * and any characters that are not letters or digits.
      *
-     * @param  object The object to check.
-     * @param  alias  The list of alias in {@code object} (may be {@code null}).
-     *                This method will never modify this list. Consequently, the
-     *                given list can be a direct reference to an internal list.
-     * @param  name   The name for which to check for equality.
+     * @param  object  The object to check.
+     * @param  aliases The list of alias in {@code object} (may be {@code null}).
+     *                 This method will never modify this list. Consequently, the
+     *                 given list can be a direct reference to an internal list.
+     * @param  name    The name for which to check for equality.
      * @return {@code true} if the primary name or at least one alias matches the given {@code
name}.
      */
-    static boolean nameMatches(final IdentifiedObject object, final Collection<GenericName>
alias, final String name) {
+    static boolean nameMatches(final IdentifiedObject object, final Collection<GenericName>
aliases, CharSequence name) {
+        name = CharSequences.toASCII(name);
         final ReferenceIdentifier id = object.getName();
         if (id != null) { // Paranoiac check.
-            final String code = id.getCode();
+            final CharSequence code = CharSequences.toASCII(id.getCode());
             if (code != null) { // Paranoiac check.
-                if (equalsFiltered(name, code, LETTERS_AND_DIGITS, true)) {
+                if (CharSequences.equalsFiltered(name, code, LETTERS_AND_DIGITS, true)) {
                     return true;
                 }
             }
         }
-        if (alias != null) {
-            for (GenericName asName : alias) {
-                if (asName != null) { // Paranoiac check.
-                    asName = asName.tip();
-                    if (equalsFiltered(name, asName.toString(), LETTERS_AND_DIGITS, true))
{
+        if (aliases != null) {
+            for (final GenericName alias : aliases) {
+                if (alias != null) { // Paranoiac check.
+                    final CharSequence tip = CharSequences.toASCII(alias.tip().toString());
+                    if (CharSequences.equalsFiltered(name, tip, LETTERS_AND_DIGITS, true))
{
                         return true;
                     }
+                    /*
+                     * Note: a previous version compared also the scoped names. We removed
that part,
+                     * because experience has shown that this method is used only for the
"code" part
+                     * of an object name. If we really want to compare scoped name, it would
probably
+                     * be better to take a GenericName argument instead than String.
+                     */
                 }
             }
         }

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -27,10 +27,8 @@ import org.apache.sis.util.Immutable;
 
 
 /**
- * A 1-, 2-, or 3-dimensional Cartesian coordinate system. The position of points are relative
- * to orthogonal straight axes in the 2- and 3-dimensional cases. In the 1-dimensional case,
- * the coordinate system contains a single straight coordinate axis. All axes shall have
the
- * same linear unit of measure.
+ * A 1-, 2-, or 3-dimensional Cartesian coordinate system with straight orthogonal axes.
+ * All axes shall have the same linear unit of measure.
  *
  * <table class="sis"><tr>
  *   <th>Used with</th>

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=1545748&r1=1545747&r2=1545748&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 Nov 26 17:43:00 2013
@@ -378,10 +378,11 @@ public class DefaultCoordinateSystemAxis
     }
 
     /**
-     * Returns {@code true} if either the {@linkplain #getName() primary name} or at least
one
-     * {@linkplain #getAlias() alias} "ends" with the specified string. This method performs
the
-     * search documented in the {@linkplain AbstractIdentifiedObject#nameMatches(String)
super-class},
-     * with the addition of special processing for latitudes and longitudes:
+     * Returns {@code true} if either the {@linkplain #getName() primary name} or at least
+     * one {@linkplain #getAlias() alias} matches the given string according heuristic rules.
+     * This method performs the comparison documented in the
+     * {@linkplain AbstractIdentifiedObject#nameMatches(String) super-class},
+     * with an additional flexibility for latitudes and longitudes:
      *
      * <ul>
      *   <li>{@code "Lat"}, {@code "Latitude"}  and {@code "Geodetic latitude"}  are
considered equivalent.</li>
@@ -391,9 +392,14 @@ public class DefaultCoordinateSystemAxis
      * The above special cases are needed in order to workaround a conflict in specifications:
      * ISO 19111 states explicitly that the latitude and longitude axis names shall be
      * "<cite>Geodetic latitude</cite>" and "<cite>Geodetic longitude</cite>",
while the legacy
-     * OGC 01-009 (where the WKT format is defined) said that the default values shall be
+     * OGC 01-009 (where version 1 of the WKT format is defined) said that the default values
shall be
      * "<cite>Lat</cite>" and "<cite>Lon</cite>".
      *
+     * {@section Future evolutions}
+     * This method implements heuristic rules learned from experience while trying to provide
inter-operability
+     * with different data producers. Those rules may be adjusted in any future SIS version
according experience
+     * gained while working with more data producers.
+     *
      * @param  name The name to compare.
      * @return {@code true} if the primary name of at least one alias matches the specified
{@code name}.
      */

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -292,16 +292,23 @@ public class AbstractDatum extends Abstr
     }
 
     /**
-     * Returns {@code true} if either the {@linkplain #getName() primary name} or at least
one
-     * {@linkplain #getAlias() alias} "ends" with the specified string. This method performs
the
-     * search documented in the {@linkplain AbstractIdentifiedObject#nameMatches(String)
super-class},
-     * with the addition of following rules:
+     * Returns {@code true} if either the {@linkplain #getName() primary name} or at least
+     * one {@linkplain #getAlias() alias} matches the given string according heuristic rules.
+     * This method performs the comparison documented in the
+     * {@linkplain AbstractIdentifiedObject#nameMatches(String) super-class},
+     * with the following additional flexibility:
      *
      * <ul>
-     *   <li>If the given name or this datum name starts with the {@code "D_"} prefix,
-     *       then the prefix is ignored. That prefix is used in ESRI datum names.</li>
+     *   <li>The {@code "D_"} prefix, if presents in the given name or this datum name,
is ignored.</li>
      * </ul>
      *
+     * {@note The <code>"D_"</code> prefix is used in ESRI datum names.}
+     *
+     * {@section Future evolutions}
+     * This method implements heuristic rules learned from experience while trying to provide
inter-operability
+     * with different data producers. Those rules may be adjusted in any future SIS version
according experience
+     * gained while working with more data producers.
+     *
      * @param  name The name to compare.
      * @return {@code true} if the primary name of at least one alias matches the specified
{@code name}.
      */

Modified: sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/IdentifiedObjectsTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/IdentifiedObjectsTest.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/IdentifiedObjectsTest.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/IdentifiedObjectsTest.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -41,7 +41,7 @@ public final strictfp class IdentifiedOb
     @Test
     public void testNameMatches() {
         final GenericName name = DefaultFactories.SIS_NAMES.createGenericName(null, "myScope",
"myName");
-        final IdentifiedObjectMock object = new IdentifiedObjectMock("myCode ", name); //
Intentional trailing space.
+        IdentifiedObjectMock object = new IdentifiedObjectMock("myCode ", name); // Intentional
trailing space.
 
         // Test the code.
         assertFalse(IdentifiedObjects.nameMatches(object, "other"));
@@ -58,5 +58,16 @@ public final strictfp class IdentifiedOb
         assertFalse(IdentifiedObjects.nameMatches(object, "other:myName"));
         assertFalse(IdentifiedObjects.nameMatches(object, "myScope:other"));
         assertFalse(IdentifiedObjects.nameMatches(object, "other:myScope:myName"));
+
+        // Test non-letter and non-digits characters.
+        object = new IdentifiedObjectMock("Mercator (1SP)", name);
+        assertTrue (IdentifiedObjects.nameMatches(object, "Mercator (1SP)"));
+        assertTrue (IdentifiedObjects.nameMatches(object, "Mercator_1SP"));
+        assertFalse(IdentifiedObjects.nameMatches(object, "Mercator_2SP"));
+
+        // Test diacritical signs
+        object = new IdentifiedObjectMock("Réunion", name);
+        assertTrue (IdentifiedObjects.nameMatches(object, "Réunion"));
+        assertTrue (IdentifiedObjects.nameMatches(object, "Reunion"));
     }
 }

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -951,7 +951,7 @@ search:     for (; fromIndex <= toIndex;
      * @param  text The text to scan for Unicode characters to replace by ASCII characters,
      *         or {@code null}.
      * @return The given text with substitution applied, or {@code text} if no replacement
-     *         has been applied.
+     *         has been applied, or {@code null} if the given text was null.
      *
      * @see StringBuilders#toASCII(StringBuilder)
      */

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/StringBuilders.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/StringBuilders.java?rev=1545748&r1=1545747&r2=1545748&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/StringBuilders.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/StringBuilders.java
[UTF-8] Tue Nov 26 17:43:00 2013
@@ -219,7 +219,7 @@ public final class StringBuilders extend
                 if (r >= 0 && r<ASCII.length()) {
                     final char ac = ASCII.charAt(r);
                     if (buffer == null) {
-                        buffer = new StringBuilder(text);
+                        buffer = new StringBuilder(text.length()).append(text);
                         text = buffer;
                     }
                     // Nothing special do to about codepoint here, since 'c' is



Mime
View raw message