KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > cjdbc > controller > cache > result > AbstractResultCache


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