Author: desruisseaux
Date: Sun Feb 8 20:57:33 2015
New Revision: 1658254
URL: http://svn.apache.org/r1658254
Log:
Added javadoc.
Restricted DefaultOperationMethod.getOperationType() to SingleOperation
subtypes.
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultOperationMethod.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultOperationMethod.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultOperationMethod.java?rev=1658254&r1=1658253&r2=1658254&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultOperationMethod.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultOperationMethod.java
[UTF-8] Sun Feb 8 20:57:33 2015
@@ -25,7 +25,7 @@ import org.opengis.referencing.operation
import org.opengis.referencing.operation.Projection;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.referencing.operation.OperationMethod;
-import org.opengis.referencing.operation.CoordinateOperation;
+import org.opengis.referencing.operation.SingleOperation;
import org.opengis.parameter.ParameterDescriptorGroup;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.ComparisonMode;
@@ -45,12 +45,30 @@ import java.util.Objects;
/**
- * Defines the algorithm and describes the parameters used to perform a
coordinate operation. An {@code OperationMethod}
- * contains an arbitrary amount of {@linkplain
org.apache.sis.parameter.DefaultParameterDescriptor parameter descriptors}.
- * Values for those parameters will be assigned by {@linkplain
DefaultSingleOperation coordinate operations}.
+ * Describes the algorithm and parameters used to perform a coordinate
operation. An {@code OperationMethod}
+ * is a kind of metadata: it does not perform any coordinate operation (e.g.
map projection) by itself, but
+ * tells us what is needed in order to perform such operation.
*
- * <div class="note"><b>Departure from the ISO 19111 standard:</b>
- * the following properties are mandatory according ISO 19111,
+ * <p>The most important parts of an {@code OperationMethod} are its
{@linkplain #getName() name} and its
+ * {@linkplain #getParameters() group of parameter descriptors}. The parameter
descriptors do not contain
+ * any value, but tell us what are the expected parameters, together with
their units of measurement.</p>
+ *
+ * <div class="note"><b>Example:</b>
+ * An operation method named “<cite>Mercator (variant A)</cite>” (EPSG:9804)
expects the following parameters:
+ * <ul>
+ * <li>“<cite>Latitude of natural origin</cite>” in degrees. Default value
is 0°.</li>
+ * <li>“<cite>Longitude of natural origin</cite>” in degrees. Default value
is 0°.</li>
+ * <li>“<cite>Scale factor at natural origin</cite>” as a dimensionless
number. Default value is 1.</li>
+ * <li>“<cite>False easting</cite>” in metres. Default value is 0 m.</li>
+ * <li>“<cite>False northing</cite>” in metres. Default value is 0 m.</li>
+ * </ul></div>
+ *
+ * In Apache SIS implementation, the {@linkplain #getName() name} is the only
mandatory property. However it is
+ * recommended to provide also {@linkplain #getIdentifiers() identifiers}
(e.g. “EPSG:9804” in the above example)
+ * since names can sometime be ambiguous or be spelled in different ways.
+ *
+ * <div class="note"><b>Departure from the ISO 19111 standard</b><br>
+ * The following properties are mandatory according ISO 19111,
* but may be missing under some conditions in Apache SIS:
* <ul>
* <li>The {@linkplain #getFormula() formula} if it has not been provided to
the
@@ -60,12 +78,26 @@ import java.util.Objects;
* constructor can not infer them.</li>
* </ul></div>
*
+ * {@section Relationship with other classes or interfaces}
+ * {@code OperationMethod} describes parameters without providing any value
(except sometime default values).
+ * When values have been assigned to parameters, the result is a {@link
SingleOperation}.
+ * Note that there is different kinds of {@code SingleOperation} depending on
the nature and accuracy of the
+ * coordinate operation. See {@link #getOperationType()} for more information.
+ *
+ * <p>The interface performing the actual work of taking coordinates in the
+ * {@linkplain AbstractCoordinateOperation#getSourceCRS() source CRS} and
calculating the new coordinates in the
+ * {@linkplain AbstractCoordinateOperation#getTargetCRS() target CRS} is
{@link MathTransform}.
+ * In order to allow Apache SIS to instantiate those {@code MathTransform}s
from given parameter values,
+ * {@code DefaultOperationMethod} subclasses should implement the
+ * {@link
org.apache.sis.referencing.operation.transform.MathTransformProvider}
interface.</p>
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @version 0.5
* @since 0.5
* @module
*
* @see DefaultSingleOperation
+ * @see org.apache.sis.referencing.operation.transform.MathTransformProvider
*/
public class DefaultOperationMethod extends AbstractIdentifiedObject
implements OperationMethod {
/**
@@ -337,29 +369,29 @@ public class DefaultOperationMethod exte
* The base {@code CoordinateOperation} interface is usually one of the
following subtypes:
*
* <ul>
- * <li>{@link org.opengis.referencing.operation.Transformation}
+ * <li><p>{@link org.opengis.referencing.operation.Transformation}
* if the coordinate operation has some errors (typically of a few
metres) because of the empirical process by
* which the operation parameters were determined. Those errors do not
depend on the floating point precision
- * or the accuracy of the implementation algorithm.</li>
- * <li>{@link org.opengis.referencing.operation.Conversion}
+ * or the accuracy of the implementation algorithm.</p></li>
+ * <li><p>{@link org.opengis.referencing.operation.Conversion}
* if the coordinate operation is theoretically of infinite precision,
ignoring the limitations of floating
- * point arithmetic (including rounding errors) and the approximations
implied by finite series expansions.</li>
- * <li>{@link org.opengis.referencing.operation.Projection}
+ * point arithmetic (including rounding errors) and the approximations
implied by finite series expansions.</p></li>
+ * <li><p>{@link org.opengis.referencing.operation.Projection}
* if the coordinate operation is a conversion (as defined above)
converting geodetic latitudes and longitudes
* to plane (map) coordinates. This type can optionally be refined
with one of the
* {@link org.opengis.referencing.operation.CylindricalProjection},
* {@link org.opengis.referencing.operation.ConicProjection} or
- * {@link org.opengis.referencing.operation.PlanarProjection}
subtypes.</li>
+ * {@link org.opengis.referencing.operation.PlanarProjection}
subtypes.</p></li>
* </ul>
*
* In case of doubt, this method can conservatively return the base type.
- * The default implementation returns {@code CoordinateOperation.class},
+ * The default implementation returns {@code SingleOperation.class},
* which is the most conservative return value.
*
* @return Interface implemented by all coordinate operations that use
this method.
*/
- public Class<? extends CoordinateOperation> getOperationType() {
- return CoordinateOperation.class;
+ public Class<? extends SingleOperation> getOperationType() {
+ return SingleOperation.class;
}
/**
@@ -404,7 +436,7 @@ public class DefaultOperationMethod exte
*
* <div class="note"><b>Departure from the ISO 19111 standard:</b>
* this property is mandatory according ISO 19111, but may be null in
Apache SIS if the
- * {@linkplain #DefaultOperationMethod(MathTransform)} constructor has
been unable to infer it.</div>
+ * {@link #DefaultOperationMethod(MathTransform)} constructor has been
unable to infer it.</div>
*
* @return The parameters, or {@code null} if unknown.
*/
@@ -515,7 +547,7 @@ public class DefaultOperationMethod exte
* Transformation, ConcatenatedOperation, PassThroughOperation, or
any user-defined type that
* do not extend Projection. All other operation types are
accepted.
*/
- final Class<? extends CoordinateOperation> type =
getOperationType();
+ final Class<? extends SingleOperation> type = getOperationType();
if (Projection.class.isAssignableFrom(type) ||
type.isAssignableFrom(Projection.class)) {
return "Projection";
}
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=1658254&r1=1658253&r2=1658254&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] Sun Feb 8 20:57:33 2015
@@ -26,14 +26,37 @@ import org.opengis.referencing.operation
/**
* An object capable to create {@code MathTransform} instances from given
parameter values.
- * The Apache SIS {@link DefaultMathTransformFactory} implementation checks
for this interface
- * when creating a {@code MathTransform} for an
- * {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod
operation method}.
+ * {@code MathTransformProvider} is the "glue" expressing an abstract formula
into concrete 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}
+ * (generally from a pair of <var>source</var> and <var>target</var> CRS),
then to invoke
+ * {@link
org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.</p>
+ *
+ * {@section How to add custom coordinate operations}
+ * To define a custom coordinate operation, one needs to define a 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:
+ *
+ * {@preformat text
+ * META-INF/services/org.opengis.referencing.operation.OperationMethod
+ * }
+ *
+ * <div class="note"><b>Design note:</b>
+ * this 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
* @module
+ *
+ * @see org.apache.sis.referencing.operation.DefaultOperationMethod
+ * @see DefaultMathTransformFactory
*/
@FunctionalInterface
public interface MathTransformProvider {
