--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.services.locks.LockFactory\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.services.locks;\r
+\r
+import org.apache.derby.iapi.util.Matchable;\r
+import org.apache.derby.iapi.error.StandardException;\r
+import org.apache.derby.iapi.services.property.PropertySetCallback;\r
+import java.util.Enumeration;\r
+\r
+\r
+/**\r
+ Generic locking of objects. Enables deadlock detection.\r
+\r
+ <BR>\r
+ MT - Mutable - Container Object - Thread Safe\r
+\r
+\r
+*/\r
+public interface LockFactory extends PropertySetCallback {\r
+\r
+ /**\r
+ * Create an object which can be used as a compatibility space. A\r
+ * compatibility space object can only be used in the\r
+ * <code>LockFactory</code> that created it.\r
+ *\r
+ * @param owner the owner of the compatibility space (typically a\r
+ * transaction object). Might be <code>null</code>.\r
+ * @return an object which represents a compatibility space\r
+ */\r
+ public CompatibilitySpace createCompatibilitySpace(Object owner);\r
+\r
+ /**\r
+ Lock an object within a compatibility space\r
+ and associate the lock with a group object,\r
+ waits up to timeout milli-seconds for the object to become unlocked. A \r
+ timeout of 0 means do not wait for the lock to be unlocked.\r
+ Note the actual time waited is approximate.\r
+ <P>\r
+ A compatibility space in an space where lock requests are assumed to be\r
+ compatible and granted by the lock manager if the trio\r
+ {compatibilitySpace, ref, qualifier} are equal (i.e. reference equality\r
+ for qualifier and compatibilitySpace, equals() method for ref).\r
+ Granted by the lock manager means that the Lockable object may or may \r
+ not be queried to see if the request is compatible.\r
+ <BR>\r
+ A compatibility space is not assumed to be owned by a single thread.\r
+ \r
+\r
+\r
+ @param compatibilitySpace object defining compatibility space\r
+ @param group handle of group, must be private to a thread.\r
+ @param ref reference to object to be locked\r
+ @param qualifier A qualification of the request.\r
+ @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.\r
+\r
+ @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock\r
+ could not be granted.\r
+\r
+ @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)\r
+ @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).\r
+ @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while\r
+ it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,\r
+ (message id will be LockFactory.InterruptedExceptionId)\r
+ @exception StandardException Standard Derby error policy.\r
+\r
+ */\r
+ public boolean lockObject(CompatibilitySpace compatibilitySpace,\r
+ Object group, Lockable ref, Object qualifier,\r
+ int timeout)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Unlock a single lock on a single object held within this compatibility\r
+ space and locked with the supplied qualifier.\r
+\r
+ @param compatibilitySpace object defining compatibility space\r
+ @param group handle of group.\r
+ @param ref Reference to object to be unlocked.\r
+ @param qualifier qualifier of lock to be unlocked\r
+\r
+ @return number of locks released (one or zero).\r
+ */\r
+ public int unlock(CompatibilitySpace compatibilitySpace, Object group,\r
+ Lockable ref, Object qualifier);\r
+\r
+ /**\r
+ Unlock all locks in a group. \r
+\r
+ @param compatibilitySpace object defining compatibility space\r
+ @param group handle of group that objects were locked with.\r
+ */\r
+ public void unlockGroup(CompatibilitySpace compatibilitySpace,\r
+ Object group);\r
+\r
+ /**\r
+ Unlock all locks on a group that match the passed in value.\r
+ */\r
+ public void unlockGroup(CompatibilitySpace compatibilitySpace,\r
+ Object group, Matchable key);\r
+\r
+ /**\r
+ Transfer a set of locks from one group to another.\r
+ */\r
+ public void transfer(CompatibilitySpace compatibilitySpace,\r
+ Object oldGroup, Object newGroup);\r
+\r
+ /**\r
+ Returns true if locks held by anyone are blocking anyone else\r
+ */\r
+ public boolean anyoneBlocked();\r
+\r
+ /**\r
+ Return true if locks are held in this compatibility space and\r
+ this group.\r
+\r
+ @param group handle of group that objects were locked with.\r
+\r
+ */\r
+ public boolean areLocksHeld(CompatibilitySpace compatibilitySpace,\r
+ Object group);\r
+\r
+ /**\r
+ Return true if locks are held in this compatibility space.\r
+ */\r
+ public boolean areLocksHeld(CompatibilitySpace compatibilitySpace);\r
+\r
+ /**\r
+ Lock an object with zero duration within a compatibility space,\r
+ waits up to timeout milli-seconds for the object to become unlocked. A \r
+ timeout of 0 means do not wait for the lock to be unlocked.\r
+ Note the actual time waited is approximate.\r
+ <P>\r
+ Zero duration means the lock is released as soon as it is obtained.\r
+ <P>\r
+ A compatibility space in an space where lock requests are assumed to be\r
+ compatible and granted by the lock manager if the trio\r
+ {compatibilitySpace, ref, qualifier} are equal (i.e. reference equality\r
+ for qualifier and compatibilitySpace, equals() method for ref).\r
+ Granted by the lock manager means that the Lockable object may or may \r
+ not be queried to see if the request is compatible.\r
+ <BR>\r
+ A compatibility space is not assumed to be owned by a single thread.\r
+ \r
+\r
+\r
+ @param compatibilitySpace object defining compatibility space\r
+ @param ref reference to object to be locked\r
+ @param qualifier A qualification of the request.\r
+ @param timeout the maximum time to wait in milliseconds, LockFactory.NO_WAIT means don't wait.\r
+\r
+ @return true if the lock was obtained, false if timeout is equal to LockFactory.NO_WAIT and the lock\r
+ could not be granted.\r
+\r
+ @exception org.apache.derby.iapi.error.StandardException A deadlock has occured (message id will be LockFactory.Deadlock)\r
+ @exception org.apache.derby.iapi.error.StandardException The wait for the lock timed out (message id will be LockFactory.TimeOut).\r
+ @exception org.apache.derby.iapi.error.StandardException Another thread interupted this thread while\r
+ it was waiting for the lock. This will be a StandardException with a nested java.lang.InterruptedException exception,\r
+ (message id will be LockFactory.InterruptedExceptionId)\r
+ @exception StandardException Standard Derby error policy.\r
+\r
+ */\r
+ public boolean zeroDurationlockObject(CompatibilitySpace compatibilitySpace,\r
+ Lockable ref, Object qualifier,\r
+ int timeout)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Check to see if a specific lock is held.\r
+ */\r
+ public boolean isLockHeld(CompatibilitySpace compatibilitySpace,\r
+ Object group, Lockable ref, Object qualifier);\r
+\r
+ /**\r
+ Install a limit that is called when the size of the group exceeds\r
+ the required limit.\r
+ <BR>\r
+ It is not guaranteed that the callback method (Limit.reached) is\r
+ called as soon as the group size exceeds the given limit.\r
+ If the callback method does not result in a decrease in the\r
+ number of locks held then the lock factory implementation\r
+ may delay calling the method again. E.g. with a limit\r
+ of 500 and a reached() method that does nothing, may result\r
+ in the call back method only being called when the group size reaches\r
+ 550.\r
+ <BR>\r
+ Only one limit may be in place for a group at any time.\r
+ @see Limit\r
+ */\r
+ public void setLimit(CompatibilitySpace compatibilitySpace, Object group,\r
+ int limit, Limit callback);\r
+\r
+ /**\r
+ Clear a limit set by setLimit.\r
+ */\r
+ public void clearLimit(CompatibilitySpace compatibilitySpace, Object group);\r
+\r
+ /**\r
+ Make a virtual lock table for diagnostics.\r
+ */\r
+ public Enumeration makeVirtualLockTable();\r
+\r
+}\r
+\r
+\r