You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2015/10/27 09:49:45 UTC
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
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.