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