Mailing-List: contact oak-dev-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Received-SPF: pass (nike.apache.org: local policy includes SPF record at
 spf.trusted-forwarder.org)
Message-ID: <525D47B2.9010305@apache.org>
Date: Tue, 15 Oct 2013 15:48:34 +0200
From: =?ISO-8859-1?Q?Michael_D=FCrig?= <mduerig@apache.org>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8;
 rv:24.0) Gecko/20100101 Thunderbird/24.0.1
MIME-Version: 1.0
To: <oak-dev@jackrabbit.apache.org>
Subject: Re: Difference between CommitHook and Editor
References: 
 <CAGnSx06LPz_iOnOm5PD2efRp+i6dKXGDCsJRzkD9LyuJ2n208w@mail.gmail.com>
 <CAOFYJNZEPqzB9GnMdMhqq9VJcLG4moUZ0Z=ay9uYs0JfYLkvUw@mail.gmail.com>
In-Reply-To: 
 <CAOFYJNZEPqzB9GnMdMhqq9VJcLG4moUZ0Z=ay9uYs0JfYLkvUw@mail.gmail.com>
Content-Type: text/plain; charset="ISO-8859-1"; format=flowed
Content-Transfer-Encoding: 7bit


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
>