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);


Reply via email to