SLING-4751 : New observation API: remove getResourceType and lazy han…

…dling of change events, remove user context listener

git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1686443 13f79535-47bb-0310-9956-ffa450edef68

bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java

@@ -24,8 +24,7 @@
 import aQute.bnd.annotation.ConsumerType;
 
 /**
- * A resource change event might be implemented in a lazy manner, however
- * it is immutable.
+ * A resource change event is immutable.
  */
 @ConsumerType
 public abstract class ResourceChange {
@@ -78,15 +77,6 @@ public ResourceChange(final @Nonnull ChangeType changeType,
     public boolean isExternal() {
         return this.isExternal;
     }
-    /**
-     * Get the resource type.
-     * TODO Clarify when this might be available - and as this is lazy
-     *      it might not be available even for added/changed resources.
-     * @return The resource type or {@code null}
-     */
-    public @CheckForNull String getResourceType() {
-        return null;
-    }
 
    /**
      * Get the type of change

bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java → bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java

@@ -25,34 +25,38 @@
 import aQute.bnd.annotation.ConsumerType;
 
 /**
- * Listener for resource events.
+ * Listener for resource change events.
  *
  * <p>
- * {@code ResourceListener} objects are registered with the Framework service
+ * {@code ResourceChangeListener} objects are registered with the Framework service
  * registry and are notified with {@code ResourceChange} objects when a
  * change occurs.
  * <p>
- * {@code ResourceListener} objects can inspect the received {@code ResourceChange} objects to
+ * {@code ResourceChangeListener} objects can inspect the received {@code ResourceChange} objects to
  * determine the type of change, location and other properties.
  *
  * <p>
- * {@code ResourceListener} objects must be registered with a service property
- * {@link ResourceListener#PATHS} whose value is the list of resource paths for which
+ * {@code ResourceChangeListener} objects must be registered with a service property
+ * {@link ResourceChangeListener#PATHS} whose value is the list of resource paths for which
  * the listener is interested in getting change events.
  *
  * <p>
  * By default a resource listener gets only local events which means events
  * caused by changes persisted on the same instance as this listener is registered.
  * If the resource listener is interested in external events, the implementation
- * should implement the {@link ExternalResourceListener} interface.
- *
- * TODO - how to register for current search paths?
+ * should implement the {@link ExternalResourceListener} interface, but still register
+ * the service as a {@code ResourceChangeListener} service.
  */
 @ConsumerType
-public interface ResourceListener {
+public interface ResourceChangeListener {
 
     /**
      * Array of paths - required.
+     * A path is either absolute or relative. If it's a relative path, the relative path
+     * will be appended to all search paths of the resource resolver. If the whole tree
+     * of all search paths should be observed, the special value {@code .} should be used.
+     * If one of the paths is a sub resource of another specified path,
+     * the sub path is ignored.
      */
     String PATHS = "resource.paths";
 

bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ObservationReporter.java

@@ -50,5 +50,5 @@ public interface ObservationReporter {
      * @param changes The list of changes.
      * @param distribute Whether the changes should be distributed to other instances.
      */
-    void reportChanges(@Nonnull List<ResourceChange> changes, boolean distribute);
+    void reportChanges(@Nonnull Iterable<ResourceChange> changes, boolean distribute);
 }

bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ObserverConfiguration.java

@@ -25,12 +25,12 @@
 import aQute.bnd.annotation.ProviderType;
 
 /**
- * A observer configuration descibes active configurations from registered listeners.
+ * A observer configuration describes active configurations from registered listeners.
  */
 @ProviderType
 public interface ObserverConfiguration {
 
-    boolean isExternal();
+    boolean includeExternal();
 
     Set<String> getPaths();