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 debfbf7 Give protected access to `execute(…)` methods in query
subclasses. This change provides an extension point for more specialized
queries.
debfbf7 is described below
commit debfbf7fab07ec7966015c3678b2445a334e2827
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Sun Oct 24 10:34:36 2021 +0200
Give protected access to `execute(…)` methods in query subclasses.
This change provides an extension point for more specialized queries.
---
.../java/org/apache/sis/storage/CoverageQuery.java | 12 +++++++++---
.../java/org/apache/sis/storage/FeatureQuery.java | 19 +++++++++++++------
.../main/java/org/apache/sis/storage/FeatureSet.java | 12 +++++++++---
.../org/apache/sis/storage/GridCoverageResource.java | 9 +++++++--
.../java/org/apache/sis/storage/package-info.java | 2 +-
5 files changed, 39 insertions(+), 15 deletions(-)
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/CoverageQuery.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/CoverageQuery.java
index e6ec06d..9692af6 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/CoverageQuery.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/CoverageQuery.java
@@ -56,7 +56,7 @@ import org.apache.sis.util.resources.Vocabulary;
*
* @author Johann Sorel (Geomatys)
* @author Martin Desruisseaux (Geomatys)
- * @version 1.1
+ * @version 1.2
* @since 1.1
* @module
*/
@@ -258,13 +258,19 @@ next: for (int i=0; i<rangeNames.length; i++) {
}
/**
- * Applies this query on the given coverage.
+ * Applies this query on the given coverage resource.
+ * This method is invoked by the default implementation of {@link
GridCoverageResource#subset(Query)}.
*
* @param source the coverage resource to filter.
* @return a view over the given coverage resource containing only the
given domain and range.
* @throws DataStoreException if an error occurred during creation of the
subset.
+ *
+ * @see GridCoverageResource#subset(CoverageQuerty)
+ * @see FeatureQuery#execute(FeatureSet)
+ *
+ * @since 1.2
*/
- final GridCoverageResource execute(final GridCoverageResource source)
throws DataStoreException {
+ protected GridCoverageResource execute(final GridCoverageResource source)
throws DataStoreException {
ArgumentChecks.ensureNonNull("source", source);
final CoverageQuery query = clone();
query.namesToIndices(source);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureQuery.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureQuery.java
index c2b4e6c..ffee909 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureQuery.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureQuery.java
@@ -72,7 +72,7 @@ import org.opengis.filter.InvalidFilterValueException;
*
* @author Johann Sorel (Geomatys)
* @author Martin Desruisseaux (Geomatys)
- * @version 1.1
+ * @version 1.2
* @since 1.1
* @module
*/
@@ -533,10 +533,12 @@ public class FeatureQuery extends Query implements
Cloneable, Serializable {
}
/**
- * Applies this query on the given feature set. The default implementation
executes the query using the default
- * {@link java.util.stream.Stream} methods. Queries executed by this
method may not benefit from accelerations
- * provided for example by databases. This method should be used only as a
fallback when the query can not be
- * executed natively by {@link FeatureSet#subset(Query)}.
+ * Applies this query on the given feature set.
+ * This method is invoked by the default implementation of {@link
FeatureSet#subset(Query)}.
+ * The default implementation executes the query using the default {@link
java.util.stream.Stream} methods.
+ * Queries executed by this method may not benefit from accelerations
provided for example by databases.
+ * This method should be used only as a fallback when the query can not be
executed natively
+ * by {@link FeatureSet#subset(Query)}.
*
* <p>The returned {@code FeatureSet} does not cache the resulting {@code
Feature} instances;
* the query is processed on every call to the {@link
FeatureSet#features(boolean)} method.</p>
@@ -544,8 +546,13 @@ public class FeatureQuery extends Query implements
Cloneable, Serializable {
* @param source the set of features to filter, sort or process.
* @return a view over the given feature set containing only the filtered
feature instances.
* @throws DataStoreException if an error occurred during creation of the
subset.
+ *
+ * @see FeatureSet#subset(Query)
+ * @see CoverageQuery#execute(GridCoverageResource)
+ *
+ * @since 1.2
*/
- final FeatureSet execute(final FeatureSet source) throws
DataStoreException {
+ protected FeatureSet execute(final FeatureSet source) throws
DataStoreException {
ArgumentChecks.ensureNonNull("source", source);
final FeatureQuery query = clone();
if (query.selection != null) {
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
index fc97a9c..286739b 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
@@ -93,15 +93,21 @@ public interface FeatureSet extends DataSet {
* However the returned subset may not have the same capabilities as this
{@link FeatureSet}.
* In particular, write operations may become unsupported after complex
queries.</p>
*
- * <p>The default implementation tries to execute the query by filtering
the {@linkplain #features(boolean) stream of features},
- * which may be inefficient — subclasses are encouraged to override. An
{@link UnsupportedQueryException} is thrown if the given
- * query is unrecognized.</p>
+ * <h4>Default implementation</h4>
+ * The default implementation delegates to {@link
FeatureQuery#execute(FeatureSet)} if the given query
+ * is an instance of {@code FeatureQuery}, or throws {@link
UnsupportedQueryException} otherwise.
+ * The default {@code FeatureQuery} implementation tries to execute the
query
+ * by filtering the {@linkplain #features(boolean) stream of features},
+ * which may be inefficient — subclasses are encouraged to override this
{@code subset(Query)} method.
*
* @param query definition of feature and feature properties filtering
applied at reading time.
* @return resulting subset of features (never {@code null}).
* @throws UnsupportedQueryException if this {@code FeatureSet} can not
execute the given query.
* This includes query validation errors.
* @throws DataStoreException if another error occurred while processing
the query.
+ *
+ * @see GridCoverageResource#subset(CoverageQuerty)
+ * @see FeatureQuery#execute(FeatureSet)
*/
default FeatureSet subset(Query query) throws UnsupportedQueryException,
DataStoreException {
ArgumentChecks.ensureNonNull("query", query);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
index ce2fe89..c135a49 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
@@ -120,14 +120,19 @@ public interface GridCoverageResource extends DataSet {
* However the returned subset may not have the same capabilities as this
{@link GridCoverageResource}.
* In particular, write operations may become unsupported after complex
queries.</p>
*
- * <p>The default implementation throws {@link
UnsupportedQueryException}.</p>
+ * <h4>Default implementation</h4>
+ * The default implementation delegates to {@link
CoverageQuery#execute(GridCoverageResource)} if the given
+ * query is an instance of {@code CoverageQuery}, or throws {@link
UnsupportedQueryException} otherwise.
*
* @param query definition of domain (grid extent) and range (sample
dimensions) filtering applied at reading time.
* @return resulting coverage resource (never {@code null}).
- * @throws UnsupportedQueryException if this {@code GridCoverageResource}
can not execute the given query.
+ * @throws UnsupportedQueryException if the given query is not valid for
this {@code GridCoverageResource}.
* This includes query validation errors.
* @throws DataStoreException if another error occurred while processing
the query.
*
+ * @see FeatureSet#subset(Query)
+ * @see CoverageQuery#execute(GridCoverageResource)
+ *
* @since 1.1
*/
default GridCoverageResource subset(final Query query) throws
UnsupportedQueryException, DataStoreException {
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
index f4ad848..8928ed7 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
@@ -26,7 +26,7 @@
*
* @author Johann Sorel (Geomatys)
* @author Martin Desruisseaux (Geomatys)
- * @version 1.1
+ * @version 1.2
* @since 0.3
* @module
*/
