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.
