sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1755369 - in /sis/branches/JDK8/core: sis-feature/src/main/java/org/apache/sis/feature/ sis-feature/src/test/java/org/apache/sis/feature/ sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/
Date Fri, 05 Aug 2016 17:36:56 GMT
Author: desruisseaux
Date: Fri Aug  5 17:36:56 2016
New Revision: 1755369

URL: http://svn.apache.org/viewvc?rev=1755369&view=rev
Log:
Javadoc.

Modified:
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/AbstractFeature.java
    sis/branches/JDK8/core/sis-feature/src/test/java/org/apache/sis/feature/FeatureTestCase.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionException.java

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/AbstractFeature.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/AbstractFeature.java?rev=1755369&r1=1755368&r2=1755369&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/AbstractFeature.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/AbstractFeature.java
[UTF-8] Fri Aug  5 17:36:56 2016
@@ -128,21 +128,18 @@ public abstract class AbstractFeature im
      * method may return the result of {@linkplain AbstractOperation#apply executing} the
operation
      * on this feature, at implementation choice.
      *
-     * <div class="note"><b>Tip:</b> This method returns the property <em>instance</em>.
If only the property
-     * <em>value</em> is desired, then {@link #getPropertyValue(String)} is preferred
since it gives to SIS a
-     * chance to avoid the creation of {@link AbstractAttribute} or {@link AbstractAssociation}
instances.</div>
+     * <p>This method returns the property <em>instance</em>. If only the
property <em>value</em> is
+     * desired, then {@link #getPropertyValue(String)} is preferred since it gives to SIS
a chance to
+     * avoid the creation of {@link AbstractAttribute} or {@link AbstractAssociation} instances.</p>
      *
      * <div class="note"><b>Note for subclass implementors:</b>
      * the default implementation returns an instance that redirect all read and write operations
to
      * {@link #getPropertyValue(String)} and {@link #setPropertyValue(String, Object)} respectively.
      * That default implementation is intended to make easier for developers to create their
own
      * customized <code>AbstractFacture</code> implementations, but has drawbacks:
-     *
-     * <ul>
-     *   <li>A new {@code Property} instance is created every time that this {@code
getProperty(String)} method is invoked.</li>
-     *   <li>The returned {@code Property} implementation is not very efficient since
it has to perform multiple lookups and type checks.</li>
-     * </ul>
-     *
+     * a new {@code Property} instance is created every time that this {@code getProperty(String)}
method is invoked,
+     * and the returned {@code Property} implementation is not very efficient
+     * since it has to perform multiple lookups and type checks.
      * Implementors are encouraged to override this method if they can provide a more efficient
implementation.
      * Note that this is already the case when using implementations created by {@link DefaultFeatureType#newInstance()}.</div>
      *
@@ -174,9 +171,9 @@ public abstract class AbstractFeature im
      *     assert property.getType() == getType().getProperty(property.getName());
      * }
      *
-     * <div class="note"><b>Note:</b> This method is useful for storing
non-default {@code Attribute} or
-     * {@code FeatureAssociation} implementations in this feature. When default implementations
are sufficient,
-     * the {@link #setPropertyValue(String, Object)} method is preferred.</div>
+     * This method is useful for storing non-default {@code Attribute} or {@code FeatureAssociation}
implementations
+     * in this feature. When default implementations are sufficient, the {@link #setPropertyValue(String,
Object)}
+     * method is preferred.
      *
      * <div class="note"><b>Note for subclass implementors:</b>
      * the default implementation verifies that the given property has the expected type
and a null or empty
@@ -184,12 +181,8 @@ public abstract class AbstractFeature im
      * {@link #setPropertyValue(String, Object)}.
      * That default implementation is intended to make easier for developers to create their
own
      * customized <code>AbstractFacture</code> implementations, but has drawbacks:
-     *
-     * <ul>
-     *   <li>The given {@code Property} instance is not retained; only its {@linkplain
AbstractAttribute#getValue() value} is stored.</li>
-     *   <li>The given {@code Property} instance can not have custom {@linkplain AbstractAttribute#characteristics()
characteristics}.</li>
-     * </ul>
-     *
+     * the given {@code Property} instance is not stored (only its {@linkplain AbstractAttribute#getValue()
value}
+     * is stored), and it can not have custom {@linkplain AbstractAttribute#characteristics()
characteristics}.
      * Implementors are encouraged to override this method if they can provide a better implementation.
      * Note that this is already the case when using implementations created by {@link DefaultFeatureType#newInstance()}.</div>
      *
@@ -349,10 +342,17 @@ public abstract class AbstractFeature im
      * number of occurrences} and does not depend on the actual number of values. If an attribute
allows more than one
      * value, then this method will always return a collection for that attribute even if
the collection is empty.</div>
      *
+     * <div class="section">Multi-valued properties and collections</div>
      * In the case of multi-valued properties (“max. occurs” &gt; 1), the collection
returned by this method may
      * or may not be modifiable, at implementation choice. Generally the caller can not add
new elements into the
      * returned collection anyway since {@code Collection<?>} does not allow such operations,
and more specific
      * casts (e.g. {@code Collection<String>} can not be checked at runtime (at least
as of Java 8).
+     * If a type-safe modifiable collection is desired, the following approach can be used
instead:
+     *
+     * {@preformat java
+     *   Attribute<String> attribute = Features.cast((Attribute<?>) feature.getProperty(name),
String.class);
+     *   Collection<String> values = attribute.getValues();    // This collection is
guaranteed to be "live".
+     * }
      *
      * @param  name  the property name.
      * @return the value for the given property, or {@code null} if none.

Modified: sis/branches/JDK8/core/sis-feature/src/test/java/org/apache/sis/feature/FeatureTestCase.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/test/java/org/apache/sis/feature/FeatureTestCase.java?rev=1755369&r1=1755368&r2=1755369&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/test/java/org/apache/sis/feature/FeatureTestCase.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/test/java/org/apache/sis/feature/FeatureTestCase.java
[UTF-8] Fri Aug  5 17:36:56 2016
@@ -351,14 +351,17 @@ public abstract strictfp class FeatureTe
         feature = createFeature(new DefaultFeatureType(
                 Collections.singletonMap(DefaultFeatureType.NAME_KEY, "City"),
                 false, null, DefaultAttributeTypeTest.universities()));
-
-        feature.setPropertyValue("universities", Arrays.asList("UCAR", "Marie-Curie"));
         /*
          * The value below is an instance of Collection<String>. But as of Java 8,
the <String> parameterized type
          * can not be verified at runtime. The best check we can have is Collection<?>,
which does not allow addition
          * of new values.
          */
-        final Collection<?> values = (Collection<?>) feature.getPropertyValue("universities");
+        Collection<?> values = (Collection<?>) feature.getPropertyValue("universities");
+        assertTrue("isEmpty", values.isEmpty());
+        // Can not perform values.add("something") here.
+
+        feature.setPropertyValue("universities", Arrays.asList("UCAR", "Marie-Curie"));
+        values = (Collection<?>) feature.getPropertyValue("universities");
         assertArrayEquals(new String[] {"UCAR", "Marie-Curie"}, values.toArray());
     }
 

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionException.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionException.java?rev=1755369&r1=1755368&r2=1755369&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionException.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionException.java
[UTF-8] Fri Aug  5 17:36:56 2016
@@ -23,6 +23,22 @@ import org.apache.sis.util.resources.Err
 /**
  * Thrown by {@link NormalizedProjection} when a map projection failed.
  *
+ * <div class="section">When this exception is thrown</div>
+ * Apache SIS implementations of map projections return a {@linkplain Double#isFinite(double)
finite} number
+ * under normal conditions, but may also return an {@linkplain Double#isInfinite(double)
infinite} number or
+ * {@linkplain Double#isNaN(double) NaN} value, or throw this exception.
+ * The behavior depends on the reason why the projection can not return a finite number:
+ *
+ * <ul>
+ *   <li>If the expected mathematical value is infinite (for example the Mercator projection
at ±90° of latitude),
+ *       then the map projection should return a {@link Double#POSITIVE_INFINITY} or {@link
Double#NEGATIVE_INFINITY},
+ *       depending on the sign of the correct mathematical answer.</li>
+ *   <li>If no real number is expected to exist for the input coordinate (for example
the root of a negative value),
+ *       then the map projection should return {@link Double#NaN}.</li>
+ *   <li>If a real number is expected to exist but the map projection fails to compute
it (for example because an
+ *       iterative algorithm does not converge), then the projection should throw {@code
ProjectionException}.</li>
+ * </ul>
+ *
  * @author  André Gosselin (MPO)
  * @author  Martin Desruisseaux (MPO, IRD, Geomatys)
  * @since   0.6



Mime
View raw message