sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1685155 - in /sis/branches/JDK8/core: sis-metadata/src/main/java/org/apache/sis/io/wkt/ sis-referencing/src/main/java/org/apache/sis/referencing/ sis-referencing/src/main/java/org/apache/sis/referencing/factory/
Date Fri, 12 Jun 2015 20:20:29 GMT
Author: desruisseaux
Date: Fri Jun 12 20:20:29 2015
New Revision: 1685155

URL: http://svn.apache.org/r1685155
Log:
Improved javadoc.

Modified:
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/Parser.java
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/package-info.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/GeodeticObjectFactory.java

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/Parser.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/Parser.java?rev=1685155&r1=1685154&r2=1685155&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/Parser.java [UTF-8]
(original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/Parser.java [UTF-8]
Fri Jun 12 20:20:29 2015
@@ -20,12 +20,20 @@ import org.opengis.util.FactoryException
 
 
 /**
- * Interfaces of parsers or factories creating a math transform or geodetic object from a
WKT.
+ * A parser or a factory capable to create an object from a string in the WKT format.
+ * The created objects may be {@linkplain org.apache.sis.referencing.crs.AbstractCRS Coordinate
Reference Systems},
+ * {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform Math
Transforms} or geometric
+ * objects for instance.
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.6
  * @version 0.6
  * @module
+ *
+ * @see org.opengis.referencing.crs.CRSFactory#createFromWKT(String)
+ * @see org.opengis.referencing.operation.MathTransformFactory#createFromWKT(String)
+ * @see org.apache.sis.referencing.CRS#fromWKT(String)
+ * @see org.apache.sis.geometry.Envelopes#fromWKT(CharSequence)
  */
 public interface Parser {
     /**

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/package-info.java?rev=1685155&r1=1685154&r2=1685155&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/io/wkt/package-info.java
[UTF-8] Fri Jun 12 20:20:29 2015
@@ -17,21 +17,30 @@
 
 /**
  * <cite>Well Known Text</cite> (WKT) parsing and formatting.
- * This package implements the services provided by the {@link org.apache.sis.referencing.CRS#fromWKT(String)}
- * and {@link org.opengis.referencing.IdentifiedObject#toWKT()} convenience methods, with
more control.
+ * This package implements the services provided by various convenience methods:
+ *
+ * <ul>
+ *   <li>{@link org.apache.sis.referencing.CRS#fromWKT(String)} (SIS parsing static
method)</li>
+ *   <li>{@link org.opengis.referencing.crs.CRSFactory#createFromWKT(String)} (GeoAPI
parsing method)</li>
+ *   <li>{@link org.opengis.referencing.operation.MathTransformFactory#createFromWKT(String)}
(GeoAPI parsing method)</li>
+ *   <li>{@link org.opengis.referencing.IdentifiedObject#toWKT()} (GeoAPI formatting
method)</li>
+ * </ul>
+ *
+ * However the {@link org.apache.sis.io.wkt.WKTFormat} class provided in this package gives
more control.
  * For example this package allows to:
  *
  * <ul>
- *   <li>Format projection and parameters using the names of a chosen authority. For
example the
- *       <cite>"Mercator (variant A)"</cite> projection is named {@code "Mercator_1SP"}
by OGC 01-009
- *       and {@code "CT_Mercator"} by GeoTIFF.</li>
- *   <li>Format the elements with curly brackets instead than square ones.
+ *   <li>Format projection and parameters using the names of a chosen authority.
+ *       For example the <cite>"Mercator (variant A)"</cite> projection is named
+ *       {@code "Mercator_1SP"} by OGC 01-009 and {@code "CT_Mercator"} by GeoTIFF.</li>
+ *   <li>Format the elements with different quote characters or brackets style.
  *       For example both {@code ID["EPSG",4326]} and {@code ID("EPSG",4326)} are legal WKT.</li>
  *   <li>Format with a different indentation or format the whole WKT on a single line.</li>
  *   <li>Apply syntactic coloring on terminal supporting <cite>ANSI escape codes</cite>
  *       (a.k.a. ECMA-48, ISO/IEC 6429 and X3.64).</li>
- *   <li>Ignore the {@code AXIS[…]} elements at parsing time. This approach can be
used as a way to force
- *       the (<var>longitude</var>, <var>latitude</var>) axes order.</li>
+ *   <li>Alter the parsing in a way compatible with non-standard (but commonly used)
WKT.
+ *       For example some others softwares ignore the {@code AXIS[…]} elements at parsing
time.</li>
+ *   <li>Report warnings that occurred during parsing or formatting.</li>
  * </ul>
  *
  * <div class="section">Referencing WKT</div>
@@ -56,6 +65,20 @@
  * provide their own, limited, WKT parsing and formatting services for the {@code BOX} and
{@code POINT} elements.
  * A description for this WKT format can be found on <a href="http://en.wikipedia.org/wiki/Well-known_text">Wikipedia</a>.
  *
+ * <div class="section">Where to find WKT examples</div>
+ * An excellent source of well-formed WKT is the online <cite>EPSG Geodetic Parameter
Registry</cite>.
+ * The WKT of many Coordinate Reference System object can be viewed using the pattern below
+ * (replace {@code 3395} by the EPSG code of the desired CRS):
+ *
+ * <blockquote><b>Example</b>: <cite>"WGS 84 / World Mercator"</cite>:
+ * <a href="http://epsg-registry.org/export.htm?wkt=urn:ogc:def:crs:EPSG::3395">http://epsg-registry.org/export.htm?wkt=urn:ogc:def:crs:EPSG::3395</a>
+ * </blockquote>
+ *
+ * Readers should be aware that some popular other sources of WKT are actually invalid,
+ * since many of them do not comply with EPSG definitions (especially on axis order).
+ * The above-cited EPSG registry is <strong>the</strong> authoritative source
+ * of CRS definitions in the EPSG namespace.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @author  Rémi Eve (IRD)
  * @author  Rueben Schulz (UBC)

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java?rev=1685155&r1=1685154&r2=1685155&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
[UTF-8] Fri Jun 12 20:20:29 2015
@@ -180,10 +180,8 @@ public final class CRS extends Static {
 
     /**
      * Creates a Coordinate Reference System object from a <cite>Well Known Text</cite>
(WKT).
-     * This convenience method delegates to
-     * {@link org.apache.sis.referencing.factory.GeodeticObjectFactory#createFromWKT(String)}
-     * using a default factory instance. The Apache SIS parser understands both the version
1
-     * (a.k.a. OGC 01-009) and version 2 (a.k.a. ISO 19162) of the WKT format.
+     * The default {@linkplain org.apache.sis.io.wkt Apache SIS parser} understands both
+     * version 1 (a.k.a. OGC 01-009) and version 2 (a.k.a. ISO 19162) of the WKT format.
      *
      * <div class="note"><b>Example:</b> below is a slightly simplified
WKT 2 string for a Mercator projection.
      * For making this example smaller, some optional {@code UNIT[…]} and {@code ORDER[…]}
elements have been omitted.
@@ -207,11 +205,25 @@ public final class CRS extends Static {
      * }
      * </div>
      *
+     * <div class="section">Usage and performance considerations</div>
+     * This convenience method delegates to
+     * {@link org.apache.sis.referencing.factory.GeodeticObjectFactory#createFromWKT(String)}
+     * using a default factory instance. This is okay for occasional use, but has the following
limitations:
+     *
+     * <ul>
+     *   <li>Performance may be sub-optimal in a multi-thread environment.</li>
+     *   <li>No control on the WKT {@linkplain org.apache.sis.io.wkt.Convention conventions}
in use.</li>
+     *   <li>No control on the handling of {@linkplain org.apache.sis.io.wkt.warnings}.</li>
+     * </ul>
+     *
+     * Applications which need to parse a large amount of WKT strings should consider to
use
+     * the {@link org.apache.sis.io.wkt.WKTFormat} class instead than this method.
+     *
      * @param  text Coordinate system encoded in Well-Known Text format (version 1 or 2).
      * @return The parsed Coordinate Reference System.
      * @throws FactoryException if the given WKT can not be parsed.
      *
-     * @see org.apache.sis.io.wkt.WKTFormat
+     * @see org.apache.sis.io.wkt
      * @see org.apache.sis.geometry.Envelopes#fromWKT(CharSequence)
      * @see <a href="http://docs.opengeospatial.org/is/12-063r5/12-063r5.html">WKT
2 specification</a>
      *

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/GeodeticObjectFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/GeodeticObjectFactory.java?rev=1685155&r1=1685154&r2=1685155&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/GeodeticObjectFactory.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/GeodeticObjectFactory.java
[UTF-8] Fri Jun 12 20:20:29 2015
@@ -1341,7 +1341,7 @@ public class GeodeticObjectFactory exten
 
     /**
      * Creates a Coordinate Reference System object from a <cite>Well Known Text</cite>
(WKT).
-     * This method understands both the version 1 (a.k.a. OGC 01-009) and version 2 (a.k.a.
ISO 19162)
+     * This method understands both version 1 (a.k.a. OGC 01-009) and version 2 (a.k.a. ISO
19162)
      * of the WKT format.
      *
      * <div class="note"><b>Example:</b> below is a slightly simplified
WKT 2 string for a Mercator projection.
@@ -1366,10 +1366,19 @@ public class GeodeticObjectFactory exten
      * }
      * </div>
      *
+     * <div class="section">Usage and performance considerations</div>
+     * The default implementation uses a shared instance of {@link org.apache.sis.io.wkt.WKTFormat}
+     * with the addition of thread-safety. This is okay for occasional use,
+     * but is sub-optimal if this method is extensively used in a multi-thread environment.
+     * Furthermore this method offers no control on the WKT {@linkplain org.apache.sis.io.wkt.Convention
conventions}
+     * in use and on the handling of {@linkplain org.apache.sis.io.wkt.warnings}.
+     * Applications which need to parse a large amount of WKT strings should consider to
use
+     * the {@link org.apache.sis.io.wkt.WKTFormat} class instead than this method.
+     *
      * @param  text Coordinate system encoded in Well-Known Text format (version 1 or 2).
      * @throws FactoryException if the object creation failed.
      *
-     * @see org.apache.sis.io.wkt.WKTFormat
+     * @see org.apache.sis.io.wkt
      * @see <a href="http://docs.opengeospatial.org/is/12-063r5/12-063r5.html">WKT
2 specification</a>
      * @see <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html">Legacy
WKT 1</a>
      */



Mime
View raw message