sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1531943 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing: TemporalObjects.java VerticalObjects.java datum/DefaultVerticalDatum.java
Date Mon, 14 Oct 2013 15:37:53 GMT
Author: desruisseaux
Date: Mon Oct 14 15:37:52 2013
New Revision: 1531943

URL: http://svn.apache.org/r1531943
Log:
Moved DefaultVerticalDatum constants to VerticalObjects enumeration.

Added:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java
  (with props)
Modified:
    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/datum/DefaultVerticalDatum.java

Modified: 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=1531943&r1=1531942&r2=1531943&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/TemporalObjects.java
[UTF-8] Mon Oct 14 15:37:52 2013
@@ -105,7 +105,7 @@ public enum TemporalObjects {
      * 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;
+    private final int key;
 
     /**
      * The date and time origin of this temporal datum.
@@ -123,7 +123,7 @@ public enum TemporalObjects {
      * 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.key   = name;
         this.epoch = epoch;
     }
 
@@ -156,9 +156,9 @@ public enum TemporalObjects {
                         object = JAVA.datum(); // Share the same instance for UNIX and JAVA.
                     } else {
                         final Map<String,Object> properties;
-                        if (name >= 0) {
+                        if (key >= 0) {
                             properties = new HashMap<>(4);
-                            final InternationalString name = Vocabulary.formatInternational(this.name);
+                            final InternationalString name = Vocabulary.formatInternational(key);
                             properties.put(NAME_KEY,  name.toString(Locale.ROOT));
                             properties.put(ALIAS_KEY, name);
                         } else {

Added: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java?rev=1531943&view=auto
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java
(added)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/VerticalObjects.java
[UTF-8] Mon Oct 14 15:37:52 2013
@@ -0,0 +1,171 @@
+/*
+ * 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.Locale;
+import java.util.Map;
+import java.util.HashMap;
+import org.opengis.util.InternationalString;
+import org.opengis.referencing.IdentifiedObject;
+import org.opengis.referencing.crs.VerticalCRS;
+import org.opengis.referencing.datum.VerticalDatum;
+import org.opengis.referencing.datum.VerticalDatumType;
+import org.opengis.referencing.datum.DatumAuthorityFactory;
+import org.apache.sis.referencing.datum.DefaultVerticalDatum;
+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 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 VerticalObjects} 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 VerticalObjects}
+ * 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 = VerticalObjects.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 enum VerticalObjects {
+    /**
+     * 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 VerticalObjects(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;
+    }
+}

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

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

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=1531943&r1=1531942&r2=1531943&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] Mon Oct 14 15:37:52 2013
@@ -26,7 +26,6 @@ import org.opengis.referencing.datum.Ver
 import org.apache.sis.io.wkt.Formatter;
 import org.apache.sis.util.Immutable;
 import org.apache.sis.util.ComparisonMode;
-import org.apache.sis.util.resources.Vocabulary;
 import org.apache.sis.internal.jaxb.Context;
 import org.apache.sis.internal.jaxb.gml.GMLAdapter;
 import org.apache.sis.internal.referencing.VerticalDatumTypes;
@@ -43,10 +42,35 @@ import java.util.Objects;
  * {@linkplain org.opengis.referencing.cs.CoordinateSystemAxis coordinate system axis} with
which
  * it is combined to create a {@linkplain org.opengis.referencing.crs.VerticalCRS vertical
CRS}.
  *
+ * {@section Creating new vertical 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 vertical
datum.
+ * The other choices provide more freedom.
+ *
+ * <ol>
+ *   <li>Create a {@code VerticalDatum} from one of the static convenience shortcuts
listed in
+ *       {@link org.apache.sis.referencing.VerticalObjects#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(…)}
+ *       method defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.</li>
+ *   <li>Create a {@code DefaultVerticalDatum} by invoking the
+ *       {@linkplain #DefaultVerticalDatum(Map, Date) constructor}.</li>
+ * </ol>
+ *
+ * <b>Example:</b> the following code gets a vertical datum for height above
the geoid:
+ *
+ * {@preformat java
+ *     VerticalDatum pm = VerticalObjects.GEOID.datum();
+ * }
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.VerticalObjects#datum()
  */
 @Immutable
 @XmlType(name = "VerticalDatumType")
@@ -64,39 +88,8 @@ public class DefaultVerticalDatum extend
     private VerticalDatumType type;
 
     /**
-     * Default vertical datum for {@linkplain VerticalDatumType#BAROMETRIC barometric heights}.
-     */
-    public static final DefaultVerticalDatum BAROMETRIC =
-            new DefaultVerticalDatum(name(Vocabulary.Keys.BarometricAltitude), VerticalDatumType.BAROMETRIC);
-
-    /**
-     * Default vertical datum for {@linkplain VerticalDatumType#GEOIDAL geoidal heights}.
-     */
-    public static final DefaultVerticalDatum GEOIDAL =
-            new DefaultVerticalDatum(name(Vocabulary.Keys.Geoidal), VerticalDatumType.GEOIDAL);
-
-    /**
-     * Default vertical datum for ellipsoidal heights. Ellipsoidal heights are 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.</p>
-     */
-    public static final DefaultVerticalDatum ELLIPSOIDAL =
-            new DefaultVerticalDatum(name(Vocabulary.Keys.Ellipsoidal), VerticalDatumType.valueOf("ELLIPSOIDAL"));
-    // Do not use the VerticalDatumTypes.ELLIPSOIDAL constant in order to avoid unneeded
class initialisation.
-
-    /**
-     * Default vertical datum for {@linkplain VerticalDatumType#OTHER_SURFACE other surface}.
-     */
-    public static final DefaultVerticalDatum OTHER_SURFACE =
-            new DefaultVerticalDatum(name(Vocabulary.Keys.OtherSurface), VerticalDatumType.OTHER_SURFACE);
-
-    /**
      * Creates a vertical datum from a name. This is a convenience constructor for
-     * {@link #DefaultVerticalDatum(Map, VerticalDatumType) DefaultTemporalDatum(Map, …)}
+     * {@link #DefaultVerticalDatum(Map, VerticalDatumType) DefaultVerticalDatum(Map, …)}
      * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY}
property.
      *
      * @param name The datum name.



Mime
View raw message