aboutsummaryrefslogtreecommitdiffstats
path: root/policy-core/src/main/java
diff options
context:
space:
mode:
authorJim Hahn <jrh3@att.com>2018-03-29 15:07:36 -0400
committerJim Hahn <jrh3@att.com>2018-04-03 10:55:19 -0400
commit3a80de9806cbdd0461716e814f5e674e259d42b3 (patch)
treee48400fcfee10f363538bad7efa177911b0c316c /policy-core/src/main/java
parentca3efc7d2ee9522f995adc55baa6fff3279bba70 (diff)
Add api-resource-locks feature
Added ResourceLockFeatureAPI, to provide an interface for PolicyGuard to use to access other locking mechanisms. Move lock API to policy-core. Changed the interface and added Callback support. Added a class to invoke the API implementers. Changed to set a future instead of expecting the callback to implement the future interface. Also refactored, creating "lock" sub-package. Add junit tests. Increase junit coverage. IsLocked & isLockedBy should check all arguments. Make ImplFuture protected instead of public. Simplify locking - move callback support to an optional feature. Move Reference class to policy-utils. Return plain Future instead of LockRequestFuture. Change-Id: I65154d33833914b4332e02d1ef2512f4c5f09b16 Issue-ID: POLICY-577 Signed-off-by: Jim Hahn <jrh3@att.com>
Diffstat (limited to 'policy-core/src/main/java')
-rw-r--r--policy-core/src/main/java/org/onap/policy/drools/core/lock/Lock.java162
-rw-r--r--policy-core/src/main/java/org/onap/policy/drools/core/lock/LockRequestFuture.java261
-rw-r--r--policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockFeatureAPI.java190
-rw-r--r--policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockManager.java208
-rw-r--r--policy-core/src/main/java/org/onap/policy/drools/core/lock/SimpleLockManager.java168
5 files changed, 989 insertions, 0 deletions
diff --git a/policy-core/src/main/java/org/onap/policy/drools/core/lock/Lock.java b/policy-core/src/main/java/org/onap/policy/drools/core/lock/Lock.java
new file mode 100644
index 00000000..ea5e2521
--- /dev/null
+++ b/policy-core/src/main/java/org/onap/policy/drools/core/lock/Lock.java
@@ -0,0 +1,162 @@
+/*
+ * ============LICENSE_START=======================================================
+ * ONAP
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.drools.core.lock;
+
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.Map.Entry;
+import org.onap.policy.drools.utils.Pair;
+
+/**
+ * Lock that is held for a resource. This not only identifies the current owner of the
+ * lock, but it also includes a queue of requesters. An item is associated with each
+ * requester that is waiting in the queue. Note: this class is <b>not</b> thread-safe.
+ *
+ * @param <T> type of item to be associated with a request
+ */
+public class Lock<T> {
+
+ /**
+ * Result returned by <i>removeRequester()</i>.
+ */
+ public enum RemoveResult {
+ /**
+ * The requester was the owner of the lock, and the lock is no longer needed,
+ * because there were no other requesters waiting to get the lock.
+ */
+ UNLOCKED,
+
+ /**
+ * The requester was the owner of the lock, and has been replaced with the next
+ * requester waiting in the queue.
+ */
+ RELOCKED,
+
+ /**
+ * The requester had been waiting in the queue, and has now been removed.
+ */
+ REMOVED,
+
+ /**
+ * The requester was not the owner, nor was it waiting in the queue.
+ */
+ NOT_FOUND
+ };
+
+ /**
+ * The last owner to grab the lock, never {@code null}.
+ */
+ private String owner;
+
+ /**
+ * Requesters waiting to get the lock. Maps the requester (i.e., owner for which the
+ * request is being made) to its associated item. Uses a Linked map so that the order
+ * of the requesters is maintained. We don't expect many requesters for any given
+ * lock, thus we'll start with a small hash size.
+ */
+ private LinkedHashMap<String, T> requester2item = new LinkedHashMap<>(5);
+
+ /**
+ *
+ * @param owner the current owner of this lock
+ */
+ public Lock(String owner) {
+ this.owner = owner;
+ }
+
+ /**
+ *
+ * @return the current owner of the lock, or the last owner of the lock, if the lock
+ * is not currently owned. (This will never be {@code null}.)
+ */
+ public String getOwner() {
+ return owner;
+ }
+
+ /**
+ * Adds a new requester to the queue of requesters.
+ *
+ * @param requester
+ * @param item to be associated with the requester, must not be {@code null}
+ * @return {@code true} if the requester was added, {@code false} if it already owns
+ * the lock or is already in the queue
+ * @throws IllegalArgumentException if the item is null
+ */
+ public boolean add(String requester, T item) {
+ if (item == null) {
+ throw LockRequestFuture.makeNullArgException("lock requester item is null");
+ }
+
+ if (requester.equals(owner)) {
+ // requester already owns the lock
+ return false;
+ }
+
+ T prev = requester2item.putIfAbsent(requester, item);
+
+ // if there's a previous value, then that means this requester is already
+ // waiting for a lock on this resource. In that case, we return false
+ return (prev == null);
+ }
+
+ /**
+ * Removes a requester from the lock. The requester may currently own the lock, or it
+ * may be in the queue waiting for the lock. Note: as this is agnostic to the type of
+ * item associated with the requester, it is unable to notify the new owner that it's
+ * the new owner; that is left up to the code that invokes this method.
+ *
+ * @param requester
+ * @param newOwner the new owner info is placed here, if the result is <i>RELOCKED</i>
+ * @return the result
+ */
+ public RemoveResult removeRequester(String requester, Pair<String, T> newOwner) {
+
+ if (!requester.equals(owner)) {
+ // requester does not currently own the lock - remove it from the
+ // queue
+ T ent = requester2item.remove(requester);
+
+ // if there was an entry in the queue, then return true to indicate
+ // that it was removed. Otherwise, return false
+ return (ent != null ? RemoveResult.REMOVED : RemoveResult.NOT_FOUND);
+ }
+
+ /*
+ * requester was the owner - find something to take over
+ */
+ Iterator<Entry<String, T>> it = requester2item.entrySet().iterator();
+ if (!it.hasNext()) {
+ // no one to take over the lock - it's now unlocked
+ return RemoveResult.UNLOCKED;
+ }
+
+ // there's another requester to take over
+ Entry<String, T> ent = it.next();
+ it.remove();
+
+ owner = ent.getKey();
+
+ newOwner.first(owner);
+ newOwner.second(ent.getValue());
+
+ return RemoveResult.RELOCKED;
+ }
+}
diff --git a/policy-core/src/main/java/org/onap/policy/drools/core/lock/LockRequestFuture.java b/policy-core/src/main/java/org/onap/policy/drools/core/lock/LockRequestFuture.java
new file mode 100644
index 00000000..46d1ff2d
--- /dev/null
+++ b/policy-core/src/main/java/org/onap/policy/drools/core/lock/LockRequestFuture.java
@@ -0,0 +1,261 @@
+/*
+ * ============LICENSE_START=======================================================
+ * ONAP
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.drools.core.lock;
+
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.concurrent.atomic.AtomicReference;
+import org.onap.policy.drools.core.lock.PolicyResourceLockFeatureAPI.Callback;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Future associated with a lock request.
+ */
+public class LockRequestFuture implements Future<Boolean> {
+
+ // messages used in exceptions
+ public static final String MSG_NULL_RESOURCE_ID = "null resourceId";
+ public static final String MSG_NULL_OWNER = "null owner";
+
+ private static Logger logger = LoggerFactory.getLogger(LockRequestFuture.class);
+
+ /**
+ * The resource on which the lock was requested.
+ */
+ private final String resourceId;
+
+ /**
+ * The owner for which the lock was requested.
+ */
+ private final String owner;
+
+ /**
+ * Possible states for this future.
+ */
+ private enum State {
+ WAITING, CANCELLED, ACQUIRED, DENIED
+ };
+
+ private AtomicReference<State> state;
+
+ /**
+ * Used to wait for the lock request to complete.
+ */
+ private CountDownLatch waiter = new CountDownLatch(1);
+
+ /**
+ * Callback to invoke once the lock is acquired (or denied). This is set to
+ * {@code null} once the callback has been invoked.
+ */
+ private final AtomicReference<Callback> callback;
+
+ /**
+ * Constructs a future that has already been completed.
+ *
+ * @param resourceId
+ * @param owner owner for which the lock was requested
+ * @param locked {@code true} if the lock has been acquired, {@code false} if the lock
+ * request has been denied
+ * @throws IllegalArgumentException if any of the arguments are {@code null}
+ */
+ public LockRequestFuture(String resourceId, String owner, boolean locked) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ this.resourceId = resourceId;
+ this.owner = owner;
+ this.callback = new AtomicReference<>(null);
+ this.state = new AtomicReference<>(locked ? State.ACQUIRED : State.DENIED);
+
+ // indicate that it's already done
+ this.waiter.countDown();
+ }
+
+ /**
+ * Constructs a future that has not yet been completed.
+ *
+ * @param resourceId
+ * @param owner owner for which the lock was requested
+ * @param callback item to be wrapped
+ * @throws IllegalArgumentException if the resourceId or owner is {@code null}
+ */
+ public LockRequestFuture(String resourceId, String owner, Callback callback) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ this.resourceId = resourceId;
+ this.owner = owner;
+ this.callback = new AtomicReference<>(callback);
+ this.state = new AtomicReference<>(State.WAITING);
+ }
+
+ public String getResourceId() {
+ return resourceId;
+ }
+
+ public String getOwner() {
+ return owner;
+ }
+
+ @Override
+ public boolean cancel(boolean mayInterruptIfRunning) {
+ boolean cancelled = state.compareAndSet(State.WAITING, State.CANCELLED);
+
+ if (cancelled) {
+ logger.info("resource {} owner {} cancelled lock request", resourceId, owner);
+ waiter.countDown();
+ }
+
+ return cancelled;
+ }
+
+ /**
+ * Indicates that the lock has been acquired or denied.
+ *
+ * @param locked {@code true} if the lock has been acquired, {@code false} if the lock
+ * request has been denied
+ *
+ * @return {@code true} if it was not already completed, {@code false} otherwise
+ */
+ protected boolean setLocked(boolean locked) {
+ State newState = (locked ? State.ACQUIRED : State.DENIED);
+ if (state.compareAndSet(State.WAITING, newState)) {
+ waiter.countDown();
+ return true;
+
+ } else {
+ return false;
+ }
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return (state.get() == State.CANCELLED);
+ }
+
+ @Override
+ public boolean isDone() {
+ return (state.get() != State.WAITING);
+ }
+
+ /**
+ * Gets the current status of the lock.
+ *
+ * @return {@code true} if the lock has been acquired, {@code false} otherwise
+ */
+ public boolean isLocked() {
+ return (state.get() == State.ACQUIRED);
+ }
+
+ /**
+ * @return {@code true} if the lock was acquired, {@code false} if it was denied
+ */
+ @Override
+ public Boolean get() throws CancellationException, InterruptedException {
+ waiter.await();
+
+ switch (state.get()) {
+ case CANCELLED:
+ throw new CancellationException("lock request was cancelled");
+ case ACQUIRED:
+ return true;
+ default:
+ // should only be DENIED at this point
+ return false;
+ }
+ }
+
+ /**
+ * @return {@code true} if the lock was acquired, {@code false} if it was denied
+ */
+ @Override
+ public Boolean get(long timeout, TimeUnit unit)
+ throws CancellationException, InterruptedException, TimeoutException {
+
+ if (!waiter.await(timeout, unit)) {
+ throw new TimeoutException("lock request did not complete in time");
+ }
+
+ return get();
+ }
+
+ /**
+ * Invokes the callback, indicating whether or not the lock was acquired.
+ *
+ * @throws IllegalStateException if the request was previously cancelled, has not yet
+ * completed, or if the callback has already been invoked
+ */
+ protected void invokeCallback() {
+ boolean locked;
+
+ switch (state.get()) {
+ case ACQUIRED:
+ locked = true;
+ break;
+ case DENIED:
+ locked = false;
+ break;
+ case CANCELLED:
+ throw new IllegalStateException("cancelled lock request callback");
+ default:
+ // only other choice is WAITING
+ throw new IllegalStateException("incomplete lock request callback");
+ }
+
+ Callback cb = callback.get();
+ if (cb == null || !callback.compareAndSet(cb, null)) {
+ throw new IllegalStateException("already invoked lock request callback");
+ }
+
+
+ // notify the callback
+ try {
+ cb.set(locked);
+
+ } catch (RuntimeException e) {
+ logger.info("lock request callback for resource {} owner {} threw an exception", resourceId, owner, e);
+ }
+ }
+
+ /**
+ * Makes an exception for when an argument is {@code null}.
+ *
+ * @param msg exception message
+ * @return a new Exception
+ */
+ public static IllegalArgumentException makeNullArgException(String msg) {
+ return new IllegalArgumentException(msg);
+ }
+}
diff --git a/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockFeatureAPI.java b/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockFeatureAPI.java
new file mode 100644
index 00000000..718ed5e9
--- /dev/null
+++ b/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockFeatureAPI.java
@@ -0,0 +1,190 @@
+/*
+ * ============LICENSE_START=======================================================
+ * api-resource-locks
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.drools.core.lock;
+
+import java.util.concurrent.Future;
+import org.onap.policy.drools.utils.OrderedService;
+import org.onap.policy.drools.utils.OrderedServiceImpl;
+
+/**
+ * Resource locks. Each lock has an "owner", which is intended to be unique across a
+ * single instance of a running PolicyEngine.
+ * <p>
+ * This interface provides a way to invoke optional features at various points in the
+ * code. At appropriate points in the application, the code iterates through this list,
+ * invoking these optional methods.
+ * <p>
+ * Implementers may choose to implement a level of locking appropriate to the application.
+ * For instance, they may choose to implement an engine-wide locking scheme, or they may
+ * choose to implement a global locking scheme (e.g., through a shared DB).
+ */
+public interface PolicyResourceLockFeatureAPI extends OrderedService {
+
+ /**
+ * 'FeatureAPI.impl.getList()' returns an ordered list of objects implementing the
+ * 'FeatureAPI' interface.
+ */
+ public static OrderedServiceImpl<PolicyResourceLockFeatureAPI> impl =
+ new OrderedServiceImpl<>(PolicyResourceLockFeatureAPI.class);
+
+ /**
+ * Callback that an implementer invokes when a lock is acquired (or denied),
+ * asynchronously. The implementer invokes the method to indicate that the lock was
+ * acquired (or denied).
+ */
+ @FunctionalInterface
+ public static interface Callback {
+
+ /**
+ *
+ * @param locked {@code true} if the lock was acquired, {@code false} if the lock
+ * was denied
+ */
+ public void set(boolean locked);
+ }
+
+ /**
+ * This method is called before a lock is acquired on a resource. If a callback is
+ * provided, and the implementer is unable to acquire the lock immediately, then the
+ * implementer will invoke the callback once the lock is acquired. If the implementer
+ * handled the request, then it will return a future, which may be in one of three
+ * states:
+ * <dl>
+ * <dt>isDone()=true and get()=true</dt>
+ * <dd>the lock has been acquired; the callback may or may not have been invoked</dd>
+ * <dt>isDone()=true and get()=false</dt>
+ * <dd>the lock request has been denied; the callback may or may not have been
+ * invoked</dd>
+ * <dt>isDone()=false</dt>
+ * <dd>the lock was not immediately available and a callback was provided. The
+ * callback will be invoked once the lock is acquired (or denied). In this case, the
+ * future may be used to cancel the request</dd>
+ * </dl>
+ *
+ * @param resourceId
+ * @param owner
+ * @param callback function to invoke, if the requester wishes to wait for the lock to
+ * come available, {@code null} to provide immediate replies
+ * @return a future for the lock, if the implementer handled the request, {@code null}
+ * if additional locking logic should be performed
+ * @throws IllegalStateException if the owner already holds the lock or is already in
+ * the queue to get the lock
+ */
+ public default Future<Boolean> beforeLock(String resourceId, String owner, Callback callback) {
+ return null;
+ }
+
+ /**
+ * This method is called after a lock for a resource has been acquired or denied. This
+ * may be invoked immediately, if the status can be determined immediately, or it may
+ * be invoked asynchronously, once the status has been determined.
+ *
+ * @param resourceId
+ * @param owner
+ * @param locked {@code true} if the lock was acquired, {@code false} if it was denied
+ * @return {@code true} if the implementer handled the request, {@code false}
+ * otherwise
+ */
+ public default boolean afterLock(String resourceId, String owner, boolean locked) {
+ return false;
+ }
+
+ /**
+ * This method is called before a lock on a resource is released.
+ *
+ * @param resourceId
+ * @param owner
+ * <dt>true</dt>
+ * <dd>the implementer handled the request and found the resource to be locked
+ * by the given owner; the resource was unlocked and no additional locking
+ * logic should be performed</dd>
+ * <dt>false</dt>
+ * <dd>the implementer handled the request and found the resource was not
+ * locked by given the owner; no additional locking logic should be
+ * performed</dd>
+ * <dt>null</dt>
+ * <dd>the implementer did not handle the request; additional locking logic
+ * <i>should be</i> performed
+ * </dl>
+ */
+ public default Boolean beforeUnlock(String resourceId, String owner) {
+ return null;
+ }
+
+ /**
+ * This method is called after a lock on a resource is released.
+ *
+ * @param resourceId
+ * @param owner
+ * @param unlocked {@code true} if the lock was released, {@code false} if the owner
+ * did not have a lock on the resource
+ * @return {@code true} if the implementer handled the request, {@code false}
+ * otherwise
+ */
+ public default boolean afterUnlock(String resourceId, String owner, boolean unlocked) {
+ return false;
+ }
+
+ /**
+ * This method is called before a check is made to determine if a resource is locked.
+ *
+ * @param resourceId
+ * @return
+ * <dl>
+ * <dt>true</dt>
+ * <dd>the implementer handled the request and found the resource to be
+ * locked; no additional locking logic should be performed</dd>
+ * <dt>false</dt>
+ * <dd>the implementer handled the request and found the resource was not
+ * locked; no additional locking logic should be performed</dd>
+ * <dt>null</dt>
+ * <dd>the implementer did not handle the request; additional locking logic
+ * <i>should be</i> performed
+ * </dl>
+ */
+ public default Boolean beforeIsLocked(String resourceId) {
+ return null;
+ }
+
+ /**
+ * This method is called before a check is made to determine if a particular owner
+ * holds the lock on a resource.
+ *
+ * @param resourceId
+ * @param owner
+ * @return
+ * <dl>
+ * <dt>true</dt>
+ * <dd>the implementer handled the request and found the resource to be locked
+ * by the given owner; no additional locking logic should be performed</dd>
+ * <dt>false</dt>
+ * <dd>the implementer handled the request and found the resource was not
+ * locked by given the owner; no additional locking logic should be
+ * performed</dd>
+ * <dt>null</dt>
+ * <dd>the implementer did not handle the request; additional locking logic
+ * <i>should be</i> performed
+ * </dl>
+ */
+ public default Boolean beforeIsLockedBy(String resourceId, String owner) {
+ return null;
+ }
+}
diff --git a/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockManager.java b/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockManager.java
new file mode 100644
index 00000000..d51f2b91
--- /dev/null
+++ b/policy-core/src/main/java/org/onap/policy/drools/core/lock/PolicyResourceLockManager.java
@@ -0,0 +1,208 @@
+/*
+ * ============LICENSE_START=======================================================
+ * ONAP
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.drools.core.lock;
+
+import static org.onap.policy.drools.core.lock.LockRequestFuture.MSG_NULL_OWNER;
+import static org.onap.policy.drools.core.lock.LockRequestFuture.MSG_NULL_RESOURCE_ID;
+import static org.onap.policy.drools.core.lock.LockRequestFuture.makeNullArgException;
+import java.util.List;
+import java.util.concurrent.Future;
+import java.util.function.Function;
+import org.onap.policy.drools.core.lock.PolicyResourceLockFeatureAPI.Callback;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Manager of resource locks. Checks for API implementers.
+ */
+public class PolicyResourceLockManager extends SimpleLockManager {
+
+ private static Logger logger = LoggerFactory.getLogger(PolicyResourceLockManager.class);
+
+ /**
+ * Used to access various objects.
+ */
+ public static Factory factory = new Factory();
+
+ /**
+ * Used by junit tests.
+ */
+ protected PolicyResourceLockManager() {
+ super();
+ }
+
+ /**
+ *
+ * @return the manager singleton
+ */
+ public static PolicyResourceLockManager getInstance() {
+ return Singleton.instance;
+ }
+
+ protected static Factory getFactory() {
+ return factory;
+ }
+
+ /**
+ * Sets the factory to be used by junit tests.
+ *
+ * @param factory
+ */
+ protected static void setFactory(Factory factory) {
+ PolicyResourceLockManager.factory = factory;
+ }
+
+ @Override
+ public Future<Boolean> lock(String resourceId, String owner, Callback callback) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ Future<Boolean> result = doIntercept(null, impl -> impl.beforeLock(resourceId, owner, callback));
+ if (result != null) {
+ return result;
+ }
+
+ // implementer didn't do the work - use superclass
+ result = super.lock(resourceId, owner, callback);
+
+ boolean locked = ((LockRequestFuture) result).isLocked();
+
+ doIntercept(false, impl -> impl.afterLock(resourceId, owner, locked));
+
+ return result;
+ }
+
+ @Override
+ public boolean unlock(String resourceId, String owner) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ Boolean result = doIntercept(null, impl -> impl.beforeUnlock(resourceId, owner));
+ if (result != null) {
+ return result;
+ }
+
+ // implementer didn't do the work - use superclass
+ boolean unlocked = super.unlock(resourceId, owner);
+
+ doIntercept(false, impl -> impl.afterUnlock(resourceId, owner, unlocked));
+
+ return unlocked;
+ }
+
+ /**
+ *
+ * @throws IllegalArgumentException if the resourceId is {@code null}
+ */
+ @Override
+ public boolean isLocked(String resourceId) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ Boolean result = doIntercept(null, impl -> impl.beforeIsLocked(resourceId));
+ if (result != null) {
+ return result;
+ }
+
+ return super.isLocked(resourceId);
+ }
+
+ /**
+ *
+ * @throws IllegalArgumentException if the resourceId or owner is {@code null}
+ */
+ @Override
+ public boolean isLockedBy(String resourceId, String owner) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ Boolean result = doIntercept(null, impl -> impl.beforeIsLockedBy(resourceId, owner));
+ if (result != null) {
+ return result;
+ }
+
+ return super.isLockedBy(resourceId, owner);
+ }
+
+ /**
+ * Applies a function to each implementer of the lock feature. Returns as soon as one
+ * of them returns a non-null value.
+ *
+ * @param continueValue if the implementer returns this value, then it continues to
+ * check addition implementers
+ * @param func function to be applied to the implementers
+ * @return first non-null value returned by an implementer, <i>continueValue<i/> if
+ * they all returned <i>continueValue<i/>
+ */
+ public static <T> T doIntercept(T continueValue, Function<PolicyResourceLockFeatureAPI, T> func) {
+
+ for (PolicyResourceLockFeatureAPI impl : factory.getImplementers()) {
+ try {
+ T result = func.apply(impl);
+ if (result != continueValue) {
+ return result;
+ }
+
+ } catch (RuntimeException e) {
+ logger.warn("lock feature {} threw an exception", impl, e);
+ }
+ }
+
+ return continueValue;
+ }
+
+ /**
+ * Initialization-on-demand holder idiom.
+ */
+ private static class Singleton {
+ private static final PolicyResourceLockManager instance = new PolicyResourceLockManager();
+ }
+
+ /**
+ * Used to access various objects.
+ */
+ public static class Factory {
+
+ /**
+ *
+ * @return the list of feature implementers
+ */
+ public List<PolicyResourceLockFeatureAPI> getImplementers() {
+ return PolicyResourceLockFeatureAPI.impl.getList();
+ }
+ }
+}
diff --git a/policy-core/src/main/java/org/onap/policy/drools/core/lock/SimpleLockManager.java b/policy-core/src/main/java/org/onap/policy/drools/core/lock/SimpleLockManager.java
new file mode 100644
index 00000000..14cffaab
--- /dev/null
+++ b/policy-core/src/main/java/org/onap/policy/drools/core/lock/SimpleLockManager.java
@@ -0,0 +1,168 @@
+/*
+ * ============LICENSE_START=======================================================
+ * ONAP
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.drools.core.lock;
+
+import static org.onap.policy.drools.core.lock.LockRequestFuture.MSG_NULL_OWNER;
+import static org.onap.policy.drools.core.lock.LockRequestFuture.MSG_NULL_RESOURCE_ID;
+import static org.onap.policy.drools.core.lock.LockRequestFuture.makeNullArgException;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.Future;
+import org.onap.policy.drools.core.lock.PolicyResourceLockFeatureAPI.Callback;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Simple lock manager. Callbacks are ignored. Does not redirect to lock feature
+ * implementers.
+ */
+public class SimpleLockManager {
+
+ protected static Logger logger = LoggerFactory.getLogger(SimpleLockManager.class);
+
+ /**
+ * Maps a resource to the owner that holds the lock on it.
+ */
+ private ConcurrentHashMap<String, String> resource2owner = new ConcurrentHashMap<>();
+
+ /**
+ *
+ */
+ public SimpleLockManager() {
+ super();
+ }
+
+ // TODO: for ease of use by clients, should we always invoke the callback, even though
+ // this is synchronous?
+
+ /**
+ * Attempts to lock a resource. This method ignores the callback and always returns a
+ * {@link CompletedLockRequest}.
+ *
+ * @param resourceId
+ * @param owner
+ * @param callback function to invoke, if the requester wishes to wait for the lock to
+ * be acquired, {@code null} to provide immediate replies
+ * @return a future for the lock request. The future will be in one of three states:
+ * <dl>
+ * <dt>isDone()=true and get()=true</dt>
+ * <dd>the lock has been acquired; the callback may or may not have been
+ * invoked</dd>
+ * <dt>isDone()=true and get()=false</dt>
+ * <dd>the lock request has been denied; the callback may or may not have been
+ * invoked</dd>
+ * <dt>isDone()=false</dt>
+ * <dd>the lock was not immediately available and a callback was provided. The
+ * callback will be invoked once the lock is acquired (or denied). In this
+ * case, the future may be used to cancel the request</dd>
+ * </dl>
+ * @throws IllegalArgumentException if the resourceId or owner is {@code null}
+ * @throws IllegalStateException if the owner already holds the lock or is already in
+ * the queue to get the lock
+ */
+ public Future<Boolean> lock(String resourceId, String owner, Callback callback) {
+
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ boolean locked = (resource2owner.putIfAbsent(resourceId, owner) == null);
+
+ if (!locked && owner.equals(resource2owner.get(resourceId))) {
+ throw new IllegalStateException("lock for resource " + resourceId + " already owned by " + owner);
+ }
+
+ logger.info("lock {} for resource {} owner {}", locked, resourceId, owner);
+
+ return new LockRequestFuture(resourceId, owner, locked);
+ }
+
+ /**
+ * Unlocks a resource.
+ *
+ * @param resourceId
+ * @param owner
+ * @return {@code true} if unlocked, {@code false} if the given owner does not
+ * currently hold a lock on the resource
+ * @throws IllegalArgumentException if the resourceId or owner is {@code null}
+ */
+ public boolean unlock(String resourceId, String owner) {
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ boolean unlocked = resource2owner.remove(resourceId, owner);
+ logger.info("unlock resource {} owner {} = {}", resourceId, owner, unlocked);
+
+ return unlocked;
+ }
+
+ /**
+ * Determines if a resource is locked by anyone.
+ *
+ * @param resourceId
+ * @return {@code true} if the resource is locked, {@code false} otherwise
+ * @throws IllegalArgumentException if the resourceId is {@code null}
+ */
+ public boolean isLocked(String resourceId) {
+
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ boolean locked = resource2owner.containsKey(resourceId);
+
+ logger.debug("resource {} isLocked = {}", resourceId, locked);
+
+ return locked;
+ }
+
+ /**
+ * Determines if a resource is locked by a particular owner.
+ *
+ * @param resourceId
+ * @param owner
+ * @return {@code true} if the resource is locked, {@code false} otherwise
+ * @throws IllegalArgumentException if the resourceId or owner is {@code null}
+ */
+ public boolean isLockedBy(String resourceId, String owner) {
+
+ if (resourceId == null) {
+ throw makeNullArgException(MSG_NULL_RESOURCE_ID);
+ }
+
+ if (owner == null) {
+ throw makeNullArgException(MSG_NULL_OWNER);
+ }
+
+ boolean locked = owner.equals(resource2owner.get(resourceId));
+ logger.debug("resource {} isLockedBy {} = {}", resourceId, owner, locked);
+
+ return locked;
+ }
+}