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 5338f09716 Try to clarify the meaning of the `hidden` argument in
`AbstractResource(StoreListeners parentListeners, boolean hidden)`.
5338f09716 is described below
commit 5338f09716e744e8933f257619541290fb47d1ee
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Mon Oct 27 16:17:28 2025 +0100
Try to clarify the meaning of the `hidden` argument in
`AbstractResource(StoreListeners parentListeners, boolean hidden)`.
---
.../sis/storage/netcdf/base/RasterResource.java | 4 +--
.../org/apache/sis/storage/AbstractFeatureSet.java | 11 ++-----
.../sis/storage/AbstractGridCoverageResource.java | 11 ++-----
.../org/apache/sis/storage/AbstractResource.java | 29 ++++++++---------
.../sis/storage/aggregate/AggregatedResource.java | 21 ++++++------
.../aggregate/BandAggregateGridResource.java | 7 ++--
.../sis/storage/aggregate/CoverageAggregator.java | 2 +-
.../org/apache/sis/storage/aggregate/Group.java | 9 ++---
.../sis/storage/aggregate/GroupAggregate.java | 6 ++--
.../apache/sis/storage/base/PseudoResource.java | 38 ++++++++--------------
10 files changed, 58 insertions(+), 80 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.storage.netcdf/main/org/apache/sis/storage/netcdf/base/RasterResource.java
b/endorsed/src/org.apache.sis.storage.netcdf/main/org/apache/sis/storage/netcdf/base/RasterResource.java
index ebc6c4e9ab..7f71230fc2 100644
---
a/endorsed/src/org.apache.sis.storage.netcdf/main/org/apache/sis/storage/netcdf/base/RasterResource.java
+++
b/endorsed/src/org.apache.sis.storage.netcdf/main/org/apache/sis/storage/netcdf/base/RasterResource.java
@@ -43,13 +43,13 @@ import
org.apache.sis.util.internal.shared.UnmodifiableArrayList;
import org.apache.sis.util.internal.shared.Strings;
import org.apache.sis.coverage.SampleDimension;
import org.apache.sis.coverage.IllegalSampleDimensionException;
-import org.apache.sis.coverage.internal.shared.RangeArgument;
-import org.apache.sis.image.internal.shared.RasterFactory;
import org.apache.sis.coverage.grid.GridExtent;
import org.apache.sis.coverage.grid.GridCoverage;
import org.apache.sis.coverage.grid.GridGeometry;
import org.apache.sis.coverage.grid.GridDerivation;
import org.apache.sis.coverage.grid.GridRoundingMode;
+import org.apache.sis.coverage.internal.shared.RangeArgument;
+import org.apache.sis.image.internal.shared.RasterFactory;
import org.apache.sis.math.MathFunctions;
import org.apache.sis.measure.MeasurementRange;
import org.apache.sis.measure.NumberRange;
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractFeatureSet.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractFeatureSet.java
index 56ca92126d..b3a0c166ca 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractFeatureSet.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractFeatureSet.java
@@ -63,15 +63,8 @@ public abstract class AbstractFeatureSet extends
AbstractResource implements Fea
/**
* Creates a new resource which can send notifications to the given set of
listeners.
- * If {@code hidden} is {@code false} (the recommended value), then this
resource will have its own set of
- * listeners with this resource declared as the {@linkplain
StoreListeners#getSource() source of events}.
- * It will be possible to add and remove listeners independently from the
set of parent listeners.
- * Conversely if {@code hidden} is {@code true}, then the given listeners
will be used directly
- * and this resource will not appear as the source of any event.
- *
- * <p>In any cases, the listeners of all parents (ultimately the data
store that created this resource)
- * will always be notified, either directly if {@code hidden} is {@code
true}
- * or indirectly if {@code hidden} is {@code false}.</p>
+ * The {@code hidden} argument specifies whether the new resource should
be invisible in the tree of resources.
+ * See the {@linkplain AbstractResource#AbstractResource(StoreListeners,
boolean) parent constructor} for more information.
*
* @param parentListeners listeners of the parent resource, or {@code
null} if none.
* This is usually the listeners of the {@link DataStore} that
created this resource.
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractGridCoverageResource.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractGridCoverageResource.java
index 9bd98bfc3f..ee56cc1167 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractGridCoverageResource.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractGridCoverageResource.java
@@ -78,15 +78,8 @@ public abstract class AbstractGridCoverageResource extends
AbstractResource impl
/**
* Creates a new resource which can send notifications to the given set of
listeners.
- * If {@code hidden} is {@code false} (the recommended value), then this
resource will have its own set of
- * listeners with this resource declared as the {@linkplain
StoreListeners#getSource() source of events}.
- * It will be possible to add and remove listeners independently from the
set of parent listeners.
- * Conversely if {@code hidden} is {@code true}, then the given listeners
will be used directly
- * and this resource will not appear as the source of any event.
- *
- * <p>In any cases, the listeners of all parents (ultimately the data
store that created this resource)
- * will always be notified, either directly if {@code hidden} is {@code
true}
- * or indirectly if {@code hidden} is {@code false}.</p>
+ * The {@code hidden} argument specifies whether the new resource should
be invisible in the tree of resources.
+ * See the {@linkplain AbstractResource#AbstractResource(StoreListeners,
boolean) parent constructor} for more information.
*
* @param parentListeners listeners of the parent resource, or {@code
null} if none.
* This is usually the listeners of the {@link DataStore} that
created this resource.
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractResource.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractResource.java
index d64b18401f..7efdf61d4f 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractResource.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/AbstractResource.java
@@ -30,7 +30,6 @@ import org.apache.sis.storage.event.StoreEvent;
import org.apache.sis.storage.event.StoreListener;
import org.apache.sis.storage.event.StoreListeners;
import org.apache.sis.storage.internal.Resources;
-import org.apache.sis.storage.base.PseudoResource;
import org.apache.sis.storage.base.MetadataBuilder;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.logging.Logging;
@@ -77,6 +76,8 @@ public abstract class AbstractResource implements Resource {
/**
* Creates a new resource, potentially as a child of another resource.
* The parent resource is typically, but not necessarily, an {@link
Aggregate}.
+ * Invoking this constructor is equivalent (except for null checks) to
invoking
+ * <code>{@link #AbstractResource(StoreListeners, boolean)
AbstractResource}(parent.listeners, false)</code>.
*
* @param parent the parent resource, or {@code null} if none.
*
@@ -85,14 +86,7 @@ public abstract class AbstractResource implements Resource {
@SuppressWarnings("this-escape")
protected AbstractResource(final Resource parent) {
StoreListeners parentListeners = null;
- if (parent instanceof PseudoResource) { // Internal hack, may
change in any future version.
- final var r = (PseudoResource) parent;
- parentListeners = r.listeners;
- if (parentListeners != null && r.childrenAreHidden) {
- listeners = parentListeners;
- return;
- }
- } else if (parent instanceof AbstractResource) {
+ if (parent instanceof AbstractResource) {
parentListeners = ((AbstractResource) parent).listeners;
} else if (parent instanceof DataStore) {
parentListeners = ((DataStore) parent).listeners;
@@ -101,12 +95,17 @@ public abstract class AbstractResource implements Resource
{
}
/**
- * Creates a new resource which can send notifications to the given set of
listeners.
- * If {@code hidden} is {@code false} (the recommended value), then this
resource will have its own set of
- * listeners with this resource declared as the {@linkplain
StoreListeners#getSource() source of events}.
- * It will be possible to add and remove listeners independently from the
set of parent listeners.
- * Conversely if {@code hidden} is {@code true}, then the given listeners
will be used directly
- * and this resource will not appear as the source of any event.
+ * Creates a new resource which will send notifications, directly or
indirectly, to the given set of listeners.
+ * The {@code hidden} argument specifies whether the new resource should
be invisible in the tree of resources.
+ * The caller may want to hide a resource if, for example, it is a
decorator that delegates most of its work to
+ * the real resource.
+ *
+ * <p>The {@code hidden} argument works as below:
+ * if {@code true}, then the {@code parentListeners} argument will be
assigned directly to the {@link #listeners}
+ * field, unless that argument is {@code null}. Consequently, any event
sent by this resources will appear to the
+ * users as if the event was sent by the parent resource. Conversely if
{@code false}, then this resource will have
+ * its own set of listeners with this resource declared as the {@linkplain
StoreListeners#getSource() source of events}.
+ * In the latter case, listeners can be added or removed independently
from the listeners of the parent resource.</p>
*
* <p>In any cases, the listeners of all parents (ultimately the data
store that created this resource)
* will always be notified, either directly if {@code hidden} is {@code
true}
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/AggregatedResource.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/AggregatedResource.java
index b037d547a7..6483743206 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/AggregatedResource.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/AggregatedResource.java
@@ -28,7 +28,6 @@ import org.apache.sis.storage.AbstractResource;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.event.StoreListeners;
import org.apache.sis.storage.base.MetadataBuilder;
-import org.apache.sis.storage.base.PseudoResource;
import org.apache.sis.geometry.Envelopes;
import org.apache.sis.geometry.ImmutableEnvelope;
import org.apache.sis.util.internal.shared.Strings;
@@ -74,15 +73,6 @@ abstract class AggregatedResource extends AbstractResource {
*/
private boolean envelopeIsEvaluated;
- /**
- * Creates a new concatenated resource as the child of the given resource.
- *
- * @param parent the parent resource, or {@code null} if none.
- */
- AggregatedResource(final PseudoResource parent) {
- super(parent);
- }
-
/**
* Creates a new concatenated resource.
*
@@ -95,6 +85,17 @@ abstract class AggregatedResource extends AbstractResource {
this.name = name;
}
+ /**
+ * Creates a new concatenated resource as the child of the given resource.
+ *
+ * @param parent the parent resource, or {@code null} if none.
+ * @param name name of this aggregate, or {@code null} if none.
+ */
+ AggregatedResource(final Resource parent, final String name) {
+ super(parent);
+ this.name = name;
+ }
+
/**
* Creates a new resource with the same data as given resource.
*
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/BandAggregateGridResource.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/BandAggregateGridResource.java
index 40d122fdf3..beea754900 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/BandAggregateGridResource.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/BandAggregateGridResource.java
@@ -32,7 +32,6 @@ import org.apache.sis.storage.RasterLoadingStrategy;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.MemoryGridCoverageResource;
import org.apache.sis.storage.base.MetadataBuilder;
-import org.apache.sis.storage.base.PseudoResource;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.internal.shared.UnmodifiableArrayList;
@@ -116,11 +115,11 @@ final class BandAggregateGridResource extends
AggregatedResource implements Grid
* @throws IllegalGridGeometryException if a grid geometry is not
compatible with the others.
* @throws IllegalArgumentException if some band indices are duplicated or
outside their range of validity.
*/
- private BandAggregateGridResource(final PseudoResource parent,
+ private BandAggregateGridResource(final Resource parent,
final
BandAggregateArgument<GridCoverageResource> aggregate,
final GridCoverageProcessor processor)
{
- super(parent);
+ super(parent, null);
this.sources = aggregate.sources();
this.gridGeometry =
aggregate.domain(BandAggregateGridResource::domain);
this.sampleDimensions = List.copyOf(aggregate.ranges());
@@ -158,7 +157,7 @@ final class BandAggregateGridResource extends
AggregatedResource implements Grid
* @throws IllegalGridGeometryException if a grid geometry is not
compatible with the others.
* @throws IllegalArgumentException if some band indices are duplicated or
outside their range of validity.
*/
- static GridCoverageResource create(final PseudoResource parent,
+ static GridCoverageResource create(final Resource parent,
GridCoverageResource[] sources, int[][] bandsPerSource,
final GridCoverageProcessor processor) throws DataStoreException
{
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/CoverageAggregator.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/CoverageAggregator.java
index 92c3203e0a..8c39f0b6d3 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/CoverageAggregator.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/CoverageAggregator.java
@@ -193,7 +193,7 @@ public final class CoverageAggregator extends
Group<GroupBySample> {
* Returns this aggregator as a pseudo-resource, used only for passing the
listeners.
*/
private PseudoResource asPseudoResource() {
- return new PseudoResource(listeners, false);
+ return new PseudoResource(listeners);
}
/**
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/Group.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/Group.java
index 21cd795f77..c586d86edb 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/Group.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/Group.java
@@ -22,6 +22,7 @@ import java.util.Map;
import java.util.HashMap;
import java.util.Locale;
import java.util.stream.Stream;
+import org.apache.sis.util.Localized;
import org.apache.sis.util.internal.shared.Strings;
import org.apache.sis.storage.base.ArrayOfLongs;
import org.apache.sis.storage.event.StoreListeners;
@@ -39,7 +40,7 @@ abstract class Group<E> {
/**
* The name of this group, or {@code null} if not yet computed.
*
- * @see #getName(StoreListeners)
+ * @see #getName(Localized)
*/
private String name;
@@ -96,12 +97,12 @@ abstract class Group<E> {
/**
* Returns the name of this group.
*
- * @param listeners listeners from which to get the locale, or {@code
null} for the default.
+ * @param parent the parent resource, or {@code null} if none.
* @return a name which can be used as aggregation name.
*/
- final String getName(final StoreListeners listeners) {
+ final String getName(final Localized parent) {
if (name == null) {
- name = createName(listeners == null ? null :
listeners.getLocale());
+ name = createName(parent != null ? parent.getLocale() : null);
}
return name;
}
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/GroupAggregate.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/GroupAggregate.java
index 3eff0a47cb..c5897639b9 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/GroupAggregate.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/aggregate/GroupAggregate.java
@@ -90,8 +90,10 @@ final class GroupAggregate extends AggregatedResource
implements Aggregate {
* @param components the resources to uses as components of this
aggregate.
* @param sampleDimensions sample dimensions common to all grid coverage
resources.
*/
- GroupAggregate(final String name, final StoreListeners listeners, final
GridCoverageResource[] components,
- final List<SampleDimension> sampleDimensions)
+ GroupAggregate(final String name,
+ final StoreListeners listeners,
+ final GridCoverageResource[] components,
+ final List<SampleDimension> sampleDimensions)
{
super(name, listeners, true);
this.components = components;
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/PseudoResource.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/PseudoResource.java
index 9d14b40547..145edfcd84 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/PseudoResource.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/PseudoResource.java
@@ -16,9 +16,10 @@
*/
package org.apache.sis.storage.base;
-import org.apache.sis.storage.Resource;
+import java.util.Locale;
import org.apache.sis.storage.AbstractResource;
import org.apache.sis.storage.event.StoreListeners;
+import org.apache.sis.util.Localized;
import org.opengis.metadata.Metadata;
@@ -29,35 +30,24 @@ import org.opengis.metadata.Metadata;
*
* @author Martin Desruisseaux (Geomatys)
*/
-public final class PseudoResource implements Resource {
+public final class PseudoResource extends AbstractResource implements
Localized {
/**
- * The listeners that {@link AbstractResource} should take. May be {@code
null}.
- */
- public final StoreListeners listeners;
-
- /**
- * Whether the children of this pseudo-resource should be hidden.
- * If {@code false} (the recommended value), then the children will have
their own set of listeners
- * and each child will be the {@linkplain StoreListeners#getSource()
source of their own events}.
- * It will be possible to add and remove listeners independently from the
set of parent listeners.
- * Conversely if {@code true}, then the {@linkplain #listeners} will be
used directly and the
- * children resource will not appear as the source of any event.
+ * Creates a new instance wrapping the given listeners.
*
- * <p>In any cases, the listeners of all parents (ultimately the data
store that created the resource)
- * will always be notified, either directly if {@code childrenAreHidden}
is {@code true} or indirectly
- * if {@code childrenAreHidden} is {@code false}.</p>
+ * @param listeners the listeners that {@link AbstractResource} should
take, or {@code null}.
*/
- public final boolean childrenAreHidden;
+ public PseudoResource(final StoreListeners listeners) {
+ super(listeners, true);
+ }
/**
- * Creates a new instance wrapping the given resources.
+ * Returns the locale for formatting messages, or {@code null} if
unspecified.
*
- * @param listeners the listeners that {@link AbstractResource}
should take, or {@code null}.
- * @param childrenAreHidden whether the children of this pseudo-resource
should be hidden.
+ * @return the locale for messages (typically specified by the data
store), or {@code null} if unknown.
*/
- public PseudoResource(final StoreListeners listeners, final boolean
childrenAreHidden) {
- this.listeners = listeners;
- this.childrenAreHidden = childrenAreHidden;
+ @Override
+ public Locale getLocale() {
+ return listeners.getLocale();
}
/**
@@ -66,7 +56,7 @@ public final class PseudoResource implements Resource {
* @return {@code null}.
*/
@Override
- public Metadata getMetadata() {
+ protected Metadata createMetadata() {
return null;
}
}
