sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1531902 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing: GeodeticObjects.java TemporalObjects.java datum/DefaultTemporalDatum.java
Date Mon, 14 Oct 2013 14:02:45 GMT
Author: desruisseaux
Date: Mon Oct 14 14:02:44 2013
New Revision: 1531902

URL: http://svn.apache.org/r1531902
Log:
Moved temporal datum constants to the TemporalObjects enum.

Added:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
  (with props)
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/datum/DefaultTemporalDatum.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=1531902&r1=1531901&r2=1531902&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] Mon Oct 14 14:02:44 2013
@@ -239,10 +239,10 @@ public enum GeodeticObjects {
     /**
      * Returns the prime meridian associated to this geodetic object.
      * The following table summarizes the prime meridians known to this class,
-     * together with a constant that can be used for fetching that prime meridian:
+     * together with an enumeration value that can be used for fetching that prime meridian:
      *
      * <blockquote><table class="sis">
-     *   <tr><th>Name or alias</th> <th>Field</th>        
 <th>EPSG</th></tr>
+     *   <tr><th>Name or alias</th> <th>Enum</th>         
 <th>EPSG</th></tr>
      *   <tr><td>Greenwich</td>     <td>{@link #WGS84}</td>
<td>8901</td></tr>
      * </table></blockquote>
      *
@@ -279,10 +279,10 @@ public enum GeodeticObjects {
     /**
      * Returns the ellipsoid associated to this geodetic object.
      * The following table summarizes the ellipsoids known to this class,
-     * together with a constant that can be used for fetching that ellipsoid:
+     * together with an enumeration value that can be used for fetching that ellipsoid:
      *
      * <blockquote><table class="sis">
-     *   <tr><th>Name or alias</th>                    <th>Field</th>
          <th>EPSG</th></tr>
+     *   <tr><th>Name or alias</th>                    <th>Enum</th>
           <th>EPSG</th></tr>
      *   <tr><td>Clarke 1866</td>                      <td>{@link
#NAD27}</td>  <td>7008</td></tr>
      *   <tr><td>International 1924</td>               <td>{@link
#ED50}</td>   <td>7022</td></tr>
      *   <tr><td>International 1979 / GRS 1980</td>    <td>{@link
#ETRS89}</td> <td>7019</td></tr>

Added: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java?rev=1531902&view=auto
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
(added)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
[UTF-8] Mon Oct 14 14:02:44 2013
@@ -0,0 +1,188 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.referencing;
+
+import java.util.Date;
+import java.util.Locale;
+import java.util.Map;
+import java.util.HashMap;
+import java.util.Collections;
+import org.opengis.util.InternationalString;
+import org.opengis.referencing.IdentifiedObject;
+import org.opengis.referencing.crs.TemporalCRS;
+import org.opengis.referencing.datum.TemporalDatum;
+import org.opengis.referencing.datum.DatumAuthorityFactory;
+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;
+
+
+/**
+ * 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 TemporalObjects}
+ * 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 = TemporalObjects.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, Datum</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 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 enum TemporalObjects {
+    /**
+     * 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(-1, 0),
+
+    /**
+     * Time measured as milliseconds since January 1st, 1970 at 00:00 UTC.
+     */
+    JAVA(-1, 0);
+
+    /**
+     * The resource keys for the name as one of the {@code Vocabulary.Keys} constants,
+     * or -1 for using the enumeration name.
+     */
+    private final int name;
+
+    /**
+     * 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 TemporalObjects(final int name, final long epoch) {
+        this.name  = 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 / Java</td>      <td>{@link #JAVA}</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;
+                        if (name >= 0) {
+                            properties = new HashMap<>(4);
+                            final InternationalString name = Vocabulary.formatInternational(this.name);
+                            properties.put(NAME_KEY,  name.toString(Locale.ROOT));
+                            properties.put(ALIAS_KEY, name);
+                        } else {
+                            properties = Collections.<String,Object>singletonMap(NAME_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;
+    }
+}

Propchange: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

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=1531902&r1=1531901&r2=1531902&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
Mon Oct 14 14:02:44 2013
@@ -22,7 +22,6 @@ import java.util.Collections;
 import javax.xml.bind.annotation.XmlType;
 import javax.xml.bind.annotation.XmlRootElement;
 import org.opengis.referencing.datum.TemporalDatum;
-import org.apache.sis.util.resources.Vocabulary;
 import org.apache.sis.util.ComparisonMode;
 import org.apache.sis.util.Immutable;
 
@@ -36,10 +35,35 @@ import java.util.Objects;
 /**
  * Defines the origin of a temporal coordinate reference system.
  *
+ * {@section Creating new temporal datum instances}
+ * New instances can be created either directly by specifying all information to a factory
method (choices 3
+ * and 4 below), or indirectly by specifying the identifier of an entry in a database (choices
1 and 2 below).
+ * Choice 1 in the following list is the easiest but most restrictive way to get a temporal
datum.
+ * The other choices provide more freedom.
+ *
+ * <ol>
+ *   <li>Create a {@code TemporalDatum} from one of the static convenience shortcuts
listed in
+ *       {@link org.apache.sis.referencing.TemporalObjects#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(…)}
+ *       method defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.</li>
+ *   <li>Create a {@code DefaultTemporalDatum} by invoking the
+ *       {@linkplain #DefaultTemporalDatum(Map, Date) constructor}.</li>
+ * </ol>
+ *
+ * <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();
+ * }
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.TemporalObjects#datum()
  */
 @Immutable
 @XmlType(name = "TemporalDatumType")
@@ -51,53 +75,6 @@ public class DefaultTemporalDatum extend
     private static final long serialVersionUID = 3357241732140076884L;
 
     /**
-     * Datum for time measured since January 1st, 4713 BC at 12:00 UTC.
-     *
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#JULIAN
-     */
-    public static final DefaultTemporalDatum JULIAN = new DefaultTemporalDatum(
-            name(Vocabulary.Keys.Julian), new Date(-2440588 * (24*60*60*1000L) + (12*60*60*1000L)));
-
-    /**
-     * Datum for time measured 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}.
-     *
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#MODIFIED_JULIAN
-     */
-    public static final DefaultTemporalDatum MODIFIED_JULIAN = new DefaultTemporalDatum(
-            name(Vocabulary.Keys.ModifiedJulian), new Date(-40587 * (24*60*60*1000L)));
-
-    /**
-     * Datum for time measured 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}.
-     *
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#TRUNCATED_JULIAN
-     */
-    public static final DefaultTemporalDatum TRUNCATED_JULIAN = new DefaultTemporalDatum(
-            name(Vocabulary.Keys.TruncatedJulian), new Date(-587 * (24*60*60*1000L)));
-
-    /**
-     * Datum for time measured 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}.
-     *
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#DUBLIN_JULIAN
-     */
-    public static final DefaultTemporalDatum DUBLIN_JULIAN = new DefaultTemporalDatum(
-            name(Vocabulary.Keys.DublinJulian), new Date(-25568 * (24*60*60*1000L) + (12*60*60*1000L)));
-
-    /**
-     * Datum for time measured since January 1st, 1970 at 00:00 UTC.
-     *
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#UNIX
-     * @see org.apache.sis.referencing.crs.DefaultTemporalCRS#JAVA
-     */
-    public static final DefaultTemporalDatum UNIX = new DefaultTemporalDatum("UNIX", new
Date(0));
-
-    /**
      * The date and time origin of this temporal datum.
      */
     private final long origin;



Mime
View raw message