CacheConcurrencyStrategy


1   //$Id: CacheConcurrencyStrategy.java,v 1.7 2005/02/12 07:19:08 steveebersole Exp $
2   package org.hibernate.cache;
3   
4   import java.util.Comparator  ;
5   
6   /**
7    * Implementors manage transactional access to cached data. Transactions
8    * pass in a timestamp indicating transaction start time. Two different
9    * implementation patterns are provided for. A transaction-aware cache
10   * implementation might be wrapped by a "synchronous" concurrency strategy, 
11   * where updates to the cache are written to the cache inside the transaction. 
12   * A non transaction-aware cache would be wrapped by an "asynchronous"
13   * concurrency strategy, where items are merely "soft locked" during the 
14   * transaction and then updated during the "after transaction completion"
15   * phase. The soft lock is not an actual lock on the database row - 
16   * only upon the cached representation of the item.<br>
17   * <br>
18   * For the client, update lifecycles are: lock->evict->release,
19   * lock->update->afterUpdate, insert->afterInsert.<br>
20   * <br>
21   * Note that, for an asynchronous cache, cache invalidation must be a two 
22   * step process (lock->release, or lock-afterUpdate), since this is the only 
23   * way to guarantee consistency with the database for a nontransaction cache 
24   * implementation. For a synchronous cache, cache invalidation is a single 
25   * step process (evict, or update). Hence, this interface defines a three
26   * step process, to cater for both models.
27   */
28  public interface CacheConcurrencyStrategy {
29      
30      /**
31       * Attempt to retrieve an object from the cache.
32       * @param key
33       * @param txTimestamp a timestamp prior to the transaction start time
34       * @return the cached object or <tt>null</tt>
35       * @throws CacheException
36       */
37      public Object   get(Object   key, long txTimestamp) throws CacheException;
38      /**
39       * Attempt to cache an object, after loading from the database.
40       * @param key
41       * @param value
42       * @param txTimestamp a timestamp prior to the transaction start time
43       * @param version the item version number
44       * @param versionComparator a comparator used to compare version numbers
45       * @param minimalPut indicates that the cache should avoid a put is the item is already cached
46       * @return <tt>true</tt> if the object was successfully cached
47       * @throws CacheException
48       */
49      public boolean put(
50              Object   key, 
51              Object   value, 
52              long txTimestamp, 
53              Object   version, 
54              Comparator   versionComparator,
55              boolean minimalPut) 
56      throws CacheException;
57  
58  
59      /**
60       * We are going to attempt to update/delete the keyed object. This
61       * method is used by "asynchronous" concurrency strategies. The
62       * returned object must be passed back to release(), to release the 
63       * lock. Concurrency strategies which do not support client-visible
64       * locks may silently return null.
65       * @param key
66       * @param version 
67       * @throws CacheException
68       */
69      public SoftLock lock(Object   key, Object   version) throws CacheException;
70      
71      
72      /**
73       * Called after an item has become stale (before the transaction completes).
74       * This method is used by "synchronous" concurrency strategies.
75       */
76      public void evict(Object   key) throws CacheException;
77      /**
78       * Called after an item has been updated (before the transaction completes),
79       * instead of calling evict().
80       * This method is used by "synchronous" concurrency strategies.
81       */
82      public boolean update(Object   key, Object   value) throws CacheException;
83      /**
84       * Called after an item has been inserted (before the transaction completes),
85       * instead of calling evict().
86       * This method is used by "synchronous" concurrency strategies.
87       */
88      public boolean insert(Object   key, Object   value) throws CacheException;
89      
90      
91      /**
92       * Called when we have finished the attempted update/delete (which may or 
93       * may not have been successful), after transaction completion.
94       * This method is used by "asynchronous" concurrency strategies.
95       * @param key
96       * @throws CacheException
97       */
98      public void release(Object   key, SoftLock lock) throws CacheException;
99      /**
100      * Called after an item has been updated (after the transaction completes),
101      * instead of calling release().
102      * This method is used by "asynchronous" concurrency strategies.
103      */
104     public boolean afterUpdate(Object   key, Object   value, Object   version, SoftLock lock) 
105     throws CacheException;
106     /**
107      * Called after an item has been inserted (after the transaction completes),
108      * instead of calling release().
109      * This method is used by "asynchronous" concurrency strategies.
110      */
111     public boolean afterInsert(Object   key, Object   value, Object   version) 
112     throws CacheException;
113     
114     
115     /**
116      * Evict an item from the cache immediately (without regard for transaction
117      * isolation).
118      * @param key
119      * @throws CacheException
120      */
121     public void remove(Object   key) throws CacheException;
122     /**
123      * Evict all items from the cache immediately.
124      * @throws CacheException
125      */
126     public void clear() throws CacheException;
127     /**
128      * Clean up all resources.
129      */
130     public void destroy();
131     /**
132      * Set the underlying cache implementation.
133      * @param cache
134      */
135     public void setCache(Cache cache);
136     
137     /**
138      * Marker interface, denoting a client-visible "soft lock"
139      * on a cached item.
140      * @author Gavin King
141      */
142     public static interface SoftLock {}
143         
144     /**
145      * Get the cache region name
146      */
147     public String   getRegionName();
148     
149     /**
150      * Get the wrapped cache implementation
151      */
152     public Cache getCache();
153 }
154 
155 
156 
157 
158 
159 
160
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags