You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by md...@apache.org on 2013/06/25 19:04:55 UTC
svn commit: r1496537 - in
/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation:
ChangeProcessor.java EventFilter.java Observable.java
ObservationManagerImpl.java RecursingNodeStateDiff.java
SecurableNodeStateDiff.java
Author: mduerig
Date: Tue Jun 25 17:04:55 2013
New Revision: 1496537
URL: http://svn.apache.org/r1496537
Log:
OAK-144 Implement Observation
javadoc
Modified:
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ChangeProcessor.java
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/EventFilter.java
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/Observable.java
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ObservationManagerImpl.java
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/RecursingNodeStateDiff.java
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/SecurableNodeStateDiff.java
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ChangeProcessor.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ChangeProcessor.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ChangeProcessor.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ChangeProcessor.java Tue Jun 25 17:04:55 2013
@@ -52,6 +52,14 @@ import org.apache.jackrabbit.oak.spi.whi
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * A {@code ChangeProcessor} generates observation {@link javax.jcr.observation.Event}s
+ * based on a {@link EventFilter} and delivers them to an {@link javax.jcr.observation.EventListener}.
+ * <p>
+ * After instantiation a {@code ChangeProcessor} must be started in order for its
+ * {@link #run()} methods to be regularly executed and stopped in order to not
+ * execute its run method anymore.
+ */
class ChangeProcessor implements Runnable {
private static final Logger log =
@@ -84,17 +92,26 @@ class ChangeProcessor implements Runnabl
filterRef = new AtomicReference<EventFilter>(filter);
}
+ /**
+ * Set the filter for the events this change processor will generate.
+ * @param filter
+ */
public void setFilter(EventFilter filter) {
filterRef.set(filter);
}
+ /**
+ * Set the user data to return with {@link javax.jcr.observation.Event#getUserData()}.
+ * @param userData
+ */
public void setUserData(String userData) {
userDataRef.set(userData);
}
/**
- * Start the change processor on the passed {@code executor}.
- * @param whiteboard
+ * Start this change processor
+ * @param whiteboard the whiteboard instance to used for scheduling individual
+ * runs of this change processor.
* @throws IllegalStateException if started already
*/
public synchronized void start(Whiteboard whiteboard) {
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/EventFilter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/EventFilter.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/EventFilter.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/EventFilter.java Tue Jun 25 17:04:55 2013
@@ -36,10 +36,9 @@ import org.apache.jackrabbit.oak.plugins
import org.apache.jackrabbit.oak.spi.state.NodeState;
/**
- * TODO document
+ * Filter for filtering observation events according to a certain criterion.
*/
class EventFilter {
-
private final ReadOnlyNodeTypeManager ntMgr;
private final NamePathMapper namePathMapper;
private final int eventTypes;
@@ -49,6 +48,21 @@ class EventFilter {
private final String[] nodeTypeOakName;
private final boolean noLocal;
+ /**
+ * Create a new instance of a filter for a certain criterion
+ * @param ntMgr
+ * @param namePathMapper
+ * @param eventTypes event types to include encoded as a bit mask
+ * @param path path to include
+ * @param deep {@code true} if descendants of {@code path} should be included. {@code false} otherwise.
+ * @param uuids uuids to include
+ * @param nodeTypeName node type names to include
+ * @param noLocal exclude session local events if {@code true}. Include otherwise.
+ * @throws NoSuchNodeTypeException if any of the node types in {@code nodeTypeName} does not exist
+ * @throws RepositoryException if an error occurs while reading from the node type manager.
+ * @see javax.jcr.observation.ObservationManager#addEventListener(javax.jcr.observation.EventListener,
+ * int, String, boolean, String[], String[], boolean)
+ */
public EventFilter(ReadOnlyNodeTypeManager ntMgr,
NamePathMapper namePathMapper, int eventTypes,
String path, boolean deep, String[] uuids,
@@ -64,6 +78,13 @@ class EventFilter {
this.noLocal = noLocal;
}
+ /**
+ * Match an event against this filter.
+ * @param eventType type of the event
+ * @param path path of the event
+ * @param associatedParentNode associated parent node of the event
+ * @return {@code true} if the filter matches this event. {@code false} otherwise.
+ */
public boolean include(int eventType, String path, @Nullable NodeState associatedParentNode) {
return include(eventType)
&& include(path)
@@ -71,6 +92,11 @@ class EventFilter {
&& (associatedParentNode == null || includeByUuid(associatedParentNode));
}
+ /**
+ * Determine whether the children of a {@code path} would be matched by this filter
+ * @param path path whose children to test
+ * @return {@code true} if the children of {@code path} could be matched by this filter
+ */
public boolean includeChildren(String path) {
String thisOakPath = namePathMapper.getOakPath(this.path);
String thatOakPath = namePathMapper.getOakPath(path);
@@ -80,10 +106,20 @@ class EventFilter {
deep && PathUtils.isAncestor(thisOakPath, thatOakPath);
}
+ /**
+ * @return the no local flag of this filter
+ */
public boolean excludeLocal() {
return noLocal;
}
+ /**
+ * @return path of this filter
+ */
+ public String getPath() {
+ return path;
+ }
+
@Override
public String toString() {
return toStringHelper(this)
@@ -96,10 +132,6 @@ class EventFilter {
.toString();
}
- public String getPath() {
- return path;
- }
-
//-----------------------------< internal >---------------------------------
private boolean include(int eventType) {
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/Observable.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/Observable.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/Observable.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/Observable.java Tue Jun 25 17:04:55 2013
@@ -21,6 +21,18 @@ package org.apache.jackrabbit.oak.plugin
import org.apache.jackrabbit.oak.plugins.observation.ChangeDispatcher.Listener;
+/**
+ * An {@code Observable} supports attaching {@link Listener} instances for
+ * listening to changes in a {@code ContentRepository}.
+ * @see ChangeDispatcher
+ */
public interface Observable {
+
+ /**
+ * Register a new {@code Listener}. Clients need to call
+ * {@link ChangeDispatcher.Listener#dispose()} when to free
+ * up any resources associated with the listener when done.
+ * @return a fresh {@code Listener} instance.
+ */
Listener newListener();
}
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ObservationManagerImpl.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ObservationManagerImpl.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ObservationManagerImpl.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/ObservationManagerImpl.java Tue Jun 25 17:04:55 2013
@@ -18,6 +18,7 @@
*/
package org.apache.jackrabbit.oak.plugins.observation;
+import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.collect.Lists.newArrayList;
import java.util.HashMap;
@@ -32,8 +33,6 @@ import javax.jcr.observation.EventListen
import javax.jcr.observation.EventListenerIterator;
import javax.jcr.observation.ObservationManager;
-import com.google.common.base.Preconditions;
-
import org.apache.jackrabbit.commons.iterator.EventListenerIteratorAdapter;
import org.apache.jackrabbit.commons.observation.ListenerTracker;
import org.apache.jackrabbit.oak.api.ContentSession;
@@ -62,10 +61,21 @@ public class ObservationManagerImpl impl
private final NamePathMapper namePathMapper;
private final Whiteboard whiteboard;
+ /**
+ * Create a new instance based on a {@link ContentSession} that needs to implement
+ * {@link Observable}.
+ *
+ * @param contentSession the content session in whose context this observation manager
+ * operates.
+ * @param nodeTypeManager node type manager for the content session
+ * @param namePathMapper name path mapper for the content session
+ * @param whiteboard
+ * @throws IllegalArgumentException if {@code contentSession} doesn't implement {@code Observable}.
+ */
public ObservationManagerImpl(ContentSession contentSession, ReadOnlyNodeTypeManager nodeTypeManager,
NamePathMapper namePathMapper, Whiteboard whiteboard) {
- Preconditions.checkArgument(contentSession instanceof Observable);
+ checkArgument(contentSession instanceof Observable);
this.contentSession = contentSession;
this.ntMgr = nodeTypeManager;
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/RecursingNodeStateDiff.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/RecursingNodeStateDiff.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/RecursingNodeStateDiff.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/RecursingNodeStateDiff.java Tue Jun 25 17:04:55 2013
@@ -24,9 +24,25 @@ import javax.annotation.Nonnull;
import org.apache.jackrabbit.oak.spi.state.DefaultNodeStateDiff;
import org.apache.jackrabbit.oak.spi.state.NodeState;
+/**
+ * A {@code RecursingNodeStateDiff} extends {@link DefaultNodeStateDiff}
+ * with a factory method for diffing child nodes.
+ * In contrast to {@code DefaultNodeStateDiff}, {@link #childNodeChanged(String, NodeState, NodeState)}
+ * should <em>not</em> recurse into child nodes but rather only be concerned about whether to continue
+ * diffing or not. The {@link #createChildDiff(String, NodeState, NodeState)} will be called instead
+ * for diffing child nodes.
+ * TODO unify with NodeStateDiff
+ */
public class RecursingNodeStateDiff extends DefaultNodeStateDiff {
public static final RecursingNodeStateDiff EMPTY = new RecursingNodeStateDiff();
+ /**
+ * Create a {@code RecursingNodeStateDiff} for a child node
+ * @param name name of the child node
+ * @param before before state of the child node
+ * @param after after state of the child node
+ * @return {@code RecursingNodeStateDiff} for the child node
+ */
@Nonnull
public RecursingNodeStateDiff createChildDiff(String name, NodeState before, NodeState after) {
return this;
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/SecurableNodeStateDiff.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/SecurableNodeStateDiff.java?rev=1496537&r1=1496536&r2=1496537&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/SecurableNodeStateDiff.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/observation/SecurableNodeStateDiff.java Tue Jun 25 17:04:55 2013
@@ -24,6 +24,11 @@ import org.apache.jackrabbit.oak.spi.sta
import org.apache.jackrabbit.oak.spi.state.NodeStateDiff;
import org.apache.jackrabbit.oak.spi.state.NodeStateUtils;
+/**
+ * Base class for {@code NodeStateDiff} implementations that can be secured.
+ * That is its call back methods are only called when its receiver has sufficient
+ * rights to access respective items.
+ */
public abstract class SecurableNodeStateDiff implements NodeStateDiff {
private final SecurableNodeStateDiff parent;