You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/03/06 18:55:58 UTC
svn commit: r1785729 -
/sis/branches/JDK8/core/sis-referencing-by-identifiers/src/main/java/org/apache/sis/referencing/gazetteer/
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 \u201c4Q\u2009FJ\u200912345\u200967890\u201d (a reference with 1 metre accuracy),
+ * optionally written with reduced resolution as in \u201c4Q\u2009FJ\u2009123\u2009678\u201d (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: \u201c4Q\u201d)<br>
+ * �� \u2514\u2500<b>100�km square identifier</b> (example: \u201cFJ\u201d)<br>
+ * ���� ��\u2514\u2500<b>Grid coordinate</b> (example: \u201c12345\u200967890\u201d)<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
+ * \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+ * \u2502 Location type: Grid coordinate \u2502
+ * \u2502 Geographic identifier: 32TNL83 \u2502
+ * \u2502 West bound: 580,000 m \u2014 9�57\u203200\u2033E \u2502
+ * \u2502 Representative value: 585,000 m \u2014 10�00\u203236\u2033E \u2502
+ * \u2502 East bound: 590,000 m \u2014 10�04\u203213\u2033E \u2502
+ * \u2502 South bound: 4,530,000 m \u2014 40�54\u203258\u2033N \u2502
+ * \u2502 Representative value: 4,535,000 m \u2014 40�57\u203242\u2033N \u2502
+ * \u2502 North bound: 4,540,000 m \u2014 41�00\u203227\u2033N \u2502
+ * \u2502 Coordinate reference system: WGS 84 / UTM zone 32N \u2502
+ * \u2502 Administrator: North Atlantic Treaty Organization \u2502
+ * \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+ * }
+ * </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 \u03c6 and \u03bb, but the verification of \u03c6 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 (\u2026{@link org.apache.sis.referencing.crs .crs} package).
+ * Mapping between geographic identifiers (addresses, grid indexes\u2026) and locations (descriptions, coordinates\u2026).
+ * 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)