Mailing-List: contact oak-dev-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Received-SPF: pass (athena.apache.org: domain of anchela@adobe.com designates
 64.18.1.233 as permitted sender)
From: Angela Schreiber <anchela@adobe.com>
To: "oak-dev@jackrabbit.apache.org" <oak-dev@jackrabbit.apache.org>
Date: Tue, 15 Oct 2013 14:52:15 +0100
Subject: Re: Difference between CommitHook and Editor
Thread-Topic: Difference between CommitHook and Editor
Thread-Index: Ac7JrcOUAvtR3vhBQx6uqziKOfaWdQ==
Message-ID: <CE8314F0.A902%anchela@adobe.com>
In-Reply-To: <525D47B2.9010305@apache.org>
Accept-Language: en-US
Content-Language: en-US
user-agent: Microsoft-MacOutlook/14.3.2.130206
acceptlanguage: en-US
Content-Type: text/plain; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

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=FCrig" <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
>>