anchela commented on code in PR #786: URL: https://github.com/apache/jackrabbit-oak/pull/786#discussion_r1042052762
########## oak-doc/src/site/markdown/dos_and_donts.md: ########## @@ -130,3 +130,19 @@ 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. Try to keep the JCR sessions as short as possible. i.e. create the session, make your changes, call session.save() and then session.logout(). If you need to do +something additional in the repository, a few lines after (maybe after some processing that could take some time), create the session again and repeat. Review Comment: i am a bit reluctant to suggest to repeatedly create sessions. instead i would recommend calling Session.refresh(false) before starting with new changes after save() has been called. ########## oak-doc/src/site/markdown/dos_and_donts.md: ########## @@ -130,3 +130,19 @@ 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. Try to keep the JCR sessions as short as possible. i.e. create the session, make your changes, call session.save() and then session.logout(). If you need to do +something additional in the repository, a few lines after (maybe after some processing that could take some time), create the session again and repeat. + +2. Try to use session.refresh(true) before saving, if you think that some significant time can pass between the login() and the save() call. + +3. 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. + +4. 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. The worst that will happen is that your changes will not be saved (if you are ok with that). Review Comment: here i would add: - if persisting changes fails with a conflict and you cannot lose it, refactor your code such that you can retry after having called session.refresh(false) ########## oak-doc/src/site/markdown/dos_and_donts.md: ########## @@ -130,3 +130,19 @@ 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. Try to keep the JCR sessions as short as possible. i.e. create the session, make your changes, call session.save() and then session.logout(). If you need to do +something additional in the repository, a few lines after (maybe after some processing that could take some time), create the session again and repeat. + +2. Try to use session.refresh(true) before saving, if you think that some significant time can pass between the login() and the save() call. Review Comment: i would recommend tocall session.refresh(false) before making changes to avoid conflicts. if that is not feasible, session.refresh(true) can be called before the save call. ########## oak-doc/src/site/markdown/dos_and_donts.md: ########## @@ -130,3 +130,19 @@ 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. Try to keep the JCR sessions as short as possible. i.e. create the session, make your changes, call session.save() and then session.logout(). If you need to do Review Comment: this is correct. but i would rephrase it a bit. something like 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. ########## oak-doc/src/site/markdown/dos_and_donts.md: ########## @@ -130,3 +130,19 @@ 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. Try to keep the JCR sessions as short as possible. i.e. create the session, make your changes, call session.save() and then session.logout(). If you need to do +something additional in the repository, a few lines after (maybe after some processing that could take some time), create the session again and repeat. + +2. Try to use session.refresh(true) before saving, if you think that some significant time can pass between the login() and the save() call. + +3. 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. + +4. 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. The worst that will happen is that your changes will not be saved (if you are ok with that). +Please check the source code of [JcrLastModifiedConflictHandler](https://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/commit/JcrLastModifiedConflictHandler.html). It seems like a good example to follow. Review Comment: 'it seems like a good example to follow' sounds a bit awkward in the oak documentation. i would rephrase the point as follows: 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. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: dev-unsubscr...@jackrabbit.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
