001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.transaction.locking;
018
019 /**
020 *
021 * Extended multi level lock. Compared to basic {@link MultiLevelLock} allows for more flexible
022 * locking including preference and more compatibility modes.
023 *
024 * @version $Id: MultiLevelLock2.java 493628 2007-01-07 01:42:48Z joerg $
025 * @see LockManager2
026 * @see MultiLevelLock
027 * @see GenericLock
028 * @since 1.1
029 */
030 public interface MultiLevelLock2 extends MultiLevelLock {
031
032 /**
033 * Compatibility mode: none reentrant. Lock level by the same owner <em>shall</em>
034 * affect compatibility.
035 */
036 public static final int COMPATIBILITY_NONE = 0;
037
038 /**
039 * Compatibility mode: reentrant. Lock level by the same owner <em>shall not</em>
040 * affect compatibility.
041 */
042 public static final int COMPATIBILITY_REENTRANT = 1;
043
044 /**
045 * Compatibility mode: supporting. Lock levels that are the same as the
046 * desired <em>shall not</em> affect compatibility, but lock level held by the same
047 * owner <em>shall</em>.
048 */
049 public static final int COMPATIBILITY_SUPPORT = 2;
050
051 /**
052 * Compatibility mode: reentrant and supporting. Lock levels that are the same as the
053 * desired and lock levels held by the same
054 * owner <em>shall not</em> affect compatibility.
055 */
056 public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT = 3;
057
058 /**
059 * Tests if a certain lock level is owned by an owner.
060 *
061 * @param ownerId
062 * a unique id identifying the entity that wants to check a
063 * certain lock level on this lock
064 * @param lockLevel
065 * the lock level to test
066 * @return <code>true</code> if the lock could be acquired at the time
067 * this method was called
068 */
069 public boolean has(Object ownerId, int lockLevel);
070
071 /**
072 * Tests if a certain lock level <em>could</em> be acquired. This method
073 * tests only and does <em>not actually acquire</em> the lock.
074 *
075 * @param ownerId
076 * a unique id identifying the entity that wants to test a
077 * certain lock level on this lock
078 * @param targetLockLevel
079 * the lock level to acquire
080 * @param compatibility
081 * {@link #COMPATIBILITY_NONE}if no additional compatibility is
082 * desired (same as reentrant set to false) ,
083 * {@link #COMPATIBILITY_REENTRANT}if lock level by the same
084 * owner shall not affect compatibility (same as reentrant set to
085 * true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
086 * are the same as the desired shall not affect compatibility, or
087 * finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
088 * a combination of reentrant and support
089 * @return <code>true</code> if the lock could be acquired at the time
090 * this method was called
091 */
092 public boolean test(Object ownerId, int targetLockLevel, int compatibility);
093
094 /**
095 * Tries to acquire a certain lock level on this lock. Does the same as
096 * {@link org.apache.commons.transaction.locking.MultiLevelLock#acquire(java.lang.Object, int, boolean, boolean, long)}
097 * except that it allows for different compatibility settings. There is an
098 * additional compatibility mode {@link #COMPATIBILITY_SUPPORT}that allows
099 * equal lock levels not to interfere with each other. This is like an
100 * additional shared compatibility and useful when you only want to make
101 * sure not to interfer with lowe levels, but are fine with the same.
102 *
103 * @param ownerId a unique id identifying the entity that wants to acquire a certain lock level on this lock
104 * @param targetLockLevel the lock level to acquire
105 * @param wait <code>true</code> if this method shall block when the desired lock level can not be acquired
106 * @param compatibility
107 * {@link #COMPATIBILITY_NONE}if no additional compatibility is
108 * desired (same as reentrant set to false) ,
109 * {@link #COMPATIBILITY_REENTRANT}if lock level by the same
110 * owner shall not affect compatibility (same as reentrant set to
111 * true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
112 * are the same as the desired shall not affect compatibility, or
113 * finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
114 * a combination of reentrant and support
115 *
116 * @param preferred
117 * in case this lock request is incompatible with existing ones
118 * and we wait, it shall be granted before other waiting requests
119 * that are not preferred
120 * @param timeoutMSecs if blocking is enabled by the <code>wait</code> parameter this specifies the maximum wait time in milliseconds
121 * @return <code>true</code> if the lock actually was acquired
122 * @throws InterruptedException when the thread waiting on this method is interrupted
123 *
124 */
125 public boolean acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility,
126 boolean preferred, long timeoutMSecs) throws InterruptedException;
127
128 }