sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1785729 - /sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/
Date Mon, 06 Mar 2017 18:55:58 GMT
Author: desruisseaux
Date: Mon Mar  6 18:55:58 2017
New Revision: 1785729

URL: http://svn.apache.org/viewvc?rev=1785729&view=rev
Log:
Improve documentation.

Modified:
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/AbstractLocation.java
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/FinalLocationType.java
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/MilitaryGridReferenceSystem.java
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ModifiableLocationType.java
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ReferencingByIdentifiers.java
    sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/package-info.java

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/AbstractLocation.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/AbstractLocation.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/AbstractLocation.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/AbstractLocation.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -61,14 +61,21 @@ import org.apache.sis.util.Debug;
  * @since   0.8
  * @version 0.8
  * @module
+ *
+ * @see ModifiableLocationType
+ * @see ReferencingByIdentifiers
+ * @see LocationFormat
  */
 public abstract class AbstractLocation implements Location {
     /**
      * The description of the nature of this geographic identifier, or {@code null} if unspecified.
      *
+     * <p>This field is non-final for sub-class constructors convenience,
+     * but its value should not be changed after {@code Location} construction.</p>
+     *
      * @see #getLocationType()
      */
-    private final LocationType type;
+    private LocationType type;
 
     /**
      * The geographic identifier, or {@code null} if unspecified.
@@ -90,6 +97,15 @@ public abstract class AbstractLocation i
     }
 
     /**
+     * Sets the location type to the unique child of current type. This method should be
invoked
+     * only when the caller know that there is at least one children and that the children
class
+     * is {@link FinalLocationType} (for performance reason).
+     */
+    final void setTypeToChild() {
+        type = ((FinalLocationType) type).children.get(0);
+    }
+
+    /**
      * Returns a unique identifier for the location instance. The methods of identifying
locations is specified
      * by the {@linkplain ModifiableLocationType#getIdentifications() location type identifications}.
      *

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/FinalLocationType.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/FinalLocationType.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/FinalLocationType.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/FinalLocationType.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -96,7 +96,7 @@ final class FinalLocationType extends Ab
      * Child location types (location types which sub-divides this location type).
      * This list is unmodifiable.
      */
-    private final List<LocationType> children;
+    final List<LocationType> children;
 
     /**
      * Creates a copy of the given location type with the reference system set to the given
value.

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/MilitaryGridReferenceSystem.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/MilitaryGridReferenceSystem.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/MilitaryGridReferenceSystem.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/MilitaryGridReferenceSystem.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -68,6 +68,48 @@ import org.opengis.referencing.gazetteer
  * Despite its name, MGRS is used not only for military purposes; it is used also for organizing
Earth Observation
  * data in directory trees for example.
  *
+ * <p>MGRS references are sequences of digits and letters like “4Q FJ 12345 67890”
(a reference with 1 metre accuracy),
+ * optionally written with reduced resolution as in “4Q FJ 123 678” (a reference
with 100 metres accuracy).
+ * Those references form a hierarchy of 3 {@linkplain ModifiableLocationType location types}:</p>
+ *
+ * <blockquote>
+ *   <b>Grid zone designator</b>         (example: “4Q”)<br>
+ *     └─<b>100 km square identifier</b> (example: “FJ”)<br>
+ *         └─<b>Grid coordinate</b>      (example: “12345 67890”)<br>
+ * </blockquote>
+ *
+ * <p>Conversions between MGRS references and spatial coordinates can be performed
by the {@link Coder Coder}
+ * inner class. The result of decoding a MGRS reference is an envelope rather than a point,
+ * but a representative point can be obtained.</p>
+ *
+ * <div class="note"><b>Example:</b>
+ * the following code:
+ *
+ * {@preformat java
+ *     MilitaryGridReferenceSystem system = new MilitaryGridReferenceSystem();
+ *     MilitaryGridReferenceSystem.Coder coder = system.createCoder();
+ *     Location loc = coder.decode("32TNL83");
+ *     System.out.println(loc);
+ * }
+ *
+ * should display (locale may vary):
+ *
+ * {@preformat text
+ *     ┌─────────────────────────────────────────────────────────────────┐
+ *     │ Location type:               Grid coordinate                    │
+ *     │ Geographic identifier:       32TNL83                            │
+ *     │ West bound:                    580,000 m    —     9°57′00″E     │
+ *     │ Representative value:          585,000 m    —    10°00′36″E     │
+ *     │ East bound:                    590,000 m    —    10°04′13″E     │
+ *     │ South bound:                 4,530,000 m    —    40°54′58″N     │
+ *     │ Representative value:        4,535,000 m    —    40°57′42″N     │
+ *     │ North bound:                 4,540,000 m    —    41°00′27″N     │
+ *     │ Coordinate reference system: WGS 84 / UTM zone 32N              │
+ *     │ Administrator:               North Atlantic Treaty Organization │
+ *     └─────────────────────────────────────────────────────────────────┘
+ * }
+ * </div>
+ *
  * <div class="section">Immutability and thread safety</div>
  * This class is immutable and thus thread-safe.
  * However the {@link Coder Coder} instances performing conversions between references and
coordinates
@@ -295,6 +337,9 @@ public class MilitaryGridReferenceSystem
      * Conversions between direct positions and references in the Military Grid Reference
System (MGRS).
      * Each {@code Coder} instance can read references at arbitrary precision, but formats
at the
      * {@linkplain #setPrecision specified precision}.
+     * The same {@code Coder} instance can be reused for reading or writing many MGRS references.
+     *
+     * <p>See the {@link MilitaryGridReferenceSystem} enclosing class for usage example.</p>
      *
      * <div class="section">Immutability and thread safety</div>
      * This class is <strong>not</strong> thread-safe. A new instance must be
created for each thread,
@@ -1181,6 +1226,19 @@ parse:                  switch (part) {
                 final MathTransform projection = crs.getConversionFromBase().getMathTransform();
                 computeGeographicBoundingBox(projection.inverse());
                 /*
+                 * Update the LocationType according the precision.
+                 * This update is mostly for documentation purpose.
+                 * There is three levels:
+                 *
+                 *   - Grid zone designator         (if hasSquareIdentification == false)
+                 *   - 100 km square identifier     (if resolution == 100 km)
+                 *   - Grid coordinate              (if resolution < 100 km)
+                 */
+                setTypeToChild();                   // Replace "Grid zone designator" by
"100 km square identifier".
+                if (sx < GRID_SQUARE_SIZE || sy < GRID_SQUARE_SIZE) {
+                    setTypeToChild();               // Replace "100 km square identifier"
by "Grid coordinate".
+                }
+                /*
                  * At this point we finished computing the position. Now perform error detection,
by verifying
                  * if the given 100 kilometres square identification is consistent with grid
zone designation.
                  * We verify both φ and λ, but the verification of φ is actually redundant
with the check of

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ModifiableLocationType.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ModifiableLocationType.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ModifiableLocationType.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ModifiableLocationType.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -110,6 +110,9 @@ import org.opengis.referencing.gazetteer
  * @since   0.8
  * @version 0.8
  * @module
+ *
+ * @see AbstractLocation
+ * @see ReferencingByIdentifiers
  */
 public class ModifiableLocationType extends AbstractLocationType {      // Not Serializable
on intend.
     /**

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ReferencingByIdentifiers.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ReferencingByIdentifiers.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ReferencingByIdentifiers.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/ReferencingByIdentifiers.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -54,6 +54,7 @@ import org.opengis.referencing.gazetteer
  * @module
  *
  * @see ModifiableLocationType
+ * @see AbstractLocation
  */
 @XmlTransient
 public class ReferencingByIdentifiers extends AbstractReferenceSystem implements ReferenceSystemUsingIdentifiers
{

Modified: sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/package-info.java?rev=1785729&r1=1785728&r2=1785729&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/package-info.java
[UTF-8] Mon Mar  6 18:55:58 2017
@@ -17,19 +17,17 @@
 
 
 /**
- * Directory mapping geographic identifiers to locations, either as descriptions or coordinates.
- * Geographic identifiers are location descriptors such as addresses and grid indexes.
- * Their reference systems are defined by <cite>Spatial referencing by geographic identifiers</cite>
(ISO 19112).
- * Gazetteers provide linking mechanism between referencing using geographic identifiers
(this package)
- * and referencing using coordinates (…{@link org.apache.sis.referencing.crs .crs} package).
+ * Mapping between geographic identifiers (addresses, grid indexes…) and locations (descriptions,
coordinates…).
+ * This package provides base classes implementing the <cite>Spatial referencing by
geographic identifiers</cite>
+ * (ISO 19112) standard. Those base classes are
+ * {@link org.apache.sis.referencing.gazetteer.AbstractLocation},
+ * {@link org.apache.sis.referencing.gazetteer.ModifiableLocationType} and
+ * {@link org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers}, completed by the
+ * {@link org.apache.sis.referencing.gazetteer.LocationFormat} utility class.
  *
- * <div class="section">Extensions to ISO 19112</div>
- * In addition to standard properties, the Apache SIS implementation provides the following
extensions:
- *
- * <ul>
- *   <li>{@link org.apache.sis.referencing.gazetteer.AbstractLocation#getEnvelope()}
can provide envelopes
- *       in non-geographic CRS.</li>
- * </ul>
+ * <p>This package provides also implementations on top of above base classes.
+ * Some implementation classes are {@link org.apache.sis.referencing.gazetteer.MilitaryGridReferenceSystem}
+ * (also for civilian use).</p>
  *
  * @author  Chris Mattmann (JPL)
  * @author  Martin Desruisseaux (Geomatys)



Mime
View raw message