kwin commented on a change in pull request #74: URL: https://github.com/apache/sling-site/pull/74#discussion_r768024453
########## File path: src/main/jbake/content/documentation/the-sling-engine/resources.md ########## @@ -215,16 +215,25 @@ To be notified whenever certain resources or their properties have been modified *This API is only available since Sling API 2.11.0 ([SLING-4751](https://issues.apache.org/jira/browse/SLING-4751)).* Register an OSGi service for [`org.apache.sling.api.resource.observation.ResourceChangeListener`][6] to be notified about local changes. To be also notified about external changes (i.e. changes triggered by another Sling instance leveraging a clustered repository make sure that your service implementation also implements the marker interface [`org.apache.sling.api.resource.observation.ExternalResourceChangeListener`][7]. The interface `ExternalResourceChangeListener` is not supposed to be registered with OSGi though. -Certain properties can be used to restrict subscription to only a subset of events. +It is possible already at a registration level to specify, which events in which path you are interested. For this attach these properties as OSGI properties to your implementing service (all of them are multi-value): Review comment: ```suggestion It is possible to specify already during registration which events in which paths you are interested in. To leverage this just set these service properties in your implementing OSGi service (all of them are multi-value strings): ``` ########## File path: src/main/jbake/content/documentation/the-sling-engine/resources.md ########## @@ -215,16 +215,25 @@ To be notified whenever certain resources or their properties have been modified *This API is only available since Sling API 2.11.0 ([SLING-4751](https://issues.apache.org/jira/browse/SLING-4751)).* Register an OSGi service for [`org.apache.sling.api.resource.observation.ResourceChangeListener`][6] to be notified about local changes. To be also notified about external changes (i.e. changes triggered by another Sling instance leveraging a clustered repository make sure that your service implementation also implements the marker interface [`org.apache.sling.api.resource.observation.ExternalResourceChangeListener`][7]. The interface `ExternalResourceChangeListener` is not supposed to be registered with OSGi though. -Certain properties can be used to restrict subscription to only a subset of events. +It is possible already at a registration level to specify, which events in which path you are interested. For this attach these properties as OSGI properties to your implementing service (all of them are multi-value): -### OSGi Event Admin +Property | Description +--- | --- +[ResourceChangeListener.PATHS](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PATHS)| denote the path (including sub paths) in which you are interested in. This property is required. +[ResourceChangeListener.CHANGES](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#CHANGES)| the type of changes you are interested in (optional) +[ResourceChhangeListener.PROPERTY_NAMES_HINT](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PROPERTY_NAMES_HINT)| optional property to specify interested on changes certain sling properties. Review comment: This is weird sentence: Rather something like filter only for event affecting the properties with the given names? ########## File path: src/main/jbake/content/documentation/the-sling-engine/resources.md ########## @@ -215,16 +215,25 @@ To be notified whenever certain resources or their properties have been modified *This API is only available since Sling API 2.11.0 ([SLING-4751](https://issues.apache.org/jira/browse/SLING-4751)).* Register an OSGi service for [`org.apache.sling.api.resource.observation.ResourceChangeListener`][6] to be notified about local changes. To be also notified about external changes (i.e. changes triggered by another Sling instance leveraging a clustered repository make sure that your service implementation also implements the marker interface [`org.apache.sling.api.resource.observation.ExternalResourceChangeListener`][7]. The interface `ExternalResourceChangeListener` is not supposed to be registered with OSGi though. -Certain properties can be used to restrict subscription to only a subset of events. +It is possible already at a registration level to specify, which events in which path you are interested. For this attach these properties as OSGI properties to your implementing service (all of them are multi-value): -### OSGi Event Admin +Property | Description +--- | --- +[ResourceChangeListener.PATHS](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PATHS)| denote the path (including sub paths) in which you are interested in. This property is required. +[ResourceChangeListener.CHANGES](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#CHANGES)| the type of changes you are interested in (optional) +[ResourceChhangeListener.PROPERTY_NAMES_HINT](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PROPERTY_NAMES_HINT)| optional property to specify interested on changes certain sling properties. -Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for [`org.osgi.service.event.EventHandler`][8]. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in [`org.apache.sling.api.SlingConstants`][9] starting with the prefix `TOPIC_`. + +### OSGi Event based resource changes (deprecated) + +Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for [`org.osgi.service.event.EventHandler`][8]. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in [`org.apache.sling.api.SlingConstants`][9] starting with the prefix `TOPIC_`. You receive events no matter whether they originate from the local repository or from a remote clustered repository. You can check though in your event listener for the [event attribute `event.application`](/apache-sling-eventing-and-job-handling.html#basic-principles), which is only set in case the event was triggered from an external resource modification (compare with [`DEAConstants`](https://sling.apache.org/apidocs/sling9/org/apache/sling/event/dea/DEAConstants.html) and try to reuse the constant from there). The OSGi event handlers may be [blacklisted by Apache Felix](http://felix.apache.org/documentation/subprojects/apache-felix-event-admin.html#configuration) in case the processing takes too long. Therefore dispatch all long-lasting operations to a new thread or start a new Sling Job. +This approach is deprecated in favor of the ResourceChangeListener described above, because the the ResourceChangeListeners allows the implementation to listen only to specific events of the repository, while the OSGI event-based approach needs to create OSGI events for **all** repository events. To ease the transition the implementation will warn whenever an listener is registered which listens for the Resource (`org/apache/sling/api/resource/Resource/*`) or ResourceProvider (`org/apache/sling/api/resource/ResourceProvider/*`) topics. Review comment: ```suggestion This approach is deprecated in favor of the ResourceChangeListener described above because the ResourceChangeListeners allows the implementation to send out only relevant events (i.e. those which have subscribers), while the OSGI event based approach needs to create OSGI events for **all** repository events. To ease the transition the implementation will warn whenever a listener is registered which listens for the Resource (`org/apache/sling/api/resource/Resource/*`) or ResourceProvider (`org/apache/sling/api/resource/ResourceProvider/*`) topics. ``` ########## File path: src/main/jbake/content/documentation/the-sling-engine/resources.md ########## @@ -215,16 +215,25 @@ To be notified whenever certain resources or their properties have been modified *This API is only available since Sling API 2.11.0 ([SLING-4751](https://issues.apache.org/jira/browse/SLING-4751)).* Register an OSGi service for [`org.apache.sling.api.resource.observation.ResourceChangeListener`][6] to be notified about local changes. To be also notified about external changes (i.e. changes triggered by another Sling instance leveraging a clustered repository make sure that your service implementation also implements the marker interface [`org.apache.sling.api.resource.observation.ExternalResourceChangeListener`][7]. The interface `ExternalResourceChangeListener` is not supposed to be registered with OSGi though. -Certain properties can be used to restrict subscription to only a subset of events. +It is possible already at a registration level to specify, which events in which path you are interested. For this attach these properties as OSGI properties to your implementing service (all of them are multi-value): -### OSGi Event Admin +Property | Description +--- | --- +[ResourceChangeListener.PATHS](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PATHS)| denote the path (including sub paths) in which you are interested in. This property is required. +[ResourceChangeListener.CHANGES](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#CHANGES)| the type of changes you are interested in (optional) +[ResourceChhangeListener.PROPERTY_NAMES_HINT](https://sling.apache.org/apidocs/sling11/org/apache/sling/api/resource/observation/ResourceChangeListener.html#PROPERTY_NAMES_HINT)| optional property to specify interested on changes certain sling properties. -Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for [`org.osgi.service.event.EventHandler`][8]. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in [`org.apache.sling.api.SlingConstants`][9] starting with the prefix `TOPIC_`. + +### OSGi Event based resource changes (deprecated) + +Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for [`org.osgi.service.event.EventHandler`][8]. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in [`org.apache.sling.api.SlingConstants`][9] starting with the prefix `TOPIC_`. Review comment: ```suggestion Resource events are sent out via the OSGi Event Admin. You can subscribe to those events by registering an OSGi service for [`org.osgi.service.event.EventHandler`][8]. Several properties should be used to restrict the subscription to only the relevant event(s). The event topics which are used for resources are listed as constants in [`org.apache.sling.api.SlingConstants`][9] starting with the prefix `TOPIC_`. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
