Author: desruisseaux
Date: Fri Jan 24 12:13:37 2014
New Revision: 1560963
URL: http://svn.apache.org/r1560963
Log:
More javadoc clarifications about whether we are talking about WKT 1 or WKT 2.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/geometry/Envelopes.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.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/FormattableObject.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/Symbols.java
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/UnformattableObjectException.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/test/java/org/apache/sis/referencing/cs/HardCodedAxes.java
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/geometry/Envelopes.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/geometry/Envelopes.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/geometry/Envelopes.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/geometry/Envelopes.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -93,7 +93,7 @@ public final class Envelopes extends Sta
ensureNonNull("wkt", wkt);
try {
return new GeneralEnvelope(wkt);
- } catch (RuntimeException e) {
+ } catch (IllegalArgumentException e) {
throw new FactoryException(Errors.format(
Errors.Keys.UnparsableStringForClass_2, Envelope.class),
e);
}
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -122,7 +122,7 @@ public final class ReferencingUtilities
/**
* Returns the unit used for all axes in the given coordinate system.
* If not all axes use the same unit, then this method returns {@code
null}.
- * This convenience method is often used for Well Know Text (WKT) version
1 formatting.
+ * This convenience method is used for Well Know Text version 1 (WKT 1)
formatting.
*
* @param cs The coordinate system for which to get the unit, or {@code
null}.
* @return The unit for all axis in the given coordinate system, or {@code
null}.
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=1560963&r1=1560962&r2=1560963&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] Fri Jan 24 12:13:37 2014
@@ -36,22 +36,23 @@ import static javax.measure.unit.NonSI.D
* 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:
+ * {@section WKT 1 variants}
+ * The WKT 2 format should be parsed and formatted consistently by all
softwares.
+ * But the WKT 1 format has been interpreted differently by various
implementors. Some of those differences
+ * are <a
href="http://home.gdal.org/projects/opengis/wktproblems.html";>documented by the
GDAL project</a>.
+ * Apache SIS can adapt itself to different WKT variants, sometime
automatically. But some aspects can not be guessed.
+ * One noticeable source of confusion is the unit of measurement of {@code
PRIMEM[…]} and {@code PARAMETER[…]} elements:
*
* <ul>
- * <li><em>Parameter names</em> - for example a parameter named
"<cite>Longitude of natural origin</cite>"
- * according {@linkplain #EPSG} may be named "{@code central_meridian}"
according {@linkplain #OGC}
- * and "{@code NatOriginLong}" according {@linkplain #GEOTIFF
GeoTIFF}.</li>
- * <li><em>WKT syntax</em> - for example {@linkplain #ORACLE Oracle} does
not enclose Bursa-Wolf parameters in a
- * {@code TOWGS84[…]} element.</li>
- * <li><em>Unit of measurement</em> - for example the unit of the Prime
Meridian shall be the angular unit of the
- * enclosing Geographic CRS according the {@linkplain #OGC} standard,
but is restricted to decimal degrees by
- * {@linkplain #ESRI}.</li>
+ * <li>The unit of the Prime Meridian shall be the angular unit of the
enclosing Geographic CRS
+ * according the OGC 01-009 (<cite>Coordinate transformation
services</cite>) specification.</li>
+ * <li>An older specification — <cite>Simple Features</cite> — was unclear
on this matter and has been
+ * interpreted by many softwares as fixing the unit to decimal
degrees.</li>
* </ul>
*
+ * Despite the first interpretation being specified by both OGC 01-009 and ISO
19162 standards, the second
+ * interpretation appears to be in wide use for WKT 1. Apache SIS uses the
standard interpretation by default.
+ *
* @author Martin Desruisseaux (Geomatys)
* @since 0.4 (derived from geotk-3.20)
* @version 0.4
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/FormattableObject.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/FormattableObject.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/FormattableObject.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/FormattableObject.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -36,15 +36,14 @@ import org.apache.sis.internal.util.X364
* representation of this object:</p>
*
* <ul>
- * <li>{@link #toWKT()} returns a strictly compliant WKT or throw an
exception.</li>
- * <li>{@link #toString()} is like {@code toWKT()} with some rules relaxed
in order
- * to never throw exception.</li>
+ * <li>{@link #toWKT()} returns a strictly compliant WKT or throws {@link
UnformattableObjectException}
+ * if this object contains elements not defined by the ISO 19162
standard.</li>
+ * <li>{@link #toString()} returns a WKT with some rules relaxed in order to
never throw exception,
+ * using non-standard representation if necessary. In some cases {@code
toString()} may also use
+ * an alternative text representation for better readability, for
example a matrix instead of
+ * a list of {@code PARAMETER["elt_…", …]} elements for linear
transforms.</li>
* </ul>
*
- * The {@code toWKT()} method may throw {@link UnformattableObjectException}
if an object
- * contains elements not defined by the official standard, while {@code
toString()} can
- * fallback on a non-standard representation.
- *
* {@section Syntax coloring}
* A convenience {@link #print()} method is provided, which is roughly
equivalent to
* {@code System.out.println(this)} except that syntax coloring is
automatically applied
@@ -94,11 +93,11 @@ public class FormattableObject {
}
/**
- * Returns a <cite>Well Known Text</cite> (WKT) using the default
convention, symbols and indentation.
+ * Returns a <cite>Well Known Text</cite> (WKT) or an alternative text
representation for this object.
* If this object can not be represented in a standard way, then this
method fallbacks on a non-standard
* representation.
*
- * @return The Well Known Text (WKT) or a pseudo-WKT representation of
this object.
+ * @return The Well Known Text (WKT) or an alternative representation of
this object.
*/
@Override
public String toString() {
@@ -144,7 +143,7 @@ public class FormattableObject {
* Returns a WKT for this object using the specified convention.
* If {@code strict} is true, then an exception is thrown if the WKT is
not standard-compliant.
*
- * @param convention The convention for choosing WKT entities names.
+ * @param convention The convention for choosing WKT element names.
* @param indentation The indentation to apply, or {@link
WKTFormat#SINGLE_LINE}.
* @param colorize {@code true} for applying syntax coloring, or
{@code false} otherwise.
* @param strict {@code true} if an exception shall be thrown for
unformattable objects,
@@ -192,7 +191,7 @@ public class FormattableObject {
* Formats the inner part of this <cite>Well Known Text</cite> (WKT)
element into the given formatter.
* This method is automatically invoked by {@link WKTFormat} when a
formattable element is found.
*
- * <p>Element keyword and authority code shall not be formatted here.
+ * <p>Keywords and authority codes shall not be formatted here.
* For example if this formattable element is for a {@code GEOGCS} element,
* then this method shall write the content starting at the insertion
point shows below:</p>
*
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=1560963&r1=1560962&r2=1560963&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] Fri Jan 24 12:13:37 2014
@@ -188,7 +188,7 @@ public class Formatter {
private boolean requestNewLine;
/**
- * {@code true} if the last formatted element was invalid WKT and shall be
highlighted with syntatic coloration.
+ * {@code true} if the last formatted element was invalid WKT and shall be
highlighted with syntactic coloration.
* This field has no effect if {@link #colors} is null. This field is
reset to {@code false} after the invalid
* part has been processed by {@link #append(FormattableObject)}, in order
to highlight only the first erroneous
* element without clearing the {@link #invalidElement} value.
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/Symbols.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -38,11 +38,11 @@ import static org.apache.sis.util.Argume
* <li>Coma separator followed by a space ({@code ", "}).</li>
* </ul>
*
- * {@note <b>Relationship between <code>Symbols</code> locale and
<code>WKTFormat</code> locale</b><br>
- * The <code>WKTFormat</code> <code>Locale</code> property specifies
the language to use when
- * formatting <code>InternationalString</code> instances. This can be
set to any value.
- * On the contrary, the <code>Locale</code> property of this
<code>Symbols</code> class controls
- * the decimal format symbols and is very rarely set to an other locale
than an English one.}
+ * {@section Relationship between <code>Symbols</code> locale and
<code>WKTFormat</code> locale}
+ * The {@link WKTFormat#getLocale()} property specifies the language to use
when formatting
+ * {@link org.opengis.util.InternationalString} instances. This can be set to
any value.
+ * On the contrary, the {@code Locale} property of this {@code Symbols} class
controls
+ * the decimal format symbols and is very rarely set to an other locale than
an English one.
*
* @author Martin Desruisseaux (IRD)
* @since 0.4 (derived from geotk-2.1)
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/UnformattableObjectException.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/UnformattableObjectException.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/UnformattableObjectException.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/io/wkt/UnformattableObjectException.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -21,7 +21,8 @@ import org.opengis.referencing.Identifie
/**
* Thrown by {@link FormattableObject#toWKT()} when an object can not be
formatted as WKT.
- * A formatting may fail because an object is too complex for the WKT format
capability.
+ * A formatting may fail because an object contains properties which can not
be represented
+ * by the standard WKT elements.
*
* {@example An engineering CRS can not be represented in the WKT 1 format if
all axes
* do not use the same unit of measurement. However such CRS can be
represented
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=1560963&r1=1560962&r2=1560963&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] Fri Jan 24 12:13:37 2014
@@ -45,11 +45,12 @@
* <a
href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html";>shown
on GeoAPI</a>.</li>
* </ul>
*
- * The WKT 1 format has been interpreted differently by various implementors.
Some of those differences have been
+ * The WKT 1 format has been interpreted differently by various implementors.
Some of those differences are
* <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.
+ * The WKT 2 format aims to solve the inter-operability problem caused by such
mismatches between implementations,
+ * but not all softwares support this new format. Consequently importing or
exporting data from a software with the
+ * WKT 1 syntax require knowledge of the WKT variant used by that software.
This variant can be specified by the
+ * {@link org.apache.sis.io.wkt.Convention} enumeration.
*
* {@section Geometry WKT}
* The {@link org.apache.sis.geometry.GeneralEnvelope} and {@link
org.apache.sis.geometry.GeneralDirectPosition} classes
Modified:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/cs/HardCodedAxes.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/cs/HardCodedAxes.java?rev=1560963&r1=1560962&r2=1560963&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/cs/HardCodedAxes.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/referencing/cs/HardCodedAxes.java
[UTF-8] Fri Jan 24 12:13:37 2014
@@ -262,7 +262,7 @@ public final strictfp class HardCodedAxe
* is {@link AxisDirection#GEOCENTRIC_X GEOCENTRIC_X}. The units are
{@linkplain SI#METRE metres}.
* The ISO 19111 name is "<cite>Geocentric X</cite>" and the abbreviation
is upper case "<var>X</var>".
*
- * <p>In legacy OGC 01-009 specification (still in use for WKT format),
+ * <p>In legacy OGC 01-009 specification (still in use for WKT 1 format),
* the direction was {@link AxisDirection#OTHER OTHER}).</p>
*
* <p>This axis is usually part of a {@link #GEOCENTRIC_X}, {@link
#GEOCENTRIC_Y}, {@link #GEOCENTRIC_Z} set.</p>
@@ -277,7 +277,7 @@ public final strictfp class HardCodedAxe
* {@link AxisDirection#GEOCENTRIC_Y GEOCENTRIC_Y}. The units are
{@linkplain SI#METRE metres}.
* The ISO 19111 name is "<cite>Geocentric Y</cite>" and the abbreviation
is upper case "<var>Y</var>".
*
- * <p>In legacy OGC 01-009 specification (still in use for WKT format),
+ * <p>In legacy OGC 01-009 specification (still in use for WKT 1 format),
* the direction was {@link AxisDirection#EAST EAST}).</p>
*
* <p>This axis is usually part of a {@link #GEOCENTRIC_X}, {@link
#GEOCENTRIC_Y}, {@link #GEOCENTRIC_Z} set.</p>
@@ -292,7 +292,7 @@ public final strictfp class HardCodedAxe
* {@link AxisDirection#GEOCENTRIC_Z GEOCENTRIC_Z}. The units are
{@linkplain SI#METRE metres}.
* The ISO 19111 name is "<cite>Geocentric Z</cite>" and the abbreviation
is upper case "<var>Z</var>".
*
- * <p>In legacy OGC 01-009 specification (still in use for WKT format),
+ * <p>In legacy OGC 01-009 specification (still in use for WKT 1 format),
* the direction was {@link AxisDirection#NORTH NORTH}).</p>
*
* <p>This axis is usually part of a {@link #GEOCENTRIC_X}, {@link
#GEOCENTRIC_Y}, {@link #GEOCENTRIC_Z} set.</p>
