jackrabbit-oak-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jukka Zitting <jukka.zitt...@gmail.com>
Subject Re: Difference between CommitHook and Editor
Date Tue, 15 Oct 2013 13:35:58 GMT

On Tue, Oct 15, 2013 at 8:33 AM, Tommaso Teofili
<tommaso.teofili@gmail.com> wrote:
> What's exactly the difference and the intended usage scenarios for
> CommitHooks and Editors ?

CommitHook is the core mechanism that Oak applies to all commits. A
commit hook is in full control of what to do with the commit, though a
typical pattern is to diff the before and after states to see what
changes are being committed.

Since the diff operation is so common (practically all hooks want to
know what changed) and since doing it repeatedly in each separate
commit hook requires a lot of extra effort, we came up with the Editor
mechanism that allows multiple hooks to "listen" on the same diff. For
example, there's no need for the name and node type validation to each
do a separate content diff, if they can both look at the same diff.

In addition to listening to the content diff, the editors can also
make related changes to the tree using the provided NodeBuilder
instance. An editor that doesn't need to make any changes (i.e. it
just looks at the diff and potentially throws a CommitFailedException
if something is wrong) is called a validator.

> I see for example EditorHook is a CommitHook but uses an EditorProvider
> which returns an Editor when the CommitHook#processCommit method is call.

Right. The idea here is that the EditorHook is the core CommitHook
implementation shared by all Editors. The EditorHook does the content
diff between the given before and after states, and notifies the
available Editors (as provided by EditorProviders) about the detected

> If I had to write a new content validator / editor which interface should
> one use and what should I expect when choosing one instead of the other?

The basic guideline would be:

1. Is a content diff *not* needed (for example a commit barrier that
simply rejects all changes during maintenance)? If it isn't, use a
2. Do you need to make content changes (for example update an
in-content index) based on the content diff? If yes, use an Editor.
3. Otherwise use a Validator.

Note due to the way the content diff operates, the pattern in which
the editors are called can feel a bit counter-intuitive at first.
Basically each editor *instance* is used for observing the changes to
just a single node. When there are changes to a subtree below that
node, the relevant childNodeAdded/Changed/Deleted method is expected
to return a new editor instance for observing changes in those areas.
If an editor is not interested in changes inside a particular subtree
it can return null to notify the calling EditorHook that there's no
need to look deeper. And if the effect of an editor isn't tied to the
location of the changes within the content tree (like how the name
validator simply checks the validity of all names regardless of where
they're stored), it can just return itself from those methods. If the
location is relevant, for example you need to keep track of the path
of the changed node, you can store that information as internal state
of the returned editor instance.

Note also that due to performance reasons, it's possible in some cases
for the childNodeChanged method to be called even if there are in fact
no changes within that subtree. That should happen fairly
infrequently, but your code should be prepared to deal with such
cases, preferably by explicitly tracking relevant property and child
node change events to see if a node indeed has been modified.


Jukka Zitting

View raw message