sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 01/03: Update documentation to better reflect the state of MD_ReferenceSystem support at XML marshalling time. It appears that https://issues.apache.org/jira/browse/SIS-431 is already mostly done, but it was not clear from the javadoc comments.
Date Wed, 11 Sep 2019 10:59:33 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 add9c3cb63c128d809408e291835501fdf0d7440
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Sep 11 10:25:21 2019 +0200

    Update documentation to better reflect the state of MD_ReferenceSystem support at XML
marshalling time.
    It appears that https://issues.apache.org/jira/browse/SIS-431 is already mostly done,
but it was not clear from the javadoc comments.
---
 .../internal/jaxb/metadata/RS_ReferenceSystem.java | 20 ++++++++++++++--
 .../metadata/replace/ReferenceSystemMetadata.java  | 12 +++++++++-
 .../apache/sis/test/integration/MetadataTest.java  | 28 +++++++++++++++-------
 .../org/apache/sis/test/integration/Metadata.xml   | 12 +++++++---
 4 files changed, 58 insertions(+), 14 deletions(-)

diff --git a/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/RS_ReferenceSystem.java
b/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/RS_ReferenceSystem.java
index 94933ce..5aba74d 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/RS_ReferenceSystem.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/RS_ReferenceSystem.java
@@ -23,8 +23,24 @@ import org.apache.sis.internal.jaxb.metadata.replace.ReferenceSystemMetadata;
 
 
 /**
- * JAXB adapter mapping implementing class to the GeoAPI interface. See
- * package documentation for more information about JAXB and interface.
+ * JAXB adapter mapping ISO 19111 Coordinate Reference Systems to {@code MD_ReferenceSystem}
object used in ISO 19115.
+ * Coordinate Reference Systems (CRS) are defined in details by {@link ReferenceSystem} implementation
classes.
+ * But the ISO 19115 metadata standards do not reference those CRS classes directly (except
in one case).
+ * Instead the metadata standards reference CRS by their identifier (for example an EPSG
code),
+ * optionally accompanied by a code telling whether the CRS type is geographic, projected,
temporal,
+ * a compound of the above, <i>etc.</i> Those two information are combined in
a {@code MD_ReferenceSystem} class
+ *
+ * {@preformat text
+ *   mrs:MD_ReferenceSystem
+ *   ├─mrs:referenceSystemIdentifier  :  mcc:MD_Identifier
+ *   └─mrs:referenceSystemType        :  mrs:MD_ReferenceSystemTypeCode
+ * }
+ *
+ * In order to have a more uniform way to handle reference systems, we replace {@code MD_ReferenceSystem}
tuples
+ * by associations to the actual Reference System objects. GeoAPI does that by using the
{@link ReferenceSystem}
+ * interface as the parent of {@link org.opengis.referencing.crs.CoordinateReferenceSystem}
interface.
+ * We use this adapter for replacing the full CRS object by the (identifier, type) tuple
at marshalling time
+ * where such tuple is expected.
  *
  * @author  Guilhem Legal (Geomatys)
  * @version 1.0
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/replace/ReferenceSystemMetadata.java
b/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/replace/ReferenceSystemMetadata.java
index 1c1fc21..8e4d741 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/replace/ReferenceSystemMetadata.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/internal/jaxb/metadata/replace/ReferenceSystemMetadata.java
@@ -33,7 +33,16 @@ import org.apache.sis.xml.Namespaces;
  * An implementation of {@link ReferenceSystem} marshalled as specified in ISO 19115.
  * This is different than the {@code ReferenceSystem} implementation provided in the
  * referencing module, since the later marshals the CRS as specified in GML (close
- * to ISO 19111 model).
+ * to ISO 19111 model). This class contains only CRS identification as below:
+ *
+ * {@preformat text
+ *   mrs:MD_ReferenceSystem
+ *   ├─mrs:referenceSystemIdentifier  :  mcc:MD_Identifier
+ *   └─mrs:referenceSystemType        :  mrs:MD_ReferenceSystemTypeCode
+ * }
+ *
+ * The {@code referenceSystemType} attribute is currently missing.
+ * See <a href="https://issues.apache.org/jira/browse/SIS-470">SIS-470</a>.
  *
  * <p>Note that this implementation is very simple and serves no other purpose than
being
  * a container for XML parsing or formatting. For real referencing service, consider using
@@ -45,6 +54,7 @@ import org.apache.sis.xml.Namespaces;
  * @version 1.0
  *
  * @see org.apache.sis.referencing.AbstractReferenceSystem
+ * @see <a href="https://issues.apache.org/jira/browse/SIS-431">SIS-431</a>
  *
  * @since 0.3
  * @module
diff --git a/core/sis-referencing/src/test/java/org/apache/sis/test/integration/MetadataTest.java
b/core/sis-referencing/src/test/java/org/apache/sis/test/integration/MetadataTest.java
index fb9081a..afa7056 100644
--- a/core/sis-referencing/src/test/java/org/apache/sis/test/integration/MetadataTest.java
+++ b/core/sis-referencing/src/test/java/org/apache/sis/test/integration/MetadataTest.java
@@ -20,6 +20,8 @@ import java.net.URI;
 import java.net.URL;
 import java.util.Arrays;
 import java.util.Locale;
+import java.util.Map;
+import java.util.HashMap;
 import java.io.StringWriter;
 import java.nio.charset.StandardCharsets;
 import javax.xml.bind.Marshaller;
@@ -66,6 +68,7 @@ import static java.util.Collections.singleton;
 import static java.util.Collections.singletonMap;
 
 // Test dependencies
+
 import org.apache.sis.test.LoggingWatcher;
 import org.apache.sis.test.TestUtilities;
 import org.apache.sis.test.xml.DocumentComparator;
@@ -258,20 +261,16 @@ public final strictfp class MetadataTest extends TestCase {
              */
             {
                 final DefaultCoordinateSystemAxis axis = new DefaultCoordinateSystemAxis(
-                        singletonMap(DefaultCoordinateSystemAxis.NAME_KEY, new NamedIdentifier(null,
"Depth")),
-                        "d", AxisDirection.DOWN, Units.METRE);
+                        nameAndIdentifier("depth", "Depth", null), "D", AxisDirection.DOWN,
Units.METRE);
 
                 final DefaultVerticalCS cs = new DefaultVerticalCS(
-                        singletonMap(DefaultVerticalCS.NAME_KEY, new NamedIdentifier(null,
"Depth")),
-                        axis);
+                        nameAndIdentifier("depth", "Depth", null), axis);
 
                 final DefaultVerticalDatum datum = new DefaultVerticalDatum(
-                        singletonMap(DefaultVerticalDatum.NAME_KEY, new NamedIdentifier(null,
"D28")),
-                        VerticalDatumType.OTHER_SURFACE);
+                        nameAndIdentifier("D28", "Depth below D28", "For testing purpose"),
VerticalDatumType.OTHER_SURFACE);
 
                 final DefaultVerticalCRS vcrs = new DefaultVerticalCRS(
-                        singletonMap(DefaultVerticalCRS.NAME_KEY, new NamedIdentifier(null,
"Depth below D28")),
-                        datum, cs);
+                        nameAndIdentifier("D28", "Depth below D28", "CRS for testing purpose"),
datum, cs);
 
                 final DefaultTemporalExtent temporal = new DefaultTemporalExtent();
                 setTemporalBounds(temporal, "1990-06-05", "1990-07-02");
@@ -364,6 +363,19 @@ public final strictfp class MetadataTest extends TestCase {
     }
 
     /**
+     * Returns a property map with a name and identifier. This is used for creating CRS components.
+     */
+    private static Map<String,?> nameAndIdentifier(final String identifier, final String
name, final String scope) {
+        final Map<String,Object> properties = new HashMap<>(4);
+        properties.put(DefaultVerticalDatum.NAME_KEY, new NamedIdentifier(null, name));
+        properties.put(DefaultVerticalDatum.IDENTIFIERS_KEY, new NamedIdentifier(null, "test",
identifier, null, null));
+        if (scope != null) {
+            properties.put(DefaultVerticalDatum.SCOPE_KEY, scope);
+        }
+        return properties;
+    }
+
+    /**
      * Returns the URL to the {@value #XML_FILE} file to use for this test.
      *
      * @return the URL to {@value #XML_FILE} test file.
diff --git a/core/sis-referencing/src/test/resources/org/apache/sis/test/integration/Metadata.xml
b/core/sis-referencing/src/test/resources/org/apache/sis/test/integration/Metadata.xml
index 566f22a..17932c7 100644
--- a/core/sis-referencing/src/test/resources/org/apache/sis/test/integration/Metadata.xml
+++ b/core/sis-referencing/src/test/resources/org/apache/sis/test/integration/Metadata.xml
@@ -402,14 +402,18 @@
               <gmd:maximumValue> <gco:Real>25</gco:Real> </gmd:maximumValue>
               <gmd:verticalCRS>
                 <gml:VerticalCRS gml:id="depth_D28">
+                  <gml:identifier codeSpace="test">D28</gml:identifier>
                   <gml:name>Depth below D28</gml:name>
+                  <gml:scope>CRS for testing purpose</gml:scope>
                   <gml:verticalCS>
                     <gml:VerticalCS gml:id="depth">
+                      <gml:identifier codeSpace="test">depth</gml:identifier>
                       <gml:name>Depth</gml:name>
                       <gml:axis>
-                        <gml:CoordinateSystemAxis uom="urn:ogc:def:uom:EPSG::9001" gml:id="d">
+                        <gml:CoordinateSystemAxis uom="urn:ogc:def:uom:EPSG::9001" gml:id="depth-axis">
+                          <gml:identifier codeSpace="test">depth</gml:identifier>
                           <gml:name>Depth</gml:name>
-                          <gml:axisAbbrev>d</gml:axisAbbrev>
+                          <gml:axisAbbrev>D</gml:axisAbbrev>
                           <gml:axisDirection codeSpace="EPSG">down</gml:axisDirection>
                         </gml:CoordinateSystemAxis>
                       </gml:axis>
@@ -417,7 +421,9 @@
                   </gml:verticalCS>
                   <gml:verticalDatum>
                     <gml:VerticalDatum gml:id="D28">
-                      <gml:name>D28</gml:name>
+                      <gml:identifier codeSpace="test">D28</gml:identifier>
+                      <gml:name>Depth below D28</gml:name>
+                      <gml:scope>For testing purpose</gml:scope>
                     </gml:VerticalDatum>
                   </gml:verticalDatum>
                 </gml:VerticalCRS>


Mime
View raw message