Author: desruisseaux
Date: Thu Jan 23 19:37:50 2014
New Revision: 1560795
URL: http://svn.apache.org/r1560795
Log:
Modified some javadoc in order to said whether we are talking about WKT 1 or
WKT 2.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/VerticalDatumTypes.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Convention.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Formatter.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/WKTFormat.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/package-info.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/VerticalDatumTypes.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/VerticalDatumTypes.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/VerticalDatumTypes.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/VerticalDatumTypes.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -87,10 +87,10 @@ public final class VerticalDatumTypes im
/**
* Returns the vertical datum type from a legacy code. The legacy codes
were defined in
- * <a href="http://www.opengis.org/docs/01-009.pdf";>Coordinate
Transformation Services</a>
- * (OGC 01-009), which also defined the
+ * <a href="http://www.opengeospatial.org/standards/ct";>OGC 01-009</a>
+ * (<cite>Coordinate Transformation Services)</cite>, which also defined
the version 1 of
* <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";><cite>Well
- * Known Text</cite> (WKT)</a> format. This method is used for WKT parsing.
+ * Known Text</cite></a> format (WKT 1). This method is used for WKT 1
parsing.
*
* @param code The legacy vertical datum code.
* @return The vertical datum type, or {@code null} if the code is
unrecognized.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Convention.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Convention.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Convention.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Convention.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -33,8 +33,12 @@ import static javax.measure.unit.NonSI.D
/**
* The convention to use for WKT formatting.
- * This enumeration attempts to address some of the variability documented in
the Frank Warmerdam's
- * <a href="http://home.gdal.org/projects/opengis/wktproblems.html";>OGC WKT
Coordinate System Issues</a> page.
+ * This enumeration specifies whether to use the <cite>Well Known Text</cite>
format defined by ISO 19162
+ * (also known as “WKT 2”), or whether to use the format previously defined in
OGC 01-009 (referenced as “WKT 1”).
+ *
+ * {@section WKT 1 flavors}
+ * The WKT 1 format has been interpreted differently by various implementors.
Some of those differences have been
+ * <a href="http://home.gdal.org/projects/opengis/wktproblems.html";>documented
by the GDAL project</a>.
* The various conventions enumerated in this class differ mostly in:
*
* <ul>
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Formatter.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Formatter.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Formatter.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Formatter.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -826,10 +826,9 @@ public class Formatter {
}
/**
- * Returns {@code true} if the WKT written by this formatter is not
strictly compliant to the
- * <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";>WKT
- * specification</a>. This method returns {@code true} if {@link
#setInvalidWKT(IdentifiedObject)}
- * has been invoked at least once. The action to take regarding invalid
WKT is caller-dependent.
+ * Returns {@code true} if the WKT written by this formatter is not
strictly compliant to the WKT specification.
+ * This method returns {@code true} if {@link
#setInvalidWKT(IdentifiedObject)} has been invoked at least once.
+ * The action to take regarding invalid WKT is caller-dependent.
* For example {@link FormattableObject#toString()} will accepts loose WKT
formatting and ignore
* this flag, while {@link FormattableObject#toWKT()} requires strict WKT
formatting and will
* thrown an exception if this flag is set.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/WKTFormat.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/WKTFormat.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/WKTFormat.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/WKTFormat.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -28,4 +28,7 @@ public class WKTFormat {
* The default indentation value.
*/
static final byte DEFAULT_INDENTATION = 2;
+
+ private WKTFormat() {
+ }
}
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/package-info.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/package-info.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -17,49 +17,44 @@
/**
* <cite>Well Known Text</cite> (WKT) parsing and formatting.
- * This package provides the internal mechanism used by SIS implementation.
Most users do not need to know about it,
- * except if they want to customize the parsing process or the WKT output. For
example this package allows to:
+ * This package implements the services provided by the {@link
org.apache.sis.referencing.CRS#parseWKT(String)}
+ * and {@link org.opengis.referencing.IdentifiedObject#toWKT()} convenience
methods. Using this package instead
+ * than the convenience methods give more control. For example this package
allows to:
*
* <ul>
- * <li>{@linkplain org.apache.sis.io.wkt.WKTFormat#setConvention Format the
parameters using the names
- * of an other authority than OGC}. For example a user may want to
format map projections using the
- * {@linkplain org.apache.sis.io.wkt.Convention#GEOTIFF GeoTIFF}
parameter names.</li>
- * <li>{@linkplain org.apache.sis.io.wkt.WKTFormat#setSymbols Use curly
brackets instead than square ones},
+ * <li>Format projection and parameters using the names of a chosen
authority, for example
+ * {@code PROJECTION["Mercator (variant A)"]} (EPSG),
+ * {@code PROJECTION["Mercator_1SP"]} (OGC) or
+ * {@code PROJECTION["CT_Mercator"]} (GeoTIFF).</li>
+ * <li>Format the elements with curly brackets instead than square ones,
* for example {@code DATUM("WGS84")} instead than {@code
DATUM["WGS84"]}.
- * The former is legal WKT, while less frequently used than the later
one.</li>
- * <li>{@linkplain org.apache.sis.io.wkt.WKTFormat#setColors Apply syntactic
coloring} for output
- * on terminal supporting <cite>ANSI escape codes</cite> (a.k.a.
ECMA-48, ISO/IEC 6429 and X3.64).</li>
- * <li>{@linkplain org.apache.sis.io.wkt.WKTFormat#setIndentation Use a
different indentation}, or
- * format the whole WKT on a {@linkplain
org.apache.sis.io.wkt.WKTFormat#SINGLE_LINE single line}.</li>
+ * Both 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>
* </ul>
*
- * Current implementation is primarily designed for parsing and formatting
referencing objects.
- * However other objects (especially the one for geometric objects) are
expected to be provided
- * here in future versions.
- *
* {@section Referencing WKT}
- * Parsing of {@linkplain org.apache.sis.referencing.crs.AbstractCRS
Coordinate Reference System}
- * and {@linkplain
org.apache.sis.referencing.operation.transform.AbstractMathTransform Math
Transform} objects
- * are performed by the {@link org.apache.sis.io.wkt.ReferencingParser} class.
The parser provides methods for:
- *
+ * Referencing WKT is defined in two versions:
* <ul>
- * <li>Specifying whatever the default axis names shall be ISO identifiers
or the
- * legacy identifiers specified in the WKT specification.</li>
- * <li>Ignoring the {@code AXIS[...]} elements. This approach can be used as
a way to force
- * the (<var>longitude</var>, <var>latitude</var>) axes order.</li>
+ * <li>ISO 19162 defines the current format, also known as “WKT 2”.</li>
+ * <li>The previous format — “WKT 1” — was defined in the <a
href="http://www.opengeospatial.org/standards/ct";>OGC
+ * document 01-009</a> using Extended Backus Naur Form (EBNF). This
definition is
+ * <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";>shown
on GeoAPI</a>.</li>
* </ul>
*
- * {@section Geometry WKT}
- * The {@link org.apache.sis.geometry.GeneralEnvelope} and
- * {@link org.apache.sis.geometry.GeneralDirectPosition} classes provide their
own, limited,
- * WKT parsing and formatting services for the {@code BOX} and {@code POINT}
elements.
+ * The WKT 1 format has been interpreted differently by various implementors.
Some of those differences have been
+ * <a href="http://home.gdal.org/projects/opengis/wktproblems.html";>documented
by the GDAL project</a>.
+ * Mismatches between implementations is one of the main motivation behind the
WKT 2 effort.
+ * Apache SIS can adapt itself to different WKT 1 flavors, with the help of the
+ * {@link org.apache.sis.io.wkt.Convention} enumeration for specifying which
one to expect.
*
- * {@section References}
- * <ul>
- * <li><a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";>Well
Known Text specification</a></li>
- * <li><a href="http://home.gdal.org/projects/opengis/wktproblems.html";>OGC
WKT Coordinate System Issues</a></li>
- * <li><a href="http://en.wikipedia.org/wiki/Well-known_text";>Wikipedia:
Well Known Text</a></li>
- * </ul>
+ * {@section Geometry WKT}
+ * The {@link org.apache.sis.geometry.GeneralEnvelope} and {@link
org.apache.sis.geometry.GeneralDirectPosition} classes
+ * 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>.
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Rémi Eve (IRD)
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java?rev=1560795&r1=1560794&r2=1560795&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] Thu Jan 23 19:37:50 2014
@@ -86,10 +86,10 @@ import java.util.Objects;
* Applications should instead instantiate the most specific subclass having a
name starting by {@code Default}.
* However exceptions to this rule may occur when it is not possible to
identify the exact type.
*
- * {@example It is sometime not possible to infer the exact coordinate system
from version 1 of
- * <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";><cite>Well
- * Known Text</cite></a>, for example when parsing a
<code>LOCAL_CS</code> element. In such exceptional
- * situation, a plain <code>AbstractCS</code> object may be
instantiated.}
+ * {@example It is sometime not possible to infer the exact coordinate system
type from
+ * <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";>version
1 of
+ * <cite>Well Known Text format</cite></a>, for example when parsing
a <code>LOCAL_CS</code> element.
+ * In such exceptional situation, a plain <code>AbstractCS</code>
object may be instantiated.}
*
* {@code IdentifiedObject} instances are created in two main ways:
*
