svn commit: r1784290 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md

[md...@apache.org]

Author: mduerig
Date: Fri Feb 24 16:05:21 2017
New Revision: 1784290

URL: http://svn.apache.org/viewvc?rev=1784290&view=rev
Log:
OAK-4893: Document conflict handling

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md?rev=1784290&r1=1784289&r2=1784290&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/architecture/transactional-model.md Fri Feb 24 16:05:21 2017
@@ -25,7 +25,8 @@ when it contains operations which are in
 saved successfully. This is different from the standard first committer wins strategy where failure
 would occur on conflicting operations rather than on incompatible operations. Incompatible is weaker
 than conflict since two write operation on the same item do conflict but are not incompatible. The
-details of what incompatible means are specified by `NodeStore.rebase()`.
+details of what incompatible is somewhat dependent on the implementation of `NodeStore.rebase()` and
+the backend being used. See [below](#rebasing).
 
 Snapshot isolation exhibits [write skew](http://http//research.microsoft.com/apps/pubs/default.aspx?id=69541)
 which can be problematic for some application level consistency requirements. Consider the following
@@ -47,3 +48,30 @@ The check method enforces an application
 saving, the constraint might not hold globally for session3.
 
 See `CompatibilityIssuesTest.sessionIsolation` for a test case demonstrating this in runnable code.
+
+
+<a name="rebasing"/> Rebasing and incompatible changes (conflicts)
+------------------------------------------------------------------
+On save the changes from a session are rebased on top of the current head. That is, all changes done withing that session are re-applied on top of the latest state of the repository. This process can lead to conflicts when the latest state includes changes that are incompatible with the changes in that session. E.g. when the session modified the value of a property while in the latest state of the repository the same property changed to a different value.  
+
+The rebasing process attempts to resolve such conflicts if possible. If a conflict is not resolvable conflicting nodes are annotated with a conflict marker denoting the type of the conflict and the value(s) before the rebase operation. The conflict marker is an internal node with the name `:conflict` and is added to the node whose properties or child nodes are in conflict.
+
+#### Types of non resolvable conflicts
+ 
+* `addExistingProperty`: A property has been added that has a different value than a property with the same name that has been added in trunk. 
+
+* `removeRemovedProperty`: A property has been removed while a property of the same name has been removed in trunk. *Note:* while this conflict is technically easy to resolve, the current JCR specification mandates a conflict here. 
+
+* `removeChangedProperty`: A property has been removed while a property of the same name has been changed in trunk. 
+
+* `changeRemovedProperty`: A property has been changed while a property of the same name has been removed in trunk. 
+
+* `changeChangedProperty`: A property has been changed while a property of the same name has been changed to a different value in trunk. 
+
+* `addExistingNode`: A node has been added that is different from a node of them same name that has been added to the trunk. *Note:* Some subtleties are currently being discussed. See [OAK-1553](https://issues.apache.org/jira/browse/OAK-1553).  
+
+* `removeRemovedNode`: A node has been removed while a node of the same name has been removed in trunk. *Note:* while this conflict is technically easy to resolve, the current JCR specification mandates a conflict here. 
+
+* `removeChangedNode`: A node has been removed while a node of the same name has been changed in trunk. 
+
+* `changeRemovedNode`: A node has been changed while a node of the same name has been removed in trunk.