Arent-Jan Banck pushed to branch feature/projectdocs at cms-community /
hippo-services-api
Commits:
66288f41 by Ard Schrijvers at 2017-11-30T14:27:23+01:00
CMS-10897 Fix javadoc and use AlreadyLockedException
- - - - -
5c36543e by Ard Schrijvers at 2017-11-30T14:32:04+01:00
CMS-10897 use 'ignore' since recognized by idea
- - - - -
b0f283d5 by Ard Schrijvers at 2017-11-30T14:38:09+01:00
CMS-10897 improve java doc
- - - - -
de90f059 by Ard Schrijvers at 2017-11-30T14:41:42+01:00
CMS-10897 improve java doc
- - - - -
22295209 by Ard Schrijvers at 2017-12-02T21:06:09+01:00
CMS-11012 Document that a LockResource is thread-safe
- - - - -
e71a0940 by Ard Schrijvers at 2018-01-03T15:30:07+01:00
CMS-11030 Improve LockManager javadoc how to work with JCR
- - - - -
e692b7cd by Ard Schrijvers at 2018-01-04T13:40:14+01:00
CMS-11030 further improve javadoc
- - - - -
641621a4 by Ate Douma at 2018-01-04T13:51:31+01:00
CMS-11030 fix javadoc typos
- - - - -
2bed9bf4 by Arent-Jan Banck at 2018-01-09T13:41:01+01:00
CMS-10930 Merge master changes in feature/projectdocs
- - - - -
3 changed files:
- src/main/java/org/onehippo/cms7/services/lock/LockManager.java
- src/main/java/org/onehippo/cms7/services/lock/LockManagerUtils.java
- src/main/java/org/onehippo/cms7/services/lock/LockResource.java
Changes:
=====================================
src/main/java/org/onehippo/cms7/services/lock/LockManager.java
=====================================
--- a/src/main/java/org/onehippo/cms7/services/lock/LockManager.java
+++ b/src/main/java/org/onehippo/cms7/services/lock/LockManager.java
@@ -39,12 +39,13 @@ import org.onehippo.cms7.services.SingletonService;
* <code>
* <pre>
* public void run() {
- * boolean locked = false;
- * try {
- * try (LockResource lock = lockManager.lock(key)){
+ * try (LockResource ignore = lockManager.lock(key)){
+ * // session.refresh(true|false) if JCR nodes are involved
* // Do work
+ * } catch (AlreadyLockedException e) {
+ * log.info("'{}' is already locked", key, e);
* } catch (LockException e) {
- * log.info("Failed to obtain lock, most likely obtained by
other cluster node already", e);
+ * log.error("Exception while trying to obtain lock, e);
* }
* }
* </pre>
@@ -57,10 +58,13 @@ import org.onehippo.cms7.services.SingletonService;
* try {
* lockManager.lock(key);
* locked = true;
+ * // session.refresh(true|false) if JCR nodes are involved
* // Do work
+ * } catch (AlreadyLockedException e) {
+ * log.info("'{}' is already locked", key, e);
* } catch (LockException e) {
- * log.info("Failed to obtain lock, most likely obtained by
other cluster node already", e);
- * } finally {
+ * log.error("Exception while trying to obtain lock, e);
+ * }finally {
* if (locked) {
* lockManager.unlock(key);
* }
@@ -70,12 +74,28 @@ import org.onehippo.cms7.services.SingletonService;
* </code>
* </p>
* <p>
- * Note that when a {@code key} is already locked, the invocation of
{@link #lock(String) #lock(key)} directly results
- * in an {@link AlreadyLockedException} : This is thus
<strong>different</strong> than
- * {@link java.util.concurrent.locks.ReentrantLock} behavior. If you need
similar behavior to {@link ReentrantLock#lock()}
- * but then <strong>cluster wide</strong>, you can use {@link
LockManagerUtils#waitForLock(LockManager, String, long)}
- * and if you need the cluster wide equivalent of {@link
java.util.concurrent.locks.ReentrantLock#tryLock(long, TimeUnit)}
- * you can use {@link LockManagerUtils#waitForLock(LockManager, String,
long, long)}.
+ * Note that when {@code key} is already locked by another {@link Thread}
or other cluster node,
+ * the invocation of {@link #lock(String) #lock(key)} directly results in
an {@link AlreadyLockedException} :
+ * This is thus <strong>different</strong> than {@link
ReentrantLock#lock()} behavior (which blocks until the lock is acquired).
+ * If you need similar behavior to {@link ReentrantLock#lock()} but then
<strong>cluster wide</strong>, you can use
+ * {@link LockManagerUtils#waitForLock(LockManager, String, long)} and if
you need the cluster wide equivalent
+ * of {@link java.util.concurrent.locks.ReentrantLock#tryLock(long,
TimeUnit)} you can use
+ * {@link LockManagerUtils#waitForLock(LockManager, String, long, long)}.
+ * </p>
+ * <p>
+ * <strong>Usage in combination with JCR:</strong>
+ * <br/>
+ * When you use this {@link LockManager} to obtain a cluster wide lock
after which the code is doing JCR node manipulation,
+ * eg updating the last modification timestamp on a JCR node, then make
sure to always invoke
+ * <code>
+ * <pre>
+ * session.refresh(true|false);
+ * </pre>
+ * </code>
+ * after obtaining the {@link LockResource}. The reason for this is that
in the cluster wide 'synchronized' part of
+ * the code, you want to make sure that all JCR nodes the code is going to
touch are in sync with the latest cluster
+ * state and that the code is not chatting with local stale JCR nodes.
Thus make sure to always invoke
+ * {@code session.refresh(true|false);} when dealing with JCR nodes in a
cluster wide synchronized code block.
* </p>
*
*/
=====================================
src/main/java/org/onehippo/cms7/services/lock/LockManagerUtils.java
=====================================
--- a/src/main/java/org/onehippo/cms7/services/lock/LockManagerUtils.java
+++ b/src/main/java/org/onehippo/cms7/services/lock/LockManagerUtils.java
@@ -20,7 +20,19 @@ import java.util.concurrent.TimeoutException;
public class LockManagerUtils {
/**
- * Utility method to create and if needed wait indefinitely (unless
interrupted) for a {@link LockManager#lock(String)}
+ * <p>
+ * Utility method to create and if needed wait indefinitely (unless
interrupted) for a {@link LockManager#lock(String)}.
+ * </p>
+ * <p>
+ * Make sure that after obtaining the cluster-wide lock, that in you are
doing JCR node invocations, you first invoke
+ * <code>
+ * <pre>
+ * session.refresh(true|false)
+ * </pre>
+ * </code>
+ * to make sure the latest global JCR cluster changes are retrieved
locally.
+ * </p>
+ *
* @param lockManager lockManager
* @param key the key for the {@link Lock} where {@code key} is now
allowed to exceed 256 chars
* @param waitInterval time in milliseconds to wait before retrying
creating the lock
@@ -39,7 +51,18 @@ public class LockManagerUtils {
}
/**
- * Utility method to create and if needed wait for a maximum amount of
time (unless interrupted) for a {@link LockManager#lock(String)}
+ * <p>
+ * Utility method to create and if needed wait for a maximum amount of
time (unless interrupted) for a {@link LockManager#lock(String)} *
+ * </p>
+ * <p>
+ * Make sure that after obtaining the cluster-wide lock, that in you are
doing JCR node invocations, you first invoke
+ * <code>
+ * <pre>
+ * session.refresh(true|false)
+ * </pre>
+ * </code>
+ * to make sure the latest global JCR cluster changes are retrieved
locally.
+ * </p>
* @param lockManager lockManager
* @param key the key for the {@link Lock} where {@code key} is now
allowed to exceed 256 chars
* @param waitInterval time in milliseconds to wait before retrying
creating the lock
=====================================
src/main/java/org/onehippo/cms7/services/lock/LockResource.java
=====================================
--- a/src/main/java/org/onehippo/cms7/services/lock/LockResource.java
+++ b/src/main/java/org/onehippo/cms7/services/lock/LockResource.java
@@ -15,7 +15,12 @@
*/
package org.onehippo.cms7.services.lock;
-
+/**
+ * <p>
+ * The returned auto closeable object in case {@link
LockManager#lock(String)} succeeds.
+ * A LockResource object can be shared across threads and is thread-safe
+ * </p>
+ */
public interface LockResource extends AutoCloseable {
/**
View it on GitLab:
https://code.onehippo.org/cms-community/hippo-services-api/compare/f23b7d4894a7d3a46eec147dca1e0bd1192d2418...2bed9bf4ebfa554e78af4626283b87c981a6d004
---
View it on GitLab:
https://code.onehippo.org/cms-community/hippo-services-api/compare/f23b7d4894a7d3a46eec147dca1e0bd1192d2418...2bed9bf4ebfa554e78af4626283b87c981a6d004
You're receiving this email because of your account on code.onehippo.org.
_______________________________________________
Hippocms-svn mailing list
Hippocms-svn@lists.onehippo.org
https://lists.onehippo.org/mailman/listinfo/hippocms-svn
