KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > continuent > sequoia > controller > cache > result > AbstractResultCache


1 /**
2  * Sequoia: Database clustering technology.
3  * Copyright (C) 2002-2004 French National Institute For Research In Computer
4  * Science And Control (INRIA).
5  * Copyright (C) 2005 AmicoSoft, Inc. dba Emic Networks
6  * Contact: sequoia@continuent.org
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  *
20  * Initial developer(s): Emmanuel Cecchet.
21  * Contributor(s): ______________________________________.
22  */
23
24 package org.continuent.sequoia.controller.cache.result;
25
26 import org.continuent.sequoia.common.i18n.Translate;
27 import org.continuent.sequoia.common.log.Trace;
28 import org.continuent.sequoia.common.xml.XmlComponent;
29 import org.continuent.sequoia.controller.backend.result.ControllerResultSet;
30 import org.continuent.sequoia.controller.cache.CacheException;
31 import org.continuent.sequoia.controller.cache.CacheStatistics;
32 import org.continuent.sequoia.controller.cache.result.entries.AbstractResultCacheEntry;
33 import org.continuent.sequoia.controller.requests.AbstractRequest;
34 import org.continuent.sequoia.controller.requests.ParsingGranularities;
35 import org.continuent.sequoia.controller.requests.SelectRequest;
36 import org.continuent.sequoia.controller.requests.UpdateRequest;
37 import org.continuent.sequoia.controller.sql.schema.DatabaseSchema;
38
39 /**
40  * This class defines the minimal functionnalities that a request cache must
41  * provide.
42  * <p>
43  * Only read requests (<code>SELECT</code>s) can be cached, there is no
44  * sense to cache writes as they do not provide any result to cache. However,
45  * the cache must be notified of the write queries in order to maintain cache
46  * coherency.
47  *
48  * @author <a HREF="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
49  * @author <a HREF="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
50  * @version 1.0
51  */
52 public abstract class AbstractResultCache implements XmlComponent
53 {
54   //
55 // How the code is organized?
56 //
57 // 1. Member variables
58 // 2. Getter/Setter (possibly in alphabetical order)
59 // 3. Cache management
60 // 4. Transaction management
61 // 5. Debug/Monitoring
62
63   /**
64    * Parsing granularity. Default is:
65    * {@link org.continuent.sequoia.controller.requests.ParsingGranularities#NO_PARSING}.
66    */
67   protected int parsingGranularity = ParsingGranularities.NO_PARSING;
68
69   /** Logger instance. */
70   protected static Trace logger = Trace
71                                                 .getLogger("org.continuent.sequoia.controller.cache");
72
73   /*
74    * Getter/Setter methods
75    */
76
77   /**
78    * Gets the needed query parsing granularity.
79    *
80    * @return needed query parsing granularity
81    * @see #setParsingGranularity
82    */
83   public int getParsingGranularity()
84   {
85     return parsingGranularity;
86   }
87
88   /**
89    * Sets the needed query parsing granularity.
90    *
91    * @param parsingGranularity the query parsing granularity to set
92    * @see #getParsingGranularity
93    */
94   public void setParsingGranularity(int parsingGranularity)
95   {
96     this.parsingGranularity = parsingGranularity;
97   }
98
99   /**
100    * Sets the <code>DatabaseSchema</code> of the current virtual database.
101    *
102    * @param dbs a <code>DatabaseSchema</code> value
103    * @see org.continuent.sequoia.controller.cache.result.schema.CacheDatabaseSchema
104    */
105   public void setDatabaseSchema(DatabaseSchema dbs)
106   {
107     if (logger.isInfoEnabled())
108       logger.info(Translate.get("cache.schemas.not.supported"));
109   }
110
111   /**
112    * Merge the given <code>DatabaseSchema</code> with the current one.
113    *
114    * @param dbs a <code>DatabaseSchema</code> value
115    * @see org.continuent.sequoia.controller.cache.result.schema.CacheDatabaseSchema
116    */
117   public void mergeDatabaseSchema(DatabaseSchema dbs)
118   {
119     if (logger.isInfoEnabled())
120       logger.info(Translate.get("cache.scheduler.doesnt.support.schemas"));
121   }
122
123   /*
124    * Cache Management
125    */
126
127   /**
128    * Add precise management and configuration of the cache behavior. A cache
129    * rule contains information on a query pattern and how to act if that pattern
130    * was matched.
131    *
132    * @param rule of action for the cache
133    * @see org.continuent.sequoia.controller.cache.result.ResultCacheRule
134    */
135   public abstract void addCachingRule(ResultCacheRule rule);
136
137   /**
138    * Return the default cache rule
139    *
140    * @return default query cache rule. Cannot be null
141    */
142   public abstract ResultCacheRule getDefaultRule();
143
144   /**
145    * Set the default query rule
146    *
147    * @param defaultRule default rule to set
148    */
149   public abstract void setDefaultRule(ResultCacheRule defaultRule);
150
151   /**
152    * Adds an entry request/reply to the cache. Note that if the request was
153    * already in the cache, its result must be updated in any case but the
154    * request must never appear twice in the cache.
155    *
156    * @param request the request
157    * @param result the result corresponding to the request
158    * @exception CacheException if an error occurs
159    */
160   public abstract void addToCache(SelectRequest request,
161       ControllerResultSet result) throws CacheException;
162
163   /**
164    * Gets the result to the given request from the cache.
165    * <p>
166    * The returned <code>AbstractResultCacheEntry</code> is <code>null</code>
167    * if the request is not present in the cache.
168    * <p>
169    * An invalid <code>CacheEntry</code> may be returned (it means that the
170    * result is <code>null</code>) but the already parsed query can be
171    * retrieved from the cache entry.
172    *
173    * @param request an SQL select request
174    * @param addToPendingQueries true if the request must be added to the pending
175    * query list on a cache miss
176    * @return the <code>AbstractResultCacheEntry</code> if found, else null
177    */
178   public abstract AbstractResultCacheEntry getFromCache(SelectRequest request,
179       boolean addToPendingQueries);
180
181   /**
182    * Removes an entry from the cache (both request and reply are dropped). The
183    * request is NOT removed from the pending query list, but it shouldn't be in
184    * this list.
185    *
186    * @param request a <code>SelectRequest</code>
187    */
188   public abstract void removeFromCache(SelectRequest request);
189
190   /**
191    * Removes an entry from the pending query list.
192    *
193    * @param request a <code>SelectRequest</code>
194    */
195   public abstract void removeFromPendingQueries(SelectRequest request);
196
197   /**
198    * Shutdown the result cache and all its threads.
199    */
200   public abstract void shutdown();
201
202   /**
203    * Notifies the cache that the given write request has been issued, so that
204    * cache coherency can be maintained. If the cache is distributed, this method
205    * is reponsible for broadcasting this information to other caches.
206    *
207    * @param request an <code>AbstractRequest</code> value
208    * @exception CacheException if an error occurs
209    */
210   public abstract void writeNotify(AbstractRequest request)
211       throws CacheException;
212
213   /**
214    * Returns true if the cache does not contain the values that are given in the
215    * update statement.
216    *
217    * @param request the update request that needs to be executed
218    * @return false if the request shouldn't be executed, true otherwise.
219    * @exception CacheException if an error occurs
220    */
221   public abstract boolean isUpdateNecessary(UpdateRequest request)
222       throws CacheException;
223
224   /**
225    * Removes all entries from the cache.
226    */
227   public abstract void flushCache();
228
229   //
230 // Transaction management
231 //
232
233   /**
234    * Commit a transaction given its id.
235    *
236    * @param transactionId the transaction id
237    * @throws CacheException if an error occurs
238    */
239   public abstract void commit(long transactionId) throws CacheException;
240
241   /**
242    * Rollback a transaction given its id.
243    *
244    * @param transactionId the transaction id
245    * @throws CacheException if an error occurs
246    */
247   public abstract void rollback(long transactionId) throws CacheException;
248
249   /*
250    * Debug/Monitoring
251    */
252
253   /**
254    * Gets information about the request cache in xml
255    *
256    * @return xml formatted <code>String</code> containing information
257    */
258   protected abstract String JavaDoc getXmlImpl();
259
260   /**
261    * @see org.continuent.sequoia.common.xml.XmlComponent#getXml()
262    */
263   public String JavaDoc getXml()
264
265   {
266     return getXmlImpl();
267   }
268
269   /**
270    * Returns the content of the cache as displayable array of array of string
271    *
272    * @return the data
273    * @throws CacheException if fails
274    */
275   public abstract String JavaDoc[][] getCacheData() throws CacheException;
276
277   /**
278    * Returns a bunch of stats collected by the cache, such as cache hits.
279    *
280    * @return the data
281    * @throws CacheException if fails to collect the data.
282    */
283   public abstract String JavaDoc[][] getCacheStatsData() throws CacheException;
284
285   /**
286    * Returns pointer to the stats collector
287    *
288    * @return <code>CacheStatistics</code> object
289    */
290   public abstract CacheStatistics getCacheStatistics();
291
292   /**
293    * Returns number of entries in the cache
294    *
295    * @return integer value representing the total number of entries
296    */
297   public abstract long getCacheSize();
298
299 }
Popular Tags