This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-resource-observation-annotations.git
The following commit(s) were added to refs/heads/master by this push:
new c5c60bf SLING-12249 Clarify that events may be received for ancestors
of the received paths
c5c60bf is described below
commit c5c60bf0b05879c13b4bea691e6f4d51d3c046fa
Author: Konrad Windszus <[email protected]>
AuthorDate: Fri Mar 1 12:51:55 2024 +0100
SLING-12249 Clarify that events may be received for ancestors of the
received paths
That may happen for both "Added" and "Removed"
---
.../annotations/SlingResourceChangeListener.java | 17 ++++++++---------
1 file changed, 8 insertions(+), 9 deletions(-)
diff --git
a/src/main/java/org/apache/sling/resource/observation/annotations/SlingResourceChangeListener.java
b/src/main/java/org/apache/sling/resource/observation/annotations/SlingResourceChangeListener.java
index 440b189..e73692a 100644
---
a/src/main/java/org/apache/sling/resource/observation/annotations/SlingResourceChangeListener.java
+++
b/src/main/java/org/apache/sling/resource/observation/annotations/SlingResourceChangeListener.java
@@ -27,8 +27,7 @@ import
org.osgi.service.component.annotations.ComponentPropertyType;
* <a
href="https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.component.html#service.component-component.property.types";>
* Component Property Type (as defined by OSGi DS 1.4)</a> for Sling
(External)ResourceChangeListener services.
* Takes care of writing the relevant service properties as being used by the
Sling Observation API
- * to register the annotated {@link ResourceChangeListener} or {@link
ExternalResourceChangeListener} DS components
- * with the correct restrictions.
+ * to register the annotated {@link ResourceChangeListener} DS components with
the correct restrictions.
*
* @see ResourceChangeListener
* @see ExternalResourceChangeListener
@@ -59,14 +58,14 @@ public @interface SlingResourceChangeListener {
* </ul>
*
* <p>
- * In general, it can't be guaranteed that the underlying implementation
of the resources will send a remove
- * event for each removed resource. For example if the root of a tree,
like {@code /foo} is removed, the underlying
+ * In general, it can't be guaranteed that the underlying implementation
of the resources will send a remove/add
+ * event for each removed/added resource. For example if the root of a
tree, like {@code /foo} is removed, the underlying
* implementation might only send a single remove event for {@code /foo}
but not for any child resources.
- * Therefore if a listener is interested in resource remove events, it
might get remove events for resources
- * that not directly match the specified pattern/filters. For example if a
listener is registered for {@code /foo/bar}
- * and {@code /foo} is removed, the listener will get a remove event for
{@code /foo}. The same is true if any pattern is used
- * and any parent of a matching resource is removed. If a listener is
interested in
- * remove events, it will get a remove of any parent resource from the
specified paths or patterns. The listener
+ * Similarly for renaming a subtree from {@code /foo} to {@code /bar} the
add event may only be sent for {@code /bar}
+ * but not for any child resources.
+ * Therefore a listener might get remove/add events for resources that not
directly match the specified paths/path patterns.
+ * For example if a listener is registered for path {@code /foo/bar} and
{@code /foo} is removed, the listener will get a remove event for {@code /foo}.
+ * The same is true if any pattern is used and any parent of a matching
resource is removed/added. The listener
* must handle these events accordingly.
*
* <p>If one of the paths is a sub resource of another specified path, the
sub path is ignored.</p>
