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 2013/11/26 18:43:01 UTC
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...
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