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 <[email protected]> > 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" <[email protected]> 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 > >> <[email protected]> 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 > >> > >
