sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1531416 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis: internal/referencing/ referencing/ referencing/datum/
Date Fri, 11 Oct 2013 20:58:08 GMT
Author: desruisseaux
Date: Fri Oct 11 20:58:08 2013
New Revision: 1531416

URL: http://svn.apache.org/r1531416
Log:
Moved the DefaultPrimeMeridian.GREENWICH constant to StandardObjects.Geodetic.[FOO].primeMeridian(),
and added documentation.

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

Added: 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=1531416&view=auto
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
(added)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
[UTF-8] Fri Oct 11 20:58:08 2013
@@ -0,0 +1,65 @@
+/*
+ * 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.internal.referencing;
+
+import java.util.Map;
+import java.util.HashMap;
+import javax.measure.unit.NonSI;
+import org.apache.sis.util.Static;
+import org.apache.sis.metadata.iso.citation.Citations;
+import org.apache.sis.referencing.NamedIdentifier;
+import org.apache.sis.referencing.datum.DefaultPrimeMeridian;
+
+import static org.opengis.referencing.IdentifiedObject.NAME_KEY;
+import static org.opengis.referencing.IdentifiedObject.IDENTIFIERS_KEY;
+
+
+/**
+ * A set of static methods working on GeoAPI referencing objects.
+ * Some of those methods may be useful, but not really rigorous.
+ * This is why they do not appear in the public packages.
+ *
+ * <p><strong>Do not rely on this API!</strong> It may change in incompatible
way in any future release.</p>
+ *
+ * @author  Martin Desruisseaux (IRD, Geomatys)
+ * @since   0.4 (derived from geotk-2.0)
+ * @version 0.4
+ * @module
+ */
+public final class ReferencingUtilities extends Static {
+    /**
+     * The EPSG code for Greenwich meridian.
+     */
+    public static final String GREENWICH_CODE = "8901";
+
+    /**
+     * The Greenwich meridian (EPSG:8901), with angular measurements in decimal degrees.
+     */
+    public static final DefaultPrimeMeridian GREENWICH;
+    static {
+        final Map<String,Object> properties = new HashMap<>(4);
+        properties.put(NAME_KEY, new NamedIdentifier(Citations.EPSG, "Greenwich")); // Name
is fixed by ISO 19111.
+        properties.put(IDENTIFIERS_KEY, new NamedIdentifier(Citations.EPSG, GREENWICH_CODE));
+        GREENWICH = new DefaultPrimeMeridian(properties, 0, NonSI.DEGREE_ANGLE);
+    }
+
+    /**
+     * Do not allow instantiation of this class.
+     */
+    private ReferencingUtilities() {
+    }
+}

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

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

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=1531416&r1=1531415&r2=1531416&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] Fri Oct 11 20:58:08 2013
@@ -26,7 +26,9 @@ import org.opengis.referencing.Identifie
 import org.opengis.referencing.crs.GeodeticCRS;
 import org.opengis.referencing.datum.Ellipsoid;
 import org.opengis.referencing.datum.GeodeticDatum;
+import org.opengis.referencing.datum.PrimeMeridian;
 import org.opengis.referencing.datum.DatumAuthorityFactory;
+import org.apache.sis.internal.referencing.ReferencingUtilities;
 import org.apache.sis.internal.system.Modules;
 import org.apache.sis.internal.system.SystemListener;
 import org.apache.sis.util.logging.Logging;
@@ -56,6 +58,7 @@ import org.apache.sis.util.logging.Loggi
  *   <tr><td>European Datum 1950 (ED50)</td>                        <td>{@link
Geodetic#ED50   Geodetic.ED50}</td></tr>
  *   <tr><td>European Terrestrial Reference Frame (ETRS) 1989</td>  <td>{@link
Geodetic#ETRS89 Geodetic.ETRS89}</td></tr>
  *   <tr><td>European Terrestrial Reference System (ETRF) 1989</td> <td>{@link
Geodetic#ETRS89 Geodetic.ETRS89}</td></tr>
+ *   <tr><td>Greenwich</td>                                         <td>{@link
Geodetic#WGS84  Geodetic.WGS84}, {@link Geodetic#WGS72 WGS72}, {@link Geodetic#ETRS89 ETRS89},
{@link Geodetic#NAD83 NAD83}, {@link Geodetic#NAD27 NAD27}, {@link Geodetic#ED50 ED50}, {@link
Geodetic#SPHERE SPHERE}</td></tr>
  *   <tr><td>GRS 1980</td>                                          <td>{@link
Geodetic#ETRS89 Geodetic.ETRS89}, {@link Geodetic#NAD83 NAD83}</td></tr>
  *   <tr><td>Hayford 1909</td>                                      <td>{@link
Geodetic#ED50   Geodetic.ED50}</td></tr>
  *   <tr><td>International 1924</td>                                <td>{@link
Geodetic#ED50   Geodetic.ED50}</td></tr>
@@ -176,6 +179,7 @@ public abstract class StandardObjects im
      *   <tr><td>European Datum 1950 (ED50)</td>                      
 <td>{@link #ED50}</td></tr>
      *   <tr><td>European Terrestrial Reference Frame (ETRS) 1989</td>
 <td>{@link #ETRS89}</td></tr>
      *   <tr><td>European Terrestrial Reference System (ETRF) 1989</td>
<td>{@link #ETRS89}</td></tr>
+     *   <tr><td>Greenwich</td>                                       
 <td>{@link #WGS84}, {@link #WGS72}, {@link #ETRS89}, {@link #NAD83}, {@link #NAD27},
{@link #ED50}, {@link #SPHERE}</td></tr>
      *   <tr><td>GRS 1980</td>                                        
 <td>{@link #ETRS89}, {@link #NAD83}</td></tr>
      *   <tr><td>Hayford 1909</td>                                    
 <td>{@link #ED50}</td></tr>
      *   <tr><td>International 1924</td>                              
 <td>{@link #ED50}</td></tr>
@@ -212,6 +216,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4326 &nbsp;(<i>datum:</i>
6326, &nbsp;<i>ellipsoid:</i> 7030)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"WGS 84" &nbsp;(<i>datum:</i>
"World Geodetic System 1984")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>(<i>datum:</i>
"WGS 84", &nbsp;<i>ellipsoid:</i> "WGS84")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378137</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356752 <i>(approximative)</i></td></tr>
          *   <tr><th>Inverse flattening:</th>      <td>298.257223563
<i>(definitive)</i></td></tr>
@@ -227,6 +232,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4322 &nbsp;(<i>datum:</i>
6322, &nbsp;<i>ellipsoid:</i> 7043)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"WGS 72" &nbsp;(<i>datum:</i>
"World Geodetic System 1972")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>(<i>datum:</i>
"WGS 72", &nbsp;<i>ellipsoid:</i> "NWL 10D")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378135</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356751 <i>(approximative)</i></td></tr>
          *   <tr><th>Inverse flattening:</th>      <td>298.26 <i>(definitive)</i></td></tr>
@@ -244,6 +250,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4258 &nbsp;(<i>datum:</i>
6258, &nbsp;<i>ellipsoid:</i> 7019)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"ETRS89" &nbsp;(<i>datum:</i>
"European Terrestrial Reference System 1989", &nbsp;<i>ellipsoid:</i> "GRS
1980")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>"ETRF89",
"EUREF89", "ETRS89-GRS80" &nbsp;(<i>ellipsoid:</i> "International 1979")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378137</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356752 <i>(approximative)</i></td></tr>
          *   <tr><th>Inverse flattening:</th>      <td>298.257222101
<i>(definitive)</i></td></tr>
@@ -266,6 +273,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4269 &nbsp;(<i>datum:</i>
6269, &nbsp;<i>ellipsoid:</i> 7019)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"NAD83" &nbsp;(<i>datum:</i>
"North American Datum 1983", &nbsp;<i>ellipsoid:</i> "GRS 1980")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>"NAD83 (1986)"
&nbsp;(<i>ellipsoid:</i> "International 1979")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378137</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356752 <i>(approximative)</i></td></tr>
          *   <tr><th>Inverse flattening:</th>      <td>298.257222101
<i>(definitive)</i></td></tr>
@@ -286,6 +294,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4267 &nbsp;(<i>datum:</i>
6267, &nbsp;<i>ellipsoid:</i> 7008)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"NAD27" &nbsp;(<i>datum:</i>
"North American Datum 1927", &nbsp;<i>ellipsoid:</i> "Clarke 1866")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>(<i>datum:</i>
"NAD27")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378206.4</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356583.8
<i>(definitive)</i></td></tr>
          *   <tr><th>Ellipsoid axes unit:</th>     <td>{@link SI#METRE}</td></tr>
@@ -300,6 +309,7 @@ public abstract class StandardObjects im
          *   <tr><th>EPSG identifiers:</th>        <td>4230 &nbsp;(<i>datum:</i>
6230, &nbsp;<i>ellipsoid:</i> 7022)</td></tr>
          *   <tr><th>Primary names:</th>           <td>"ED50" &nbsp;(<i>datum:</i>
"European Datum 1950", &nbsp;<i>ellipsoid:</i> "International 1924")</td></tr>
          *   <tr><th>Abbreviations or aliases:</th><td>(<i>datum:</i>
"ED50", <i>ellipsoid:</i> "Hayford 1909")</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6378388</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6356912 <i>(approximative)</i></td></tr>
          *   <tr><th>Inverse flattening:</th>      <td>297 <i>(definitive)</i></td></tr>
@@ -315,6 +325,7 @@ public abstract class StandardObjects im
          *
          * <blockquote><table class="compact" style="text-align:left">
          *   <tr><th>Primary names:</th>           <td>"Sphere"</td></tr>
+         *   <tr><th>Prime meridian:</th>          <td>Greenwich</td></tr>
          *   <tr><th>Semi-major axis length:</th>  <td>6371000</td></tr>
          *   <tr><th>Semi-minor axis length:</th>  <td>6371000 <i>(definitive)</i></td></tr>
          *   <tr><th>Ellipsoid axes unit:</th>     <td>{@link SI#METRE}</td></tr>
@@ -338,26 +349,39 @@ public abstract class StandardObjects im
         }
 
         /**
-         * Returns the ellipsoid associated to this geodetic object.
+         * 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:
+         *
+         * <blockquote><table class="sis">
+         *   <tr><th>Name or alias</th> <th>Constant</th> 
     <th>EPSG</th></tr>
+         *   <tr><td>Greenwich</td>     <td>{@link #WGS84}</td>
<td>8901</td></tr>
+         * </table></blockquote>
+         *
+         * @return The prime meridian associated to this constant.
          *
-         * @return The ellipsoid.
+         * @see org.apache.sis.referencing.datum.DefaultPrimeMeridian
+         * @see DatumAuthorityFactory#createPrimeMeridian(String)
          */
-        public Ellipsoid ellipsoid() {
-            Ellipsoid object = ellipsoid(cached);
+        public PrimeMeridian primeMeridian() {
+            PrimeMeridian object = primeMeridian(cached);
             if (object == null) {
                 synchronized (this) {
-                    object = ellipsoid(cached);
+                    object = primeMeridian(cached);
                     if (object == null) {
-                        if (ellipsoid >= 0) {
+                        if (this != WGS84) {
+                            object = WGS84.primeMeridian(); // Share the same instance for
all constants.
+                        } else {
                             final DatumAuthorityFactory factory = datumFactory();
                             if (factory != null) try {
-                                cached = object = factory.createEllipsoid(String.valueOf(ellipsoid));
+                                cached = object = factory.createPrimeMeridian(ReferencingUtilities.GREENWICH_CODE);
                                 return object;
                             } catch (FactoryException e) {
-                                failure("ellipsoid", e);
+                                failure("primeMeridian", e);
                             }
+                            object = ReferencingUtilities.GREENWICH;
                         }
-                        cached = object = StandardDefinitions.createEllipsoid(ellipsoid);
+                        cached = object;
                     }
                 }
             }
@@ -365,6 +389,68 @@ public abstract class StandardObjects im
         }
 
         /**
+         * 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:
+         *
+         * <blockquote><table class="compact">
+         *   <tr><th>Name or alias</th>                    <th>Constant</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>
+         *   <tr><td>World Geodetic System (WGS) 1972</td> <td>{@link
#WGS72}</td>  <td>7043</td></tr>
+         *   <tr><td>World Geodetic System (WGS) 1984</td> <td>{@link
#WGS84}</td>  <td>7030</td></tr>
+         * </table></blockquote>
+         *
+         * @return The ellipsoid associated to this constant.
+         *
+         * @see org.apache.sis.referencing.datum.DefaultEllipsoid
+         * @see DatumAuthorityFactory#createEllipsoid(String)
+         */
+        public Ellipsoid ellipsoid() {
+            Ellipsoid object = ellipsoid(cached);
+            if (object == null) {
+                synchronized (this) {
+                    object = ellipsoid(cached);
+                    if (object == null) {
+                        if (this == NAD83) {
+                            object = ETRS89.ellipsoid(); // Share the same instance for NAD83
and ETRS89.
+                        } else {
+                            if (ellipsoid >= 0) {
+                                final DatumAuthorityFactory factory = datumFactory();
+                                if (factory != null) try {
+                                    cached = object = factory.createEllipsoid(String.valueOf(ellipsoid));
+                                    return object;
+                                } catch (FactoryException e) {
+                                    failure("ellipsoid", e);
+                                }
+                            }
+                            object = StandardDefinitions.createEllipsoid(ellipsoid);
+                        }
+                        cached = object;
+                    }
+                }
+            }
+            return object;
+        }
+
+        /**
+         * Returns the prime meridian associated to the given object, or {@code null} if
none.
+         */
+        private static PrimeMeridian primeMeridian(final IdentifiedObject object) {
+            if (object instanceof PrimeMeridian) {
+                return (PrimeMeridian) object;
+            }
+            if (object instanceof GeodeticDatum) {
+                return ((GeodeticDatum) object).getPrimeMeridian();
+            }
+            if (object instanceof GeodeticCRS) {
+                return ((GeodeticCRS) object).getDatum().getPrimeMeridian();
+            }
+            return null;
+        }
+
+        /**
          * Returns the ellipsoid associated to the given object, or {@code null} if none.
          */
         private static Ellipsoid ellipsoid(final IdentifiedObject object) {

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java?rev=1531416&r1=1531415&r2=1531416&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
[UTF-8] Fri Oct 11 20:58:08 2013
@@ -71,18 +71,40 @@ import java.util.Objects;
  *
  * {@section Distance calculations}
  * This class contains an {@link #orthodromicDistance(double, double, double, double)} convenience
method
- * for calculating distances on the great circle. This convenience method is provided as
an alternative to
+ * for calculating distances on great circles. This convenience method is provided as an
alternative to
  * the {@link org.apache.sis.referencing.GeodeticCalculator}.
  *
- * {@section Frequently used ellipsoids}
- * A set of constants for frequently used ellipsoids is defined in the
- * {@link org.apache.sis.referencing.StandardObjects.Geodetic} class.
+ * {@section Creating new ellipsoid instances}
+ * New instances can be created either directly by specifying all information to a factory
method, or
+ * indirectly by specifying the identifier (primary key) of a database entry containing all
needed information.
+ * In particular, the <a href="http://www.epsg.org">EPSG</a> database provides
definitions for many ellipsoids
+ * currently or historically used by various countries around the world, and
+ * Apache SIS provides convenience shortcuts for some frequently used EPSG definitions.
+ *
+ * <p>The first item in the following list is the easiest but most restrictive way
to get an ellipsoid.
+ * Any other item can be chosen for more freedom. Each item typically implies all subsequent
items under
+ * the hood, so this list can been seen as <cite>top to bottom</cite> API.</p>
+ *
+ * <ol>
+ *   <li>Create an {@code Ellipsoid} from one of the static convenience shortcuts listed
in
+ *       {@link org.apache.sis.referencing.StandardObjects.Geodetic#ellipsoid()}.</li>
+ *   <li>Create an {@code Ellipsoid} from an identifier in a database by invoking
+ *       {@link org.opengis.referencing.datum.DatumAuthorityFactory#createEllipsoid(String)}.</li>
+ *   <li>Create an {@code Ellipsoid} by invoking the {@code createEllipsoid(…)} or
{@code createFlattenedSphere(…)}
+ *       methods defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.</li>
+ *   <li>Create a {@code DefaultEllipsoid} by invoking the
+ *       {@link #createEllipsoid(Map, double, double, Unit) createEllipsoid(…)} or
+ *       {@link #createFlattenedSphere(Map, double, double, Unit) createFlattenedSphere(…)}
+ *       static methods defined in this class.</li>
+ * </ol>
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @author  Cédric Briançon (Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.StandardObjects.Geodetic#ellipsoid()
  */
 @Immutable
 @XmlType(name="EllipsoidType", propOrder={

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java?rev=1531416&r1=1531415&r2=1531416&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
[UTF-8] Fri Oct 11 20:58:08 2013
@@ -17,7 +17,6 @@
 package org.apache.sis.referencing.datum;
 
 import java.util.Map;
-import java.util.HashMap;
 import java.util.Collections;
 import javax.measure.unit.Unit;
 import javax.measure.unit.NonSI;
@@ -26,9 +25,7 @@ import javax.xml.bind.annotation.XmlType
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;
 import org.opengis.referencing.datum.PrimeMeridian;
-import org.apache.sis.referencing.NamedIdentifier;
 import org.apache.sis.referencing.AbstractIdentifiedObject;
-import org.apache.sis.metadata.iso.citation.Citations;
 import org.apache.sis.internal.util.Numerics;
 import org.apache.sis.io.wkt.Formatter;
 import org.apache.sis.util.ComparisonMode;
@@ -36,6 +33,7 @@ import org.apache.sis.util.Immutable;
 
 import static org.apache.sis.util.ArgumentChecks.ensureFinite;
 import static org.apache.sis.util.ArgumentChecks.ensureNonNull;
+import static org.apache.sis.internal.referencing.ReferencingUtilities.GREENWICH;
 
 // Related to JDK7
 import java.util.Objects;
@@ -44,11 +42,35 @@ import java.util.Objects;
 /**
  * Defines the origin from which longitude values are determined.
  *
+ * {@section Creating new prime meridian instances}
+ * New instances can be created either directly by specifying all information to a constructor,
or
+ * indirectly by specifying the identifier (primary key) of a database entry containing all
needed information.
+ * In particular, the <a href="http://www.epsg.org">EPSG</a> database provides
definitions for many prime meridians
+ * currently or historically used by various countries around the world, and
+ * Apache SIS provides convenience shortcuts for some frequently used EPSG definitions.
+ *
+ * <p>The first item in the following list is the easiest but most restrictive way
to get a prime meridian.
+ * Any other item can be chosen for more freedom. Each item typically implies all subsequent
items under
+ * the hood, so this list can been seen as <cite>top to bottom</cite> API.</p>
+ *
+ * <ol>
+ *   <li>Create a {@code PrimeMeridian} from one of the static convenience shortcuts
listed in
+ *       {@link org.apache.sis.referencing.StandardObjects.Geodetic#primeMeridian()}.</li>
+ *   <li>Create a {@code PrimeMeridian} from an identifier in a database by invoking
+ *       {@link org.opengis.referencing.datum.DatumAuthorityFactory#createPrimeMeridian(String)}.</li>
+ *   <li>Create a {@code PrimeMeridian} by invoking the {@code createPrimeMeridian(…)}
+ *       method defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.</li>
+ *   <li>Create a {@code DefaultPrimeMeridian} by invoking the
+ *       {@linkplain #DefaultPrimeMeridian(Map, double, Unit) constructor}.</li>
+ * </ol>
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @author  Cédric Briançon (Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.StandardObjects.Geodetic#primeMeridian()
  */
 @Immutable
 @XmlType(name = "PrimeMeridianType")
@@ -60,17 +82,6 @@ public class DefaultPrimeMeridian extend
     private static final long serialVersionUID = 541978454643213305L;;
 
     /**
-     * The Greenwich meridian (EPSG:8901), with angular measurements in decimal degrees.
-     */
-    public static final DefaultPrimeMeridian GREENWICH;
-    static {
-        final Map<String,Object> properties = new HashMap<>(4);
-        properties.put(NAME_KEY, "Greenwich"); // Name is fixed by ISO 19111.
-        properties.put(IDENTIFIERS_KEY, new NamedIdentifier(Citations.EPSG, "8901"));
-        GREENWICH = new DefaultPrimeMeridian(properties, 0, NonSI.DEGREE_ANGLE);
-    }
-
-    /**
      * Longitude of the prime meridian measured from the Greenwich meridian, positive eastward.
      */
     @XmlElement(required = true)



Mime
View raw message