sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] branch geoapi-4.0 updated: Minor cleanup on filter package. The change in imports order is for reducing the risk of conflicts when code will be marged to master.
Date Wed, 15 Jan 2020 15:35:48 GMT
This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git


The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
     new b0b189c  Minor cleanup on filter package. The change in imports order is for reducing
the risk of conflicts when code will be marged to master.
b0b189c is described below

commit b0b189cde268e10cc74acf619b1375dd2d47cfd2
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Jan 15 16:34:56 2020 +0100

    Minor cleanup on filter package. The change in imports order is for reducing the risk
of conflicts when code will be marged to master.
---
 .../org/apache/sis/filter/ArithmeticFunction.java  |  8 +--
 .../java/org/apache/sis/filter/BinaryFunction.java | 16 ++---
 .../org/apache/sis/filter/ComparisonFunction.java  | 76 ++++++++++------------
 .../apache/sis/filter/DefaultFilterFactory.java    | 44 ++++++-------
 .../org/apache/sis/filter/LogicalFunction.java     |  6 +-
 .../org/apache/sis/filter/TemporalFunction.java    |  7 +-
 .../java/org/apache/sis/filter/UnaryFunction.java  |  8 +--
 .../java/org/apache/sis/filter/package-info.java   | 63 +++++++++---------
 .../java/org/apache/sis/internal/filter/Node.java  |  8 ++-
 .../apache/sis/internal/filter/package-info.java   | 27 ++++++++
 10 files changed, 144 insertions(+), 119 deletions(-)

diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/ArithmeticFunction.java
b/core/sis-feature/src/main/java/org/apache/sis/filter/ArithmeticFunction.java
index 44afa99..0b55c38 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/ArithmeticFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/ArithmeticFunction.java
@@ -146,7 +146,7 @@ abstract class ArithmeticFunction extends BinaryFunction implements BinaryExpres
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '+';}
 
         /** Applies this expression to the given operands. */
@@ -180,7 +180,7 @@ abstract class ArithmeticFunction extends BinaryFunction implements BinaryExpres
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '−';}
 
         /** Applies this expression to the given operands. */
@@ -214,7 +214,7 @@ abstract class ArithmeticFunction extends BinaryFunction implements BinaryExpres
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '×';}
 
         /** Applies this expression to the given operands. */
@@ -248,7 +248,7 @@ abstract class ArithmeticFunction extends BinaryFunction implements BinaryExpres
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '÷';}
 
         /** Applies this expression to the given operands. */
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/BinaryFunction.java b/core/sis-feature/src/main/java/org/apache/sis/filter/BinaryFunction.java
index 4050c83..19aab05 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/BinaryFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/BinaryFunction.java
@@ -16,18 +16,18 @@
  */
 package org.apache.sis.filter;
 
-import java.math.BigDecimal;
-import java.math.BigInteger;
 import java.util.Arrays;
 import java.util.Collection;
-
-import org.opengis.filter.expression.Expression;
-
-import org.apache.sis.internal.filter.Node;
-import org.apache.sis.math.DecimalFunctions;
+import java.math.BigInteger;
+import java.math.BigDecimal;
+import org.apache.sis.util.Numbers;
 import org.apache.sis.math.Fraction;
+import org.apache.sis.math.DecimalFunctions;
 import org.apache.sis.util.ArgumentChecks;
-import org.apache.sis.util.Numbers;
+import org.apache.sis.internal.filter.Node;
+
+// Branch-dependent imports
+import org.opengis.filter.expression.Expression;
 
 
 /**
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/ComparisonFunction.java
b/core/sis-feature/src/main/java/org/apache/sis/filter/ComparisonFunction.java
index bd393d8..d8780b2 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/ComparisonFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/ComparisonFunction.java
@@ -18,6 +18,8 @@ package org.apache.sis.filter;
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
+import java.util.Arrays;
+import java.util.Collection;
 import java.util.Date;
 import java.util.Calendar;
 import java.time.Instant;
@@ -32,8 +34,6 @@ import java.time.chrono.ChronoLocalDateTime;
 import java.time.chrono.ChronoZonedDateTime;
 import java.time.temporal.ChronoField;
 import java.time.temporal.Temporal;
-import java.util.Arrays;
-import java.util.Collection;
 import org.apache.sis.internal.filter.Node;
 import org.apache.sis.math.Fraction;
 import org.apache.sis.util.ArgumentChecks;
@@ -46,10 +46,10 @@ import org.opengis.filter.FilterVisitor;
 
 
 /**
- * Comparison operators between two values. Values are converted to the same before comparison,
using a widening conversion
- * (for example from {@link Integer} to {@link Double}). If values can not be compared because
they can not be converted to
- * a common type, or because a value is null or NaN, then the comparison result if {@code
false}. A consequence of this rule
- * is that the two conditions {@literal A < B} and {@literal A ≧ B} may be false in
same time.
+ * Comparison operators between two values. Values are converted to the same type before
comparison, using a widening
+ * conversion (for example from {@link Integer} to {@link Double}). If values can not be
compared because they can not
+ * be converted to a common type, or because a value is null or NaN, then the comparison
result if {@code false}.
+ * A consequence of this rule is that the conditions {@literal A < B} and {@literal A
≧ B} may be false in same time.
  *
  * <p>If one operand is a collection, all collection elements may be compared to the
other value.
  * Null elements in the collection (not to be confused with null operands) are ignored.
@@ -523,7 +523,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '<';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -558,7 +558,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '≤';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -593,7 +593,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '>';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -628,7 +628,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '≥';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -663,7 +663,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '=';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -698,7 +698,7 @@ abstract class ComparisonFunction extends BinaryFunction implements BinaryCompar
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '≠';}
 
         /** Converts {@link Comparable#compareTo(Object)} result to this filter result. */
@@ -720,53 +720,47 @@ abstract class ComparisonFunction extends BinaryFunction implements
BinaryCompar
     }
 
     /**
-     * The {@value #NAME} filter.
+     * The {@value #NAME} filter. This can be seen as a specialization of
+     * {@link org.apache.sis.filter.LogicalFunction.And} when one expression is
+     * {@link LessThanOrEqualTo} and a second expression is {@link GreaterThanOrEqualTo}.
+     *
+     * @see org.apache.sis.filter.LogicalFunction.And
      */
     static final class Between extends Node implements org.opengis.filter.PropertyIsBetween
{
         /** For cross-version compatibility during (de)serialization. */
         private static final long serialVersionUID = -2434954008425799595L;
 
-        private final GreaterThanOrEqualTo lower;
-        private final LessThanOrEqualTo upper;
+        /** The first  operation to apply. */ private final GreaterThanOrEqualTo lower;
+        /** The second operation to apply. */ private final LessThanOrEqualTo upper;
 
+        /** Creates a new filter for the {@value #NAME} operation. */
         Between(final Expression expression, final Expression lower, final Expression upper)
{
             this.lower = new GreaterThanOrEqualTo(expression, lower, true, MatchAction.ANY);
-            this.upper = new LessThanOrEqualTo(expression, upper, true, MatchAction.ANY);
+            this.upper = new    LessThanOrEqualTo(expression, upper, true, MatchAction.ANY);
         }
 
-
-        /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
-
-        @Override
-        protected Collection<?> getChildren() {
+        /**
+         * Returns the 3 children of this node. Since {@code lower.expression2}
+         * is the same as {@code upper.expression1}, that repetition is omitted.
+         */
+        @Override protected Collection<?> getChildren() {
             return Arrays.asList(lower.expression1, lower.expression2, upper.expression2);
         }
 
-        @Override
-        public Expression getExpression() {
-            return lower.expression1;
-        }
-
-        @Override
-        public Expression getLowerBoundary() {
-            return lower.expression2;
-        }
-
-        @Override
-        public Expression getUpperBoundary() {
-            return upper.expression2;
-        }
+        /** Identification of this operation. */
+        @Override public String     getName()          {return NAME;}
+        @Override public Expression getExpression()    {return lower.expression1;}
+        @Override public Expression getLowerBoundary() {return lower.expression2;}
+        @Override public Expression getUpperBoundary() {return upper.expression2;}
 
-        @Override
-        public boolean evaluate(Object object) {
+        /** Execute the filter like and AND operation. */
+        @Override public boolean evaluate(final Object object) {
             return lower.evaluate(object) && upper.evaluate(object);
         }
 
-        @Override
-        public Object accept(FilterVisitor visitor, Object extraData) {
+        /** Implementation of the visitor pattern (not used by Apache SIS). */
+        @Override public Object accept(FilterVisitor visitor, Object extraData) {
             return visitor.visit(this, extraData);
         }
-
     }
 }
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/DefaultFilterFactory.java
b/core/sis-feature/src/main/java/org/apache/sis/filter/DefaultFilterFactory.java
index b564dad..c516bc7 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/DefaultFilterFactory.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/DefaultFilterFactory.java
@@ -22,7 +22,6 @@ import java.util.List;
 import java.util.Map;
 import java.util.ServiceLoader;
 import java.util.Set;
-
 import org.opengis.filter.*;
 import org.opengis.filter.capability.*;
 import org.opengis.filter.expression.Add;
@@ -63,8 +62,6 @@ import org.apache.sis.internal.feature.Resources;
 import org.apache.sis.internal.filter.sqlmm.SQLMM;
 import org.apache.sis.referencing.CRS;
 import org.apache.sis.util.collection.BackingStoreException;
-
-import org.apache.sis.geometry.GeneralEnvelope;
 import org.apache.sis.geometry.ImmutableEnvelope;
 
 
@@ -102,9 +99,9 @@ public class DefaultFilterFactory implements FilterFactory2 {
     }
 
     /**
-     * According to OGC Filter encoding v2.0, comparison operators should default to cas
sensitive comparison. We'll
-     * use this constant to model it, so it will be easier to change default value is the
standard evolves.
-     * Doc reference : OGC 09-026r1 and ISO 19143:2010(E), section 7.7.3.2
+     * According to OGC Filter encoding v2.0, comparison operators should default to case
sensitive comparison.
+     * We use this constant to model it, so it will be easier to change default value if
the standard evolves.
+     * Documentation reference: OGC 09-026r1 and ISO 19143:2010(E), section 7.7.3.2.
      */
     private static final boolean DEFAULT_MATCH_CASE = true;
 
@@ -142,26 +139,27 @@ public class DefaultFilterFactory implements FilterFactory2 {
      * {@inheritDoc}
      */
     @Override
-    public BBOX bbox(final Expression e, final double minx, final double miny,
-            final double maxx, final double maxy, final String srs)
+    public BBOX bbox(final Expression e,
+                     final double minx, final double miny,
+                     final double maxx, final double maxy, final String srs)
     {
-        final CoordinateReferenceSystem crs = readCrs(srs);
-        final GeneralEnvelope env = new GeneralEnvelope(2);
-        env.setEnvelope(minx, miny, maxx, maxy);
-        if (crs != null) env.setCoordinateReferenceSystem(crs);
-        return bbox(e, new ImmutableEnvelope(env));
+        final CoordinateReferenceSystem crs = decodeCRS(srs);
+        return bbox(e, new ImmutableEnvelope(new double[] {minx, miny},
+                                             new double[] {maxx, maxy}, crs));
     }
 
     /**
-     * Try to decode a full {@link CoordinateReferenceSystem} from given text. First, we
try to interpret it as a code,
-     * and if it fails, we try to read it as a WKT.
+     * Tries to decode a full {@link CoordinateReferenceSystem} from given text.
+     * First, we try to interpret it as a code, and if it fails, we try to read it as a WKT.
      *
-     * @param srs The text describing the system. If null or blank, a null value is returned.
-     * @return Possible null value if input text is empty.
-     * @throws BackingStoreException If an error occurs while decoding the text.
+     * @param  srs  the text describing the reference system. If null or blank, a null value
is returned.
+     * @return possible null value if input text is empty or blank.
+     * @throws BackingStoreException if an error occurs while decoding the text.
      */
-    private static CoordinateReferenceSystem readCrs(String srs) {
-        if (srs == null || (srs = srs.trim()).isEmpty()) return null;
+    private static CoordinateReferenceSystem decodeCRS(String srs) {
+        if (srs == null || (srs = srs.trim()).isEmpty()) {
+            return null;
+        }
         try {
             return CRS.forCode(srs);
         } catch (NoSuchAuthorityCodeException e) {
@@ -515,7 +513,7 @@ public class DefaultFilterFactory implements FilterFactory2 {
      */
     @Override
     public PropertyIsGreaterThan greater(final Expression expression1, final Expression expression2)
{
-        return greater(expression1,expression2,DEFAULT_MATCH_CASE, MatchAction.ANY);
+        return greater(expression1, expression2, DEFAULT_MATCH_CASE, MatchAction.ANY);
     }
 
     /**
@@ -533,7 +531,7 @@ public class DefaultFilterFactory implements FilterFactory2 {
      */
     @Override
     public PropertyIsGreaterThanOrEqualTo greaterOrEqual(final Expression expression1, final
Expression expression2) {
-        return greaterOrEqual(expression1, expression2,DEFAULT_MATCH_CASE, MatchAction.ANY);
+        return greaterOrEqual(expression1, expression2, DEFAULT_MATCH_CASE, MatchAction.ANY);
     }
 
     /**
@@ -597,7 +595,7 @@ public class DefaultFilterFactory implements FilterFactory2 {
     public PropertyIsLike like(final Expression expression, final String pattern,
             final String wildcard, final String singleChar, final String escape)
     {
-        return like(expression,pattern,wildcard,singleChar,escape,DEFAULT_MATCH_CASE);
+        return like(expression, pattern, wildcard, singleChar, escape, DEFAULT_MATCH_CASE);
     }
 
     /**
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/LogicalFunction.java b/core/sis-feature/src/main/java/org/apache/sis/filter/LogicalFunction.java
index caea1af..9d2e925 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/LogicalFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/LogicalFunction.java
@@ -94,6 +94,8 @@ abstract class LogicalFunction extends Node {
 
     /**
      * The "And" operation (⋀).
+     *
+     * @see org.apache.sis.filter.ComparisonFunction.Between
      */
     static final class And extends LogicalFunction implements org.opengis.filter.And {
         /** For cross-version compatibility. */
@@ -105,7 +107,7 @@ abstract class LogicalFunction extends Node {
         }
 
         /** Returns a name for this filter. */
-        @Override public String getName() {return "And";}
+        @Override public    String getName() {return "And";}
         @Override protected char   symbol()  {return filters.length <= 2 ? '∧' : '⋀';}
 
         /** Implementation of the visitor pattern. */
@@ -138,7 +140,7 @@ abstract class LogicalFunction extends Node {
         }
 
         /** Returns a name for this filter. */
-        @Override public String getName() {return "Or";}
+        @Override public    String getName() {return "Or";}
         @Override protected char   symbol()  {return filters.length <= 2 ? '∨' : '⋁';}
 
         /** Implementation of the visitor pattern. */
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/TemporalFunction.java b/core/sis-feature/src/main/java/org/apache/sis/filter/TemporalFunction.java
index 7fb081a..65c7cc7 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/TemporalFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/TemporalFunction.java
@@ -27,7 +27,6 @@ import org.opengis.temporal.Period;
 import org.apache.sis.math.Fraction;
 
 
-
 /**
  * Temporal operations between a period and an instant.
  * The nature of the operation depends on the subclass.
@@ -221,7 +220,7 @@ abstract class TemporalFunction extends BinaryFunction implements BinaryTemporal
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '=';}
 
         /** Condition defined by ISO 19108:2002 §5.2.3.5. */
@@ -266,7 +265,7 @@ abstract class TemporalFunction extends BinaryFunction implements BinaryTemporal
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '<';}
 
         /** Condition defined by ISO 19108:2002 §5.2.3.5. */
@@ -309,7 +308,7 @@ abstract class TemporalFunction extends BinaryFunction implements BinaryTemporal
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '>';}
 
         /** Condition defined by ISO 19108:2002 §5.2.3.5. */
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/UnaryFunction.java b/core/sis-feature/src/main/java/org/apache/sis/filter/UnaryFunction.java
index b5a1a49..76d5474 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/UnaryFunction.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/UnaryFunction.java
@@ -19,11 +19,11 @@ package org.apache.sis.filter;
 import java.io.Serializable;
 import java.util.Collection;
 import java.util.Collections;
-import org.apache.sis.internal.filter.Node;
 import org.apache.sis.util.ArgumentChecks;
-import org.opengis.filter.Filter;
+import org.apache.sis.internal.filter.Node;
 
 // Branch-dependent imports
+import org.opengis.filter.Filter;
 import org.opengis.filter.FilterVisitor;
 import org.opengis.filter.expression.Expression;
 
@@ -113,7 +113,7 @@ abstract class UnaryFunction extends Node implements Serializable {
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return NAME;}
+        @Override public    String getName() {return NAME;}
         @Override protected char   symbol()  {return '∅';}
 
         /** Returns {@code true} if the given value evaluates to {@code null}. */
@@ -145,7 +145,7 @@ abstract class UnaryFunction extends Node implements Serializable {
         }
 
         /** Identification of this operation. */
-        @Override public String getName() {return "Not";}
+        @Override public    String getName() {return "Not";}
         @Override protected char   symbol()  {return '¬';}
 
         /** Returns the singleton filter used by this operation. */
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java b/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
index 1846bc2..8009048 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
@@ -25,52 +25,51 @@
  *     <li><a href="http://docs.opengeospatial.org/is/09-026r2/09-026r2.html">OGC®
Filter Encoding 2.0 Encoding Standard</a></li>
  * </ul>
  *
- * <div class="section">General considerations:</div>
- * <div class="section">Coordinate reference system handling:</div>
+ * <h2>General considerations:</h2>
+ * <h3>Coordinate reference system handling:</h3>
  * As stated by Filter encoding 2.0.2, section 7.8.4, heterogeneous coordinate reference
systems must be handled by
  * libraries, one way or another. The standard does not define any strategy. As Apache-SIS
contains a powerful
- * transform system, we'll try to handle differences in the following way:
+ * transform system, we try to handle differences in the following way:
  * <ul>
- *     <li>
- *         If all evaluated geometries define a srid, but their not the same, we'll try to
project them in a common
- *         space. The strategy will be guided by {@link org.apache.sis.referencing.CRS#suggestCommonTarget(org.opengis.metadata.extent.GeographicBoundingBox,
org.opengis.referencing.crs.CoordinateReferenceSystem...) Referencing utility method}.
- *         If it cannot provide a common space, we will fail any ongoing operation.
- *     </li>
- *     <li>
- *         Missing information:
- *         <ul>
- *              <li>If no geometry contains any srid, consider they're defined in the
same space, and proceed</li>
- *              <li>If one geometry define a CRS but the other do not, consider that
an ambiguity resides: fail.</li>
- *         </ul>
- *     </li>
+ *   <li>
+ *     If all evaluated geometries define a {@code srid}, but they are not the same, we try
to project them in a common space.
+ *     The strategy is guided by {@linkplain org.apache.sis.referencing.CRS#suggestCommonTarget
Referencing utility method}.
+ *     If it cannot provide a common space, we fail any ongoing operation.
+ *   </li><li>
+ *     Missing information:
+ *     <ul>
+ *       <li>If no geometry contains any {@code srid}, consider they are defined in
the same space, and proceed.</li>
+ *       <li>If one geometry define a CRS but the other do not, consider that an ambiguity
resides: fail.</li>
+ *     </ul>
+ *   </li>
  * </ul>
  *
- * <div class="section">Optimisations</div>
- * For now, few to no optimisation is done in the operators. Most of important ones would
require one of the two
- * following things:
+ * <h2>Optimizations</h2>
+ * For now, few to no optimization is done in the operators.
+ * Most important ones would require one of the two following things:
  * <ul>
- *     <li>
- *         Context information: Filters does not know in advance the feature type they're
operating upon, which is
- *         vital to define some calculus parameters, as property value conversion strategy,
spatial system changes, etc.
- *         Such information would allow operators to prepare data at initialisation time.
- *     </li>
- *     <li>
- *         User hints: some operations could be set faster at the cost of precision. To activate
such things, it would
- *         require user consent. Most naïve example is spatial reference system conversion,
which could be de-activated
- *         for systems with nearly equal parameters (see {@link org.apache.sis.util.Utilities#equalsApproximately(java.lang.Object,
java.lang.Object)}.
- *     </li>
+ *   <li>
+ *     Context information: Filters does not know in advance the feature type they are operating
upon,
+ *     which is essential to define some calculus parameters, as property value conversion
strategy,
+ *     spatial system changes, <i>etc.</i>
+ *     Such information would allow operators to prepare data at initialization time.
+ *   </li><li>
+ *     User hints: some operations could be set faster at the cost of precision. To activate
such things, it would
+ *     require user consent. Most naive example is spatial reference system conversion, which
could be de-activated
+ *     for systems with nearly equal parameters (see {@link org.apache.sis.util.Utilities#equalsApproximately(Object,
Object)}.
+ *   </li>
  * </ul>
  *
- * <div class="section">Thread-safety</div>
- * <p>All filter and expression implementations provided by Apache SIS are thread-safe.
+ * <h2>Thread-safety</h2>
+ * All filter and expression implementations provided by Apache SIS are thread-safe.
  * They are not necessarily stateless however; for example a filter may remember which
- * warnings have been reported in order to avoid to report the same warning twice.</p>
+ * warnings have been reported in order to avoid to report the same warning twice.
  *
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
  * @version 1.1
  *
- * @since 1.0
+ * @since 1.1
  * @module
  */
 package org.apache.sis.filter;
diff --git a/core/sis-feature/src/main/java/org/apache/sis/internal/filter/Node.java b/core/sis-feature/src/main/java/org/apache/sis/internal/filter/Node.java
index 7fd8b35..e3057b1 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/internal/filter/Node.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/internal/filter/Node.java
@@ -61,6 +61,7 @@ public abstract class Node implements Serializable {
      * Creates an attribute type for values of the given type and name.
      * The attribute is mandatory, unbounded and has no default value.
      *
+     * @param  <T>   compile-time value of {@code type}.
      * @param  type  type of values in the attribute.
      * @param  name  name of the attribute to create.
      * @return an attribute of the given type and name.
@@ -151,6 +152,9 @@ public abstract class Node implements Serializable {
 
     /**
      * Returns {@code true} if the given object is an instance of the same class with the
equal children.
+     *
+     * @param  other  the other object to compare with this node.
+     * @return whether the two object are equal.
      */
     @Override
     public boolean equals(final Object other) {
@@ -164,11 +168,13 @@ public abstract class Node implements Serializable {
      * Reports that an operation failed because of the given exception.
      * This method assumes that the warning occurred in an {@code evaluate(…)} method.
      *
+     * @param  e  the exception that occurred.
+     *
      * @todo Consider defining a {@code Context} class providing, among other information,
listeners where to report warnings.
      *
      * @see <a href="https://issues.apache.org/jira/browse/SIS-460">SIS-460</a>
      */
-    public final void warning(final Exception e) {
+    protected final void warning(final Exception e) {
         Logging.recoverableException(Logging.getLogger(Loggers.FILTER), getClass(), "evaluate",
e);
     }
 }
diff --git a/core/sis-feature/src/main/java/org/apache/sis/internal/filter/package-info.java
b/core/sis-feature/src/main/java/org/apache/sis/internal/filter/package-info.java
new file mode 100644
index 0000000..915385a
--- /dev/null
+++ b/core/sis-feature/src/main/java/org/apache/sis/internal/filter/package-info.java
@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Base implementation shared by the main {@code filter} package and the SQLMM extension.
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 1.1
+ * @since   1.1
+ * @module
+ */
+package org.apache.sis.internal.filter;


Mime
View raw message