1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.ehcache.transaction;
17
18 import net.sf.ehcache.Element;
19
20 import java.io.Serializable;
21
22 /***
23 * A soft lock is used to lock elements in transactional stores
24 *
25 * @author Ludovic Orban
26 */
27 public interface SoftLock extends Serializable {
28
29 /***
30 * Get the key of the element this soft lock is guarding
31 * @return the key
32 */
33 Object getKey();
34
35 /***
36 * Get the ID of the transaction under which this soft lock is operating
37 * @return the TransactionID
38 */
39 TransactionID getTransactionID();
40
41 /***
42 * Get the element the current transaction is supposed to see.
43 * @param currentTransactionId the current transaction under which this call is executed
44 * @return the Element visible to the current transaction
45 */
46 Element getElement(TransactionID currentTransactionId);
47
48 /***
49 * Change the Element at the key this soft lock is guarding
50 * @param element the new Element
51 * @return the previous Element
52 */
53 Element updateElement(Element element);
54
55 /***
56 * Lock the soft lock
57 */
58 void lock();
59
60 /***
61 * Attempt to lock the soft lock
62 * @param ms the time in milliseconds before this method gives up
63 * @return true if the soft lock was locked, false otherwise
64 * @throws InterruptedException if the thread calling this method was interrupted
65 */
66 boolean tryLock(long ms) throws InterruptedException;
67
68 /***
69 * Clear the state of the soft lock after a tryLock() call succeeded.
70 */
71 void clearTryLock();
72
73 /***
74 * Unlock the soft lock. Once a soft lock got unlocked, it is considered 'dead': it cannot be
75 * locked again and must be cleaned up
76 */
77 void unlock();
78
79 /***
80 * Freeze the soft lock. A soft lock should only be frozen for a very short period of time as this blocks
81 * the {@link #getElement(TransactionID)} method calls.
82 * Freeze is used to mark the start of a commit / rollback phase
83 */
84 void freeze();
85
86 /***
87 * Unfreeze the soft lock
88 */
89 void unfreeze();
90
91 /***
92 * Check if the soft lock expired, ie: that the thread which locked it died
93 * @return true if the soft lock is orphan and should be cleaned up, false otherwise
94 */
95 boolean isExpired();
96
97 /***
98 * Get the Element with which this soft lock should be replaced by a commit, rollback or clean up
99 * @return the Element
100 */
101 Element getFrozenElement();
102
103 }