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