sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1660860 - in /sis/branches/JDK8/core: sis-metadata/src/main/java/org/apache/sis/metadata/iso/ sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/ sis-referencing/src/main/java/org/apache/sis/referencing/ sis-utility/src/main/j...
Date Thu, 19 Feb 2015 11:52:08 GMT
Author: desruisseaux
Date: Thu Feb 19 11:52:08 2015
New Revision: 1660860

URL: http://svn.apache.org/r1660860
Log:
Usage of getIdentifier(...) versus getUnicodeIdentifier(...)
- Document better the policy.
- Replace getUnicodeIdentifier by getIdentifier when used only for WKT or toString() formatting
purpose.

Modified:
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifiedObject.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifier.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/io/IdentifiedObjectFormat.java

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -39,7 +39,6 @@ import org.apache.sis.io.wkt.ElementKind
 import static org.apache.sis.util.ArgumentChecks.ensureNonNull;
 import static org.apache.sis.util.CharSequences.trimWhitespaces;
 import static org.apache.sis.util.collection.Containers.property;
-import static org.apache.sis.internal.util.Citations.getUnicodeIdentifier;
 import static org.opengis.referencing.IdentifiedObject.REMARKS_KEY;
 
 // Branch-dependent imports
@@ -357,7 +356,7 @@ public class ImmutableIdentifier extends
          */
         value = properties.get(CODESPACE_KEY);
         if (value == null && !properties.containsKey(CODESPACE_KEY)) {
-            codeSpace = getUnicodeIdentifier(authority);
+            codeSpace = org.apache.sis.internal.util.Citations.getUnicodeIdentifier(authority);
         } else if (value instanceof String) {
             codeSpace = trimWhitespaces((String) value);
         } else {
@@ -559,7 +558,8 @@ public class ImmutableIdentifier extends
     protected String formatTo(final Formatter formatter) {
         String keyword = null;
         if (code != null) {
-            final String cs = (codeSpace != null) ? codeSpace : getUnicodeIdentifier(authority);
+            final String cs = (codeSpace != null) ? codeSpace :
+                    org.apache.sis.internal.util.Citations.getIdentifier(authority, true);
             if (cs != null) {
                 final Convention convention = formatter.getConvention();
                 if (convention.majorVersion() == 1) {

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -220,8 +220,7 @@ public final class Citations extends Sta
      *
      * @param  c1 The first citation to compare, or {@code null}.
      * @param  c2 the second citation to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and at least one title or
-     *         alternate title matches.
+     * @return {@code true} if both arguments are non-null, and at least one title or alternate
title matches.
      */
     public static boolean titleMatches(final Citation c1, final Citation c2) {
         return org.apache.sis.internal.util.Citations.titleMatches(c1, c2);
@@ -235,10 +234,10 @@ public final class Citations extends Sta
      *
      * @param  citation The citation to check for, or {@code null}.
      * @param  title The title or alternate title to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and the title or alternate
+     * @return {@code true} if both arguments are non-null, and the title or an alternate
      *         title matches the given string.
      */
-    public static boolean titleMatches(final Citation citation, String title) {
+    public static boolean titleMatches(final Citation citation, final String title) {
         return org.apache.sis.internal.util.Citations.titleMatches(citation, title);
     }
 
@@ -257,10 +256,7 @@ public final class Citations extends Sta
      *
      * @param  c1 The first citation to compare, or {@code null}.
      * @param  c2 the second citation to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and at least one identifier,
-     *         title or alternate title matches.
-     *
-     * @see org.apache.sis.referencing.IdentifierMatching
+     * @return {@code true} if both arguments are non-null, and at least one identifier matches.
      */
     public static boolean identifierMatches(final Citation c1, final Citation c2) {
         return org.apache.sis.internal.util.Citations.identifierMatches(c1, c2);
@@ -279,10 +275,7 @@ public final class Citations extends Sta
      *
      * @param  citation The citation to check for, or {@code null}.
      * @param  identifier The identifier to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and the title or alternate title
-     *         matches the given string.
-     *
-     * @see org.apache.sis.referencing.IdentifierMatching
+     * @return {@code true} if both arguments are non-null, and an identifier matches the
given string.
      */
     public static boolean identifierMatches(final Citation citation, final String identifier)
{
         return org.apache.sis.internal.util.Citations.identifierMatches(citation, null, identifier);
@@ -290,8 +283,8 @@ public final class Citations extends Sta
 
     /**
      * Infers an identifier from the given citation, or returns {@code null} if no identifier
has been found.
-     * This method is useful for extracting the namespace from an authority, for example
{@code "EPSG"}.
-     * The implementation performs the following choices:
+     * This method is useful for extracting the namespace from an authority (e.g. {@code
"EPSG"})
+     * for display purpose. This method performs the following choices:
      *
      * <ul>
      *   <li>If the given citation is {@code null}, then this method returns {@code
null}.</li>
@@ -313,10 +306,15 @@ public final class Citations extends Sta
      *
      * <div class="note"><b>Note:</b>
      * This method searches in alternate titles as a fallback because ISO specification said
-     * that those titles are often used for abbreviations.</div>
+     * that those titles are often used for abbreviations. However titles are never searched
+     * if the given citation contains at least one identifier.</div>
      *
-     * This method ignores leading and trailing whitespaces of every character sequences.
-     * Null references, empty character sequences and sequences of whitespaces only are ignored.
+     * This method ignores leading and trailing {@linkplain Character#isWhitespace(int) whitespaces}
+     * in every character sequences. Null or empty trimmed character sequences are ignored.
+     * This method does <em>not</em> remove {@linkplain Character#isIdentifierIgnorable(int)
ignorable characters}.
+     * The result is a string which is <em>likely</em>, but not guaranteed, to
be a valid XML or Unicode identifier.
+     * The returned string is useful when an "identifier-like" string is desired for display
or information purpose,
+     * but does not need to be a strictly valid identifier.
      *
      * @param  citation The citation for which to get the identifier, or {@code null}.
      * @return A non-empty identifier for the given citation without leading or trailing
whitespaces,
@@ -328,25 +326,25 @@ public final class Citations extends Sta
 
     /**
      * Infers a valid Unicode identifier from the given citation, or returns {@code null}
if none.
-     * This method performs the following actions:
+     * This method is useful for extracting the namespace from an authority (e.g. {@code
"EPSG"})
+     * for processing purpose. This method performs the following actions:
      *
      * <ul>
      *   <li>First, invoke {@link #getIdentifier(Citation)}.</li>
      *   <li>If the result of above method call is {@code null} or is not a
      *       {@linkplain org.apache.sis.util.CharSequences#isUnicodeIdentifier valid Unicode
identifier},
      *       then return {@code null}.</li>
-     *   <li>Otherwise remove the {@linkplain Character#isIdentifierIgnorable(int)
ignorable identifier characters},
-     *       if any. Then:
-     *       <ul>
-     *         <li>If the result is an empty string, returns {@code null}.</li>
-     *         <li>Otherwise returns the result.</li>
-     *       </ul>
-     *   </li>
+     *   <li>Otherwise remove the {@linkplain Character#isIdentifierIgnorable(int)
ignorable characters},
+     *       if any, and returns the result.</li>
      * </ul>
      *
-     * If non-null, the result is suitable for use as a XML identifier except for rarely
used characters
-     * (‘{@code µ}’, ‘{@code ª}’ (feminine ordinal indicator), ‘{@code º}’
(masculine ordinal indicator)
-     * and ‘{@code ⁔}’).
+     * <div class="note"><b>Note:</b>
+     * examples of ignorable identifier characters are <cite>zero width space</cite>
or <cite>word joiner</cite>.
+     * Those characters are illegal in XML identifiers, and should therfore be removed if
the Unicode identifier
+     * may also be used as XML identifier.</div>
+     *
+     * If non-null, the result is suitable for use as a XML identifier except for a few uncommon
characters
+     * ({@code µ}, {@code ª} (feminine ordinal indicator), {@code º} (masculine ordinal
indicator) and {@code ⁔}).
      *
      * @param  citation The citation for which to get the Unicode identifier, or {@code null}.
      * @return A non-empty Unicode identifier for the given citation without leading or trailing
whitespaces,

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/IdentifiedObjects.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -479,7 +479,7 @@ public final class IdentifiedObjects ext
         final String code = identifier.getCode();
         String cs = identifier.getCodeSpace();
         if (cs == null || cs.isEmpty()) {
-            cs = org.apache.sis.internal.util.Citations.getUnicodeIdentifier(identifier.getAuthority());
+            cs = org.apache.sis.internal.util.Citations.getIdentifier(identifier.getAuthority(),
true);
         }
         if (cs != null) {
             return cs + DefaultNameSpace.DEFAULT_SEPARATOR + code;

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifiedObject.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifiedObject.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifiedObject.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifiedObject.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -249,7 +249,7 @@ public class SimpleIdentifiedObject impl
             buffer.append(codespace).append(DefaultNameSpace.DEFAULT_SEPARATOR);
         }
         buffer.append(code).append('"');
-        final String identifier = Citations.getUnicodeIdentifier(authority);
+        final String identifier = Citations.getIdentifier(authority, true);
         if (identifier != null) {
             buffer.append(", ID[\"").append(identifier).append("\"]");
         }

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifier.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifier.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifier.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/simple/SimpleIdentifier.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -220,7 +220,7 @@ public class SimpleIdentifier implements
      */
     public String toWKT() {
         final StringBuilder buffer = new StringBuilder(40).append("ID[");
-        append(buffer, Citations.getUnicodeIdentifier(authority)); // Do not invoke getCodeSpace().
+        append(buffer, Citations.getIdentifier(authority, true));   // Do not invoke getCodeSpace().
         append(buffer.append(", "), code);
         return buffer.append(']').toString();
     }

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -38,11 +38,6 @@ import java.util.Objects;
  * defined in the {@link org.apache.sis.metadata.iso.citation.Citations} class, but the actual
  * implementation is defined here since it is needed by some utility methods.
  *
- * {@section Argument checks}
- * Every methods in this class accept {@code null} argument. This is different from the methods
- * in the {@link org.apache.sis.metadata.iso.citation.Citations} facade, which perform checks
- * against null argument for trapping user errors.
- *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
  * @version 0.6
@@ -87,16 +82,14 @@ public final class Citations extends Sta
     }
 
     /**
-     * Returns {@code true} if at least one {@linkplain Citation#getTitle() title} or
-     * {@linkplain Citation#getAlternateTitles() alternate title} in {@code c1} is leniently
-     * equal to a title or alternate title in {@code c2}. The comparison is case-insensitive
-     * and ignores every character which is not a {@linkplain Character#isLetterOrDigit(int)
-     * letter or a digit}. The titles ordering is not significant.
+     * Returns {@code true} if the two citations have at least one title in common,
+     * ignoring case and non-alphanumeric characters.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#titleMatches(Citation, Citation)}
+     * for the public documentation of this method.
      *
      * @param  c1 The first citation to compare, or {@code null}.
      * @param  c2 the second citation to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and at least one title or
-     *         alternate title matches.
+     * @return {@code true} if both arguments are non-null, and at least one title or alternate
title matches.
      */
     public static boolean titleMatches(final Citation c1, final Citation c2) {
         if (c1 != null && c2 != null) {
@@ -130,14 +123,14 @@ public final class Citations extends Sta
     }
 
     /**
-     * Returns {@code true} if the {@linkplain Citation#getTitle() title} or any
-     * {@linkplain Citation#getAlternateTitles() alternate title} in the given citation
-     * matches the given string. The comparison is case-insensitive and ignores every character
-     * which is not a {@linkplain Character#isLetterOrDigit(int) letter or a digit}.
+     * Returns {@code true} if the given citation has at least one title equals to the given
string,
+     * ignoring case and non-alphanumeric characters.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#titleMatches(Citation, String)}
+     * for the public documentation of this method.
      *
      * @param  citation The citation to check for, or {@code null}.
      * @param  title The title or alternate title to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and the title or alternate
+     * @return {@code true} if both arguments are non-null, and the title or an alternate
      *         title matches the given string.
      */
     public static boolean titleMatches(final Citation citation, final CharSequence title)
{
@@ -169,22 +162,15 @@ public final class Citations extends Sta
     }
 
     /**
-     * Returns {@code true} if at least one {@linkplain Citation#getIdentifiers() identifier}
-     * {@linkplain Identifier#getCode() code} in {@code c1} is equal to an identifier code
in
-     * {@code c2}. {@linkplain Identifier#getCodeSpace() Code spaces} are compared only if
-     * provided in the two identifiers being compared. Comparisons are case-insensitive and
ignores
-     * every character which is not a {@linkplain Character#isLetterOrDigit(int) letter or
a digit}.
-     * The identifier ordering is not significant.
-     *
-     * <p>If (and <em>only</em> if) the citations do not contains any identifier,
then this method
-     * fallback on titles comparison using the {@link #titleMatches(Citation,Citation) titleMatches}
-     * method. This fallback exists for compatibility with client codes using the citation
-     * {@linkplain Citation#getTitle() titles} without identifiers.</p>
+     * Returns {@code true} if the two citations have at least one identifier in common,
+     * ignoring case and non-alphanumeric characters. If and <em>only</em> if
the citations
+     * do not contain any identifier, then this method fallback on titles comparison.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#identifierMatches(Citation,
Citation)}
+     * for the public documentation of this method.
      *
      * @param  c1 The first citation to compare, or {@code null}.
      * @param  c2 the second citation to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and at least one identifier,
-     *         title or alternate title matches.
+     * @return {@code true} if both arguments are non-null, and at least one identifier matches.
      */
     public static boolean identifierMatches(Citation c1, Citation c2) {
         if (c1 != null && c2 != null) {
@@ -216,24 +202,16 @@ public final class Citations extends Sta
     }
 
     /**
-     * Returns {@code true} if at least one {@linkplain Citation#getIdentifiers() identifier}
-     * in the given citation have a {@linkplain Identifier#getCode() code} matching the given
-     * one. The comparison is case-insensitive and ignores every character which is not a
-     * {@linkplain Character#isLetterOrDigit(int) letter or a digit}.
-     *
-     * <p>If a match is found, if the given {@code identifier} is non-null and if the
code space
-     * of both objects is non-null, then the code space is also compared.</p>
-     *
-     * <p>If (and <em>only</em> if) the citation does not contain any identifier,
then this method
-     * fallback on titles comparison using the {@link #titleMatches(Citation, CharSequence)
titleMatches}
-     * method. This fallback exists for compatibility with client codes using citation
-     * {@linkplain Citation#getTitle() title} without identifiers.</p>
+     * Returns {@code true} if the given citation has at least one identifier equals to the
given string,
+     * ignoring case and non-alphanumeric characters. If and <em>only</em> if
the citations do not contain
+     * any identifier, then this method fallback on titles comparison.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#identifierMatches(Citation,
String)}
+     * for the public documentation of this method.
      *
      * @param  citation   The citation to check for, or {@code null}.
      * @param  identifier The identifier to compare, or {@code null} to unknown.
      * @param  code       The identifier code to compare, or {@code null}.
-     * @return {@code true} if both arguments are non-null, and the title or alternate title
-     *         matches the given string.
+     * @return {@code true} if both arguments are non-null, and an identifier matches the
given string.
      */
     public static boolean identifierMatches(final Citation citation, final Identifier identifier,
final CharSequence code) {
         if (citation != null && code != null) {
@@ -262,34 +240,17 @@ public final class Citations extends Sta
 
     /**
      * Infers an identifier from the given citation, or returns {@code null} if no identifier
has been found.
-     * This method is useful for extracting the namespace from an authority, for example
{@code "EPSG"}.
-     * The implementation performs the following choices:
+     * This method removes leading and trailing {@linkplain Character#isWhitespace(int) whitespaces}.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#getIdentifier(Citation)}
+     * for the public documentation of this method.
      *
+     * <p><b>Which method to use:</b></p>
      * <ul>
-     *   <li>If the given citation is {@code null}, then this method returns {@code
null}.</li>
-     *   <li>Otherwise if the citation contains at least one {@linkplain Citation#getIdentifiers()
identifier}, then:
-     *     <ul>
-     *       <li>If at least one identifier is a {@linkplain org.apache.sis.util.CharSequences#isUnicodeIdentifier
-     *           unicode identifier}, then the shortest of those identifiers is returned.</li>
-     *       <li>Otherwise the shortest identifier is returned, despite not being a
Unicode identifier.</li>
-     *     </ul></li>
-     *   <li>Otherwise if the citation contains at least one {@linkplain Citation#getTitle()
title} or
-     *       {@linkplain Citation#getAlternateTitles() alternate title}, then:
-     *     <ul>
-     *       <li>If at least one title is a {@linkplain org.apache.sis.util.CharSequences#isUnicodeIdentifier
-     *           unicode identifier}, then the shortest of those titles is returned.</li>
-     *       <li>Otherwise the shortest title is returned, despite not being a Unicode
identifier.</li>
-     *     </ul></li>
-     *   <li>Otherwise this method returns {@code null}.</li>
+     *   <li>For information purpose (e.g. some {@code toString()} methods), use {@code
getIdentifier(…, false)}.</li>
+     *   <li>For WKT formatting, use {@code getIdentifier(…, true)} in order to preserve
formatting characters.</li>
+     *   <li>For assigning a value to a {@code codeSpace} field, use {@link #getUnicodeIdentifier(Citation)}.</li>
      * </ul>
      *
-     * <div class="note"><b>Note:</b>
-     * This method searches in alternate titles as a fallback because ISO specification said
-     * that those titles are often used for abbreviations.</div>
-     *
-     * This method ignores leading and trailing whitespaces of every character sequences.
-     * Null references, empty character sequences and sequences of whitespaces only are ignored.
-     *
      * @param  citation The citation for which to get the identifier, or {@code null}.
      * @param  strict {@code true} for returning a non-null value only if the identifier
is a valid Unicode identifier.
      * @return A non-empty identifier for the given citation without leading or trailing
whitespaces,
@@ -351,25 +312,16 @@ public final class Citations extends Sta
 
     /**
      * Infers a valid Unicode identifier from the given citation, or returns {@code null}
if none.
-     * This method performs the following actions:
-     *
-     * <ul>
-     *   <li>First, invoke {@link #getIdentifier(Citation, boolean)}.</li>
-     *   <li>If the result of above method call is {@code null} or is not a
-     *       {@linkplain org.apache.sis.util.CharSequences#isUnicodeIdentifier valid Unicode
identifier},
-     *       then return {@code null}.</li>
-     *   <li>Otherwise remove the {@linkplain Character#isIdentifierIgnorable(int)
ignorable identifier characters},
-     *       if any. Then:
-     *       <ul>
-     *         <li>If the result is an empty string, returns {@code null}.</li>
-     *         <li>Otherwise returns the result.</li>
-     *       </ul>
-     *   </li>
-     * </ul>
-     *
-     * If non-null, the result is suitable for use as a XML identifier except for rarely
used characters
-     * (‘{@code µ}’, ‘{@code ª}’ (feminine ordinal indicator), ‘{@code º}’
(masculine ordinal indicator)
-     * and ‘{@code ⁔}’).
+     * This method removes {@linkplain Character#isIdentifierIgnorable(int) ignorable characters}.
+     * See {@link org.apache.sis.metadata.iso.citation.Citations#getUnicodeIdentifier(Citation)}
+     * for the public documentation of this method.
+     *
+     * {@section When to use}
+     * Use this method when assigning values to be returned by methods like {@link Identifier#getCodeSpace()},
+     * since those values are likely to be compared without special care about ignorable
identifier characters.
+     * But if the intend is to format a more complex string like WKT or {@code toString()},
then we suggest to
+     * use {@code getIdentifier(citation, true)} instead, which will produce the same result
but preserving the
+     * ignorable characters, which can be useful for formatting purpose.
      *
      * @param  citation The citation for which to get the Unicode identifier, or {@code null}.
      * @return A non-empty Unicode identifier for the given citation without leading or trailing
whitespaces,
@@ -408,7 +360,9 @@ public final class Citations extends Sta
                             buffer.appendCodePoint(c);
                         }
                     }
-                    return (buffer.length() != 0) ? buffer.toString() : null;
+                    // No need to verify if the buffer is empty, because ignorable
+                    // characters are not legal Unicode identifier start.
+                    return buffer.toString();
                 }
                 i += n;
             }

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/io/IdentifiedObjectFormat.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/io/IdentifiedObjectFormat.java?rev=1660860&r1=1660859&r2=1660860&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/io/IdentifiedObjectFormat.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/io/IdentifiedObjectFormat.java
[UTF-8] Thu Feb 19 11:52:08 2015
@@ -70,7 +70,7 @@ final class IdentifiedObjectFormat exten
         final String code = identifier.getCode();
         String cs = identifier.getCodeSpace();
         if (cs == null || cs.isEmpty()) {
-            cs = Citations.getUnicodeIdentifier(identifier.getAuthority());
+            cs = Citations.getIdentifier(identifier.getAuthority(), true);
         }
         if (cs != null) {
             toAppendTo.append(cs).append(DefaultNameSpace.DEFAULT_SEPARATOR);



Mime
View raw message