jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mdue...@apache.org
Subject 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
Date Tue, 25 Jun 2013 17:04:55 GMT
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;
 



Mime
View raw message