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,
093: int compatibility);
094:
095: /**
096: * Tries to acquire a certain lock level on this lock. Does the same as
097: * {@link org.apache.commons.transaction.locking.MultiLevelLock#acquire(java.lang.Object, int, boolean, boolean, long)}
098: * except that it allows for different compatibility settings. There is an
099: * additional compatibility mode {@link #COMPATIBILITY_SUPPORT}that allows
100: * equal lock levels not to interfere with each other. This is like an
101: * additional shared compatibility and useful when you only want to make
102: * sure not to interfer with lowe levels, but are fine with the same.
103: *
104: * @param ownerId a unique id identifying the entity that wants to acquire a certain lock level on this lock
105: * @param targetLockLevel the lock level to acquire
106: * @param wait <code>true</code> if this method shall block when the desired lock level can not be acquired
107: * @param compatibility
108: * {@link #COMPATIBILITY_NONE}if no additional compatibility is
109: * desired (same as reentrant set to false) ,
110: * {@link #COMPATIBILITY_REENTRANT}if lock level by the same
111: * owner shall not affect compatibility (same as reentrant set to
112: * true), or {@link #COMPATIBILITY_SUPPORT}if lock levels that
113: * are the same as the desired shall not affect compatibility, or
114: * finally {@link #COMPATIBILITY_REENTRANT_AND_SUPPORT}which is
115: * a combination of reentrant and support
116: *
117: * @param preferred
118: * in case this lock request is incompatible with existing ones
119: * and we wait, it shall be granted before other waiting requests
120: * that are not preferred
121: * @param timeoutMSecs if blocking is enabled by the <code>wait</code> parameter this specifies the maximum wait time in milliseconds
122: * @return <code>true</code> if the lock actually was acquired
123: * @throws InterruptedException when the thread waiting on this method is interrupted
124: *
125: */
126: public boolean acquire(Object ownerId, int targetLockLevel,
127: boolean wait, int compatibility, boolean preferred,
128: long timeoutMSecs) throws InterruptedException;
129:
130: }
|