[jackrabbit-oak] branch trunk updated: OAK-10025 - Documentation regarding conflicts is added. (#786)

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

angela pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 1572996e12 OAK-10025 - Documentation regarding conflicts is added. (#786)
1572996e12 is described below

commit 1572996e12da63cd6af31823b70178d506c31a83
Author: Jorge Eduardo Flórez <jo...@gmail.com>
AuthorDate: Tue Dec 13 04:51:46 2022 -0500

    OAK-10025 - Documentation regarding conflicts is added. (#786)
---
 oak-doc/src/site/markdown/dos_and_donts.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/oak-doc/src/site/markdown/dos_and_donts.md b/oak-doc/src/site/markdown/dos_and_donts.md
index b788669c46..41b32dc227 100644
--- a/oak-doc/src/site/markdown/dos_and_donts.md
+++ b/oak-doc/src/site/markdown/dos_and_donts.md
@@ -130,3 +130,17 @@ c = d.getParent();                              // preferred way to fetch the pa
 this is that Oak internally uses various classes from the `nio` package that implement 
 `InterruptibleChannel`, which are [asynchronously closed](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/channels/InterruptibleChannel.html) 
 when receiving an `InterruptedException` while blocked on IO. See [OAK-2609](https://issues.apache.org/jira/browse/OAK-2609).  
+
+### Avoid or minimize conflicts
+To reduce the possiblity of having errors like `OakState0001: Unresolved conflicts in ...`:
+
+1. Make sure you always release the session by calling session.logout(). If possible, avoid long-running sessions. If they are required (e.g. for observation) make sure 
+to always call session.refresh(false) before applying changes or session.refresh(true) before saving the changes. 
+
+2. Enable the DEBUG level for `org.apache.jackrabbit.oak.plugins.commit.MergingNodeStateDiff` and `org.apache.jackrabbit.oak.plugins.commit.ConflictValidator` loggers if you want 
+to have more information on the circumstances of a conflict that happened in a point of time.
+
+3. Write your own conflict handler and add it when configuring your Oak or WhiteBoard instances. Only if you know what you are doing (i.e. you know how to resolve 
+the conflict in each one of the possible situations). By default, the [AnnotatingConflictHandler](https://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/commit/AnnotatingConflictHandler.html) instance will discard your changes 
+and your commit will fail. If persisting changes fails with a conflict and you cannot lose them, refactor your code such that you can retry after having called session.refresh(false).
+Check the source code of [JcrLastModifiedConflictHandler](https://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/commit/JcrLastModifiedConflictHandler.html) for an example of a conflict handler.
\ No newline at end of file