jackrabbit-oak-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tommaso Teofili <tommaso.teof...@gmail.com>
Subject Re: Difference between CommitHook and Editor
Date Tue, 15 Oct 2013 13:56:59 GMT
thanks a lot Jukka, this really clarified the design and how both are
intended to work, big +1 for having it in the doc.

Tommaso


2013/10/15 Angela Schreiber <anchela@adobe.com>

> i would prefer to have it in the javadoc, which is a bit sparse.
> in particular Editor#enter lacks any kind of documentation.
>
> regards
> angela
>
> On 10/15/13 3:48 PM, "Michael Dürig" <mduerig@apache.org> wrote:
>
> >
> >Nice summary Jukka! How about adding this to oak-doc?
> >
> >Michael
> >
> >On 15.10.13 3:35 , Jukka Zitting wrote:
> >> Hi,
> >>
> >> 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
> >> changes.
> >>
> >>> 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
> >> CommitHook.
> >> 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.
> >>
> >> BR,
> >>
> >> Jukka Zitting
> >>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message