sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1534805 [1/2] - in /sis/trunk: ./ core/sis-metadata/src/main/java/org/apache/sis/metadata/ core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/ core/sis-refer...
Date Tue, 22 Oct 2013 21:36:50 GMT
Author: desruisseaux
Date: Tue Oct 22 21:36:49 2013
New Revision: 1534805

URL: http://svn.apache.org/r1534805
Log:
Merge from the JDK6 branch.

Added:
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/ReferencingUtilities.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjects.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardDefinitions.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardDefinitions.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/referencing/StandardObjects.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/BursaWolfParameters.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
      - copied unchanged from r1534802, sis/branches/JDK6/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
Modified:
    sis/trunk/   (props changed)
    sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
    sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
    sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/DefaultScopeDescription.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractReferenceSystem.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/NamedIdentifier.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEngineeringDatum.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultImageDatum.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/Sphere.java
    sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/GeneralMatrix.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/Modules.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/CollectionsExt.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleDouble.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/LineAppender.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/CodeListSet.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Errors.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Errors.properties
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Errors_fr.properties
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Vocabulary.java
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Vocabulary.properties
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/resources/Vocabulary_fr.properties
    sis/trunk/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
    sis/trunk/core/sis-utility/src/test/java/org/apache/sis/io/LineAppenderTest.java
    sis/trunk/core/sis-utility/src/test/java/org/apache/sis/test/TestSuite.java
    sis/trunk/src/main/javadoc/stylesheet.css
    sis/trunk/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/AttributeNames.java

Propchange: sis/trunk/
------------------------------------------------------------------------------
  Merged /sis/branches/JDK7:r1530580-1533381
  Merged /sis/branches/JDK6:r1530582-1534802

Modified: sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java [UTF-8] (original)
+++ sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -609,7 +609,7 @@ public abstract class ModifiableMetadata
             return EnumSet.noneOf((Class) elementType);
         }
         if (CodeList.class.isAssignableFrom(elementType) && Modifier.isFinal(elementType.getModifiers())) {
-            return new CodeListSet((Class) elementType);
+            return new CodeListSet(elementType);
         }
         return new CheckedHashSet<E>(elementType, capacity);
     }

Modified: sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java [UTF-8] (original)
+++ sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ImmutableIdentifier.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -141,8 +141,8 @@ public class ImmutableIdentifier impleme
         codeSpace = identifier.getCodeSpace();
         authority = identifier.getAuthority();
         version   = identifier.getVersion();
-        if (identifier instanceof ImmutableIdentifier) {
-            remarks = ((ImmutableIdentifier) identifier).getRemarks();
+        if (identifier instanceof Deprecable) {
+            remarks = ((Deprecable) identifier).getRemarks();
         } else {
             remarks = null;
         }
@@ -197,7 +197,7 @@ public class ImmutableIdentifier impleme
     }
 
     /**
-     * Constructs an identifier from a set of properties. Keys are strings from the table below.
+     * Constructs an identifier from the given properties. Keys are strings from the table below.
      * The map given in argument shall contain an entry at least for the
      * {@value org.opengis.metadata.Identifier#CODE_KEY} key.
      * Other properties listed in the table below are optional.
@@ -246,9 +246,9 @@ public class ImmutableIdentifier impleme
      */
     public ImmutableIdentifier(final Map<String,?> properties) throws IllegalArgumentException {
         ensureNonNull("properties", properties);
-        code      = property(properties, CODE_KEY,      String.class);
-        version   = property(properties, VERSION_KEY,   String.class);
-        remarks   = Types.toInternationalString(properties, REMARKS_KEY);
+        code    = property(properties, CODE_KEY,    String.class);
+        version = property(properties, VERSION_KEY, String.class);
+        remarks = Types.toInternationalString(properties, REMARKS_KEY);
         /*
          * Map String authority to one of the pre-defined constants (typically EPSG or OGC).
          */

Modified: sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/DefaultScopeDescription.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/DefaultScopeDescription.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/DefaultScopeDescription.java [UTF-8] (original)
+++ sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/DefaultScopeDescription.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -17,6 +17,7 @@
 package org.apache.sis.metadata.iso.maintenance;
 
 import java.util.Set;
+import java.util.Collection;
 import javax.xml.bind.annotation.XmlType;
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;
@@ -145,12 +146,12 @@ public class DefaultScopeDescription ext
                     switch (i) {
                         case ATTRIBUTES:
                         case ATTRIBUTE_INSTANCES: {
-                            candidate = copySet((Set<AttributeType>) candidate, AttributeType.class);
+                            candidate = copySet((Collection<AttributeType>) candidate, AttributeType.class);
                             break;
                         }
                         case FEATURES:
                         case FEATURE_INSTANCES: {
-                            candidate = copySet((Set<FeatureType>) candidate, FeatureType.class);
+                            candidate = copySet((Collection<FeatureType>) candidate, FeatureType.class);
                             break;
                         }
                     }

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -31,7 +31,6 @@ import javax.xml.bind.annotation.adapter
 import javax.xml.bind.annotation.adapters.CollapsedStringAdapter;
 import org.opengis.util.GenericName;
 import org.opengis.util.InternationalString;
-import org.opengis.metadata.Identifier;
 import org.opengis.metadata.citation.Citation;
 import org.opengis.referencing.ObjectFactory;
 import org.opengis.referencing.AuthorityFactory;
@@ -158,24 +157,7 @@ public class AbstractIdentifiedObject ex
     private transient int hashCode;
 
     /**
-     * Constructs a new identified object with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a
-     * user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param object The object to shallow copy.
-     */
-    public AbstractIdentifiedObject(final IdentifiedObject object) {
-        ensureNonNull("object", object);
-        name        =          object.getName();
-        alias       = nonEmpty(object.getAlias()); // Favor null for empty set in case it is not Collections.EMPTY_SET
-        identifiers = nonEmpty(object.getIdentifiers());
-        remarks     =          object.getRemarks();
-    }
-
-    /**
-     * Constructs an object from a set of properties. Keys are strings from the table below.
+     * Constructs an object from the given properties. Keys are strings from the table below.
      * The map given in argument shall contain an entry at least for the
      * {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} key.
      * Other properties listed in the table below are optional.
@@ -291,6 +273,23 @@ public class AbstractIdentifiedObject ex
     }
 
     /**
+     * Constructs a new identified object with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a
+     * user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param object The object to shallow copy.
+     */
+    protected AbstractIdentifiedObject(final IdentifiedObject object) {
+        ensureNonNull("object", object);
+        name        =          object.getName();
+        alias       = nonEmpty(object.getAlias()); // Favor null for empty set in case it is not Collections.EMPTY_SET
+        identifiers = nonEmpty(object.getIdentifiers());
+        remarks     =          object.getRemarks();
+    }
+
+    /**
      * The {@code gml:id}, which is mandatory. The current implementation searches for the first identifier,
      * regardless its authority. If no identifier is found, then the name is used.
      * If no name is found (which should not occur for valid objects), then this method returns {@code null}.
@@ -578,7 +577,7 @@ public class AbstractIdentifiedObject ex
      * <code>{@linkplain #equals(Object, ComparisonMode) equals}(object, IGNORE_METADATA)</code>.
      * This feature allows users to implement metadata-insensitive {@link java.util.HashMap}.
      *
-     * @param  mode Specifies the set of properties that can be used for hash code computation.
+     * @param  mode Specifies the properties that can be used for hash code computation.
      * @return The hash code value. This value may change between different execution of the Apache SIS library.
      * @throws IllegalArgumentException If the given {@code mode} is not one of {@code STRICT}, {@code BY_CONTRACT}
      *         or {@code IGNORE_METADATA} enumeration values.

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractReferenceSystem.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractReferenceSystem.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractReferenceSystem.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractReferenceSystem.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -91,7 +91,7 @@ public class AbstractReferenceSystem ext
     }
 
     /**
-     * Constructs a reference system from a set of properties.
+     * Constructs a reference system from the given properties.
      * The properties given in argument follow the same rules than for the
      * {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
      * Additionally, the following properties are understood by this constructor:

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/NamedIdentifier.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/NamedIdentifier.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/NamedIdentifier.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/NamedIdentifier.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -99,7 +99,7 @@ public class NamedIdentifier extends Imm
     }
 
     /**
-     * Constructs an identifier from a set of properties. The content of the properties map is used as
+     * Constructs an identifier from the given properties. The content of the properties map is used as
      * described in the {@linkplain ImmutableIdentifier#ImmutableIdentifier(Map) super-class constructor}.
      *
      * @param  properties The properties to be given to this identifier.

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/AbstractDatum.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -18,8 +18,6 @@ package org.apache.sis.referencing.datum
 
 import java.util.Date;
 import java.util.Map;
-import java.util.HashMap;
-import java.util.Locale;
 import javax.xml.bind.annotation.XmlType;
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
@@ -33,7 +31,6 @@ import org.apache.sis.util.iso.Types;
 import org.apache.sis.util.Classes;
 import org.apache.sis.util.Immutable;
 import org.apache.sis.util.ComparisonMode;
-import org.apache.sis.util.resources.Vocabulary;
 import org.apache.sis.internal.metadata.MetadataUtilities;
 import org.apache.sis.internal.jaxb.gco.DateAsLongAdapter;
 
@@ -56,8 +53,8 @@ import org.apache.sis.internal.jdk7.Obje
  * Typical applications should create instances of the most specific subclass prefixed by {@code Default} instead.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
- * @since   0.3 (derived from geotk-1.2)
- * @version 0.3
+ * @since   0.4 (derived from geotk-1.2)
+ * @version 0.4
  * @module
  *
  * @see org.apache.sis.referencing.cs.AbstractCS
@@ -100,24 +97,7 @@ public class AbstractDatum extends Abstr
     private final InternationalString scope;
 
     /**
-     * Constructs a new datum with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param datum The datum to copy.
-     */
-    public AbstractDatum(final Datum datum) {
-        super(datum);
-        realizationEpoch = MetadataUtilities.toMilliseconds(datum.getRealizationEpoch());
-        domainOfValidity = datum.getDomainOfValidity();
-        scope            = datum.getScope();
-        anchorPoint      = datum.getAnchorPoint();
-    }
-
-    /**
-     * Constructs a datum from a set of properties.
+     * Creates a datum from the given properties.
      * The properties given in argument follow the same rules than for the
      * {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
      * Additionally, the following properties are understood by this constructor:
@@ -161,16 +141,20 @@ public class AbstractDatum extends Abstr
     }
 
     /**
-     * Same convenience method than {@link org.apache.sis.cs.AbstractCS#name(int)} except that we get the
-     * unlocalized name (usually in English locale), because the name is part of the elements compared by
-     * the {@link #equals(Object, ComparisonMode)} method.
-     */
-    static Map<String,Object> name(final int key) {
-        final Map<String,Object> properties = new HashMap<String,Object>(4);
-        final InternationalString name = Vocabulary.formatInternational(key);
-        properties.put(NAME_KEY,  name.toString(Locale.ROOT));
-        properties.put(ALIAS_KEY, name);
-        return properties;
+     * Creates a new datum with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param datum The datum to copy.
+     */
+    protected AbstractDatum(final Datum datum) {
+        super(datum);
+        realizationEpoch = MetadataUtilities.toMilliseconds(datum.getRealizationEpoch());
+        domainOfValidity = datum.getDomainOfValidity();
+        scope            = datum.getScope();
+        anchorPoint      = datum.getAnchorPoint();
     }
 
     /**
@@ -302,6 +286,8 @@ public class AbstractDatum extends Abstr
      * {@linkplain #getAnchorPoint() anchor point}, {@linkplain #getRealizationEpoch() realization epoch},
      * {@linkplain #getDomainOfValidity() domain of validity} and the {@linkplain #getScope() scope}
      * properties are ignored.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java [UTF-8] Tue Oct 22 21:36:49 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.SI;
 import javax.measure.unit.Unit;
@@ -33,10 +32,8 @@ import org.apache.sis.internal.jaxb.Cont
 import org.apache.sis.internal.jaxb.gco.Measure;
 import org.apache.sis.internal.jaxb.referencing.SecondDefiningParameter;
 import org.apache.sis.internal.referencing.Formulas;
-import org.apache.sis.referencing.NamedIdentifier;
 import org.apache.sis.referencing.IdentifiedObjects;
 import org.apache.sis.referencing.AbstractIdentifiedObject;
-import org.apache.sis.metadata.iso.citation.Citations;
 import org.apache.sis.io.wkt.Formatter;
 import org.apache.sis.util.Immutable;
 import org.apache.sis.util.ComparisonMode;
@@ -65,11 +62,54 @@ import org.apache.sis.internal.jdk7.Obje
  *       {@linkplain #getSemiMinorAxis() semi-minor axis}.</li>
  * </ul>
  *
+ * Some numerical values derived from the above properties are:
+ *
+ * <ul>
+ *   <li>{@linkplain #getAuthalicRadius() authalic radius}</li>
+ *   <li>{@linkplain #getEccentricity() eccentricity}</li>
+ * </ul>
+ *
+ * {@section Distance calculations}
+ * This class contains an {@link #orthodromicDistance(double, double, double, double)} convenience method
+ * for calculating distances on great circles. This convenience method is provided as an alternative to
+ * the {@link org.apache.sis.referencing.GeodeticCalculator}.
+ *
+ * {@section Creating new ellipsoid 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).
+ * In particular, the <a href="http://www.epsg.org">EPSG</a> database provides definitions for many ellipsoids,
+ * and Apache SIS provides convenience shortcuts for some of them.
+ *
+ * <p>Choice 1 in the following list is the easiest but most restrictive way to get an ellipsoid.
+ * The other choices provide more freedom. Each choice delegates its work to the subsequent items
+ * (in the default configuration), 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.GeodeticObjects#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>
+ *
+ * <b>Example:</b> the following code gets the WGS84 ellipsoid:
+ *
+ * {@preformat java
+ *     Ellipsoid e = GeodeticObjects.WGS84.ellipsoid();
+ * }
+ *
  * @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.GeodeticObjects#ellipsoid()
  */
 @Immutable
 @XmlType(name="EllipsoidType", propOrder={
@@ -101,89 +141,6 @@ public class DefaultEllipsoid extends Ab
     private static final double COMPARISON_THRESHOLD = 1E-10;
 
     /**
-     * Returns a properties map with the given name and EPSG code.
-     * This is used for the creation of default ellipsoid constants.
-     */
-    private static Map<String,?> properties(final String name, final int code, final Object alias) {
-        final Map<String,Object> map = new HashMap<String,Object>(8);
-        map.put(NAME_KEY, name);
-        map.put(IDENTIFIERS_KEY, new NamedIdentifier(Citations.EPSG, String.valueOf(code)));
-        if (alias != null) {
-            map.put(ALIAS_KEY, alias);
-        }
-        return map;
-    }
-
-    /**
-     * WGS 1984 ellipsoid (EPSG:7030) used in GPS systems.
-     * The semi-major and semi-minor axis length are approximatively 6378137 and 6356752
-     * {@linkplain SI#METRE metres} respectively.
-     * This is the default ellipsoid for most {@code org.apache.sis} packages.
-     *
-     * @see DefaultGeodeticDatum#WGS84
-     */
-    public static final DefaultEllipsoid WGS84 = createFlattenedSphere(
-            properties("WGS84", 7030, "WGS 1984"), 6378137.0, 298.257223563, SI.METRE);
-
-    /**
-     * WGS 1972 ellipsoid (EPSG:7043).
-     * The semi-major and semi-minor axis length are approximatively 6378135 and 6356751
-     * {@linkplain SI#METRE metres} respectively.
-     *
-     * @see DefaultGeodeticDatum#WGS72
-     */
-    public static final DefaultEllipsoid WGS72 = createFlattenedSphere(
-            properties("WGS72", 7043, "WGS 1972"), 6378135.0, 298.26, SI.METRE);
-
-    /**
-     * GRS 1980 ellipsoid (EPSG:7019), also called "<cite>International 1979</cite>".
-     * The semi-major and semi-minor axis length are approximatively 6378137 and 6356752
-     * {@linkplain SI#METRE metres} respectively. This ellipsoid is very close, but not
-     * identical, to {@linkplain #WGS84}.
-     *
-     * {@note The <cite>NAD83</cite> ellipsoid uses the same semi-axis length and units.
-     *        The <cite>Web Map Server</cite> <code>"CRS:83"</code> authority code uses that NAD83 ellipsoid.
-     *        The <code>"IGNF:MILLER"</code> authority code uses the GRS80 ellipsoid.}
-     */
-    public static final DefaultEllipsoid GRS80 = createFlattenedSphere(
-            properties("GRS80", 7019, new String[] {"GRS 1980", "International 1979"}),
-            6378137.0, 298.257222101, SI.METRE);
-
-    /**
-     * International 1924 ellipsoid (EPSG:7022).
-     * The semi-major and semi-minor axis length are approximatively 6378388 and 6356912
-     * {@linkplain SI#METRE metres} respectively.
-     *
-     * {@note The <cite>European Datum 1950</cite> ellipsoid uses the same semi-axis length and units.}
-     */
-    public static final DefaultEllipsoid INTERNATIONAL_1924 = createFlattenedSphere(
-            properties("International 1924", 7022, null), 6378388.0, 297.0, SI.METRE);
-
-    /**
-     * Clarke 1866 ellipsoid (EPSG:7008).
-     * The semi-major and semi-minor axis length are approximatively 6378206 and 6356584
-     * {@linkplain SI#METRE metres} respectively.
-     *
-     * {@note The <cite>NAD27</cite> ellipsoid uses the same semi-axis length and units.
-     *        The <cite>Web Map Server</cite> <code>"CRS:27"</code> authority code uses that NAD27 ellipsoid.}
-     */
-    public static final DefaultEllipsoid CLARKE_1866 = createEllipsoid(
-            properties("Clarke 1866", 7008, null), 6378206.4, 6356583.8, SI.METRE);
-
-    /**
-     * A sphere with a radius of 6371000 {@linkplain SI#METRE metres}. Spheres use a simpler
-     * algorithm for {@linkplain #orthodromicDistance orthodromic distance computation}, which
-     * may be faster and more robust.
-     *
-     * {@note This ellipsoid is close to the <cite>GRS 1980 Authalic Sphere</cite> (EPSG:7048),
-     *        which has a radius of 6371007 metres.}
-     *
-     * @see DefaultGeodeticDatum#SPHERE
-     */
-    public static final DefaultEllipsoid SPHERE =
-            createEllipsoid("SPHERE", 6371000, 6371000, SI.METRE);
-
-    /**
      * The equatorial radius. This field should be considered as final.
      * It is modified only by JAXB at unmarshalling time.
      *
@@ -221,31 +178,11 @@ public class DefaultEllipsoid extends Ab
     private Unit<Length> unit;
 
     /**
-     * Constructs a new ellipsoid with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param ellipsoid The ellipsoid to copy.
-     *
-     * @see #castOrCopy(Ellipsoid)
-     */
-    protected DefaultEllipsoid(final Ellipsoid ellipsoid) {
-        super(ellipsoid);
-        semiMajorAxis     = ellipsoid.getSemiMajorAxis();
-        semiMinorAxis     = ellipsoid.getSemiMinorAxis();
-        inverseFlattening = ellipsoid.getInverseFlattening();
-        ivfDefinitive     = ellipsoid.isIvfDefinitive();
-        unit              = ellipsoid.getAxisUnit();
-    }
-
-    /**
-     * Constructs a new ellipsoid using the specified axis length. The properties map is
-     * given unchanged to the {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map)
-     * super-class constructor}.
+     * Creates a new ellipsoid using the specified axis length.
+     * The properties map is given unchanged to the
+     * {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
      *
-     * @param properties        Set of properties. Should contains at least {@code "name"}.
+     * @param  properties       The properties to be given to the identified object.
      * @param semiMajorAxis     The equatorial radius.
      * @param semiMinorAxis     The polar radius.
      * @param inverseFlattening The inverse of the flattening value.
@@ -275,30 +212,51 @@ public class DefaultEllipsoid extends Ab
     }
 
     /**
-     * Constructs a new ellipsoid using the specified axis length.
+     * Creates a new ellipsoid with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param ellipsoid The ellipsoid to copy.
+     *
+     * @see #castOrCopy(Ellipsoid)
+     */
+    protected DefaultEllipsoid(final Ellipsoid ellipsoid) {
+        super(ellipsoid);
+        semiMajorAxis     = ellipsoid.getSemiMajorAxis();
+        semiMinorAxis     = ellipsoid.getSemiMinorAxis();
+        inverseFlattening = ellipsoid.getInverseFlattening();
+        ivfDefinitive     = ellipsoid.isIvfDefinitive();
+        unit              = ellipsoid.getAxisUnit();
+    }
+
+    /**
+     * Creates a new ellipsoid using the specified name and axis length in metres.
+     * This is a convenience method for {@link #createEllipsoid(Map, double, double, Unit) createEllipsoid(Map, …)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property
+     * and the unit of measurement fixed to {@link SI#METRE}.
      *
      * @param name          The ellipsoid name.
-     * @param semiMajorAxis The equatorial radius.
-     * @param semiMinorAxis The polar radius.
-     * @param unit          The units of the semi-major and semi-minor axis values.
+     * @param semiMajorAxis The equatorial radius in metres.
+     * @param semiMinorAxis The polar radius in metres.
      * @return An ellipsoid with the given axis length.
      */
     public static DefaultEllipsoid createEllipsoid(final String name,
                                                    final double semiMajorAxis,
-                                                   final double semiMinorAxis,
-                                                   final Unit<Length> unit)
+                                                   final double semiMinorAxis)
     {
-        return createEllipsoid(Collections.singletonMap(NAME_KEY, name), semiMajorAxis, semiMinorAxis, unit);
+        return createEllipsoid(Collections.singletonMap(NAME_KEY, name), semiMajorAxis, semiMinorAxis, SI.METRE);
     }
 
     /**
-     * Constructs a new ellipsoid using the specified axis length. The properties map is
-     * given unchanged to the {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map)
-     * super-class constructor}.
+     * Creates a new ellipsoid using the specified properties and axis length.
+     * The properties map is given unchanged to the
+     * {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
      *
-     * @param properties    Set of properties. Should contains at least {@code "name"}.
-     * @param semiMajorAxis The equatorial radius.
-     * @param semiMinorAxis The polar radius.
+     * @param properties    The properties to be given to the identified object.
+     * @param semiMajorAxis The equatorial radius in the given unit.
+     * @param semiMinorAxis The polar radius in the given unit.
      * @param unit          The units of the semi-major and semi-minor axis values.
      * @return An ellipsoid with the given axis length.
      */
@@ -316,29 +274,30 @@ public class DefaultEllipsoid extends Ab
     }
 
     /**
-     * Constructs a new ellipsoid using the specified axis length and inverse flattening value.
+     * Creates a new ellipsoid using the specified name, axis length in metres and inverse flattening value. This is
+     * a convenience method for {@link #createFlattenedSphere(Map, double, double, Unit) createFlattenedSphere(Map, …)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property and the unit
+     * of measurement fixed to {@link SI#METRE}.
      *
      * @param name              The ellipsoid name.
-     * @param semiMajorAxis     The equatorial radius.
+     * @param semiMajorAxis     The equatorial radius in metres.
      * @param inverseFlattening The inverse flattening value.
-     * @param unit              The units of the semi-major and semi-minor axis values.
      * @return An ellipsoid with the given axis length.
      */
     public static DefaultEllipsoid createFlattenedSphere(final String name,
                                                          final double semiMajorAxis,
-                                                         final double inverseFlattening,
-                                                         final Unit<Length> unit)
+                                                         final double inverseFlattening)
     {
-        return createFlattenedSphere(Collections.singletonMap(NAME_KEY, name), semiMajorAxis, inverseFlattening, unit);
+        return createFlattenedSphere(Collections.singletonMap(NAME_KEY, name), semiMajorAxis, inverseFlattening, SI.METRE);
     }
 
     /**
-     * Constructs a new ellipsoid using the specified axis length and
-     * inverse flattening value. The properties map is given unchanged to the
+     * Creates a new ellipsoid using the specified properties, axis length and inverse flattening value.
+     * The properties map is given unchanged to the
      * {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
      *
-     * @param properties        Set of properties. Should contains at least {@code "name"}.
-     * @param semiMajorAxis     The equatorial radius.
+     * @param  properties       The properties to be given to the identified object.
+     * @param semiMajorAxis     The equatorial radius in the given unit.
      * @param inverseFlattening The inverse flattening value.
      * @param unit              The units of the semi-major and semi-minor axis values.
      * @return An ellipsoid with the given axis length.
@@ -597,6 +556,8 @@ public class DefaultEllipsoid extends Ab
      * @param  x2 Longitude of second point (in decimal degrees).
      * @param  y2 Latitude  of second point (in decimal degrees).
      * @return The orthodromic distance (in the units of this ellipsoid's axis).
+     *
+     * @see org.apache.sis.referencing.GeodeticCalculator
      */
     public double orthodromicDistance(double x1, double y1, double x2, double y2) {
         x1 = toRadians(x1);
@@ -726,6 +687,8 @@ public class DefaultEllipsoid extends Ab
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEngineeringDatum.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEngineeringDatum.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEngineeringDatum.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEngineeringDatum.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -47,20 +47,9 @@ public class DefaultEngineeringDatum ext
     private static final long serialVersionUID = 1498304918725248637L;
 
     /**
-     * Constructs a new datum with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param datum The datum to copy.
-     */
-    public DefaultEngineeringDatum(final EngineeringDatum datum) {
-        super(datum);
-    }
-
-    /**
-     * Constructs an engineering datum from a name.
+     * Creates an engineering datum from a name. This is a convenience constructor for
+     * {@link #DefaultEngineeringDatum(Map)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property.
      *
      * @param name The datum name.
      */
@@ -69,16 +58,31 @@ public class DefaultEngineeringDatum ext
     }
 
     /**
-     * Constructs an engineering datum from a set of properties. The properties map is given
+     * Creates an engineering datum from the given properties. The properties map is given
      * unchanged to the {@linkplain AbstractDatum#AbstractDatum(Map) super-class constructor}.
      *
-     * @param properties Set of properties. Shall contains at least {@code "name"}.
+     * @param properties The properties to be given to the identified object.
      */
     public DefaultEngineeringDatum(final Map<String,?> properties) {
         super(properties);
     }
 
     /**
+     * Creates a new datum with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param datum The datum to copy.
+     *
+     * @see #castOrCopy(EngineeringDatum)
+     */
+    protected DefaultEngineeringDatum(final EngineeringDatum datum) {
+        super(datum);
+    }
+
+    /**
      * Returns a SIS datum implementation with the same values than the given arbitrary implementation.
      * If the given object is {@code null}, then this method returns {@code null}.
      * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
@@ -112,6 +116,8 @@ public class DefaultEngineeringDatum ext
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultImageDatum.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultImageDatum.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultImageDatum.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultImageDatum.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -57,21 +57,9 @@ public class DefaultImageDatum extends A
     private final PixelInCell pixelInCell;
 
     /**
-     * Constructs a new datum with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param datum The datum to copy.
-     */
-    public DefaultImageDatum(final ImageDatum datum) {
-        super(datum);
-        pixelInCell = datum.getPixelInCell();
-    }
-
-    /**
-     * Constructs an image datum from a name.
+     * Creates an image datum from a name. This is a convenience constructor for
+     * {@link #DefaultImageDatum(Map, PixelInCell) DefaultImageDatum(Map, …)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property.
      *
      * @param name The datum name.
      * @param pixelInCell the way the image grid is associated with the image data attributes.
@@ -81,11 +69,11 @@ public class DefaultImageDatum extends A
     }
 
     /**
-     * Constructs an image datum from a set of properties. The properties map is given
+     * Creates an image datum from the given properties. The properties map is given
      * unchanged to the {@linkplain AbstractDatum#AbstractDatum(Map) super-class constructor}.
      *
-     * @param properties  Set of properties. Should contains at least {@code "name"}.
-     * @param pixelInCell the way the image grid is associated with the image data attributes.
+     * @param properties  The properties to be given to the identified object.
+     * @param pixelInCell The way the image grid is associated with the image data attributes.
      */
     public DefaultImageDatum(final Map<String,?> properties, final PixelInCell pixelInCell) {
         super(properties);
@@ -94,6 +82,22 @@ public class DefaultImageDatum extends A
     }
 
     /**
+     * Creates a new datum with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param datum The datum to copy.
+     *
+     * @see #castOrCopy(ImageDatum)
+     */
+    protected DefaultImageDatum(final ImageDatum datum) {
+        super(datum);
+        pixelInCell = datum.getPixelInCell();
+    }
+
+    /**
      * Returns a SIS datum implementation with the same values than the given arbitrary implementation.
      * If the given object is {@code null}, then this method returns {@code null}.
      * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
@@ -150,6 +154,8 @@ public class DefaultImageDatum extends A
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java [UTF-8] Tue Oct 22 21:36:49 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;
@@ -42,13 +39,42 @@ import org.apache.sis.internal.jdk7.Obje
 
 
 /**
- * A prime meridian defines the origin from which longitude values are determined.
+ * 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 factory method (choices 3
+ * and 4 below), or indirectly by specifying the identifier of an entry in a database (choices 1 and 2 below).
+ * In particular, the <a href="http://www.epsg.org">EPSG</a> database provides definitions for many prime meridians,
+ * and Apache SIS provides convenience shortcuts for some of them.
+ *
+ * <p>Choice 1 in the following list is the easiest but most restrictive way to get a prime meridian.
+ * The other choices provide more freedom. Each choice delegates its work to the subsequent items
+ * (in the default configuration), 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.GeodeticObjects#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>
+ *
+ * <b>Example:</b> the following code gets the Greenwich prime meridian:
+ *
+ * {@preformat java
+ *     PrimeMeridian pm = GeodeticObjects.WGS84.primeMeridian();
+ * }
  *
  * @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.GeodeticObjects#primeMeridian()
  */
 @Immutable
 @XmlType(name = "PrimeMeridianType")
@@ -60,17 +86,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<String,Object>(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)
@@ -82,57 +97,25 @@ public class DefaultPrimeMeridian extend
     private final Unit<Angle> angularUnit;
 
     /**
-     * Constructs a new object in which every attributes are set to a default value.
-     * <strong>This is not a valid object.</strong> This constructor is strictly
-     * reserved to JAXB, which will assign values to the fields using reflexion.
-     */
-    private DefaultPrimeMeridian() {
-        this(GREENWICH);
-    }
-
-    /**
-     * Constructs a new prime meridian with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param meridian The prime meridian to copy.
-     */
-    public DefaultPrimeMeridian(final PrimeMeridian meridian) {
-        super(meridian);
-        greenwichLongitude = meridian.getGreenwichLongitude();
-        angularUnit        = meridian.getAngularUnit();
-    }
-
-    /**
-     * Constructs a prime meridian from a name and Greenwich longitude.
-     * The {@code greenwichLongitude} value is assumed in {@linkplain NonSI#DEGREE_ANGLE decimal degrees}.
-     *
-     * @param name The datum name.
-     * @param greenwichLongitude The longitude value relative to the Greenwich Meridian, in degrees.
-     */
-    public DefaultPrimeMeridian(final String name, final double greenwichLongitude) {
-        this(name, greenwichLongitude, NonSI.DEGREE_ANGLE);
-    }
-
-    /**
-     * Constructs a prime meridian from a name, Greenwich longitude and angular unit.
+     * Creates a prime meridian from a name and Greenwich longitude in degrees. This is a convenience
+     * constructor for {@link #DefaultPrimeMeridian(Map, double, Unit) DefaultPrimeMeridian(Map, …)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property,
+     * and with the unit of measurement fixed to {@link NonSI#DEGREE_ANGLE}.
      *
      * @param name                The datum name.
-     * @param greenwichLongitude  The longitude value relative to the Greenwich Meridian.
-     * @param angularUnit         The angular unit of the longitude, in degrees.
+     * @param greenwichLongitude  The longitude value relative to the Greenwich Meridian, in degrees.
+     *                            Positive values are east of Greenwich.
      */
-    public DefaultPrimeMeridian(final String name, final double greenwichLongitude, final Unit<Angle> angularUnit) {
-        this(Collections.singletonMap(NAME_KEY, name), greenwichLongitude, angularUnit);
+    public DefaultPrimeMeridian(final String name, final double greenwichLongitude) {
+        this(Collections.singletonMap(NAME_KEY, name), greenwichLongitude, NonSI.DEGREE_ANGLE);
     }
 
     /**
-     * Constructs a prime meridian from a set of properties. The properties map is given
+     * Creates a prime meridian from the given properties. The properties map is given
      * unchanged to the {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map)
      * super-class constructor}.
      *
-     * @param properties          Set of properties. Should contains at least {@code "name"}.
+     * @param properties          The properties to be given to the identified object.
      * @param greenwichLongitude  The longitude value relative to the Greenwich Meridian.
      * @param angularUnit         The angular unit of the longitude.
      */
@@ -147,6 +130,23 @@ public class DefaultPrimeMeridian extend
     }
 
     /**
+     * Creates a new prime meridian with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param meridian The prime meridian to copy.
+     *
+     * @see #castOrCopy(PrimeMeridian)
+     */
+    protected DefaultPrimeMeridian(final PrimeMeridian meridian) {
+        super(meridian);
+        greenwichLongitude = meridian.getGreenwichLongitude();
+        angularUnit        = meridian.getAngularUnit();
+    }
+
+    /**
      * Returns a SIS prime meridian implementation with the same values than the given arbitrary implementation.
      * If the given object is {@code null}, then this method returns {@code null}.
      * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
@@ -242,6 +242,8 @@ public class DefaultPrimeMeridian extend
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {
@@ -264,7 +266,7 @@ public class DefaultPrimeMeridian extend
     }
 
     /**
-     * Formats the inner part of a<cite>Well Known Text</cite> (WKT) element.
+     * Formats the inner part of a <cite>Well Known Text</cite> (WKT) element.
      *
      * @param  formatter The formatter to use.
      * @return The WKT element name, which is {@code "PRIMEM"}.

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java Tue Oct 22 21:36:49 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;
 
@@ -34,12 +33,37 @@ import org.apache.sis.internal.jdk7.Obje
 
 
 /**
- * A temporal datum defines the origin of a temporal coordinate reference system.
+ * 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.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(…)}
+ *       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 datum = GeodeticObjects.Temporal.JULIAN.datum();
+ * }
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.GeodeticObjects.Temporal#datum()
  */
 @Immutable
 @XmlType(name = "TemporalDatumType")
@@ -51,73 +75,14 @@ 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)));
-
-    /**
-     * Default 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;
 
     /**
-     * Constructs a new datum with the same values than the specified one.
-     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
-     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
-     *
-     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
-     *
-     * @param datum The datum to copy.
-     */
-    public DefaultTemporalDatum(final TemporalDatum datum) {
-        super(datum);
-        origin = datum.getOrigin().getTime();
-    }
-
-    /**
-     * Constructs a temporal datum from a name.
+     * Creates a temporal datum from a name. This is a convenience constructor for
+     * {@link #DefaultTemporalDatum(Map, Date) DefaultTemporalDatum(Map, …)}
+     * with a map containing only the {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} property.
      *
      * @param name   The datum name.
      * @param origin The date and time origin of this temporal datum.
@@ -127,10 +92,10 @@ public class DefaultTemporalDatum extend
     }
 
     /**
-     * Constructs a temporal datum from a set of properties. The properties map is given
+     * Creates a temporal datum from the given properties. The properties map is given
      * unchanged to the {@linkplain AbstractDatum#AbstractDatum(Map) super-class constructor}.
      *
-     * @param properties Set of properties. Should contains at least {@code "name"}.
+     * @param properties The properties to be given to the identified object.
      * @param origin The date and time origin of this temporal datum.
      */
     public DefaultTemporalDatum(final Map<String,?> properties, final Date origin) {
@@ -140,6 +105,22 @@ public class DefaultTemporalDatum extend
     }
 
     /**
+     * Creates a new datum with the same values than the specified one.
+     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
+     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
+     *
+     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
+     *
+     * @param datum The datum to copy.
+     *
+     * @see #castOrCopy(TemporalDatum)
+     */
+    protected DefaultTemporalDatum(final TemporalDatum datum) {
+        super(datum);
+        origin = datum.getOrigin().getTime();
+    }
+
+    /**
      * Returns a SIS datum implementation with the same values than the given arbitrary implementation.
      * If the given object is {@code null}, then this method returns {@code null}.
      * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
@@ -196,6 +177,8 @@ public class DefaultTemporalDatum extend
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java [UTF-8] Tue Oct 22 21:36:49 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 org.apache.sis.internal.jdk7.Obje
  * {@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.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(…)}
+ *       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 datum = GeodeticObjects.Vertical.GEOID.datum();
+ * }
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
+ *
+ * @see org.apache.sis.referencing.GeodeticObjects.Vertical#datum()
  */
 @Immutable
 @XmlType(name = "VerticalDatumType")
@@ -64,38 +88,9 @@ 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);
-
-    /**
-     * Constructs a vertical datum from a name.
+     * Creates a vertical datum from a name. This is a convenience constructor for
+     * {@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.
      * @param type The type of this vertical datum.
@@ -105,33 +100,35 @@ public class DefaultVerticalDatum extend
     }
 
     /**
-     * Constructs a new datum with the same values than the specified one.
+     * Creates a vertical datum from the given properties. The properties map is given
+     * unchanged to the {@linkplain AbstractDatum#AbstractDatum(Map) super-class constructor}.
+     *
+     * @param properties The properties to be given to the identified object.
+     * @param type       The type of this vertical datum.
+     */
+    public DefaultVerticalDatum(final Map<String,?> properties, final VerticalDatumType type) {
+        super(properties);
+        this.type = type;
+        ensureNonNull("type", type);
+    }
+
+    /**
+     * Creates a new datum with the same values than the specified one.
      * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
      * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
      *
      * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
      *
      * @param datum The datum to copy.
+     *
+     * @see #castOrCopy(VerticalDatum)
      */
-    public DefaultVerticalDatum(final VerticalDatum datum) {
+    protected DefaultVerticalDatum(final VerticalDatum datum) {
         super(datum);
         type = datum.getVerticalDatumType();
     }
 
     /**
-     * Constructs a vertical datum from a set of properties. The properties map is given
-     * unchanged to the {@linkplain AbstractDatum#AbstractDatum(Map) super-class constructor}.
-     *
-     * @param properties Set of properties. Should contains at least {@code "name"}.
-     * @param type       The type of this vertical datum.
-     */
-    public DefaultVerticalDatum(final Map<String,?> properties, final VerticalDatumType type) {
-        super(properties);
-        this.type = type;
-        ensureNonNull("type", type);
-    }
-
-    /**
      * Returns a SIS datum implementation with the same values than the given arbitrary implementation.
      * If the given object is {@code null}, then this method returns {@code null}.
      * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
@@ -236,6 +233,8 @@ public class DefaultVerticalDatum extend
 
     /**
      * Computes a hash value consistent with the given comparison mode.
+     *
+     * @return The hash code value for the given comparison mode.
      */
     @Override
     public int hashCode(final ComparisonMode mode) throws IllegalArgumentException {
@@ -249,10 +248,10 @@ public class DefaultVerticalDatum extend
     }
 
     /**
-     * Formats the inner part of a Well Known Text</cite> (WKT) element.
+     * Formats the inner part of a <cite>Well Known Text</cite> (WKT) element.
      *
      * @param  formatter The formatter to use.
-     * @return The WKT element name, which is "VERT_DATUM"
+     * @return The WKT element name, which is {@code "VERT_DATUM"}.
      */
     @Override
     public String formatTo(final Formatter formatter) {

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/Sphere.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/Sphere.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/Sphere.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/Sphere.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -43,9 +43,9 @@ final class Sphere extends DefaultEllips
     private static final long serialVersionUID = 7867565381280669821L;
 
     /**
-     * Constructs a new sphere using the specified radius.
+     * Creates a new sphere using the specified radius.
      *
-     * @param properties    Set of properties. Should contains at least {@code "name"}.
+     * @param properties    The properties to be given to the identified object.
      * @param radius        The equatorial and polar radius.
      * @param ivfDefinitive {@code true} if the inverse flattening is definitive.
      * @param unit          The units of the radius value.

Modified: sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/GeneralMatrix.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/GeneralMatrix.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/GeneralMatrix.java [UTF-8] (original)
+++ sis/trunk/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/GeneralMatrix.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -20,7 +20,6 @@ import java.util.Arrays;
 import org.opengis.referencing.operation.Matrix;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.ArraysExt;
-import org.apache.sis.math.MathFunctions;
 import org.apache.sis.internal.util.DoubleDouble;
 
 
@@ -394,24 +393,33 @@ class GeneralMatrix extends MatrixSIS {
 
     /**
      * {@inheritDoc}
-     *
-     * <p>The current implementation discards the extended precision, if any.</p>
      */
     @Override
     public final void normalizeColumns() {
         final int numRow = this.numRow; // Protection against accidental changes.
         final int numCol = this.numCol;
-        final double[] column = new double[numRow];
+        final int errors = numRow * numCol; // Where error values start.
+        final double[] elt = getExtendedElements(this, numRow, numCol, false);
+        final DoubleDouble sum = new DoubleDouble();
+        final DoubleDouble dot = new DoubleDouble();
         for (int i=0; i<numCol; i++) {
+            sum.clear();
             for (int j=0; j<numRow; j++) {
-                column[j] = elements[j*numCol + i];
+                dot.setFrom(elt, j*numCol + i, errors);
+                dot.multiply(dot);
+                sum.add(dot);
             }
-            final double m = MathFunctions.magnitude(column);
+            sum.sqrt();
             for (int j=0; j<numRow; j++) {
-                elements[j*numCol + i] /= m;
+                final int k = j*numCol + i;
+                dot.setFrom(sum);
+                dot.inverseDivide(elt, k, errors);
+                dot.storeTo(elt, k, errors);
             }
         }
-        Arrays.fill(elements, numRow * numCol, elements.length, 0);
+        if (elt != elements) {
+            System.arraycopy(elt, 0, elements, 0, elements.length);
+        }
     }
 
     /**

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/Modules.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/Modules.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/Modules.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/Modules.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -24,7 +24,7 @@ package org.apache.sis.internal.system;
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
- * @version 0.3
+ * @version 0.4
  * @module
  */
 public final class Modules {
@@ -41,6 +41,11 @@ public final class Modules {
     /**
      * The {@value} module name.
      */
+    public static final String REFERENCING = "org.apache.sis.referencing";
+
+    /**
+     * The {@value} module name.
+     */
     public static final String STORAGE = "org.apache.sis.storage";
 
     /**

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/CollectionsExt.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/CollectionsExt.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/CollectionsExt.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/CollectionsExt.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -17,6 +17,7 @@
 package org.apache.sis.internal.util;
 
 import java.util.*;
+import java.lang.reflect.Array;
 import org.apache.sis.util.Static;
 import org.apache.sis.util.collection.CodeListSet;
 import org.apache.sis.util.resources.Errors;
@@ -92,16 +93,29 @@ public final class CollectionsExt extend
     }
 
     /**
+     * Returns the given array if non-empty, or {@code null} if the given array is null or empty.
+     * This method is generally not recommended, since public API should prefer empty array instead of null.
+     * However this method is occasionally useful for managing private fields.
+     *
+     * @param  <E> The type of elements in the array.
+     * @param  array The array, or {@code null}.
+     * @return The given array, or {@code null} if the given array was empty.
+     */
+    public static <E> E[] nonEmpty(final E[] array) {
+        return (array != null && array.length == 0) ? null : array;
+    }
+
+    /**
      * Returns the given collection if non-empty, or {@code null} if the given collection is null or empty.
-     * This method is generally not recommended, since public API should prefer empty collection instead of
-     * null. However it is occasionally useful for managing private fields, especially for inter-operability
+     * This method is generally not recommended, since public API should prefer empty collection instead of null.
+     * However this method is occasionally useful for managing private fields, especially for inter-operability
      * with frameworks that may expect or return null (e.g. if we want to exclude completely an empty collection
      * from marshalling with JAXB).
      *
      * @param  <T> The type of the collection.
      * @param  <E> The type of elements in the collection.
      * @param  c   The collection, or {@code null}.
-     * @return The given collection, or an empty set of the given collection was null.
+     * @return The given collection, or {@code null} if the given collection was empty.
      */
     public static <T extends Collection<E>, E> T nonEmpty(final T c) {
         return (c != null && c.isEmpty()) ? null : c;
@@ -112,7 +126,7 @@ public final class CollectionsExt extend
      *
      * @param  <E> The type of elements in the collection.
      * @param  c The collection, or {@code null}.
-     * @return The given collection, or an empty set of the given collection was null.
+     * @return The given collection, or an empty set if the given collection was null.
      */
     public static <E> Collection<E> nonNull(final Collection<E> c) {
         return (c != null) ? c : Collections.<E>emptySet();
@@ -123,13 +137,68 @@ public final class CollectionsExt extend
      *
      * @param  <E> The type of elements in the collection.
      * @param  c The collection, or {@code null}.
-     * @return The given collection, or an empty set of the given collection was null.
+     * @return The given collection, or an empty set if the given collection was null.
      */
     public static <E> Set<E> nonNull(final Set<E> c) {
         return (c != null) ? c : Collections.<E>emptySet();
     }
 
     /**
+     * Given a value which is either {@code null}, an instance of {@code <E>} or an array of {@code <E>},
+     * returns a non-null array containing all elements without null and without duplicated values.
+     * More specifically:
+     *
+     * <ul>
+     *   <li>If the given value is {@code null}, then this method returns {@code emptyArray}.</li>
+     *   <li>If the given value is an instance of {@code <E>}, then this method returns an array of length 1
+     *       which contain only {@code value}.</li>
+     *   <li>If the given value is an array of {@code <E>}, then this method returns copy of that array,
+     *       omitting {@code null} elements and duplicated elements.</li>
+     *   <li>Otherwise this method throws {@link IllegalArgumentException}.</li>
+     * </ul>
+     *
+     * {@note It would be very easy to add support for <code>value</code> argument of type <code>Object[]</code>
+     *        or collections. But we do not provide such support for now because this method is used mostly as a
+     *        helper method for constructors of <code>AbstractIdentifiedObject</code> subclasses receiving a map
+     *        of properties, and the contract of our constructors do not allow those other types for now.}
+     *
+     * @param  <E>        The type of elements in the array to be returned.
+     * @param  name       The parameter name, used only for formatting an error message in case of failure.
+     * @param  value      The value to return as an array, or {@code null}.
+     * @param  emptyArray An instance of {@code new E[0]}. This argument can not be null.
+     * @return The given value as an array of {@code <E>}. Never null.
+     * throws  IllegalArgumentException If the given value is not null, an instance of {@code <E>}
+     *         or an array of {@code <E>}.
+     *
+     * @since 0.4
+     */
+    @SuppressWarnings("unchecked")
+    public static <E> E[] nonNullArraySet(final String name, final Object value, final E[] emptyArray)
+            throws IllegalArgumentException
+    {
+        if (value == null) {
+            return emptyArray;
+        }
+        Class<?> type = emptyArray.getClass();
+        final Class<?> valueType = value.getClass();
+        if (valueType.isArray()) {
+            if (type.isAssignableFrom(valueType)) {
+                final Set<E> set = new LinkedHashSet<E>(Arrays.asList((E[]) value));
+                set.remove(null);
+                return set.toArray(emptyArray);
+            }
+        } else {
+            type = type.getComponentType();
+            if (type.isAssignableFrom(valueType)) {
+                final E[] array = (E[]) Array.newInstance(type, 1);
+                array[0] = (E) value;
+                return array;
+            }
+        }
+        throw new IllegalArgumentException(Errors.format(Errors.Keys.IllegalPropertyClass_2, name, valueType));
+    }
+
+    /**
      * Returns the specified array as an immutable set, or {@code null} if the array is null.
      * If the given array contains duplicated elements, i.e. elements that are equal in the
      * sense of {@link Object#equals(Object)}, then only the last instance of the duplicated

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleDouble.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleDouble.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleDouble.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleDouble.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -696,6 +696,16 @@ public final class DoubleDouble extends 
     }
 
     /**
+     * Sets this double-double value to its square root.
+     *
+     * @todo This method is not yet implemented with double-double precision.
+     */
+    public void sqrt() {
+        value = Math.sqrt(value);
+        error = 0;
+    }
+
+    /**
      * Returns a string representation of this number for debugging purpose.
      * The returned string does not need to contains all digits that this {@code DoubleDouble} can handle.
      *

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/LineAppender.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/LineAppender.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/LineAppender.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/LineAppender.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -59,7 +59,7 @@ import org.apache.sis.internal.jdk7.JDK7
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.00)
- * @version 0.3
+ * @version 0.4
  * @module
  */
 @Decorator(Appendable.class)
@@ -563,6 +563,7 @@ searchHyp:  for (int i=buffer.length(); 
     public void flush() throws IOException {
         out.append(buffer);
         buffer.setLength(0);
+        printableLength = 0;
         IO.flush(out);
     }
 

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -144,7 +144,7 @@ public enum FunctionProperty {
      *
      * @see #isBijective(Set)
      */
-    private static EnumSet<FunctionProperty> BIJECTIVE = EnumSet.of(INJECTIVE, SURJECTIVE);
+    private static final EnumSet<FunctionProperty> BIJECTIVE = EnumSet.of(INJECTIVE, SURJECTIVE);
 
     /**
      * Returns {@code true} if a function having the given set of properties is <cite>bijective</cite>.

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/math/MathFunctions.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -199,7 +199,8 @@ public final class MathFunctions extends
             dot.setToProduct(v1, v1);
             sum.add(dot);
         }
-        return Math.sqrt(sum.value);
+        sum.sqrt();
+        return sum.value;
     }
 
     /**

Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/CodeListSet.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/CodeListSet.java?rev=1534805&r1=1534804&r2=1534805&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/CodeListSet.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/CodeListSet.java [UTF-8] Tue Oct 22 21:36:49 2013
@@ -183,6 +183,8 @@ public class CodeListSet<E extends CodeL
 
     /**
      * Returns {@code true} if this set does not contains any element.
+     *
+     * @return {@code true} if this set is empty.
      */
     @Override
     public boolean isEmpty() {
@@ -522,7 +524,9 @@ public class CodeListSet<E extends CodeL
     }
 
     /**
-     * Returns a clone of this set.
+     * Returns a new set of the same class containing the same elements than this set.
+     *
+     * @return A clone of this set.
      */
     @Override
     @SuppressWarnings("unchecked")



Mime
View raw message