sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1558164 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing: cs/AbstractCS.java cs/AxesConvention.java cs/SubTypes.java cs/package-info.java datum/SubTypes.java
Date Tue, 14 Jan 2014 18:57:37 GMT
Author: desruisseaux
Date: Tue Jan 14 18:57:37 2014
New Revision: 1558164

URL: http://svn.apache.org/r1558164
Log:
Implemented AbstractCS.castOrCopy and added documentation.

Added:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/SubTypes.java
      - copied, changed from r1556838, sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java
Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AbstractCS.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/package-info.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AbstractCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AbstractCS.java?rev=1558164&r1=1558163&r2=1558164&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AbstractCS.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AbstractCS.java
[UTF-8] Tue Jan 14 18:57:37 2014
@@ -229,6 +229,42 @@ public class AbstractCS extends Abstract
     }
 
     /**
+     * Returns a SIS coordinate system implementation with the values of the given arbitrary
implementation.
+     * This method performs the first applicable actions in the following choices:
+     *
+     * <ul>
+     *   <li>If the given object is {@code null}, then this method returns {@code null}.</li>
+     *   <li>Otherwise if the given object is is an instance of
+     *       {@link org.opengis.referencing.cs.AffineCS},
+     *       {@link org.opengis.referencing.cs.CartesianCS},
+     *       {@link org.opengis.referencing.cs.SphericalCS},
+     *       {@link org.opengis.referencing.cs.EllipsoidalCS},
+     *       {@link org.opengis.referencing.cs.CylindricalCS},
+     *       {@link org.opengis.referencing.cs.PolarCS},
+     *       {@link org.opengis.referencing.cs.LinearCS},
+     *       {@link org.opengis.referencing.cs.VerticalCS},
+     *       {@link org.opengis.referencing.cs.TimeCS} or
+     *       {@link org.opengis.referencing.cs.UserDefinedCS},
+     *       then this method delegates to the {@code castOrCopy(…)} method of the corresponding
SIS subclass.
+     *       Note that if the given object implements more than one of the above-cited interfaces,
+     *       then the {@code castOrCopy(…)} method to be used is unspecified.</li>
+     *   <li>Otherwise if the given object is already an instance of
+     *       {@code AbstractCS}, then it is returned unchanged.</li>
+     *   <li>Otherwise a new {@code AbstractCS} instance is created using the
+     *       {@linkplain #AbstractCS(CoordinateSystem) copy constructor}
+     *       and returned. Note that this is a <cite>shallow</cite> copy operation,
since the other
+     *       properties contained in the given object are not recursively copied.</li>
+     * </ul>
+     *
+     * @param  object The object to get as a SIS implementation, or {@code null} if none.
+     * @return A SIS implementation containing the values of the given object (may be the
+     *         given object itself), or {@code null} if the argument was null.
+     */
+    public static AbstractCS castOrCopy(final CoordinateSystem object) {
+        return SubTypes.castOrCopy(object);
+    }
+
+    /**
      * Returns {@link #VALID} if the given argument values are allowed for an axis in this
coordinate system,
      * or an {@code INVALID_*} error code otherwise. This method is invoked at construction
time for checking
      * argument validity. The default implementation returns {@code VALID} in all cases.
Subclasses override

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java?rev=1558164&r1=1558163&r2=1558164&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/AxesConvention.java
[UTF-8] Tue Jan 14 18:57:37 2014
@@ -66,19 +66,29 @@ import org.opengis.referencing.cs.Coordi
 public enum AxesConvention {
     /**
      * Axes order, direction and units are forced to commonly used pre-defined values.
-     * This enum identifies the following changes.
+     * This enum identifies the following changes to apply on a coordinate system:
      *
      * <ul>
-     *   <li>Any direction colinear with {@link AxisDirection#EAST EAST}, {@link AxisDirection#NORTH
NORTH},
-     *       {@link AxisDirection#UP UP}, {@link AxisDirection#FUTURE FUTURE},
-     *       {@link AxisDirection#DISPLAY_RIGHT DISPLAY_RIGHT}, {@link AxisDirection#DISPLAY_DOWN
DISPLAY_DOWN},
-     *       {@link AxisDirection#ROW_POSITIVE ROW_POSITIVE} and {@link AxisDirection#COLUMN_POSITIVE
COLUMN_POSITIVE}
-     *       is replaced by the corresponding above-cited direction.</li>
+     *   <li>Directions opposites to the following ones are replaced by their "forward"
counterpart
+     *       (e.g. {@code SOUTH} → {@code NORTH}):
+     *     <ul>
+     *       <li>{@link AxisDirection#EAST EAST}, {@link AxisDirection#NORTH NORTH},
+     *           {@link AxisDirection#UP UP}, {@link AxisDirection#FUTURE FUTURE} —
+     *           commonly used directions for (<var>x</var>, <var>y</var>,
<var>z</var>, <var>t</var>) coordinates.</li>
+     *       <li>{@link AxisDirection#DISPLAY_RIGHT DISPLAY_RIGHT}, {@link AxisDirection#DISPLAY_DOWN
DISPLAY_DOWN} —
+     *           commonly used (<var>x</var>, <var>y</var>) directions
for screen devices.</li>
+     *       <li>{@link AxisDirection#ROW_POSITIVE ROW_POSITIVE},
+     *           {@link AxisDirection#COLUMN_POSITIVE COLUMN_POSITIVE} — indices in grids
or matrices.</li>
+     *     </ul>
+     *   </li>
      *   <li>Axes with the new directions are reordered for a <cite>right-handed</cite>
coordinate system.</li>
      *   <li>Angular units are set to {@link javax.measure.unit.NonSI#DEGREE_ANGLE}.</li>
      *   <li>Linear units are set to {@link javax.measure.unit.SI#METRE}.</li>
      *   <li>Temporal units are set to {@link javax.measure.unit.NonSI#DAY}.</li>
      * </ul>
+     *
+     * {@note The rules for normalized coordinate systems may be adjusted in future SIS versions
based on experience
+     *        gained. For more predictable results, consider using the <code>RIGHT_HANDED</code>
enum instead.}
      */
     NORMALIZED,
 

Copied: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/SubTypes.java
(from r1556838, sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java)
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/SubTypes.java?p2=sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/SubTypes.java&p1=sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java&r1=1556838&r2=1558164&rev=1558164&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/SubTypes.java
[UTF-8] Tue Jan 14 18:57:37 2014
@@ -14,24 +14,28 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.sis.referencing.datum;
+package org.apache.sis.referencing.cs;
 
-import org.opengis.referencing.datum.Datum;
-import org.opengis.referencing.datum.GeodeticDatum;
-import org.opengis.referencing.datum.VerticalDatum;
-import org.opengis.referencing.datum.TemporalDatum;
-import org.opengis.referencing.datum.EngineeringDatum;
-import org.opengis.referencing.datum.ImageDatum;
+import org.opengis.referencing.cs.AffineCS;
+import org.opengis.referencing.cs.CoordinateSystem;
+import org.opengis.referencing.cs.CylindricalCS;
+import org.opengis.referencing.cs.EllipsoidalCS;
+import org.opengis.referencing.cs.LinearCS;
+import org.opengis.referencing.cs.PolarCS;
+import org.opengis.referencing.cs.SphericalCS;
+import org.opengis.referencing.cs.TimeCS;
+import org.opengis.referencing.cs.UserDefinedCS;
+import org.opengis.referencing.cs.VerticalCS;
 
 
 /**
- * Implementation of {@link AbstractDatum} methods that require knowledge about subclasses.
+ * Implementation of {@link AbstractCS} methods that require knowledge about subclasses.
  * Those methods are defined in a separated static class for avoiding class loading of all
- * datum implementations before necessary.
+ * coordinate system implementations before necessary.
  *
  * <p>This class currently provides implementation for the following methods:</p>
  * <ul>
- *   <li>{@link AbstractDatum#castOrCopy(Datum)}</li>
+ *   <li>{@link AbstractCS#castOrCopy(CoordinateSystem)}</li>
  * </ul>
  *
  * @author  Martin Desruisseaux (Geomatys)
@@ -47,30 +51,47 @@ final class SubTypes {
     }
 
     /**
-     * Returns a SIS implementation for the given datum.
+     * Returns a SIS implementation for the given coordinate system.
      *
-     * @see AbstractDatum#castOrCopy(Datum)
+     * @see AbstractCS#castOrCopy(CoordinateSystem)
      */
-    static AbstractDatum castOrCopy(final Datum object) {
-        if (object instanceof GeodeticDatum) {
-            return DefaultGeodeticDatum.castOrCopy((GeodeticDatum) object);
+    static AbstractCS castOrCopy(final CoordinateSystem object) {
+        if (object instanceof AffineCS) {
+            return DefaultAffineCS.castOrCopy((AffineCS) object);
         }
-        if (object instanceof VerticalDatum) {
-            return DefaultVerticalDatum.castOrCopy((VerticalDatum) object);
+        if (object instanceof SphericalCS) {
+            return DefaultSphericalCS.castOrCopy((SphericalCS) object);
         }
-        if (object instanceof TemporalDatum) {
-            return DefaultTemporalDatum.castOrCopy((TemporalDatum) object);
+        if (object instanceof EllipsoidalCS) {
+            return DefaultEllipsoidalCS.castOrCopy((EllipsoidalCS) object);
         }
-        if (object instanceof EngineeringDatum) {
-            return DefaultEngineeringDatum.castOrCopy((EngineeringDatum) object);
+        if (object instanceof CylindricalCS) {
+            return DefaultCylindricalCS.castOrCopy((CylindricalCS) object);
         }
-        if (object instanceof ImageDatum) {
-            return DefaultImageDatum.castOrCopy((ImageDatum) object);
+        if (object instanceof PolarCS) {
+            return DefaultPolarCS.castOrCopy((PolarCS) object);
         }
-        // Intentionally tested after the sub-interfaces.
-        if (object == null || object instanceof AbstractDatum) {
-            return (AbstractDatum) object;
+        if (object instanceof LinearCS) {
+            return DefaultLinearCS.castOrCopy((LinearCS) object);
         }
-        return new AbstractDatum(object);
+        if (object instanceof VerticalCS) {
+            return DefaultVerticalCS.castOrCopy((VerticalCS) object);
+        }
+        if (object instanceof TimeCS) {
+            return DefaultTimeCS.castOrCopy((TimeCS) object);
+        }
+        if (object instanceof UserDefinedCS) {
+            return DefaultUserDefinedCS.castOrCopy((UserDefinedCS) object);
+        }
+        /*
+         * Intentionally check for AbstractCS after the interfaces because user may have
defined his own
+         * subclass implementing the interface. If we were checking for AbstractCS before
the interfaces,
+         * the returned instance could have been a user subclass without the JAXB annotations
required
+         * for XML marshalling.
+         */
+        if (object == null || object instanceof AbstractCS) {
+            return (AbstractCS) object;
+        }
+        return new AbstractCS(object);
     }
 }

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/package-info.java?rev=1558164&r1=1558163&r2=1558164&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/package-info.java
[UTF-8] Tue Jan 14 18:57:37 2014
@@ -22,7 +22,11 @@
  *
  * <p>The root class in this package is {@link org.apache.sis.referencing.cs.AbstractCS}.
  * Various subclasses are defined for various kinds of mathematical rules that determine
- * how coordinates are associated to quantities such as angles and distances.</p>
+ * how coordinates are associated to quantities such as angles and distances.
+ * Those SIS subclasses provide additional methods that are not part of OGC/ISO specifications:</p>
+ * <ul>
+ *   <li>{@link org.apache.sis.referencing.cs.AbstractCS#forConvention AbstractCS.forConvention(AxesConvention)}</li>
+ * </ul>
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-2.0)

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java?rev=1558164&r1=1558163&r2=1558164&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/SubTypes.java
[UTF-8] Tue Jan 14 18:57:37 2014
@@ -67,7 +67,12 @@ final class SubTypes {
         if (object instanceof ImageDatum) {
             return DefaultImageDatum.castOrCopy((ImageDatum) object);
         }
-        // Intentionally tested after the sub-interfaces.
+        /*
+         * Intentionally check for AbstractDatum after the interfaces because user may have
defined his own
+         * subclass implementing the interface. If we were checking for AbstractDatum before
the interfaces,
+         * the returned instance could have been a user subclass without the JAXB annotations
required for
+         * XML marshalling.
+         */
         if (object == null || object instanceof AbstractDatum) {
             return (AbstractDatum) object;
         }



Mime
View raw message