[sis] 01/02: Add a warning about possible future API change. https://issues.apache.org/jira/browse/SIS-560

[de...@apache.org]

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

commit 09d94c2c6c3b41afc128ef82ae53fffbd53c1f1c
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Tue Dec 6 14:32:29 2022 +0100

    Add a warning about possible future API change.
    https://issues.apache.org/jira/browse/SIS-560
---
 .../main/java/org/apache/sis/storage/WritableFeatureSet.java   | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
index ccb5b982b6..4dbeb53985 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
@@ -81,6 +81,16 @@ public interface WritableFeatureSet extends FeatureSet {
     /**
      * Removes all feature instances from this {@code FeatureSet} which matches the given predicate.
      *
+     * <div class="warning"><b>Possible API change:</b>
+     * The {@code boolean} return type may be removed in a future version.
+     * It currently exists for compatibility with the {@link java.util.Collection#removeIf(Predicate)} method
+     * if an implementation chooses to implements {@code WritableFeatureSet} and {@link java.util.Collection}
+     * in same time. But this is not recommended, and the current method signature is a blocker for deferred
+     * method execution. Telling if there is any feature to remove requires immediate execution of the filter,
+     * while an implementation may want to wait in case the filtering can be combined with other operations
+     * such as {@code add(…)} or {@code replaceIf(…)}.
+     * See <a href="https://issues.apache.org/jira/browse/SIS-560">SIS-560 on issue tracker</a>.</div>
+     *
      * @param  filter  a predicate which returns {@code true} for feature instances to be removed.
      * @return {@code true} if any elements were removed.
      * @throws DataStoreException if an error occurred while removing features.