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 e1aab234bfd82ebe7e9454ff655d1e57f819a809
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Fri Sep 3 10:08:12 2021 +0200
Document better the purpose of the "parent" list of listeners.
---
.../main/java/org/apache/sis/metadata/iso/ISOMetadata.java | 8 ++++----
.../org/apache/sis/internal/storage/AbstractFeatureSet.java | 2 ++
.../apache/sis/internal/storage/AbstractGridResource.java | 2 ++
.../org/apache/sis/internal/storage/AbstractResource.java | 5 ++++-
.../apache/sis/internal/storage/AggregatedFeatureSet.java | 2 ++
.../org/apache/sis/internal/storage/TiledGridResource.java | 2 ++
.../apache/sis/internal/storage/query/CoverageSubset.java | 2 +-
.../java/org/apache/sis/storage/event/StoreListeners.java | 12 +++++++++---
8 files changed, 26 insertions(+), 9 deletions(-)
diff --git
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ISOMetadata.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ISOMetadata.java
index 90d22a0..45fb40c 100644
---
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ISOMetadata.java
+++
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/ISOMetadata.java
@@ -93,10 +93,10 @@ public class ISOMetadata extends ModifiableMetadata
implements IdentifiedObject,
if (object instanceof IdentifiedObject) {
if (object instanceof ISOMetadata &&
Containers.isNullOrEmpty(((ISOMetadata) object).identifiers)) {
/*
- * If the other object is an ISOMetadata instance, take a
look at its 'identifiers' collection
+ * If the other object is an ISOMetadata instance, take a
look at its `identifiers` collection
* before to invoke object.getIdentifiers() in order to avoid
unnecessary initialization of its
* backing collection. We do this optimization because the
vast majority of metadata objects do
- * not have 'identifiers' collection.
+ * not have `identifiers` collection.
*
* Actually this optimization is a little bit dangerous, since
users could override getIdentifiers()
* without invoking super.getIdentifiers(), in which case
their identifiers will not be copied.
@@ -176,7 +176,7 @@ public class ISOMetadata extends ModifiableMetadata
implements IdentifiedObject,
}
/*
* We do not cache (for now) the IdentifierMap because it is cheap to
create, and if we were
- * caching it we would need anyway to check if 'identifiers' still
references the same list.
+ * caching it we would need anyway to check if `identifiers` still
references the same list.
*/
return (super.state() != State.FINAL) ? new
ModifiableIdentifierMap(identifiers)
: new
IdentifierMapAdapter(identifiers);
@@ -228,7 +228,7 @@ public class ISOMetadata extends ModifiableMetadata
implements IdentifiedObject,
final boolean changed = super.transitionTo(target);
if (changed) {
/*
- * The 'identifiers' collection will have been replaced by an
unmodifiable collection if
+ * The `identifiers` collection will have been replaced by an
unmodifiable collection if
* subclass has an "identifiers" property. If this is not the
case, then the collection
* is unchanged (or null) so we have to make it unmodifiable here.
*/
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
index 910a6be..5952636 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
@@ -55,6 +55,8 @@ public abstract class AbstractFeatureSet extends
AbstractResource implements Fea
* Creates a new resource.
*
* @param parent listeners of the parent resource, or {@code null} if
none.
+ * This is usually the listeners of the {@link
org.apache.sis.storage.DataStore}
+ * that created this resource.
*/
protected AbstractFeatureSet(final StoreListeners parent) {
super(parent);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
index fe5b1ce..3706455 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
@@ -81,6 +81,8 @@ public abstract class AbstractGridResource extends
AbstractResource implements G
* Creates a new resource.
*
* @param parent listeners of the parent resource, or {@code null} if
none.
+ * This is usually the listeners of the {@link
org.apache.sis.storage.DataStore}
+ * that created this resource.
*/
protected AbstractGridResource(final StoreListeners parent) {
super(parent);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
index c2def88..83ba7bf 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
@@ -64,9 +64,12 @@ public class AbstractResource extends StoreListeners
implements Resource {
private Metadata metadata;
/**
- * Creates a new resource.
+ * Creates a new resource. This resource will have its own set of
listeners,
+ * but the listeners of the data store that created this resource will be
notified as well.
*
* @param parent listeners of the parent resource, or {@code null} if
none.
+ * This is usually the listeners of the {@link
org.apache.sis.storage.DataStore}
+ * that created this resource.
*/
public AbstractResource(final StoreListeners parent) {
super(parent, null);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AggregatedFeatureSet.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AggregatedFeatureSet.java
index 5b48f15..7879855 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AggregatedFeatureSet.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AggregatedFeatureSet.java
@@ -63,6 +63,8 @@ abstract class AggregatedFeatureSet extends
AbstractFeatureSet {
* Creates a new aggregated feature set.
*
* @param parent listeners of the parent resource, or {@code null} if
none.
+ * This is usually the listeners of the {@link
org.apache.sis.storage.DataStore}
+ * that created this resource.
*/
protected AggregatedFeatureSet(final StoreListeners parent) {
super(parent);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TiledGridResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TiledGridResource.java
index 1d6f1ea..0a2bad4 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TiledGridResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TiledGridResource.java
@@ -120,6 +120,8 @@ public abstract class TiledGridResource extends
AbstractGridResource {
* Creates a new resource.
*
* @param parent listeners of the parent resource, or {@code null} if
none.
+ * This is usually the listeners of the {@link
org.apache.sis.storage.DataStore}
+ * that created this resource.
*/
protected TiledGridResource(final StoreListeners parent) {
super(parent);
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/query/CoverageSubset.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/query/CoverageSubset.java
index 09ee469..eb0a1a4 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/query/CoverageSubset.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/query/CoverageSubset.java
@@ -47,7 +47,7 @@ import org.apache.sis.internal.util.UnmodifiableArrayList;
*/
final class CoverageSubset extends AbstractGridResource {
/**
- * The coverage resource instances which provides the data.
+ * The coverage resource instance which provides the data.
*/
private final GridCoverageResource source;
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/event/StoreListeners.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/event/StoreListeners.java
index 55d3d69..8943dc6 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/event/StoreListeners.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/event/StoreListeners.java
@@ -53,8 +53,9 @@ import org.apache.sis.storage.Resource;
* When a warning is emitted, the default behavior is:
*
* <ul>
- * <li>Notify all listeners registered for {@link WarningEvent} type
- * in this {@code StoreListeners} and in the parent managers.</li>
+ * <li>Notify all listeners that are registered for a given {@link
WarningEvent} type in this {@code StoreListeners}
+ * and in the parent resource or data store. Each listener will be
notified only once, even if the same listener
+ * is registered in two or more places.</li>
* <li>If previous step found no listener registered for {@code
WarningEvent},
* then log the warning in the first logger found in following choices:
* <ol>
@@ -79,6 +80,7 @@ import org.apache.sis.storage.Resource;
public class StoreListeners implements Localized {
/**
* Parent manager to notify in addition to this manager.
+ * This is used when a data store is created for reading components of a
larger data store.
*/
private final StoreListeners parent;
@@ -205,7 +207,11 @@ public class StoreListeners implements Localized {
/**
* Creates a new instance with the given parent and initially no listener.
- * The parent is typically the listeners of the {@link DataStore} that
created a resource.
+ * The parent is typically the {@linkplain DataStore#listeners listeners}
+ * of the {@link DataStore} that created a resource.
+ * When an event is {@linkplain #fire fired}, listeners registered in the
parent
+ * will be notified as well as listeners registered in this {@code
StoreListeners}.
+ * Each listener will be notified only once even if it has been registered
in two places.
*
* @param parent the manager to notify in addition to this manager, or
{@code null} if none.
* @param source the source of events. Can not be null.
