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
