sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 03/04: Documentation and formatting related to WKT parsing. Deprecate Symbols.containsAxis(…) because AXIS elements are no longer optional in WKT 2.
Date Tue, 03 Nov 2020 22:54:54 GMT
This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git

commit c60795e3e6b344d2a72a4fea67727abd44beef75
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Tue Nov 3 21:42:29 2020 +0100

    Documentation and formatting related to WKT parsing.
    Deprecate Symbols.containsAxis(…) because AXIS elements are no longer optional in WKT
2.
---
 .../java/org/apache/sis/io/wkt/AbstractParser.java |  3 ++-
 .../main/java/org/apache/sis/io/wkt/Colors.java    |  1 +
 .../apache/sis/io/wkt/GeodeticObjectParser.java    | 10 ++++-----
 .../main/java/org/apache/sis/io/wkt/Symbols.java   | 24 +++++++++++++++++-----
 .../java/org/apache/sis/io/wkt/SymbolsTest.java    | 12 +++++------
 .../src/main/java/org/apache/sis/io/IO.java        |  2 +-
 .../main/java/org/apache/sis/io/package-info.java  |  4 ++--
 7 files changed, 36 insertions(+), 20 deletions(-)

diff --git a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/AbstractParser.java
b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/AbstractParser.java
index eff03e6..85596cd 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/AbstractParser.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/AbstractParser.java
@@ -240,7 +240,8 @@ abstract class AbstractParser implements Parser {
 
     /**
      * Returns the index after the end of the fragment name starting at the given index.
-     * Current implementation assumes that the fragment name is a Unicode identifier.
+     * Current implementation assumes that the fragment name is a Unicode identifier,
+     * except for the first character which is not required to be an identifier start.
      */
     static int endOfFragmentName(final String text, int upper) {
         final int length = text.length();
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Colors.java b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Colors.java
index 9d0b45a..dc0b592 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Colors.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Colors.java
@@ -127,6 +127,7 @@ public class Colors implements Cloneable, Serializable {
      * @param  key    the syntactic element for which to set the color.
      * @param  color  the color to give to the specified element, or {@code null} if none.
      * @throws IllegalArgumentException if the given color name is not recognized.
+     * @throws UnsupportedOperationException if this {@code Colors} instance is immutable.
      */
     public void setName(final ElementKind key, final String color) throws IllegalArgumentException
{
         if (isImmutable) {
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/GeodeticObjectParser.java
b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/GeodeticObjectParser.java
index f5aea8e..257bbcb 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/GeodeticObjectParser.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/GeodeticObjectParser.java
@@ -398,11 +398,11 @@ class GeodeticObjectParser extends MathTransformParser implements Comparator<Coo
         properties.put(IdentifiedObject.NAME_KEY, (name.isEmpty() && fallback !=
null) ? fallback.getName() : name);
         Element element;
         while ((element = parent.pullElement(OPTIONAL, ID_KEYWORDS)) != null) {
-            final String   codeSpace = element.pullString("codeSpace");
-            final String   code      = element.pullObject("code").toString();       // Accepts
Integer as well as String.
-            final Object   version   = element.pullOptional(Object.class);          // Accepts
Number as well as String.
-            final Element  citation  = element.pullElement(OPTIONAL, WKTKeywords.Citation);
-            final String   authority;
+            final String  codeSpace = element.pullString("codeSpace");
+            final String  code      = element.pullObject("code").toString();        // Accepts
Integer as well as String.
+            final Object  version   = element.pullOptional(Object.class);           // Accepts
Number as well as String.
+            final Element citation  = element.pullElement(OPTIONAL, WKTKeywords.Citation);
+            final String  authority;
             if (citation != null) {
                 authority = citation.pullString("authority");
                 citation.close(ignoredElements);
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
index c3287d7..1854302 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
@@ -73,7 +73,7 @@ import static org.apache.sis.util.ArgumentChecks.*;
  * Users can create their own {@code Symbols} instance for parsing or formatting a WKT with
different symbols.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
- * @version 1.0
+ * @version 1.1
  *
  * @see WKTFormat#getSymbols()
  * @see WKTFormat#setSymbols(Symbols)
@@ -239,7 +239,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
     /**
      * Throws an exception if this set of symbols is immutable.
      */
-    final void checkWritePermission() throws UnsupportedOperationException {
+    private void checkWritePermission() throws UnsupportedOperationException {
         if (isImmutable) {
             throw new UnsupportedOperationException(Errors.format(Errors.Keys.UnmodifiableObject_1,
"Symbols"));
         }
@@ -280,6 +280,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
      * Such WKT can be used for human reading, but not for data export.
      *
      * @param  locale  the new symbols locale.
+     * @throws UnsupportedOperationException if this {@code Symbols} instance is immutable.
      */
     public void setLocale(final Locale locale) {
         checkWritePermission();
@@ -361,6 +362,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
      *
      * @param  preferred     the preferred pair of opening and closing quotes, used at formatting
time.
      * @param  alternatives  alternative pairs of opening and closing quotes accepted at
parsing time.
+     * @throws UnsupportedOperationException if this {@code Symbols} instance is immutable.
      */
     public void setPairedBrackets(final String preferred, final String... alternatives) {
         checkWritePermission();
@@ -439,6 +441,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
      *
      * @param  preferred     the preferred pair of opening and closing quotes, used at formatting
time.
      * @param  alternatives  alternative pairs of opening and closing quotes accepted at
parsing time.
+     * @throws UnsupportedOperationException if this {@code Symbols} instance is immutable.
      */
     public void setPairedQuotes(final String preferred, final String... alternatives) {
         checkWritePermission();
@@ -508,6 +511,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
      *
      * @param  openSequence   the character for opening a sequence of values, as a Unicode
code point.
      * @param  closeSequence  the character for closing a sequence of values, as a Unicode
code point.
+     * @throws UnsupportedOperationException if this {@code Symbols} instance is immutable.
      */
     public void setSequenceBrackets(final int openSequence, final int closeSequence) {
         checkWritePermission();
@@ -533,6 +537,7 @@ public class Symbols implements Localized, Cloneable, Serializable {
      * but leading and trailing spaces will be ignored at parsing time.
      *
      * @param  separator  the new string to use as a separator in a list of values.
+     * @throws UnsupportedOperationException if this {@code Symbols} instance is immutable.
      */
     public void setSeparator(final String separator) {
         checkWritePermission();
@@ -609,6 +614,10 @@ public class Symbols implements Localized, Cloneable, Serializable {
      * The purpose of this method is to guess some characteristics about the encoded object
without
      * the cost of a full WKT parsing.
      *
+     * <div class="note"><b>Example:</b>
+     * {@code containsElement(wkt, "AXIS")} returns {@code true} if the given WKT contains
at least
+     * one instance of the {@code AXIS[…]} element, ignoring case.</div>
+     *
      * @param  wkt      the WKT to inspect.
      * @param  element  the element to search for.
      * @return {@code true} if the given WKT contains at least one instance of the given
element.
@@ -631,12 +640,16 @@ public class Symbols implements Localized, Cloneable, Serializable {
      * The check for axis elements is of particular interest because the axis order is a
frequent cause
      * of confusion when processing geographic data. Some applications just ignore any declared
axis order
      * in favor of their own hard-coded (<var>longitude</var>, <var>latitude</var>)
axis order.
-     * Consequently, the presence of {@code AXIS[…]} elements in a WKT is an indication
that the encoded
-     * object may not be understood as intended by some external software products.
+     * Consequently, the presence of {@code AXIS[…]} elements in a WKT 1 string is an indication
+     * that the encoded object may not be understood as intended by some external software
products.
      *
      * @param  wkt  the WKT to inspect.
      * @return {@code true} if the given WKT contains at least one instance of the {@code
AXIS[…]} element.
+     *
+     * @deprecated The {@code AXIS} element is no longer optional in WKT 2.
+     *             Consequently testing for its presence should not be needed anymore.
      */
+    @Deprecated
     public boolean containsAxis(final CharSequence wkt) {
         ensureNonNull("wkt", wkt);
         return containsElement(wkt, "AXIS", 0);
@@ -713,8 +726,9 @@ public class Symbols implements Localized, Cloneable, Serializable {
 
     /**
      * Returns a clone of this {@code Symbols}.
+     * The returned instance is modifiable (i.e. setter methods will not throw {@link UnsupportedOperationException}).
      *
-     * @return a clone of this {@code Symbols}.
+     * @return a modifiable clone of this {@code Symbols}.
      */
     @Override
     public Symbols clone() {
diff --git a/core/sis-referencing/src/test/java/org/apache/sis/io/wkt/SymbolsTest.java b/core/sis-referencing/src/test/java/org/apache/sis/io/wkt/SymbolsTest.java
index 4fed03d..87e6523 100644
--- a/core/sis-referencing/src/test/java/org/apache/sis/io/wkt/SymbolsTest.java
+++ b/core/sis-referencing/src/test/java/org/apache/sis/io/wkt/SymbolsTest.java
@@ -28,16 +28,16 @@ import static org.apache.sis.test.Assert.*;
  * Tests the {@link Symbols} class.
  *
  * @author  Martin Desruisseaux (Geomatys)
- * @version 0.4
+ * @version 1.1
  * @since   0.4
  * @module
  */
 public final strictfp class SymbolsTest extends TestCase {
     /**
-     * Tests the {@link Symbols#containsAxis(CharSequence)} method.
+     * Tests the {@link Symbols#containsElement(CharSequence, String)} method.
      */
     @Test
-    public void testContainsAxis() {
+    public void testContainsElement() {
         assertContainsAxis("At beginning of a line.",   true,                  "AXIS[“Long”,
EAST]");
         assertContainsAxis("Embeded in GEOGCS.",        true,  "GEOGCS[“WGS84”, AXIS[“Long”,
EAST]]");
         assertContainsAxis("Using different brackets.", true,  "GEOGCS[“WGS84”, AXIS
(“Long”, EAST)]");
@@ -48,17 +48,17 @@ public final strictfp class SymbolsTest extends TestCase {
     }
 
     /**
-     * Asserts that the call to {@link Symbols#containsAxis(CharSequence)} produce the given
result.
+     * Asserts that the call to {@code Symbols.containsElement(wkt, "AXIS")} produce the
given result.
      * This method expects an array using the {@code “…”} quotation marks, which will
be replaced by
      * the standard {@code '"'} quotation mark after we tested the given string.
      */
     private static void assertContainsAxis(final String message, final boolean expected,
final String wkt) {
-        assertEquals(message, expected, Symbols.getDefault().containsAxis(wkt));
+        assertEquals(message, expected, Symbols.getDefault().containsElement(wkt, "AXIS"));
         final StringBuilder buffer = new StringBuilder(wkt);
         StringBuilders.replace(buffer, '“', '"');
         StringBuilders.replace(buffer, '”', '"');
         assertFalse(wkt.contentEquals(buffer));
-        assertEquals(message, expected, Symbols.getDefault().containsAxis(buffer));
+        assertEquals(message, expected, Symbols.getDefault().containsElement(buffer, "AXIS"));
     }
 
     /**
diff --git a/core/sis-utility/src/main/java/org/apache/sis/io/IO.java b/core/sis-utility/src/main/java/org/apache/sis/io/IO.java
index 04b3586..a5e26b4 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/io/IO.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/io/IO.java
@@ -139,7 +139,7 @@ public final class IO extends Static {
      * or the localized <cite>"Unavailable content"</cite> string otherwise.
      */
     static String toString(final Appendable out) {
-        final CharSequence content = IO.content(out);
+        final CharSequence content = content(out);
         if (content != null) {
             return content.toString();
         }
diff --git a/core/sis-utility/src/main/java/org/apache/sis/io/package-info.java b/core/sis-utility/src/main/java/org/apache/sis/io/package-info.java
index d830ac1..70ff233 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/io/package-info.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/io/package-info.java
@@ -17,7 +17,7 @@
 
 /**
  * Extensions to standard Java I/O ({@link java.io.Reader}, {@link java.io.Writer},
- * {@link java.lang.Appendable}).
+ * {@link java.lang.Appendable}) and {@link java.text.Format}.
  * Many classes defined in this package are filters applying on-the-fly formatting while
writing
  * text to the output device. For example {@link org.apache.sis.io.LineAppender} can wrap
lines
  * to some maximal line length (e.g. 80 characters), and {@link org.apache.sis.io.TableAppender}
@@ -41,7 +41,7 @@
  * Unicode supplementary characters}.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
- * @version 0.3
+ * @version 1.1
  * @since   0.3
  * @module
  */


Mime
View raw message