svn commit: r1658261 - in /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation: DefaultFormula.java DefaultOperationMethod.java transform/MathTransformProvider.java

[de...@apache.org]

Author: desruisseaux
Date: Sun Feb  8 22:01:42 2015
New Revision: 1658261

URL: http://svn.apache.org/r1658261
Log:
Additional javadoc clarification.

Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java
    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/DefaultFormula.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java?rev=1658261&r1=1658260&r2=1658261&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultFormula.java [UTF-8] Sun Feb  8 22:01:42 2015
@@ -47,6 +47,7 @@ import java.util.Objects;
  *
  * @see DefaultOperationMethod
  * @see org.apache.sis.referencing.operation.transform.AbstractMathTransform
+ * @see org.apache.sis.referencing.operation.transform.MathTransformProvider
  */
 public class DefaultFormula extends FormattableObject implements Formula, Serializable {
     /**

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=1658261&r1=1658260&r2=1658261&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 22:01:42 2015
@@ -91,6 +91,12 @@ import java.util.Objects;
  * {@code DefaultOperationMethod} subclasses should implement the
  * {@link org.apache.sis.referencing.operation.transform.MathTransformProvider} interface.</p>
  *
+ * {@section Immutability and thread safety}
+ * This class is immutable and thread-safe if all properties given to the constructor are also immutable and thread-safe.
+ * It is strongly recommended for all subclasses to be thread-safe, especially the
+ * {@link org.apache.sis.referencing.operation.transform.MathTransformProvider} implementations to be used with
+ * {@link org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory}.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @version 0.5
  * @since   0.5

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=1658261&r1=1658260&r2=1658261&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 22:01:42 2015
@@ -26,7 +26,8 @@ import org.opengis.referencing.operation
 
 /**
  * An object capable to create {@code MathTransform} instances from given parameter values.
- * {@code MathTransformProvider} is the "glue" expressing an abstract formula into concrete Java code.
+ * {@code MathTransformProvider} 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>.
  *
@@ -37,7 +38,8 @@ import org.opengis.referencing.operation
  * {@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
+ * 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:
@@ -47,8 +49,8 @@ import org.opengis.referencing.operation
  * }
  *
  * <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>
+ * 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
@@ -57,6 +59,7 @@ import org.opengis.referencing.operation
  *
  * @see org.apache.sis.referencing.operation.DefaultOperationMethod
  * @see DefaultMathTransformFactory
+ * @see AbstractMathTransform
  */
 @FunctionalInterface
 public interface MathTransformProvider {