Author: desruisseaux
Date: Fri May 15 16:26:44 2015
New Revision: 1679601
URL: http://svn.apache.org/r1679601
Log:
Referencing: javadoc.
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjectFactory.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/AbstractDerivedCRS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultDerivedCRS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeocentricCRS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeographicCRS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultProjectedCRS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultEllipsoidalCS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultSphericalCS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultVerticalCS.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/crs/DefaultDerivedCRSTest.java
sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/XML.java
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjectFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjectFactory.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjectFactory.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticObjectFactory.java [UTF-8] Fri May 15 16:26:44 2015
@@ -24,6 +24,7 @@ import java.util.Collections;
import javax.measure.unit.Unit;
import javax.measure.quantity.Angle;
import javax.measure.quantity.Length;
+import javax.xml.bind.JAXBException;
import org.opengis.util.GenericName;
import org.opengis.util.FactoryException;
import org.opengis.util.InternationalString;
@@ -43,7 +44,9 @@ import org.apache.sis.internal.util.Abst
import org.apache.sis.internal.util.CollectionsExt;
import org.apache.sis.util.collection.WeakHashSet;
import org.apache.sis.util.iso.AbstractFactory;
+import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.xml.XML;
/**
@@ -176,13 +179,17 @@ import org.apache.sis.util.ArgumentCheck
*/
public class GeodeticObjectFactory extends AbstractFactory implements CRSFactory, CSFactory, DatumFactory {
/**
- * The default properties, or an empty map if none.
+ * The default properties, or an empty map if none. This map shall not change after construction in
+ * order to allow usage without synchronization in multi-thread context. But we do not need to wrap
+ * in a unmodifiable map since {@code GeodeticObjectFactory} does not provide public access to it.
*/
private final Map<String,?> defaultProperties;
/**
* The math transform factory. Will be created only when first needed.
* This is normally not needed by this factory, except when constructing derived and projected CRS.
+ *
+ * @see #getMathTransformFactory()
*/
private volatile MathTransformFactory mtFactory;
@@ -276,6 +283,9 @@ public class GeodeticObjectFactory exten
/**
* Returns the math transform factory for internal usage only.
+ * The {@code MathTransformFactory} is normally not needed by {@code GeodeticObjectFactory},
+ * except when constructing the Apache SIS implementation of derived and projected CRS.
+ * For this reason, we will fetch this dependency only if really requested.
*/
final MathTransformFactory getMathTransformFactory() {
MathTransformFactory factory = mtFactory;
@@ -287,14 +297,24 @@ public class GeodeticObjectFactory exten
/**
* Creates a geocentric coordinate reference system from a {@linkplain CartesianCS Cartesian coordinate system}.
+ * Geocentric CRS have their origin at the approximate centre of mass of the earth.
+ * An {@linkplain #createGeocentricCRS(Map, GeodeticDatum, SphericalCS) alternate method} allows creation of the
+ * same kind of CRS with spherical coordinate system instead than a Cartesian one.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createGeodeticDatum(Map, Ellipsoid, PrimeMeridian)}</li>
+ * <li>{@link #createCartesianCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultGeocentricCRS} instance.
*
* @param properties Name and other properties to give to the new object.
* @param datum The geodetic datum to use in created CRS.
- * @param cs The Cartesian coordinate system for the created CRS.
+ * @param cs The three-dimensional Cartesian coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultGeocentricCRS
+ * @see DefaultGeocentricCRS#DefaultGeocentricCRS(Map, GeodeticDatum, CartesianCS)
*/
@Override
public GeocentricCRS createGeocentricCRS(final Map<String,?> properties,
@@ -311,15 +331,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a three-dimensional Cartesian coordinate system from the given set of axis.
+ * This coordinate system can be used with geocentric, engineering and derived CRS.
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultCartesianCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Geocentric X”).
+ * @param axis1 The second axis (e.g. “Geocentric Y”).
+ * @param axis2 The third axis (e.g. “Geocentric Z”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultCartesianCS
+ * @see DefaultCartesianCS#DefaultCartesianCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public CartesianCS createCartesianCS(final Map<String,?> properties,
@@ -338,6 +365,16 @@ public class GeodeticObjectFactory exten
/**
* Creates a geocentric coordinate reference system from a {@linkplain SphericalCS spherical coordinate system}.
+ * Geocentric CRS have their origin at the approximate centre of mass of the earth.
+ * An {@linkplain #createGeocentricCRS(Map, GeodeticDatum, CartesianCS) alternate method} allows creation of the
+ * same kind of CRS with Cartesian coordinate system instead than a spherical one.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createGeodeticDatum(Map, Ellipsoid, PrimeMeridian)}</li>
+ * <li>{@link #createSphericalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultGeocentricCRS} instance.
*
* @param properties Name and other properties to give to the new object.
@@ -345,7 +382,7 @@ public class GeodeticObjectFactory exten
* @param cs The spherical coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultGeocentricCRS
+ * @see DefaultGeocentricCRS#DefaultGeocentricCRS(Map, GeodeticDatum, SphericalCS)
*/
@Override
public GeocentricCRS createGeocentricCRS(final Map<String,?> properties,
@@ -362,15 +399,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a spherical coordinate system from the given set of axis.
+ * This coordinate system can be used with geocentric, engineering and derived CRS.
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultSphericalCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Spherical latitude”).
+ * @param axis1 The second axis (e.g. “Spherical longitude”).
+ * @param axis2 The third axis (e.g. “Geocentric radius”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultSphericalCS
+ * @see DefaultSphericalCS#DefaultSphericalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public SphericalCS createSphericalCS(final Map<String,?> properties,
@@ -388,16 +432,23 @@ public class GeodeticObjectFactory exten
}
/**
- * Creates a geographic coordinate reference system.
- * It can be <var>latitude</var>/<var>longitude</var> or <var>longitude</var>/<var>latitude</var>.
+ * Creates a geographic coordinate reference system. It can be (<var>latitude</var>, <var>longitude</var>)
+ * or (<var>longitude</var>, <var>latitude</var>), optionally with an ellipsoidal height.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createGeodeticDatum(Map, Ellipsoid, PrimeMeridian)}</li>
+ * <li>{@link #createEllipsoidalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultGeographicCRS} instance.
*
* @param properties Name and other properties to give to the new object.
* @param datum Geodetic datum to use in created CRS.
- * @param cs The ellipsoidal coordinate system for the created CRS.
+ * @param cs The two- or three-dimensional ellipsoidal coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultGeographicCRS
+ * @see DefaultGeographicCRS#DefaultGeographicCRS(Map, GeodeticDatum, EllipsoidalCS)
*/
@Override
public GeographicCRS createGeographicCRS(final Map<String,?> properties,
@@ -414,6 +465,15 @@ public class GeodeticObjectFactory exten
/**
* Creates geodetic datum from ellipsoid and (optionally) Bursa-Wolf parameters.
+ * Geodetic datum defines the location and orientation of an ellipsoid that approximates the shape of the earth.
+ * This datum can be used with geographic, geocentric and engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createEllipsoid(Map, double, double, Unit)} or {@link #createFlattenedSphere(Map, double, double, Unit)}</li>
+ * <li>{@link #createPrimeMeridian(Map, double, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultGeodeticDatum} instance.
*
* @param properties Name and other properties to give to the new object.
@@ -421,7 +481,7 @@ public class GeodeticObjectFactory exten
* @param primeMeridian The prime meridian to use in new geodetic datum.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultGeodeticDatum
+ * @see DefaultGeodeticDatum#DefaultGeodeticDatum(Map, Ellipsoid, PrimeMeridian)
*/
@Override
public GeodeticDatum createGeodeticDatum(final Map<String,?> properties,
@@ -438,14 +498,16 @@ public class GeodeticObjectFactory exten
/**
* Creates a prime meridian, relative to Greenwich.
- * The default implementation creates a {@link DefaultPrimeMeridian} instance.
+ * Defines the origin from which longitude values are determined.
+ *
+ * <p>The default implementation creates a {@link DefaultPrimeMeridian} instance.</p>
*
* @param properties Name and other properties to give to the new object.
* @param longitude The longitude of prime meridian in supplied angular units East of Greenwich.
* @param angularUnit The angular units of longitude.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultPrimeMeridian
+ * @see DefaultPrimeMeridian#DefaultPrimeMeridian(Map, double, Unit)
*/
@Override
public PrimeMeridian createPrimeMeridian(final Map<String,?> properties,
@@ -462,14 +524,21 @@ public class GeodeticObjectFactory exten
/**
* Creates an ellipsoidal coordinate system without ellipsoidal height.
+ * It can be (<var>latitude</var>, <var>longitude</var>) or (<var>longitude</var>, <var>latitude</var>).
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultEllipsoidalCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis (e.g. “Geodetic latitude”).
+ * @param axis1 The second axis (e.g. “Geodetic longitude”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultEllipsoidalCS
+ * @see DefaultEllipsoidalCS#DefaultEllipsoidalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public EllipsoidalCS createEllipsoidalCS(final Map<String,?> properties,
@@ -487,15 +556,23 @@ public class GeodeticObjectFactory exten
/**
* Creates an ellipsoidal coordinate system with ellipsoidal height.
+ * It can be (<var>latitude</var>, <var>longitude</var>, <var>height</var>)
+ * or (<var>longitude</var>, <var>latitude</var>, <var>height</var>).
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultEllipsoidalCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Geodetic latitude”).
+ * @param axis1 The second axis (e.g. “Geodetic longitude”).
+ * @param axis2 The third axis (e.g. “Ellipsoidal height”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultEllipsoidalCS
+ * @see DefaultEllipsoidalCS#DefaultEllipsoidalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public EllipsoidalCS createEllipsoidalCS(final Map<String,?> properties,
@@ -566,23 +643,34 @@ public class GeodeticObjectFactory exten
/**
* Creates a projected coordinate reference system from a conversion.
- * The supplied conversion should <strong>not</strong> includes the operation steps for performing
- * {@linkplain AbstractCS#swapAndScaleAxis unit conversions and change of axis order} since those
- * operations will be inferred by this constructor.
+ * Projected CRS are used to approximate the shape of the earth on a planar surface in such a way
+ * that the distortion that is inherent to the approximation is controlled and known.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createGeographicCRS(Map, GeodeticDatum, EllipsoidalCS)}</li>
+ * <li>{@link org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)}</li>
+ * <li>{@link #createCartesianCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
+ * The supplied {@code conversion} argument shall <strong>not</strong> includes the operation steps
+ * for performing {@linkplain org.apache.sis.referencing.cs.CoordinateSystems#swapAndScaleAxes unit
+ * conversions and change of axis order} since those operations will be inferred by this constructor.
*
* <p>The default implementation creates a {@link DefaultProjectedCRS} instance.</p>
*
* @param properties Name and other properties to give to the new object.
* @param baseCRS The geographic coordinate reference system to base projection on.
- * @param conversion The defining conversion from a normalized base.
+ * @param conversion The defining conversion from a {@linkplain org.apache.sis.referencing.cs.AxesConvention#NORMALIZED
+ * normalized} base to a normalized derived CRS.
* @param derivedCS The coordinate system for the projected CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultProjectedCRS
+ * @see DefaultProjectedCRS#DefaultProjectedCRS(Map, GeographicCRS, Conversion, CartesianCS)
*/
@Override
public ProjectedCRS createProjectedCRS(final Map<String,?> properties,
- final GeographicCRS baseCRS, Conversion conversion,
+ final GeographicCRS baseCRS, final Conversion conversion,
final CartesianCS derivedCS) throws FactoryException
{
final ProjectedCRS crs;
@@ -596,14 +684,21 @@ public class GeodeticObjectFactory exten
/**
* Creates a two-dimensional Cartesian coordinate system from the given pair of axis.
+ * This coordinate system can be used with projected, engineering and derived CRS.
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultCartesianCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis (e.g. “Easting”).
+ * @param axis1 The second axis (e.g. “Northing”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultCartesianCS
+ * @see DefaultCartesianCS#DefaultCartesianCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public CartesianCS createCartesianCS(final Map<String,?> properties,
@@ -621,16 +716,31 @@ public class GeodeticObjectFactory exten
/**
* Creates a derived coordinate reference system from a conversion.
+ * The derived CRS returned by this method may also implement the {@link GeodeticCRS}, {@link VerticalCRS},
+ * {@link TemporalCRS} or {@link EngineeringCRS} interface depending on the type of the base CRS and the
+ * coordinate system.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>An other {@code createFooCRS(…)} method for geocentric, geographic, vertical, temporal or engineering CRS.</li>
+ * <li>{@link org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory#createDefiningConversion(Map, OperationMethod, ParameterValueGroup)}</li>
+ * <li>A {@code createFooCS(…)} method for Cartesian, spherical, ellipsoidal, vertical, temporal, linear, affine, polar, cylindrical or user-defined CS.</li>
+ * </ul>
+ *
+ * The supplied {@code conversion} argument shall <strong>not</strong> includes the operation steps
+ * for performing {@linkplain org.apache.sis.referencing.cs.CoordinateSystems#swapAndScaleAxes unit
+ * conversions and change of axis order} since those operations will be inferred by this constructor.
*
* <p>The default implementation creates a {@link DefaultDerivedCRS} instance.</p>
*
* @param properties Name and other properties to give to the new object.
- * @param baseCRS The coordinate reference system to base projection on.
- * @param conversion The defining conversion from a normalized base.
+ * @param baseCRS The coordinate reference system to base projection on. Shall be an instance of {@link SingleCRS}.
+ * @param conversion The defining conversion from a {@linkplain org.apache.sis.referencing.cs.AxesConvention#NORMALIZED
+ * normalized} base to a normalized derived CRS.
* @param derivedCS The coordinate system for the derived CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultDerivedCRS
+ * @see DefaultDerivedCRS#create(Map, SingleCRS, Conversion, CoordinateSystem)
*/
@Override
public DerivedCRS createDerivedCRS(final Map<String,?> properties,
@@ -649,6 +759,15 @@ public class GeodeticObjectFactory exten
/**
* Creates a vertical coordinate reference system.
+ * Vertical CRSs make use of the direction of gravity to define the concept of height or depth,
+ * but the relationship with gravity may not be straightforward.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createVerticalDatum(Map, VerticalDatumType)}</li>
+ * <li>{@link #createVerticalCS(Map, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultVerticalCRS} instance.
*
* @param properties Name and other properties to give to the new object.
@@ -656,7 +775,7 @@ public class GeodeticObjectFactory exten
* @param cs The vertical coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultVerticalCRS
+ * @see DefaultVerticalCRS#DefaultVerticalCRS(Map, VerticalDatum, VerticalCS)
*/
@Override
public VerticalCRS createVerticalCRS(final Map<String,?> properties,
@@ -679,7 +798,7 @@ public class GeodeticObjectFactory exten
* @param type The type of this vertical datum (often geoidal).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultVerticalDatum
+ * @see DefaultVerticalDatum#DefaultVerticalDatum(Map, VerticalDatumType)
*/
@Override
public VerticalDatum createVerticalDatum(final Map<String,?> properties,
@@ -696,13 +815,20 @@ public class GeodeticObjectFactory exten
/**
* Creates a vertical coordinate system.
+ * This coordinate system can be used with vertical and derived CRS.
+ *
+ * <p>The components needed by this method can be created by the following method:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultVerticalCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis The single axis.
+ * @param axis The single axis (e.g. “height” or “depth”).
* @throws FactoryException if the object creation failed.
*
- * @see DefaultVerticalCS
+ * @see DefaultVerticalCS#DefaultVerticalCS(Map, CoordinateSystemAxis)
*/
@Override
public VerticalCS createVerticalCS(final Map<String,?> properties,
@@ -719,6 +845,13 @@ public class GeodeticObjectFactory exten
/**
* Creates a temporal coordinate reference system.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createTemporalDatum(Map, Date)}</li>
+ * <li>{@link #createTimeCS(Map, CoordinateSystemAxis)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultTemporalCRS} instance.
*
* @param properties Name and other properties to give to the new object.
@@ -726,7 +859,7 @@ public class GeodeticObjectFactory exten
* @param cs The temporal coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultTemporalCRS
+ * @see DefaultTemporalCRS#DefaultTemporalCRS(Map, TemporalDatum, TimeCS)
*/
@Override
public TemporalCRS createTemporalCRS(final Map<String,?> properties,
@@ -749,7 +882,7 @@ public class GeodeticObjectFactory exten
* @param origin The date and time origin of this temporal datum.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultTemporalDatum
+ * @see DefaultTemporalDatum#DefaultTemporalDatum(Map, Date)
*/
@Override
public TemporalDatum createTemporalDatum(final Map<String,?> properties,
@@ -766,13 +899,20 @@ public class GeodeticObjectFactory exten
/**
* Creates a temporal coordinate system.
+ * This coordinate system can be used with temporal and derived CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultTimeCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis The single axis.
+ * @param axis The single axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultTimeCS
+ * @see DefaultTimeCS#DefaultTimeCS(Map, CoordinateSystemAxis)
*/
@Override
public TimeCS createTimeCS(final Map<String,?> properties,
@@ -789,13 +929,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a compound coordinate reference system from an ordered list of {@code CoordinateReferenceSystem} objects.
+ * Apache SIS puts no restriction on the components that can be used in a compound CRS.
+ * However for better inter-operability, users are encouraged to follow the order mandated by ISO 19162:
+ *
+ * <ul>
+ * <li>A mandatory horizontal CRS (only one of two-dimensional {@code GeographicCRS} or {@code ProjectedCRS} or {@code EngineeringCRS}).</li>
+ * <li>Optionally followed by a {@code VerticalCRS} or a {@code ParametricCRS} (but not both).</li>
+ * <li>Optionally followed by a {@code TemporalCRS}.</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultCompoundCRS} instance.
*
* @param properties Name and other properties to give to the new object.
* @param elements Ordered array of {@code CoordinateReferenceSystem} objects.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultCompoundCRS
+ * @see DefaultCompoundCRS#DefaultCompoundCRS(Map, CoordinateReferenceSystem...)
*/
@Override
public CompoundCRS createCompoundCRS(final Map<String,?> properties,
@@ -819,7 +968,7 @@ public class GeodeticObjectFactory exten
* @param cs The Cartesian or oblique Cartesian coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultImageCRS
+ * @see DefaultImageCRS#DefaultImageCRS(Map, ImageDatum, AffineCS)
*/
@Override
public ImageCRS createImageCRS(final Map<String,?> properties,
@@ -842,7 +991,7 @@ public class GeodeticObjectFactory exten
* @param pixelInCell Specification of the way the image grid is associated with the image data attributes.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultImageDatum
+ * @see DefaultImageDatum#DefaultImageDatum(Map, PixelInCell)
*/
@Override
public ImageDatum createImageDatum(final Map<String,?> properties,
@@ -859,14 +1008,21 @@ public class GeodeticObjectFactory exten
/**
* Creates a two-dimensional affine coordinate system from the given pair of axis.
+ * This coordinate system can be used with image and engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultAffineCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultAffineCS
+ * @see DefaultAffineCS#DefaultAffineCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public AffineCS createAffineCS(final Map<String,?> properties,
@@ -884,6 +1040,19 @@ public class GeodeticObjectFactory exten
/**
* Creates a engineering coordinate reference system.
+ * Engineering CRS can be divided into two broad categories:
+ *
+ * <ul>
+ * <li>earth-fixed systems applied to engineering activities on or near the surface of the earth;</li>
+ * <li>CRSs on moving platforms such as road vehicles, vessels, aircraft, or spacecraft.</li>
+ * </ul>
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createEngineeringDatum(Map)}</li>
+ * <li>A {@code createFooCS(…)} method for Cartesian, spherical, linear, affine, polar, cylindrical or user-defined CS.</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultEngineeringCRS} instance.
*
* @param properties Name and other properties to give to the new object.
@@ -891,7 +1060,7 @@ public class GeodeticObjectFactory exten
* @param cs The coordinate system for the created CRS.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultEngineeringCRS
+ * @see DefaultEngineeringCRS#DefaultEngineeringCRS(Map, EngineeringDatum, CoordinateSystem)
*/
@Override
public EngineeringCRS createEngineeringCRS(final Map<String,?> properties,
@@ -913,7 +1082,7 @@ public class GeodeticObjectFactory exten
* @param properties Name and other properties to give to the new object.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultEngineeringDatum
+ * @see DefaultEngineeringDatum#DefaultEngineeringDatum(Map)
*/
@Override
public EngineeringDatum createEngineeringDatum(final Map<String,?> properties)
@@ -930,15 +1099,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a three-dimensional affine coordinate system from the given set of axis.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultAffineCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
+ * @param axis2 The third axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultAffineCS
+ * @see DefaultAffineCS#DefaultAffineCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public AffineCS createAffineCS(final Map<String,?> properties,
@@ -957,15 +1133,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a cylindrical coordinate system from the given set of axis.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultCylindricalCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
+ * @param axis2 The third axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultCylindricalCS
+ * @see DefaultCylindricalCS#DefaultCylindricalCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public CylindricalCS createCylindricalCS(final Map<String,?> properties,
@@ -984,14 +1167,21 @@ public class GeodeticObjectFactory exten
/**
* Creates a polar coordinate system from the given pair of axis.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultPolarCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultPolarCS
+ * @see DefaultPolarCS#DefaultPolarCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public PolarCS createPolarCS(final Map<String,?> properties,
@@ -1009,13 +1199,20 @@ public class GeodeticObjectFactory exten
/**
* Creates a linear coordinate system.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultLinearCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis The single axis.
+ * @param axis The single axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultLinearCS
+ * @see DefaultLinearCS#DefaultLinearCS(Map, CoordinateSystemAxis)
*/
@Override
public LinearCS createLinearCS(final Map<String,?> properties,
@@ -1032,14 +1229,21 @@ public class GeodeticObjectFactory exten
/**
* Creates a two-dimensional user defined coordinate system from the given pair of axis.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultUserDefinedCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultUserDefinedCS
+ * @see DefaultUserDefinedCS#DefaultUserDefinedCS(Map, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public UserDefinedCS createUserDefinedCS(final Map<String,?> properties,
@@ -1057,15 +1261,22 @@ public class GeodeticObjectFactory exten
/**
* Creates a three-dimensional user defined coordinate system from the given set of axis.
+ * This coordinate system can be used with engineering CRS.
+ *
+ * <p>The components needed by this method can be created by the following methods:</p>
+ * <ul>
+ * <li>{@link #createCoordinateSystemAxis(Map, String, AxisDirection, Unit)}</li>
+ * </ul>
+ *
* The default implementation creates a {@link DefaultUserDefinedCS} instance.
*
* @param properties Name and other properties to give to the new object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis.
+ * @param axis1 The second axis.
+ * @param axis2 The third axis.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultUserDefinedCS
+ * @see DefaultUserDefinedCS#DefaultUserDefinedCS(Map, CoordinateSystemAxis, CoordinateSystemAxis, CoordinateSystemAxis)
*/
@Override
public UserDefinedCS createUserDefinedCS(final Map<String,?> properties,
@@ -1084,7 +1295,10 @@ public class GeodeticObjectFactory exten
/**
* Creates a coordinate system axis from an abbreviation and a unit.
- * The default implementation creates a {@link DefaultCoordinateSystemAxis} instance.
+ * Note that the axis name is constrained by ISO 19111 depending on the coordinate reference system type.
+ * See the GeoAPI {@link CoordinateSystemAxis} javadoc for more information.
+ *
+ * <p>The default implementation creates a {@link DefaultCoordinateSystemAxis} instance.</p>
*
* @param properties Name and other properties to give to the new object.
* @param abbreviation The coordinate axis abbreviation.
@@ -1092,7 +1306,7 @@ public class GeodeticObjectFactory exten
* @param unit The coordinate axis unit.
* @throws FactoryException if the object creation failed.
*
- * @see DefaultCoordinateSystemAxis
+ * @see DefaultCoordinateSystemAxis#DefaultCoordinateSystemAxis(Map, String, AxisDirection, Unit)
*/
@Override
public CoordinateSystemAxis createCoordinateSystemAxis(final Map<String,?> properties,
@@ -1110,15 +1324,28 @@ public class GeodeticObjectFactory exten
/**
* Creates a coordinate reference system object from a XML string.
+ * Note that the given argument is the XML document itself,
+ * <strong>not</strong> a URL to a XML document.
+ *
+ * <p>The default implementation delegates to {@link XML#unmarshal(String)}</p>
*
* @param xml Coordinate reference system encoded in XML format.
* @throws FactoryException if the object creation failed.
- *
- * @todo Not yet implemented.
*/
@Override
public CoordinateReferenceSystem createFromXML(final String xml) throws FactoryException {
- throw new FactoryException("Not yet implemented");
+ final Object object;
+ try {
+ object = XML.unmarshal(xml);
+ } catch (JAXBException e) {
+ throw new FactoryException(e);
+ }
+ if (object instanceof CoordinateReferenceSystem) {
+ return (CoordinateReferenceSystem) object;
+ } else {
+ throw new FactoryException(Errors.format(Errors.Keys.IllegalClass_2,
+ CoordinateReferenceSystem.class, object.getClass()));
+ }
}
/**
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/AbstractDerivedCRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/AbstractDerivedCRS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/AbstractDerivedCRS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/AbstractDerivedCRS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -87,7 +87,7 @@ abstract class AbstractDerivedCRS<C exte
*
* @param properties The properties to be given to the new derived CRS object.
* @param baseCRS Coordinate reference system to base the derived CRS on.
- * @param conversion The conversion from the base CRS to this derived CRS.
+ * @param conversion The defining conversion from a normalized base to a normalized derived CRS.
* @param derivedCS The coordinate system for the derived CRS. The number of axes
* must match the target dimension of the {@code baseToDerived} transform.
* @throws MismatchedDimensionException if the source and target dimension of {@code baseToDerived}
@@ -101,7 +101,7 @@ abstract class AbstractDerivedCRS<C exte
{
super(properties, derivedCS);
ArgumentChecks.ensureNonNull("baseCRS", baseCRS);
- ArgumentChecks.ensureNonNull("conversionFromBase", conversion); // "conversionFromBase" is the name used by subclass constructors.
+ ArgumentChecks.ensureNonNull("conversion", conversion);
final MathTransform baseToDerived = conversion.getMathTransform();
if (baseToDerived != null) {
ArgumentChecks.ensureDimensionMatches("baseCRS", baseToDerived.getSourceDimensions(), baseCRS);
@@ -145,7 +145,7 @@ abstract class AbstractDerivedCRS<C exte
return DefaultConversion.castOrCopy(conversion).specialize(getConversionType(), baseCRS, this, factory);
} catch (FactoryException e) {
throw new IllegalArgumentException(Errors.getResources(properties).getString(
- Errors.Keys.IllegalArgumentValue_2, "conversionFromBase", conversion.getName()), e);
+ Errors.Keys.IllegalArgumentValue_2, "conversion", conversion.getName()), e);
}
}
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultDerivedCRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultDerivedCRS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultDerivedCRS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultDerivedCRS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -144,10 +144,15 @@ public class DefaultDerivedCRS extends A
* </tr>
* </table>
*
+ * The supplied {@code conversion} argument shall <strong>not</strong> includes the operation steps
+ * for performing {@linkplain org.apache.sis.referencing.cs.CoordinateSystems#swapAndScaleAxes unit
+ * conversions and change of axis order} since those operations will be inferred by this constructor.
+ *
* @param properties The properties to be given to the new derived CRS object.
- * @param baseCRS Coordinate reference system to base the derived CRS on.
- * @param conversionFromBase The conversion from the base CRS to this derived CRS.
- * @param derivedCS The coordinate system for the derived CRS. The number of axes
+ * @param baseCRS Coordinate reference system to base the derived CRS on.
+ * @param conversion The defining conversion from a {@linkplain AxesConvention#NORMALIZED normalized} base
+ * to a normalized derived CRS.
+ * @param derivedCS The coordinate system for the derived CRS. The number of axes
* must match the target dimension of the {@code baseToDerived} transform.
* @throws MismatchedDimensionException if the source and target dimension of {@code baseToDerived}
* do not match the dimension of {@code base} and {@code derivedCS} respectively.
@@ -156,11 +161,11 @@ public class DefaultDerivedCRS extends A
*/
protected DefaultDerivedCRS(final Map<String,?> properties,
final SingleCRS baseCRS,
- final Conversion conversionFromBase,
+ final Conversion conversion,
final CoordinateSystem derivedCS)
throws MismatchedDimensionException
{
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ super(properties, baseCRS, conversion, derivedCS);
}
/**
@@ -187,9 +192,9 @@ public class DefaultDerivedCRS extends A
* See the class javadoc for more information.
*
* @param properties The properties to be given to the new derived CRS object.
- * @param baseCRS Coordinate reference system to base the derived CRS on.
- * @param conversionFromBase The conversion from the base CRS to this derived CRS.
- * @param derivedCS The coordinate system for the derived CRS. The number of axes
+ * @param baseCRS Coordinate reference system to base the derived CRS on.
+ * @param conversion The defining conversion from a normalized base to a normalized derived CRS.
+ * @param derivedCS The coordinate system for the derived CRS. The number of axes
* must match the target dimension of the {@code baseToDerived} transform.
* @return The newly created derived CRS, potentially implementing an additional CRS interface.
* @throws MismatchedDimensionException if the source and target dimension of {@code baseToDerived}
@@ -199,19 +204,19 @@ public class DefaultDerivedCRS extends A
*/
public static DefaultDerivedCRS create(final Map<String,?> properties,
final SingleCRS baseCRS,
- final Conversion conversionFromBase,
+ final Conversion conversion,
final CoordinateSystem derivedCS)
throws MismatchedDimensionException
{
if (baseCRS != null && derivedCS != null) {
switch (getType(baseCRS, derivedCS)) {
- case WKTKeywords.GeodeticCRS: return new Geodetic (properties, (GeodeticCRS) baseCRS, conversionFromBase, (EllipsoidalCS) derivedCS);
- case WKTKeywords.VerticalCRS: return new Vertical (properties, (VerticalCRS) baseCRS, conversionFromBase, (VerticalCS) derivedCS);
- case WKTKeywords.TimeCRS: return new Temporal (properties, (TemporalCRS) baseCRS, conversionFromBase, (TimeCS) derivedCS);
- case WKTKeywords.EngineeringCRS: return new Engineering(properties, baseCRS, conversionFromBase, derivedCS);
+ case WKTKeywords.GeodeticCRS: return new Geodetic (properties, (GeodeticCRS) baseCRS, conversion, (EllipsoidalCS) derivedCS);
+ case WKTKeywords.VerticalCRS: return new Vertical (properties, (VerticalCRS) baseCRS, conversion, (VerticalCS) derivedCS);
+ case WKTKeywords.TimeCRS: return new Temporal (properties, (TemporalCRS) baseCRS, conversion, (TimeCS) derivedCS);
+ case WKTKeywords.EngineeringCRS: return new Engineering(properties, baseCRS, conversion, derivedCS);
}
}
- return new DefaultDerivedCRS(properties, baseCRS, conversionFromBase, derivedCS);
+ return new DefaultDerivedCRS(properties, baseCRS, conversion, derivedCS);
}
/**
@@ -472,8 +477,8 @@ public class DefaultDerivedCRS extends A
}
/** Creates a new geodetic CRS derived from the given one. */
- Geodetic(Map<String,?> properties, GeodeticCRS baseCRS, Conversion conversionFromBase, EllipsoidalCS derivedCS) {
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ Geodetic(Map<String,?> properties, GeodeticCRS baseCRS, Conversion conversion, EllipsoidalCS derivedCS) {
+ super(properties, baseCRS, conversion, derivedCS);
}
/** Returns the datum of the base geodetic CRS. */
@@ -513,8 +518,8 @@ public class DefaultDerivedCRS extends A
}
/** Creates a new vertical CRS derived from the given one. */
- Vertical(Map<String,?> properties, VerticalCRS baseCRS, Conversion conversionFromBase, VerticalCS derivedCS) {
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ Vertical(Map<String,?> properties, VerticalCRS baseCRS, Conversion conversion, VerticalCS derivedCS) {
+ super(properties, baseCRS, conversion, derivedCS);
}
/** Returns the datum of the base vertical CRS. */
@@ -554,8 +559,8 @@ public class DefaultDerivedCRS extends A
}
/** Creates a new temporal CRS derived from the given one. */
- Temporal(Map<String,?> properties, TemporalCRS baseCRS, Conversion conversionFromBase, TimeCS derivedCS) {
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ Temporal(Map<String,?> properties, TemporalCRS baseCRS, Conversion conversion, TimeCS derivedCS) {
+ super(properties, baseCRS, conversion, derivedCS);
}
/** Returns the datum of the base temporal CRS. */
@@ -598,8 +603,8 @@ public class DefaultDerivedCRS extends A
}
/** Creates a new temporal CRS derived from the given one. */
- Engineering(Map<String,?> properties, SingleCRS baseCRS, Conversion conversionFromBase, CoordinateSystem derivedCS) {
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ Engineering(Map<String,?> properties, SingleCRS baseCRS, Conversion conversion, CoordinateSystem derivedCS) {
+ super(properties, baseCRS, conversion, derivedCS);
}
/** Returns the datum of the base engineering CRS. */
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeocentricCRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeocentricCRS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeocentricCRS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeocentricCRS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -38,6 +38,29 @@ import org.apache.sis.referencing.Abstra
* {@linkplain org.apache.sis.referencing.cs.DefaultSphericalCS Spherical}.
* </p>
*
+ * <div class="section">Creating new geocentric CRS instances</div>
+ * 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 geocentric CRS.
+ * The other choices provide more freedom.
+ *
+ * <ol>
+ * <li>Create a {@code GeocentricCRS} from one of the static convenience shortcuts listed in
+ * {@link org.apache.sis.referencing.CommonCRS#geocentric()}.</li>
+ * <li>Create a {@code GeocentricCRS} from an identifier in a database by invoking
+ * {@link org.opengis.referencing.crs.CRSAuthorityFactory#createGeocentricCRS(String)}.</li>
+ * <li>Create a {@code GeocentricCRS} by invoking the {@code CRSFactory.createGeocentricCRS(…)} method
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
+ * <li>Create a {@code GeocentricCRS} by invoking the
+ * {@link #DefaultGeocentricCRS(Map, GeodeticDatum, CartesianCS) constructor}.</li>
+ * </ol>
+ *
+ * <b>Example:</b> the following code gets a geocentric CRS using the <cite>World Geodetic System 1984</cite> datum:
+ *
+ * {@preformat java
+ * GeodeticDatum datum = CommonCRS.WGS84.geocentric();
+ * }
+ *
* <div class="section">Immutability and thread safety</div>
* This class is immutable and thus thread-safe if the property <em>values</em> (not necessarily the map itself),
* the coordinate system and the datum instances given to the constructor are also immutable. Unless otherwise noted
@@ -121,7 +144,7 @@ public class DefaultGeocentricCRS extend
*
* @param properties The properties to be given to the coordinate reference system.
* @param datum The datum.
- * @param cs The coordinate system.
+ * @param cs The coordinate system, which must be three-dimensional.
*/
public DefaultGeocentricCRS(final Map<String,?> properties,
final GeodeticDatum datum,
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeographicCRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeographicCRS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeographicCRS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultGeographicCRS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -51,6 +51,31 @@ import static org.apache.sis.internal.ut
* {@linkplain org.apache.sis.referencing.cs.DefaultEllipsoidalCS Ellipsoidal}.
* </p>
*
+ * <div class="section">Creating new geographic CRS instances</div>
+ * 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 geographic CRS.
+ * The other choices provide more freedom.
+ *
+ * <ol>
+ * <li>Create a {@code GeographicCRS} from one of the static convenience shortcuts listed in
+ * {@link org.apache.sis.referencing.CommonCRS#geographic()} or
+ * {@link org.apache.sis.referencing.CommonCRS#geographic3D()}.</li>
+ * <li>Create a {@code GeographicCRS} from an identifier in a database by invoking
+ * {@link org.opengis.referencing.crs.CRSAuthorityFactory#createGeographicCRS(String)}.</li>
+ * <li>Create a {@code GeographicCRS} by invoking the {@code CRSFactory.createGeographicCRS(…)} method
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
+ * <li>Create a {@code GeographicCRS} by invoking the
+ * {@link #DefaultGeographicCRS(Map, GeodeticDatum, EllipsoidalCS) constructor}.</li>
+ * </ol>
+ *
+ * <b>Example:</b> the following code gets a two-dimensional geographic CRS
+ * using the <cite>World Geodetic System 1984</cite> datum:
+ *
+ * {@preformat java
+ * GeodeticDatum datum = CommonCRS.WGS84.geographic();
+ * }
+ *
* <div class="section">Immutability and thread safety</div>
* This class is immutable and thus thread-safe if the property <em>values</em> (not necessarily the map itself),
* the coordinate system and the datum instances given to the constructor are also immutable. Unless otherwise noted
@@ -133,7 +158,7 @@ public class DefaultGeographicCRS extend
*
* @param properties The properties to be given to the coordinate reference system.
* @param datum The datum.
- * @param cs The coordinate system.
+ * @param cs The two- or three-dimensional coordinate system.
*/
public DefaultGeographicCRS(final Map<String,?> properties,
final GeodeticDatum datum,
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultProjectedCRS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultProjectedCRS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultProjectedCRS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/crs/DefaultProjectedCRS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -135,21 +135,26 @@ public class DefaultProjectedCRS extends
* </tr>
* </table>
*
+ * The supplied {@code conversion} argument shall <strong>not</strong> includes the operation steps
+ * for performing {@linkplain org.apache.sis.referencing.cs.CoordinateSystems#swapAndScaleAxes unit
+ * conversions and change of axis order} since those operations will be inferred by this constructor.
+ *
* @param properties The properties to be given to the new derived CRS object.
- * @param baseCRS Coordinate reference system to base the derived CRS on.
- * @param conversionFromBase The conversion from the base CRS to this derived CRS.
- * @param derivedCS The coordinate system for the derived CRS. The number of axes
+ * @param baseCRS Coordinate reference system to base the derived CRS on.
+ * @param conversion The defining conversion from a {@linkplain AxesConvention#NORMALIZED normalized} base
+ * to a normalized derived CRS.
+ * @param derivedCS The coordinate system for the derived CRS. The number of axes
* must match the target dimension of the {@code baseToDerived} transform.
* @throws MismatchedDimensionException if the source and target dimension of {@code baseToDerived}
* do not match the dimension of {@code base} and {@code derivedCS} respectively.
*/
public DefaultProjectedCRS(final Map<String,?> properties,
final GeographicCRS baseCRS,
- final Conversion conversionFromBase,
+ final Conversion conversion,
final CartesianCS derivedCS)
throws MismatchedDimensionException
{
- super(properties, baseCRS, conversionFromBase, derivedCS);
+ super(properties, baseCRS, conversion, derivedCS);
}
/**
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultCartesianCS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -121,8 +121,8 @@ public class DefaultCartesianCS extends
* </table>
*
* @param properties The properties to be given to the identified object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis (e.g. “Easting”).
+ * @param axis1 The second axis (e.g. “Northing”).
*/
public DefaultCartesianCS(final Map<String,?> properties,
final CoordinateSystemAxis axis0,
@@ -138,9 +138,9 @@ public class DefaultCartesianCS extends
* {@linkplain AbstractCS#AbstractCS(Map,CoordinateSystemAxis[]) super-class constructor}.
*
* @param properties The properties to be given to the identified object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Geocentric X”).
+ * @param axis1 The second axis (e.g. “Geocentric Y”).
+ * @param axis2 The third axis (e.g. “Geocentric Z”).
*/
public DefaultCartesianCS(final Map<String,?> properties,
final CoordinateSystemAxis axis0,
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultEllipsoidalCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultEllipsoidalCS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultEllipsoidalCS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultEllipsoidalCS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -113,8 +113,8 @@ public class DefaultEllipsoidalCS extend
* </table>
*
* @param properties The properties to be given to the identified object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
+ * @param axis0 The first axis (e.g. “Geodetic latitude”).
+ * @param axis1 The second axis (e.g. “Geodetic longitude”).
*/
public DefaultEllipsoidalCS(final Map<String,?> properties,
final CoordinateSystemAxis axis0,
@@ -136,9 +136,9 @@ public class DefaultEllipsoidalCS extend
* {@linkplain AbstractCS#AbstractCS(Map,CoordinateSystemAxis[]) super-class constructor}.
*
* @param properties The properties to be given to the identified object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Geodetic latitude”).
+ * @param axis1 The second axis (e.g. “Geodetic longitude”).
+ * @param axis2 The third axis (e.g. “Ellipsoidal height”).
*/
public DefaultEllipsoidalCS(final Map<String,?> properties,
final CoordinateSystemAxis axis0,
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultSphericalCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultSphericalCS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultSphericalCS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultSphericalCS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -117,9 +117,9 @@ public class DefaultSphericalCS extends
* </table>
*
* @param properties The properties to be given to the identified object.
- * @param axis0 The first axis.
- * @param axis1 The second axis.
- * @param axis2 The third axis.
+ * @param axis0 The first axis (e.g. “Spherical latitude”).
+ * @param axis1 The second axis (e.g. “Spherical longitude”).
+ * @param axis2 The third axis (e.g. “Geocentric radius”).
*/
public DefaultSphericalCS(final Map<String,?> properties,
final CoordinateSystemAxis axis0,
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultVerticalCS.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultVerticalCS.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultVerticalCS.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/cs/DefaultVerticalCS.java [UTF-8] Fri May 15 16:26:44 2015
@@ -126,7 +126,7 @@ public class DefaultVerticalCS extends A
* </table>
*
* @param properties The properties to be given to the identified object.
- * @param axis The axis.
+ * @param axis The single axis (e.g. “height” or “depth”).
*/
public DefaultVerticalCS(final Map<String,?> properties, final CoordinateSystemAxis axis) {
super(properties, axis);
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultEllipsoid.java [UTF-8] Fri May 15 16:26:44 2015
@@ -91,8 +91,8 @@ import java.util.Objects;
* {@link org.apache.sis.referencing.CommonCRS#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 an {@code Ellipsoid} by invoking the {@code DatumFactory.createEllipsoid(…)} or {@code createFlattenedSphere(…)}
+ * method (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
* <li>Create a {@code DefaultEllipsoid} by invoking the
* {@link #createEllipsoid(Map, double, double, Unit) createEllipsoid(…)} or
* {@link #createFlattenedSphere(Map, double, double, Unit) createFlattenedSphere(…)}
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultGeodeticDatum.java [UTF-8] Fri May 15 16:26:44 2015
@@ -99,8 +99,8 @@ import java.util.Objects;
* {@link org.apache.sis.referencing.CommonCRS#datum()}.</li>
* <li>Create a {@code GeodeticDatum} from an identifier in a database by invoking
* {@link org.opengis.referencing.datum.DatumAuthorityFactory#createGeodeticDatum(String)}.</li>
- * <li>Create a {@code GeodeticDatum} by invoking the {@code createGeodeticDatum(…)}
- * method defined in the {@link org.opengis.referencing.datum.DatumFactory} interface.</li>
+ * <li>Create a {@code GeodeticDatum} by invoking the {@code DatumFactory.createGeodeticDatum(…)} method
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
* <li>Create a {@code DefaultGeodeticDatum} by invoking the
* {@link #DefaultGeodeticDatum(Map, Ellipsoid, PrimeMeridian) constructor}.</li>
* </ol>
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultPrimeMeridian.java [UTF-8] Fri May 15 16:26:44 2015
@@ -61,8 +61,8 @@ import java.util.Objects;
* {@link org.apache.sis.referencing.CommonCRS#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 PrimeMeridian} by invoking the {@code DatumFactory.createPrimeMeridian(…)} method
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
* <li>Create a {@code DefaultPrimeMeridian} by invoking the
* {@linkplain #DefaultPrimeMeridian(Map, double, Unit) constructor}.</li>
* </ol>
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultTemporalDatum.java [UTF-8] Fri May 15 16:26:44 2015
@@ -54,8 +54,8 @@ import java.util.Objects;
* {@link org.apache.sis.referencing.CommonCRS.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 TemporalDatum} by invoking the {@code DatumFactory.createTemporalDatum(…)} method,
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
* <li>Create a {@code DefaultTemporalDatum} by invoking the
* {@linkplain #DefaultTemporalDatum(Map, Date) constructor}.</li>
* </ol>
Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/datum/DefaultVerticalDatum.java [UTF-8] Fri May 15 16:26:44 2015
@@ -56,8 +56,8 @@ import java.util.Objects;
* {@link org.apache.sis.referencing.CommonCRS.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 VerticalDatum} by invoking the {@code DatumFactory.createVerticalDatum(…)} method
+ * (implemented for example by {@link org.apache.sis.referencing.GeodeticObjectFactory}).</li>
* <li>Create a {@code DefaultVerticalDatum} by invoking the
* {@linkplain #DefaultVerticalDatum(Map, VerticalDatumType) constructor}.</li>
* </ol>
Modified: sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/crs/DefaultDerivedCRSTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/crs/DefaultDerivedCRSTest.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/crs/DefaultDerivedCRSTest.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/crs/DefaultDerivedCRSTest.java [UTF-8] Fri May 15 16:26:44 2015
@@ -125,6 +125,12 @@ public final strictfp class DefaultDeriv
/**
* Tests the WKT 1 formatting.
* Note that in the particular case of {@code DerivedCRS}, WKT 1 and WKT 2 formats are very different.
+ *
+ * <div class="note"><b>Note:</b>
+ * The CRS formatted by this test is a dummy CRS which should not exist in the reality.
+ * In particular, we use <cite>"Longitude rotation"</cite> (EPSG:9601) as if it was a conversion,
+ * while in reality it is a transformation. We do that only because this operation is so simple,
+ * it is easy to create and test.</div>
*/
@Test
@DependsOnMethod("testConstruction")
@@ -150,6 +156,12 @@ public final strictfp class DefaultDeriv
/**
* Tests the WKT 2 formatting.
* Note that in the particular case of {@code DerivedCRS}, WKT 1 and WKT 2 formats are very different.
+ *
+ * <div class="note"><b>Note:</b>
+ * The CRS formatted by this test is a dummy CRS which should not exist in the reality.
+ * In particular, we use <cite>"Longitude rotation"</cite> (EPSG:9601) as if it was a conversion,
+ * while in reality it is a transformation. We do that only because this operation is so simple,
+ * it is easy to create and test.</div>
*/
@Test
@DependsOnMethod("testWKT1")
Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/XML.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/XML.java?rev=1679601&r1=1679600&r2=1679601&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/XML.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/XML.java [UTF-8] Fri May 15 16:26:44 2015
@@ -423,14 +423,16 @@ public final class XML extends Static {
/**
* Unmarshall an object from the given string.
+ * Note that the given argument is the XML document itself,
+ * <strong>not</strong> a URL to a XML document.
*
- * @param input The XML representation of an object.
+ * @param xml The XML representation of an object.
* @return The object unmarshalled from the given input.
* @throws JAXBException If an error occurred during the unmarshalling.
*/
- public static Object unmarshal(final String input) throws JAXBException {
- ensureNonNull("input", input);
- final StringReader in = new StringReader(input);
+ public static Object unmarshal(final String xml) throws JAXBException {
+ ensureNonNull("input", xml);
+ final StringReader in = new StringReader(xml);
final MarshallerPool pool = getPool();
final Unmarshaller unmarshaller = pool.acquireUnmarshaller();
final Object object = unmarshaller.unmarshal(in);
|