sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1532859 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing: GeodeticObjects.java StandardObjects.java TemporalObjects.java VerticalObjects.java datum/DefaultTemporalDatum.java datum/DefaultVerticalDatum.java
Date Wed, 16 Oct 2013 18:44:10 GMT
Author: desruisseaux
Date: Wed Oct 16 18:44:10 2013
New Revision: 1532859

URL: http://svn.apache.org/r1532859
Log:
Moved VerticalObjects and TemporalObjects enumeration as inner enum of GeodeticObjects, as
suggested on the mailing list.

Removed:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java
Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java?rev=1532859&r1=1532858&r2=1532859&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
[UTF-8] Wed Oct 16 18:44:10 2013
@@ -16,14 +16,30 @@
  */
 package org.apache.sis.referencing;
 
+import java.util.Map;
+import java.util.HashMap;
+import java.util.Date;
+import java.util.Locale;
 import javax.measure.unit.SI;
 import org.opengis.util.FactoryException;
+import org.opengis.util.InternationalString;
 import org.opengis.referencing.IdentifiedObject;
 import org.opengis.referencing.crs.GeodeticCRS;
+import org.opengis.referencing.crs.VerticalCRS;
+import org.opengis.referencing.crs.TemporalCRS;
 import org.opengis.referencing.datum.Ellipsoid;
 import org.opengis.referencing.datum.GeodeticDatum;
 import org.opengis.referencing.datum.PrimeMeridian;
+import org.opengis.referencing.datum.VerticalDatum;
+import org.opengis.referencing.datum.VerticalDatumType;
+import org.opengis.referencing.datum.TemporalDatum;
 import org.opengis.referencing.datum.DatumAuthorityFactory;
+import org.apache.sis.referencing.datum.DefaultVerticalDatum;
+import org.apache.sis.referencing.datum.DefaultTemporalDatum;
+import org.apache.sis.util.resources.Vocabulary;
+
+import static org.opengis.referencing.IdentifiedObject.NAME_KEY;
+import static org.opengis.referencing.IdentifiedObject.ALIAS_KEY;
 
 
 /**
@@ -353,4 +369,302 @@ public enum GeodeticObjects {
         }
         return null;
     }
+
+
+
+
+    /**
+     * Frequently-used vertical CRS and datum that are guaranteed to be available in SIS.
+     * Methods in this enumeration are shortcuts for object definitions in the EPSG database.
+     * If there is no EPSG database available, or if the query failed, or if there is no
EPSG definition for an object,
+     * then {@code Vertical} fallback on hard-coded values. Consequently, those methods never
return {@code null}.
+     *
+     * <p>Referencing objects are cached after creation. Invoking the same method on
the same {@code Vertical}
+     * instance twice will return the same {@link IdentifiedObject} instance, unless the
internal cache has been cleared
+     * (e.g. the application is running in a container environment, and some modules have
been installed or uninstalled).</p>
+     *
+     * <p><b>Example:</b> the following code fetches a vertical Coordinate
Reference System for height above the geoid:</p>
+     *
+     * {@preformat java
+     *   VerticalCRS crs = GeodeticObjects.Vertical.GEOIDAL.crs();
+     * }
+     *
+     * Below is an alphabetical list of object names available in this enumeration:
+     *
+     * <blockquote><table class="sis">
+     *   <tr><th>Name or alias</th>       <th>Object type</th>
<th>Enumeration value</th></tr>
+     *   <tr><td>Barometric altitude</td> <td>CRS, Datum</td>
 <td>{@link #BAROMETRIC}</td></tr>
+     *   <tr><td>Geoidal height</td>      <td>CRS, Datum</td>
 <td>{@link #GEOIDAL}</td></tr>
+     *   <tr><td>Ellipsoidal height</td>  <td>CRS, Datum</td>
 <td>{@link #ELLIPSOIDAL}</td></tr>
+     *   <tr><td>Other surface</td>       <td>CRS, Datum</td>
 <td>{@link #OTHER_SURFACE}</td></tr>
+     * </table></blockquote>
+     *
+     * @author  Martin Desruisseaux (Geomatys)
+     * @since   0.4
+     * @version 0.4
+     * @module
+     */
+    public static enum Vertical {
+        /**
+         * Height measured by atmospheric pressure.
+         *
+         * @see VerticalDatumType#BAROMETRIC
+         */
+        BAROMETRIC(Vocabulary.Keys.BarometricAltitude),
+
+        /**
+         * Height measured above an equipotential surface.
+         *
+         * @see VerticalDatumType#GEOIDAL
+         */
+        GEOIDAL(Vocabulary.Keys.Geoidal),
+
+        /**
+         * Height measured along the normal to the ellipsoid used in the definition of horizontal
datum.
+         *
+         * <p><b>This datum is not part of ISO 19111 international standard.</b>
+         * Usage of this datum is generally not recommended since ellipsoidal heights make
little sense without
+         * their (<var>latitude</var>, <var>longitude</var>) locations.
The ISO specification defines instead
+         * three-dimensional {@code GeographicCRS} for that reason. However Apache SIS provides
this value
+         * because it is sometime useful to temporarily express ellipsoidal heights independently
from other
+         * ordinate values.</p>
+         */
+        ELLIPSOIDAL(Vocabulary.Keys.Ellipsoidal),
+
+        /**
+         * Height measured above other kind of surface, for example a geological feature.
+         *
+         * @see VerticalDatumType#OTHER_SURFACE
+         */
+        OTHER_SURFACE(Vocabulary.Keys.OtherSurface);
+
+        /**
+         * The resource keys for the name as one of the {@code Vocabulary.Keys} constants.
+         */
+        private final int key;
+
+        /**
+         * The cached object. This is initially {@code null}, then set to various kind of
objects depending
+         * on which method has been invoked. The kind of object stored in this field may
change during the
+         * application execution.
+         */
+        private transient volatile IdentifiedObject cached;
+
+        /**
+         * Creates a new enumeration value of the given name.
+         *
+         * {@note This constructor does not expect <code>VerticalDatumType</code>
constant in order to avoid too
+         *        early class initialization. In particular, we do not want early dependency
to the SIS-specific
+         *        <code>VerticalDatumTypes.ELLIPSOIDAL</code> constant.}
+         */
+        private Vertical(final int name) {
+            this.key = name;
+        }
+
+        /**
+         * Returns the datum associated to this vertical object.
+         * The following table summarizes the datum known to this class,
+         * together with an enumeration value that can be used for fetching that datum:
+         *
+         * <blockquote><table class="sis">
+         *   <tr><th>Name or alias</th>       <th>Enum</th></tr>
+         *   <tr><td>Barometric altitude</td> <td>{@link #BAROMETRIC}</td></tr>
+         *   <tr><td>Geoidal height</td>      <td>{@link #GEOIDAL}</td></tr>
+         *   <tr><td>Ellipsoidal height</td>  <td>{@link #ELLIPSOIDAL}</td></tr>
+         *   <tr><td>Other surface</td>       <td>{@link #OTHER_SURFACE}</td></tr>
+         * </table></blockquote>
+         *
+         * @return The datum associated to this constant.
+         *
+         * @see DefaultVerticalDatum
+         * @see DatumAuthorityFactory#createVerticalDatum(String)
+         */
+        public VerticalDatum datum() {
+            VerticalDatum object = datum(cached);
+            if (object == null) {
+                synchronized (this) {
+                    object = datum(cached);
+                    if (object == null) {
+                        final Map<String,Object> properties = new HashMap<>(4);
+                        final InternationalString name = Vocabulary.formatInternational(key);
+                        properties.put(NAME_KEY,  name.toString(Locale.ROOT));
+                        properties.put(ALIAS_KEY, name);
+                        object = new DefaultVerticalDatum(properties, VerticalDatumType.valueOf(name()));
+                        cached = object;
+                    }
+                }
+            }
+            return object;
+        }
+
+        /**
+         * Returns the datum associated to the given object, or {@code null} if none.
+         */
+        private static VerticalDatum datum(final IdentifiedObject object) {
+            if (object instanceof VerticalDatum) {
+                return (VerticalDatum) object;
+            }
+            if (object instanceof VerticalCRS) {
+                return ((VerticalCRS) object).getDatum();
+            }
+            return null;
+        }
+    }
+
+
+
+
+    /**
+     * Frequently-used temporal CRS and datum that are guaranteed to be available in SIS.
+     *
+     * <p>Referencing objects are cached after creation. Invoking the same method on
the same {@code Temporal}
+     * instance twice will return the same {@link IdentifiedObject} instance, unless the
internal cache has been cleared
+     * (e.g. the application is running in a container environment, and some modules have
been installed or uninstalled).</p>
+     *
+     * <p><b>Example:</b> the following code fetches a temporal Coordinate
Reference System using the Julian calendar:</p>
+     *
+     * {@preformat java
+     *   TemporalCRS crs = GeodeticObjects.Temporal.JULIAN.crs();
+     * }
+     *
+     * Below is an alphabetical list of object names available in this enumeration:
+     *
+     * <blockquote><table class="sis">
+     *   <tr><th>Name or alias</th>    <th>Object type</th>
<th>Enumeration value</th></tr>
+     *   <tr><td>Dublin Julian</td>    <td>CRS, Datum</td>
 <td>{@link #DUBLIN_JULIAN}</td></tr>
+     *   <tr><td>Java time</td>        <td>CRS</td>       
 <td>{@link #JAVA}</td></tr>
+     *   <tr><td>Julian</td>           <td>CRS, Datum</td>
 <td>{@link #JULIAN}</td></tr>
+     *   <tr><td>Modified Julian</td>  <td>CRS, Datum</td>
 <td>{@link #MODIFIED_JULIAN}</td></tr>
+     *   <tr><td>Truncated Julian</td> <td>CRS, Datum</td>
 <td>{@link #TRUNCATED_JULIAN}</td></tr>
+     *   <tr><td>Unix/POSIX time</td>  <td>CRS, Datum</td>
 <td>{@link #UNIX}</td></tr>
+     * </table></blockquote>
+     *
+     * @author  Martin Desruisseaux (Geomatys)
+     * @since   0.4
+     * @version 0.4
+     * @module
+     */
+    public static enum Temporal {
+        /**
+         * Time measured as days since January 1st, 4713 BC at 12:00 UTC.
+         */
+        JULIAN(Vocabulary.Keys.Julian, -2440588 * (24*60*60*1000L) + (12*60*60*1000L)),
+
+        /**
+         * Time measured as days since November 17, 1858 at 00:00 UTC.
+         * A <cite>Modified Julian day</cite> (MJD) is defined relative to
+         * <cite>Julian day</cite> (JD) as {@code MJD = JD − 2400000.5}.
+         */
+        MODIFIED_JULIAN(Vocabulary.Keys.ModifiedJulian, -40587 * (24*60*60*1000L)),
+
+        /**
+         * Time measured as days since May 24, 1968 at 00:00 UTC.
+         * This epoch was introduced by NASA for the space program.
+         * A <cite>Truncated Julian day</cite> (TJD) is defined relative to
+         * <cite>Julian day</cite> (JD) as {@code TJD = JD − 2440000.5}.
+         */
+        TRUNCATED_JULIAN(Vocabulary.Keys.TruncatedJulian, -587 * (24*60*60*1000L)),
+
+        /**
+         * Time measured as days since December 31, 1899 at 12:00 UTC.
+         * A <cite>Dublin Julian day</cite> (DJD) is defined relative to
+         * <cite>Julian day</cite> (JD) as {@code DJD = JD − 2415020}.
+         */
+        DUBLIN_JULIAN(Vocabulary.Keys.DublinJulian, -25568 * (24*60*60*1000L) + (12*60*60*1000L)),
+
+        /**
+         * Time measured as seconds since January 1st, 1970 at 00:00 UTC.
+         */
+        UNIX(Vocabulary.Keys.Time_1, 0),
+
+        /**
+         * Time measured as milliseconds since January 1st, 1970 at 00:00 UTC.
+         */
+        JAVA(Vocabulary.Keys.Time_1, 0);
+
+        /**
+         * The resource keys for the name as one of the {@code Vocabulary.Keys} constants.
+         */
+        private final int key;
+
+        /**
+         * The date and time origin of this temporal datum.
+         */
+        private final long epoch;
+
+        /**
+         * The cached object. This is initially {@code null}, then set to various kind of
objects depending
+         * on which method has been invoked. The kind of object stored in this field may
change during the
+         * application execution.
+         */
+        private transient volatile IdentifiedObject cached;
+
+        /**
+         * Creates a new enumeration value of the given name with time counted since the
given epoch.
+         */
+        private Temporal(final int name, final long epoch) {
+            this.key   = name;
+            this.epoch = epoch;
+        }
+
+        /**
+         * Returns the datum associated to this temporal object.
+         * The following table summarizes the datum known to this class,
+         * together with an enumeration value that can be used for fetching that datum:
+         *
+         * <blockquote><table class="sis">
+         *   <tr><th>Name or alias</th>      <th>Enum</th></tr>
+         *   <tr><td>Dublin Julian</td>      <td>{@link #DUBLIN_JULIAN}</td></tr>
+         *   <tr><td>Julian</td>             <td>{@link #JULIAN}</td></tr>
+         *   <tr><td>Modified Julian</td>    <td>{@link #MODIFIED_JULIAN}</td></tr>
+         *   <tr><td>Truncated Julian</td>   <td>{@link #TRUNCATED_JULIAN}</td></tr>
+         *   <tr><td>Unix/POSIX or Java</td> <td>{@link #UNIX}</td></tr>
+         * </table></blockquote>
+         *
+         * @return The datum associated to this constant.
+         *
+         * @see DefaultTemporalDatum
+         * @see DatumAuthorityFactory#createTemporalDatum(String)
+         */
+        public TemporalDatum datum() {
+            TemporalDatum object = datum(cached);
+            if (object == null) {
+                synchronized (this) {
+                    object = datum(cached);
+                    if (object == null) {
+                        if (this == UNIX) {
+                            object = JAVA.datum(); // Share the same instance for UNIX and
JAVA.
+                        } else {
+                            final Map<String,Object> properties;
+                            properties = new HashMap<>(4);
+                            final InternationalString name;
+                            if (key == Vocabulary.Keys.Time_1) {
+                                name = Vocabulary.formatInternational(key, this == JAVA ?
"Java" : "Unix/POSIX");
+                            } else {
+                                name = Vocabulary.formatInternational(key);
+                            }
+                            properties.put(NAME_KEY,  name.toString(Locale.ROOT));
+                            properties.put(ALIAS_KEY, name);
+                            object = new DefaultTemporalDatum(properties, new Date(epoch));
+                        }
+                        cached = object;
+                    }
+                }
+            }
+            return object;
+        }
+
+        /**
+         * Returns the datum associated to the given object, or {@code null} if none.
+         */
+        private static TemporalDatum datum(final IdentifiedObject object) {
+            if (object instanceof TemporalDatum) {
+                return (TemporalDatum) object;
+            }
+            if (object instanceof TemporalCRS) {
+                return ((TemporalCRS) object).getDatum();
+            }
+            return null;
+        }
+    }
 }

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java?rev=1532859&r1=1532858&r2=1532859&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
[UTF-8] Wed Oct 16 18:44:10 2013
@@ -25,7 +25,7 @@ import org.apache.sis.util.logging.Loggi
 
 
 /**
- * Utility methods for the {@link GeodeticObjects}, {@link VerticalObjects} and {@link TemporalObjects}
enumerations.
+ * Utility methods for the {@link GeodeticObjects} enumeration.
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.4

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java?rev=1532859&r1=1532858&r2=1532859&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
(original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
Wed Oct 16 18:44:10 2013
@@ -43,7 +43,7 @@ import java.util.Objects;
  *
  * <ol>
  *   <li>Create a {@code TemporalDatum} from one of the static convenience shortcuts
listed in
- *       {@link org.apache.sis.referencing.TemporalObjects#datum()}.</li>
+ *       {@link org.apache.sis.referencing.GeodeticObjects.Temporal#datum()}.</li>
  *   <li>Create a {@code TemporalDatum} from an identifier in a database by invoking
  *       {@link org.opengis.referencing.datum.DatumAuthorityFactory#createTemporalDatum(String)}.</li>
  *   <li>Create a {@code TemporalDatum} by invoking the {@code createTemporalDatum(…)}
@@ -55,7 +55,7 @@ import java.util.Objects;
  * <b>Example:</b> the following code gets a temporal datum having its origin
at January 1st, 4713 BC at 12:00 UTC:
  *
  * {@preformat java
- *     TemporalDatum pm = TemporalObjects.JULIAN.datum();
+ *     TemporalDatum pm = GeodeticObjects.Temporal.JULIAN.datum();
  * }
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
@@ -63,7 +63,7 @@ import java.util.Objects;
  * @version 0.4
  * @module
  *
- * @see org.apache.sis.referencing.TemporalObjects#datum()
+ * @see org.apache.sis.referencing.GeodeticObjects.Temporal#datum()
  */
 @Immutable
 @XmlType(name = "TemporalDatumType")

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java?rev=1532859&r1=1532858&r2=1532859&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
[UTF-8] Wed Oct 16 18:44:10 2013
@@ -50,7 +50,7 @@ import java.util.Objects;
  *
  * <ol>
  *   <li>Create a {@code VerticalDatum} from one of the static convenience shortcuts
listed in
- *       {@link org.apache.sis.referencing.VerticalObjects#datum()}.</li>
+ *       {@link org.apache.sis.referencing.GeodeticObjects.Vertical#datum()}.</li>
  *   <li>Create a {@code VerticalDatum} from an identifier in a database by invoking
  *       {@link org.opengis.referencing.datum.DatumAuthorityFactory#createVerticalDatum(String)}.</li>
  *   <li>Create a {@code VerticalDatum} by invoking the {@code createVerticalDatum(…)}
@@ -62,7 +62,7 @@ import java.util.Objects;
  * <b>Example:</b> the following code gets a vertical datum for height above
the geoid:
  *
  * {@preformat java
- *     VerticalDatum pm = VerticalObjects.GEOID.datum();
+ *     VerticalDatum pm = GeodeticObjects.Vertical.GEOID.datum();
  * }
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
@@ -70,7 +70,7 @@ import java.util.Objects;
  * @version 0.4
  * @module
  *
- * @see org.apache.sis.referencing.VerticalObjects#datum()
+ * @see org.apache.sis.referencing.GeodeticObjects.Vertical#datum()
  */
 @Immutable
 @XmlType(name = "VerticalDatumType")



Mime
View raw message