00001 /** 00002 * C-JDBC: Clustered JDBC. 00003 * Copyright (C) 2002-2004 French National Institute For Research In Computer 00004 * Science And Control (INRIA). 00005 * Contact: c-jdbc@objectweb.org 00006 * 00007 * This library is free software; you can redistribute it and/or modify it 00008 * under the terms of the GNU Lesser General Public License as published by the 00009 * Free Software Foundation; either version 2.1 of the License, or any later 00010 * version. 00011 * 00012 * This library is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00014 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 00015 * for more details. 00016 * 00017 * You should have received a copy of the GNU Lesser General Public License 00018 * along with this library; if not, write to the Free Software Foundation, 00019 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 00020 * 00021 * Initial developer(s): Emmanuel Cecchet. 00022 * Contributor(s): ______________________________________. 00023 */ 00024 00025 package org.objectweb.cjdbc.controller.cache.result; 00026 00027 import org.objectweb.cjdbc.common.i18n.Translate; 00028 import org.objectweb.cjdbc.common.log.Trace; 00029 import org.objectweb.cjdbc.common.sql.AbstractWriteRequest; 00030 import org.objectweb.cjdbc.common.sql.ParsingGranularities; 00031 import org.objectweb.cjdbc.common.sql.SelectRequest; 00032 import org.objectweb.cjdbc.common.sql.UpdateRequest; 00033 import org.objectweb.cjdbc.common.sql.schema.DatabaseSchema; 00034 import org.objectweb.cjdbc.common.xml.XmlComponent; 00035 import org.objectweb.cjdbc.controller.cache.CacheException; 00036 import org.objectweb.cjdbc.controller.cache.CacheStatistics; 00037 import org.objectweb.cjdbc.controller.cache.result.entries.CacheEntry; 00038 import org.objectweb.cjdbc.controller.virtualdatabase.ControllerResultSet; 00039 00040 /** 00041 * This class defines the minimal functionnalities that a request cache must 00042 * provide. 00043 * <p> 00044 * Only read requests (<code>SELECT</code>s) can be cached, there is no 00045 * sense to cache writes as they do not provide any result to cache. However, 00046 * the cache must be notified of the write queries in order to maintain cache 00047 * coherency. 00048 * 00049 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a> 00050 * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a> 00051 * @version 1.0 00052 */ 00053 public abstract class AbstractResultCache implements XmlComponent 00054 { 00055 // 00056 // How the code is organized? 00057 // 00058 // 1. Member variables 00059 // 2. Getter/Setter (possibly in alphabetical order) 00060 // 3. Cache management 00061 // 4. Transaction management 00062 // 5. Debug/Monitoring 00063 00064 /** 00065 * Parsing granularity. Default is: 00066 * {@link org.objectweb.cjdbc.common.sql.ParsingGranularities#NO_PARSING}. 00067 */ 00068 protected int parsingGranularity = ParsingGranularities.NO_PARSING; 00069 00070 /** Logger instance. */ 00071 protected static Trace logger = Trace 00072 .getLogger("org.objectweb.cjdbc.controller.cache"); 00073 00074 /* 00075 * Getter/Setter methods 00076 */ 00077 00078 /** 00079 * Gets the needed query parsing granularity. 00080 * 00081 * @return needed query parsing granularity 00082 * @see #setParsingGranularity 00083 */ 00084 public int getParsingGranularity() 00085 { 00086 return parsingGranularity; 00087 } 00088 00089 /** 00090 * Sets the needed query parsing granularity. 00091 * 00092 * @param parsingGranularity the query parsing granularity to set 00093 * @see #getParsingGranularity 00094 */ 00095 public void setParsingGranularity(int parsingGranularity) 00096 { 00097 this.parsingGranularity = parsingGranularity; 00098 } 00099 00100 /** 00101 * Sets the <code>DatabaseSchema</code> of the current virtual database. 00102 * 00103 * @param dbs a <code>DatabaseSchema</code> value 00104 * @see org.objectweb.cjdbc.controller.cache.result.schema.CacheDatabaseSchema 00105 */ 00106 public void setDatabaseSchema(DatabaseSchema dbs) 00107 { 00108 if (logger.isInfoEnabled()) 00109 logger.info(Translate.get("cache.schemas.not.supported")); 00110 } 00111 00112 /** 00113 * Merge the given <code>DatabaseSchema</code> with the current one. 00114 * 00115 * @param dbs a <code>DatabaseSchema</code> value 00116 * @see org.objectweb.cjdbc.controller.cache.result.schema.CacheDatabaseSchema 00117 */ 00118 public void mergeDatabaseSchema(DatabaseSchema dbs) 00119 { 00120 if (logger.isInfoEnabled()) 00121 logger.info(Translate.get("cache.scheduler.doesnt.support.schemas")); 00122 } 00123 00124 /* 00125 * Cache Management 00126 */ 00127 00128 /** 00129 * Add precise management and configuration of the cache behavior. A cache 00130 * rule contains information on a query pattern and how to act if that pattern 00131 * was matched. 00132 * 00133 * @param rule of action for the cache 00134 * @see org.objectweb.cjdbc.controller.cache.result.ResultCacheRule 00135 */ 00136 public abstract void addCachingRule(ResultCacheRule rule); 00137 00138 /** 00139 * Return the default cache rule 00140 * 00141 * @return default query cache rule. Cannot be null 00142 */ 00143 public abstract ResultCacheRule getDefaultRule(); 00144 00145 /** 00146 * Set the default query rule 00147 * 00148 * @param defaultRule default rule to set 00149 */ 00150 public abstract void setDefaultRule(ResultCacheRule defaultRule); 00151 00152 /** 00153 * Adds an entry request/reply to the cache. Note that if the request was 00154 * already in the cache, its result must be updated in any case but the 00155 * request must never appear twice in the cache. 00156 * 00157 * @param request the request 00158 * @param result the result corresponding to the request 00159 * @exception CacheException if an error occurs 00160 */ 00161 public abstract void addToCache(SelectRequest request, 00162 ControllerResultSet result) throws CacheException; 00163 00164 /** 00165 * Gets the result to the given request from the cache. 00166 * <p> 00167 * The returned <code>ResultCacheEntry</code> is <code>null</code> if the 00168 * request is not present in the cache. 00169 * <p> 00170 * An invalid <code>CacheEntry</code> may be returned (it means that the 00171 * result is <code>null</code>) but the already parsed query can be 00172 * retrieved from the cache entry. 00173 * 00174 * @param request an SQL select request 00175 * @param addToPendingQueries true if the request must be added to the pending 00176 * query list on a cache miss 00177 * @return the <code>ResultCacheEntry</code> if found, else null 00178 */ 00179 public abstract CacheEntry getFromCache(SelectRequest request, 00180 boolean addToPendingQueries); 00181 00182 /** 00183 * Removes an entry from the cache (both request and reply are dropped). The 00184 * request is NOT removed from the pending query list, but it shouldn't be in 00185 * this list. 00186 * 00187 * @param request a <code>SelectRequest</code> 00188 */ 00189 public abstract void removeFromCache(SelectRequest request); 00190 00191 /** 00192 * Removes an entry from the pending query list. 00193 * 00194 * @param request a <code>SelectRequest</code> 00195 */ 00196 public abstract void removeFromPendingQueries(SelectRequest request); 00197 00198 /** 00199 * Notifies the cache that the given write request has been issued, so that 00200 * cache coherency can be maintained. If the cache is distributed, this method 00201 * is reponsible for broadcasting this information to other caches. 00202 * 00203 * @param request an <code>AbstractWriteRequest</code> value 00204 * @exception CacheException if an error occurs 00205 */ 00206 public abstract void writeNotify(AbstractWriteRequest request) 00207 throws CacheException; 00208 00209 /** 00210 * Returns true if the cache does not contain the values that are given in the 00211 * update statement. 00212 * 00213 * @param request the update request that needs to be executed 00214 * @return false if the request shouldn't be executed, true otherwise. 00215 * @exception CacheException if an error occurs 00216 */ 00217 public abstract boolean isUpdateNecessary(UpdateRequest request) 00218 throws CacheException; 00219 00220 /** 00221 * Removes all entries from the cache. 00222 */ 00223 public abstract void flushCache(); 00224 00225 // 00226 // Transaction management 00227 // 00228 00229 /** 00230 * Commit a transaction given its id. 00231 * 00232 * @param transactionId the transaction id 00233 * @throws CacheException if an error occurs 00234 */ 00235 public abstract void commit(long transactionId) throws CacheException; 00236 00237 /** 00238 * Rollback a transaction given its id. 00239 * 00240 * @param transactionId the transaction id 00241 * @throws CacheException if an error occurs 00242 */ 00243 public abstract void rollback(long transactionId) throws CacheException; 00244 00245 /* 00246 * Debug/Monitoring 00247 */ 00248 00249 /** 00250 * Gets information about the request cache in xml 00251 * 00252 * @return xml formatted <code>String</code> containing information 00253 */ 00254 protected abstract String getXmlImpl(); 00255 00256 /** 00257 * @see org.objectweb.cjdbc.common.xml.XmlComponent#getXml() 00258 */ 00259 public String getXml() 00260 00261 { 00262 return getXmlImpl(); 00263 } 00264 00265 /** 00266 * Returns the content of the cache as displayable array of array of string 00267 * 00268 * @return the data 00269 * @throws CacheException if fails 00270 */ 00271 public abstract String[][] getCacheData() throws CacheException; 00272 00273 /** 00274 * Returns a bunch of stats collected by the cache, such as cache hits. 00275 * 00276 * @return the data 00277 * @throws CacheException if fails to collect the data. 00278 */ 00279 public abstract String[][] getCacheStatsData() throws CacheException; 00280 00281 /** 00282 * Returns pointer to the stats collector 00283 * 00284 * @return <code>CacheStatistics</code> object 00285 */ 00286 public abstract CacheStatistics getCacheStatistics(); 00287 00288 /** 00289 * Returns number of entries in the cache 00290 * 00291 * @return integer value representing the total number of entries 00292 */ 00293 public abstract long getCacheSize(); 00294 00295 }