1
2
3
4
5
6
7 package ca.uhn.cache;
8
9 import java.util.Date;
10
11 import ca.uhn.cache.exception.CacheException;
12
13 /***
14 * A <code>ISemanticCache</code> keeps rapidly available copies of data in some
15 * underlying system. Data are stored in <code>IChunk</code>s which contain groups
16 * of data items that are likely to be requested together.
17 *
18 * Cache size and consistency with source data must be maintained by ongoing removal
19 * of old data from the cache. However the details are internal and thus not part of
20 * this interface.
21 *
22 * NOTE:
23 *
24 * This class will throw checked exception only to alert the client of situations when
25 * the requested method could not fulfill its intended semantic. For example assume we have
26 * an implementation of this interface that uses a relational backend to store the cached data,
27 * such implementation will define a new exception that inherits from
28 * <code>CacheException</code> named RelationalBackendNotAvailable to indicate that the relational
29 * backend couldn't be reached.
30 *
31 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
32 * @version $Revision: 1.1 $ updated on $Date: 2005/01/24 22:52:08 $ by $Author: bryan_tripp $
33 */
34 public interface ISemanticCache {
35
36 /***
37 * Given an IQuery, find a small list of new IQuery that span all the data in
38 * the original IQuery that are not present in the cache. Some extra data
39 * may (i.e. data in the cache or data not requested) may be spaned. Generally
40 * there is a trade-off between extra data and number of new queries returned.
41 *
42 * @param theQuery parameters identifying the scope of data requested
43 * @param theMaxGroups maximum number of <code>IQuery</code>s returned (lower numbers
44 * will generally force more extra data to be spanned). A value of 0 means that
45 * no grouping is requested.
46 *
47 * @return the smallest query emcompassing all data that are in chunks
48 * relevant to the original query and which are not in the cache.
49 *
50 * @throws CacheException If the <b>remainder</b> operation could not be successfully completed.
51 *
52 * @precondition theQuery != null && !theQuery.isEmpty() && theMaxGroups >= 0
53 *
54 * @postcondition return != null
55 */
56 public IQuery[] remainder(IQuery theQuery, int theMaxGroups) throws CacheException;
57
58 /***
59 * @param theQuery parameters identifying the scope of data requested
60 *
61 * @return whatever part of requested data that is available from the cache.
62 *
63 * @throws CacheException If the <b>get</b> operation could not be successfully completed.
64 *
65 * @precondition theQuery != null && !theQuery.isEmpty()
66 * @precondition theQuery must be equals to one of the queries previously returned by remainder.
67 *
68 * @postcondition return != null
69 */
70 public IQueryResult get(IQuery theQuery) throws CacheException;
71
72 /***
73 * @param theQueryScope parameters identifying the scope of a query
74 *
75 * @param theResult the results from the underlying system that are not
76 * already in the cache (to be cached)
77 *
78 * @throws CacheException If the <b>put</b> operation could not be successfully completed.
79 *
80 * @precondition theQueryScope != null && !theQueryScope.isEmpty()
81 * @precondition theQuery must be equals to one of the queries previously returned by reminder.
82 * @precondition theResult != null
83 */
84 public void put(IQuery theQueryScope, IQueryResult theResult) throws CacheException;
85
86 /***
87 * @param theQuery parameters identifying the scope of data requested
88 *
89 * @return the earlist time at which any data matching the query was cached, or null
90 * if there are no matching data
91 *
92 * @throws CacheException if operation could not be completed successfully
93 */
94 public Date getEarliestCacheTime(IQuery theQuery) throws CacheException;
95
96 /***
97 * Updates semantic regions that are already in the cache with revised data. This
98 * does not change the semantic scope of the cache, but may add or alter data items.
99 *
100 * If a data item moves from one semantic region to another as a result of an update,
101 * then if both regions are cached, the changed data will replace the old data, effectively
102 * removing it from the old region. If the new region is not cached, the data will
103 * remain in the old region, until it is evicted.
104 * @param theResult new or changed data items for semantic regions already in the cache
105 *
106 * @throws CacheException if operation could not be completed successfully
107 */
108 public void update(IQueryResult theResult) throws CacheException;
109
110 }