1
2
3
4
5
6
7 package ca.uhn.cache;
8
9 import java.util.Date;
10
11 import ca.uhn.cache.exception.DataSourceException;
12
13 /***
14 * An extension of IDataSource that allows unstationary data. We call data "unstationary"
15 * if it might move from one semantic region to another over time. (In other words, if
16 * an IQuery might return a certain data item at one time but not return the same item
17 * at another time because its values have changed.)
18 *
19 * If any item in a set of source data might be unstationary in any dimension, you must use
20 * this interface to provide access to it. If not, you should use IDataSource.
21 *
22 * This interface is used as follows:
23 *
24 * <ol><li>Client queries cache.</li>
25 * <li>Cache finds remainder query and uses IDataSource.execute(IQuery[]) to get missing semantic regions</li>
26 * <li>Cache uses IUnstationaryDataSource.execute(IQuery[], Date) to get updates for regions that are
27 * already in the cache (the cache time is used as the second paramter)</li>
28 * <li>Combined cache results and remainder results returned to client. </li></ol>
29 *
30 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
31 * @version $Revision: 1.1 $ updated on $Date: 2005/01/24 22:52:08 $ by $Author: bryan_tripp $
32 */
33 public interface IUnstationaryDataSource extends IDataSource {
34
35 /***
36 * Runs one or more queries against the data source.
37 *
38 * @param theQueries queries to run
39 * @param theUpdatedSinceTime only data that have been updated since this time should be returned
40 *
41 * @return data matching the given queries (may return before all
42 * data are available)
43 *
44 * @throws DataSourceException If the <b>execute</b> operation could not be successfully completed.
45 *
46 * @precondition theQueries != null
47 * @precondition CollectionUtils.select( Arrays.asList( theQueries ), NotNullPredicate.INSTANCE ).isEmpty()
48 */
49 public IQueryResult execute( IQuery[] theQueries, Date theUpdatedSinceTime ) throws DataSourceException;
50
51 }