sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cziege...@apache.org
Subject svn commit: r1710745 - in /sling/trunk/bundles/api/src/main/java/org/apache/sling: api/resource/observation/ResourceChange.java api/resource/observation/ResourceChangeListener.java spi/resource/provider/ResourceProvider.java
Date Tue, 27 Oct 2015 08:49:45 GMT
Author: cziegeler
Date: Tue Oct 27 08:49:45 2015
New Revision: 1710745

URL: http://svn.apache.org/viewvc?rev=1710745&view=rev
Log:
SLING-4751 : Update observation api. Clarify required vs optional properties

Modified:
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ResourceProvider.java

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java?rev=1710745&r1=1710744&r2=1710745&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
Tue Oct 27 08:49:45 2015
@@ -18,6 +18,8 @@
  */
 package org.apache.sling.api.resource.observation;
 
+import java.util.Set;
+
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
@@ -25,22 +27,55 @@ import aQute.bnd.annotation.ConsumerType
 
 /**
  * A resource change event is immutable.
+ *
+ * A change event can either be local or external. Local changes happended
+ * on the same instance, while external changes happended on a different
+ * instance.
+ *
+ * Resource listeners only receive external changes if they mark themselves
+ * as a {@link ExternalResourceListener}.
+ *
+ * For all events (local and external), the path and the type of change is
+ * set.
+ *
+ * Resource provider events are always local events and only provide the path.
+ *
+ * Local events for resources provide the names of the properties that
+ * have been added, removed or changed. This information might be missing
+ * for external events.
  */
 @ConsumerType
 public abstract class ResourceChange {
 
+    /**
+     * The type of the change
+     */
     public enum ChangeType {
-        ADDED,
-        REMOVED,
-        CHANGED,
-        PROVIDER_ADDED,
-        PROVIDER_REMOVED
+        ADDED,            // the resource has been added
+        REMOVED,          // the resource has been removed
+        CHANGED,          // the resource has been changed
+        PROVIDER_ADDED,   // a provider has been added
+        PROVIDER_REMOVED  // a provider has been removed
     }
 
+    /** The resource path. */
     private final String path;
+
+    /** The resource change. */
     private final ChangeType changeType;
+
+    /** Flag whether the change is external. */
     private final boolean isExternal;
 
+    /** Optional set of added property names. */
+    private final Set<String> addedPropertyNames;
+
+    /** Optional set of changed property names. */
+    private final Set<String> changedPropertyNames;
+
+    /** Optional set of removed property names. */
+    private final Set<String> removedPropertyNames;
+
     /**
      * Create a new change object
      * @param changeType The change type
@@ -48,10 +83,16 @@ public abstract class ResourceChange {
      */
     public ResourceChange(final @Nonnull ChangeType changeType,
             final @Nonnull String path,
-            final boolean isExternal) {
+            final boolean isExternal,
+            final Set<String> addedPropertyNames,
+            final Set<String> changedPropertyNames,
+            final Set<String> removedPropertyNames) {
         this.path = path;
         this.changeType = changeType;
         this.isExternal = isExternal;
+        this.addedPropertyNames = addedPropertyNames;
+        this.changedPropertyNames = changedPropertyNames;
+        this.removedPropertyNames = removedPropertyNames;
     }
 
     /**
@@ -88,25 +129,28 @@ public abstract class ResourceChange {
 
     /**
      * Optional information about changed properties.
-     * TODO Clarify when these might be available.
+     * @return The set of changed property names. For external events or
+     *         resource provider events {@code null} is returned.
      */
-    public @CheckForNull String[] getChangedAttributeNames() {
-        return null;
+    public @CheckForNull Set<String> getChangedPropertyNames() {
+        return this.changedPropertyNames;
     }
 
     /**
      * Optional information about added properties.
-     * TODO Clarify when these might be available.
+     * @return The set of changed property names. For external events or
+     *         resource provider events {@code null} is returned.
      */
-    public @CheckForNull String[] getAddedAttributeNames() {
-        return null;
+    public @CheckForNull Set<String> getAddedPropertyNames() {
+        return this.addedPropertyNames;
     }
 
     /**
      * Optional information about removed properties.
-     * TODO Clarify when these might be available.
+     * @return The set of changed property names. For external events or
+     *         resource provider events {@code null} is returned.
      */
-    public @CheckForNull String[] getRemovedAttributeNames() {
-        return null;
+    public @CheckForNull Set<String> getRemovedPropertyNames() {
+        return this.removedPropertyNames;
     }
 }

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java?rev=1710745&r1=1710744&r2=1710745&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java
Tue Oct 27 08:49:45 2015
@@ -72,7 +72,7 @@ public interface ResourceChangeListener
     String CHANGES = "resource.change.types";
 
     /**
-     * Report a resource change based on the filter properties of this listener.
+     * Report resource changes based on the filter properties of this listener.
      * @param changes The changes.
      */
     void onChange(@Nonnull List<ResourceChange> changes);

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ResourceProvider.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ResourceProvider.java?rev=1710745&r1=1710744&r2=1710745&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ResourceProvider.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/spi/resource/provider/ResourceProvider.java
Tue Oct 27 08:49:45 2015
@@ -42,7 +42,7 @@ import aQute.bnd.annotation.ConsumerType
  * repository, a database, or bundle resources.
  * <p>
  * This extension point is defined by an abstract class (in contrast to
- * an interface) as this will allow to add new functionality in new versions
+ * an interface) as this allows to add new functionality in new versions
  * without breaking any implementation.
  * <p>
  * This service is intended to be implemented by providers of resource
@@ -72,7 +72,11 @@ import aQute.bnd.annotation.ConsumerType
  * the current user. This object is passed into the provider with
  * every method through {@link ResolveContext#getProviderState()}.
  * If a provider requires authentication, the {@link #logout(Object)} method
- * is called, when the resource resolver is closed.
+ * is called, when the resource resolver is closed. If the provider
+ * does not set this service property or sets it to {@link #AUTHENTICATE_NO}
+ * the {@link #authenticate(Map)} and {@link #logout(Object)} method
+ * are never called and therefore {@link ResolveContext#getProviderState()}
+ * will return {@code null}.
  * <p>
  * Each method gets the {@link ResolveContext} which gives access to
  * further functionality.



Mime
View raw message