001 package org.apache.ojb.broker.locking;
002
003 /* Copyright 2002-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * 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
018
019 /**
020 * This interface declares the functionality of the OJB locking-api for support of
021 * pessimistic locking.
022 * <p>
023 * OJB allows to provide user defined implementations of this interface.
024 * To activate a user defined LockManager implementation it must be configured in
025 * the OJB.properties file.
026 * </p>
027 * <p>
028 * All locks have to be reentrant, this means if you already have a lock for
029 * writing and you try to acquire write access again you will not be blocked
030 * by this first lock.
031 * </p>
032 * <p>
033 * It's optional to support the <em>lockTimeout</em> and <em>blockTimeout</em> properties.
034 * </p>
035 *
036 * @see LockManagerInMemoryImpl
037 * @see LockManagerCommonsImpl
038 * @version $Id: LockManager.java,v 1.1 2007-08-24 22:17:41 ewestfal Exp $
039 */
040 public interface LockManager extends IsolationLevels
041 {
042 /**
043 * Default lock timeout value - set to 60000 ms.
044 */
045 public final static long DEFAULT_LOCK_TIMEOUT = 60000;
046
047 /**
048 * Default lock wait time in millisecond - set to 1000 ms;
049 */
050 public final static long DEFAULT_BLOCK_TIMEOUT = 1000;
051
052 /**
053 * The maximal time to wait for acquire a lock.
054 *
055 * @return
056 */
057 public long getBlockTimeout();
058
059 /**
060 * Set the maximal time to wait for acquire a lock in milliseconds.
061 * All so called <em>non-blocking</em> implementation will ignore this setting.
062 *
063 * @param timeout The time to wait for acquire a lock.
064 */
065 public void setBlockTimeout(long timeout);
066
067 /**
068 * Get the current used lock timeout value in milliseconds.
069 * @return Current used locking timeout value in ms.
070 */
071 public long getLockTimeout();
072
073 /**
074 * Set the lock timeout value in milliseconds. If timeout was set to <em>-1</em>
075 * the never will never timeout.
076 *
077 * @param timeout The lock timeout in <em>ms</em> of acquired read/write/upgrade locks.
078 */
079 public void setLockTimeout(long timeout);
080
081 /**
082 * Returns info about the used lock manager implementation and the state
083 * of the lock manager.
084 */
085 public String getLockInfo();
086
087 /**
088 * Acquires a readlock for lock key on resource object.
089 * Returns true if successful, else false.
090 *
091 * @param key The owner key of the lock.
092 * @param resourceId The resource to lock.
093 * @param isolationLevel The isolation level of the lock.
094 * @return <em>True</em> if the lock was successfully acquired.
095 */
096 public boolean readLock(Object key, Object resourceId, int isolationLevel);
097
098 /**
099 * Acquires a write lock for lock key on resource object.
100 * Returns true if successful, else false.
101 *
102 * @param key The owner key of the lock.
103 * @param resourceId The resource to lock.
104 * @param isolationLevel The isolation level of the lock.
105 * @return <em>True</em> if the lock was successfully acquired.
106 */
107 public boolean writeLock(Object key, Object resourceId, int isolationLevel);
108
109 /**
110 * Acquire an upgrade lock.
111 * (Current implementations always acquire a write lock instead).
112 *
113 * @param key The owner key of the lock.
114 * @param resourceId The resource to lock.
115 * @param isolationLevel The isolation level of the lock.
116 * @return <em>True</em> if the lock was successfully acquired.
117 */
118 public boolean upgradeLock(Object key, Object resourceId, int isolationLevel);
119
120 /**
121 * Releases a lock for lock key on resource object.
122 * Returns true if successful, else false.
123 *
124 * @param key The owner key of the lock.
125 * @param resourceId The resource to release.
126 * @return <em>True</em> if the lock was successfully released.
127 */
128 public boolean releaseLock(Object key, Object resourceId);
129
130 /**
131 * Release all resource locks hold by the specified owner key.
132 *
133 * @param key The owner key to release all associated locks.
134 */
135 public void releaseLocks(Object key);
136
137 /**
138 * Checks if there is a read lock for owner key on resource object.
139 * Returns true if so, else false.
140 *
141 * @param key The owner key of the lock.
142 * @param resourceId The resource to check.
143 * @return <em>True</em> if the lock exists.
144 */
145 public boolean hasRead(Object key, Object resourceId);
146
147 /**
148 * Checks if there is a write lock for lock key on resource object.
149 * Returns true if so, else false.
150 *
151 * @param key The owner key of the lock.
152 * @param resourceId The resource to check.
153 * @return <em>True</em> if the lock exists.
154 */
155 public boolean hasWrite(Object key, Object resourceId);
156
157 /**
158 * Checks if there is a upgrade lock for lock key on resource object.
159 * Returns true if so, else false.
160 *
161 * @param key The owner key of the lock.
162 * @param resourceId The resource to check.
163 * @return <em>True</em> if the lock exists.
164 */
165 public boolean hasUpgrade(Object key, Object resourceId);
166 }