Author: desruisseaux
Date: Mon Feb 16 21:06:54 2015
New Revision: 1660202
URL: http://svn.apache.org/r1660202
Log:
Documentation editions.
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -36,9 +36,8 @@
* More on this convention is explained below.</p>
*
* <p>Users wanting to know more about the available projections and their
parameters should look at the
- * <a href="http://sis.apache.org/CoordinateOperationMethods.html";>Coordinate
Operation Methods</a> page.
- * Only users interested in the <em>implementation</em> or parameters of those
projections should look at
- * this package.</p>
+ * <a href="http://sis.apache.org/CoordinateOperationMethods.html";>list of
coordinate operation methods</a>.
+ * Only users interested in the <em>implementation</em> of those projections
should look at this package.</p>
*
*
* {@section Definition of terms}
@@ -93,7 +92,7 @@
* where the other steps change units and swap ordinates.
* </blockquote>
*
- * The Geotk implementation extends this rule to axis directions as well, i.e.
(<var>x</var>, <var>y</var>) coordinates
+ * The Apache SIS implementation extends this rule to axis directions as well,
i.e. (<var>x</var>, <var>y</var>) coordinates
* must be ({@linkplain org.opengis.referencing.cs.AxisDirection#EAST East},
* {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) oriented.
*
@@ -164,6 +163,5 @@
*
* @see <a href="http://www.remotesensing.org/geotiff/proj_list";>Projections
list on RemoteSensing.org</a>
* @see <a href="http://mathworld.wolfram.com/MapProjection.html";>Map
projections on MathWorld</a>
- * @see <a
href="http://atlas.gc.ca/site/english/learningresources/carto_corner/map_projections.html";>Map
projections on the atlas of Canada</a>
*/
package org.apache.sis.referencing.operation.projection;
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -81,6 +81,8 @@ import static org.apache.sis.util.Argume
* @since 0.5
* @version 0.5
* @module
+ *
+ * @see DefaultMathTransformFactory
*/
public abstract class AbstractMathTransform extends FormattableObject
implements MathTransform, Parameterized, LenientComparable
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -67,21 +67,76 @@ import org.apache.sis.util.resources.Mes
/**
* Low level factory for creating {@linkplain AbstractMathTransform math
transforms}.
- * High level GIS applications usually do not need to use this factory
directly.
+ * The objects created by this factory do not know what the source and target
coordinate systems mean.
+ * Because of this low semantic value, high level GIS applications usually do
not need to use this factory directly.
* They can use the static convenience methods in the {@link
org.apache.sis.referencing.CRS}
* or {@link MathTransforms} classes instead.
*
- * {@section Math transforms discovery}
- * Unless {@linkplain #DefaultMathTransformFactory(Iterable) specified
explicitely at construction time},
- * {@code OperationMethod} implementations shall be listed in the following
file:
- *
- * {@preformat text
- * META-INF/services/org.opengis.referencing.operation.OperationMethod
- * }
- *
- * {@code DefaultMathTransformFactory} parses the above-cited files in all JAR
files in order to find all available
- * operation methods. By default, only operation methods that implement the
{@link MathTransformProvider} interface
- * can be used by the {@code create(…)} methods in this class.
+ *
+ * {@section Standard parameters}
+ * {@code MathTransform} instances are created from {@linkplain
org.apache.sis.parameter.DefaultParameterValueGroup
+ * parameter values}. The parameters expected by each operation available in a
default Apache SIS installation is
+ * <a href="http://sis.apache.org/CoordinateOperationMethods.html";>listed
here</a>.
+ * The set of parameters varies for each operation or projection, but the
following can be considered typical:
+ *
+ * <ul>
+ * <li>A <cite>semi-major</cite> and <cite>semi-minor</cite> axis length in
metres.</li>
+ * <li>A <cite>central meridian</cite> and <cite>latitude of origin</cite>
in decimal degrees.</li>
+ * <li>A <cite>scale factor</cite>, which default to 1.</li>
+ * <li>A <cite>false easting</cite> and <cite>false northing</cite> in
metres, which default to 0.</li>
+ * </ul>
+ *
+ * <p>Each descriptor has many aliases, and those aliases may vary between
different projections.
+ * For example the <cite>false easting</cite> parameter is usually called
{@code "false_easting"}
+ * by OGC, while EPSG uses various names like "<cite>False easting</cite>" or
"<cite>Easting at
+ * false origin</cite>".</p>
+ *
+ * {@section Dynamic parameters}
+ * A few non-standard parameters are defined for compatibility reasons,
+ * but delegates their work to standard parameters. Those dynamic parameters
are not listed in the
+ * {@linkplain org.apache.sis.parameter.DefaultParameterValueGroup#values()
parameter values}.
+ * Dynamic parameters are:
+ *
+ * <ul>
+ * <li>{@code "earth_radius"}, which copy its value to the {@code
"semi_major"} and
+ * {@code "semi_minor"} parameter values.</li>
+ * <li>{@code "inverse_flattening"}, which compute the {@code "semi_minor"}
value from
+ * the {@code "semi_major"} parameter value.</li>
+ * <li>{@code "standard_parallel"} expecting an array of type {@code
double[]}, which copy
+ * its elements to the {@code "standard_parallel_1"} and {@code
"standard_parallel_2"}
+ * parameter scalar values.</li>
+ * </ul>
+ *
+ * <p>The main purpose of those dynamic parameters is to support some less
commonly used conventions
+ * without duplicating the most commonly used conventions. The alternative
ways are used in NetCDF
+ * files for example, which often use spherical models instead than
ellipsoidal ones.</p>
+ *
+ *
+ * <a name="Obligation">{@section Mandatory and optional parameters}</a>
+ * Parameters are flagged as either <cite>mandatory</cite> or
<cite>optional</cite>.
+ * A parameter may be mandatory and still have a default value. In the context
of this package, "mandatory"
+ * means that the parameter is an essential part of the projection defined by
standards.
+ * Such mandatory parameters will always appears in any <cite>Well Known
Text</cite> (WKT) formatting,
+ * even if not explicitly set by the user. For example the central meridian is
typically a mandatory
+ * parameter with a default value of 0° (the Greenwich meridian).
+ *
+ * <p>Optional parameters, on the other hand, are often non-standard
extensions.
+ * They will appear in WKT formatting only if the user defined explicitly a
value which is different than the
+ * default value.</p>
+ *
+ *
+ * {@section Operation methods discovery}
+ * {@link OperationMethod} describes all the parameters expected for
instantiating a particular kind of
+ * math transform. The set of operation methods known to this factory can be
obtained in two ways:
+ *
+ * <ul>
+ * <li>{@linkplain #DefaultMathTransformFactory(Iterable) specified
explicitely at construction time}, or</li>
+ * <li>{@linkplain #DefaultMathTransformFactory() discovered by scanning the
classpath}.</li>
+ * </ul>
+ *
+ * The default way is to scan the classpath. See {@link MathTransformProvider}
for indications about how to add
+ * custom coordinate operation methods in a default Apache SIS installation.
+ *
*
* {@section Thread safety}
* This class is safe for multi-thread usage if all referenced {@code
OperationMethod} instances are thread-safe.
@@ -91,6 +146,9 @@ import org.apache.sis.util.resources.Mes
* @since 0.6
* @version 0.6
* @module
+ *
+ * @see MathTransformProvider
+ * @see AbstractMathTransform
*/
public class DefaultMathTransformFactory extends AbstractFactory implements
MathTransformFactory {
/*
@@ -155,7 +213,7 @@ public class DefaultMathTransformFactory
/**
* Creates a new factory which will discover operation methods with a
{@link ServiceLoader}.
- * {@code OperationMethod} implementations shall be listed in the
following file:
+ * The {@link OperationMethod} implementations shall be listed in the
following file:
*
* {@preformat text
* META-INF/services/org.opengis.referencing.operation.OperationMethod
@@ -164,6 +222,8 @@ public class DefaultMathTransformFactory
* {@code DefaultMathTransformFactory} parses the above-cited files in all
JAR files in order to find all available
* operation methods. By default, only operation methods that implement
the {@link MathTransformProvider} interface
* can be used by the {@code create(…)} methods in this class.
+ *
+ * @see #reload()
*/
public DefaultMathTransformFactory() {
this(ServiceLoader.load(OperationMethod.class));
@@ -586,20 +646,23 @@ public class DefaultMathTransformFactory
}
/**
- * Creates a transform from a group of parameters. The {@code
OperationMethod} name is inferred
- * from the {@linkplain ParameterDescriptorGroup#getName() parameter group
name}.
+ * Creates a transform from a group of parameters.
+ * The set of expected parameters varies for each operation.
+ * The easiest way to provide parameter values is to get an initially
empty group for the desired
+ * operation by calling {@link #getDefaultParameters(String)}, then to
fill the parameter values.
* Example:
*
* {@preformat java
- * ParameterValueGroup p =
factory.getDefaultParameters("Transverse_Mercator");
- * p.parameter("semi_major").setValue(6378137.000);
- * p.parameter("semi_minor").setValue(6356752.314);
- * MathTransform mt = factory.createParameterizedTransform(p);
+ * ParameterValueGroup group =
factory.getDefaultParameters("Transverse_Mercator");
+ * group.parameter("semi_major").setValue(6378137.000);
+ * group.parameter("semi_minor").setValue(6356752.314);
+ * MathTransform mt = factory.createParameterizedTransform(group);
* }
*
- * @param parameters The parameter values.
- * @return The parameterized transform.
- * @throws NoSuchIdentifierException if there is no transform registered
for the coordinate operation method.
+ * @param parameters The parameter values. The {@linkplain
ParameterDescriptorGroup#getName() parameter group name}
+ * shall be the name of the desired {@linkplain
DefaultOperationMethod operation method}.
+ * @return The transform created from the given parameters.
+ * @throws NoSuchIdentifierException if there is no method for the given
parameter group name.
* @throws FactoryException if the object creation failed. This exception
is thrown
* if some required parameter has not been supplied, or has
illegal value.
*
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -25,33 +25,55 @@ import org.opengis.referencing.operation
/**
- * An object capable to create {@code MathTransform} instances from given
parameter values.
- * {@code MathTransformProvider} is the Apache SIS mechanism by which
+ * An object capable to create {@link MathTransform} instances from given
parameter values.
+ * This interface is the Apache SIS mechanism by which
* {@linkplain org.apache.sis.referencing.operation.DefaultFormula formula}
are concretized as Java code.
- * There is one {@code MathTransformProvider} for each map projection: one for
Mercator, one for Lambert,
- * <i>etc</i>.
*
- * <p>This interface is used by {@link DefaultMathTransformFactory} or by
developers who want to plug
- * their own operation methods into Apache SIS. This interface is generally
not used directly.
- * The recommended way to get a {@code MathTransform} is to first get the
{@code CoordinateOperation}
+ * <p>Implementations of this interface usually extend {@link
org.apache.sis.referencing.operation.DefaultOperationMethod},
+ * but this is not mandatory. This interface can also be used alone since
{@link MathTransform} instances can be created
+ * for other purpose than coordinate operations.</p>
+ *
+ * <p>This interface is generally not used directly. The recommended way to
get a {@code MathTransform}
+ * is to {@linkplain org.apache.sis.referencing.CRS#findOperation find the
coordinate operation}
* (generally from a pair of <var>source</var> and <var>target</var> CRS),
then to invoke
- * {@link
org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.</p>
+ * {@link
org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.
+ * Alternative, one can also use a {@linkplain DefaultMathTransformFactory
math transform factory}</p>
+ *
*
- * {@section How to add custom coordinate operations}
- * To define a custom coordinate operation,
+ * {@section How to add custom coordinate operations to Apache SIS}
+ * {@link DefaultMathTransformFactory} can discover automatically new
coordinate operations
+ * (including map projections) by scanning the classpath. To define a custom
coordinate operation,
* one needs to define a <strong>thread-safe</strong> class implementing
<strong>both</strong> this
* {@code MathTransformProvider} interface and the {@link
org.opengis.referencing.operation.OperationMethod} one.
* While not mandatory, we suggest to extend {@link
org.apache.sis.referencing.operation.DefaultOperationMethod}.
- * Then the fully-qualified class name of that implementation should be listed
in a file having this exact name:
+ * Example:
+ *
+ * <div class="note">{@preformat java
+ * public class MyProjectionProvider extends DefaultOperationMethod
implements MathTransformProvider {
+ * public MyProjectionProvider() {
+ * super(Collections.singletonMap(NAME_KEY, "My projection"),
+ * 2, // Number of source dimensions
+ * 2, // Number of target dimensions
+ * parameters);
+ * }
+ *
+ * @Override
+ * public MathTransform createMathTransform(ParameterValueGroup
values) {
+ * double semiMajor =
values.parameter("semi_major").doubleValue(SI.METRE);
+ * double semiMinor =
values.parameter("semi_minor").doubleValue(SI.METRE);
+ * // etc...
+ * return new MyProjection(semiMajor, semiMinor, ...);
+ * }
+ * }
+ * }</div>
+ *
+ * Then the fully-qualified class name of that implementation should be listed
in a file reachable on the classpath
+ * with this exact name:
*
* {@preformat text
* META-INF/services/org.opengis.referencing.operation.OperationMethod
* }
*
- * <div class="note"><b>Design note:</b>
- * this {@code MathTransformProvider} interface does not extend {@code
OperationMethod} directly
- * in order to allow its usage in other contexts than coordinate
operations.</div>
- *
* @author Martin Desruisseaux (Geomatys, IRD)
* @since 0.6
* @version 0.6
@@ -71,10 +93,12 @@ public interface MathTransformProvider {
* before to instantiate the transform:
*
* {@preformat java
- * double semiMajor =
values.parameter("semi_major").doubleValue(SI.METRE);
- * double semiMinor =
values.parameter("semi_minor").doubleValue(SI.METRE);
- * // etc...
- * return new MyTransform(semiMajor, semiMinor, ...);
+ * public MathTransform createMathTransform(ParameterValueGroup
values) {
+ * double semiMajor =
values.parameter("semi_major").doubleValue(SI.METRE);
+ * double semiMinor =
values.parameter("semi_minor").doubleValue(SI.METRE);
+ * // etc...
+ * return new MyProjection(semiMajor, semiMinor, ...);
+ * }
* }
* </div>
*
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -38,57 +38,15 @@
* in their own {@linkplain org.apache.sis.referencing.operation.projection
projection} package.</p>
*
*
- * {@section Standard parameters}
- * Some {@code MathTransform} implementations declare a single {@link
org.opengis.parameter.ParameterDescriptorGroup}
- * constant named {@code PARAMETERS}. Each group describes all the parameters
expected by the
- * {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod
operation method}
- * associated to the transform implementation.
- * The set of parameters varies for each operation or projection, but the
following can be considered typical:
- *
- * <ul>
- * <li>A <cite>semi-major</cite> and <cite>semi-minor</cite> axis length in
metres.</li>
- * <li>A <cite>central meridian</cite> and <cite>latitude of origin</cite>
in decimal degrees.</li>
- * <li>A <cite>scale factor</cite>, which default to 1.</li>
- * <li>A <cite>false easting</cite> and <cite>false northing</cite> in
metres, which default to 0.</li>
- * </ul>
- *
- * <p>Each descriptor has many aliases, and those aliases may vary between
different projections.
- * For example the <cite>false easting</cite> parameter is usually called
{@code "false_easting"}
- * by OGC, while EPSG uses various names like "<cite>False easting</cite>" or
"<cite>Easting at
- * false origin</cite>".</p>
- *
- * {@section Dynamic parameters}
- * A few non-standard parameters are defined for compatibility reasons,
- * but delegates their work to standard parameters. Those dynamic parameters
are not listed in the
- * {@linkplain org.apache.sis.parameter.DefaultParameterValueGroup#values()
parameter values}.
- * Dynamic parameters are:
- *
- * <ul>
- * <li>{@code "earth_radius"}, which copy its value to the {@code
"semi_major"} and
- * {@code "semi_minor"} parameter values.</li>
- * <li>{@code "inverse_flattening"}, which compute the {@code "semi_minor"}
value from
- * the {@code "semi_major"} parameter value.</li>
- * <li>{@code "standard_parallel"} expecting an array of type {@code
double[]}, which copy
- * its elements to the {@code "standard_parallel_1"} and {@code
"standard_parallel_2"}
- * parameter scalar values.</li>
- * </ul>
- *
- * <p>The main purpose of those dynamic parameters is to support some less
commonly used conventions
- * without duplicating the most commonly used conventions. The alternative
ways are used in NetCDF
- * files for example, which often use spherical models instead than
ellipsoidal ones.</p>
- *
- *
- * {@section Mandatory and optional parameters}
- * <a name="Obligation">Parameters are flagged as either
<cite>mandatory</cite> or <cite>optional</cite></a>.
- * A parameter may be mandatory and still have a default value. In the context
of this package, "mandatory"
- * means that the parameter is an essential part of the projection defined by
standards.
- * Such mandatory parameters will always appears in any <cite>Well Known
Text</cite> (WKT) formatting,
- * even if not explicitly set by the user. For example the central meridian is
typically a mandatory
- * parameter with a default value of 0° (the Greenwich meridian).
- *
- * <p>Optional parameters, on the other hand, are often non-standard
extensions.
- * They will appear in WKT formatting only if the user defined explicitly a
value which is different than the
- * default value.</p>
+ * {@section Creating math transforms}
+ * {@code MathTransform} instances can be created either directly or
indirectly.
+ * The recommended way is the indirect one: first
+ * {@linkplain org.apache.sis.referencing.CRS#findOperation find the
coordinate operation}
+ * (generally from a pair of <var>source</var> and <var>target</var> CRS),
then invoke
+ * {@link
org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.
+ * However sophisticated users can also create math transforms explicitely
from a group of parameter values
+ * using the {@linkplain
org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory math
+ * transform factory}.
*
*
* {@section Non-spatial coordinates}
@@ -104,7 +62,7 @@
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Adrian Custer (Geomatys)
* @since 0.5
- * @version 0.5
+ * @version 0.6
* @module
*/
package org.apache.sis.referencing.operation.transform;
