001: /**
002: * Sequoia: Database clustering technology.
003: * Copyright (C) 2002-2004 French National Institute For Research In Computer
004: * Science And Control (INRIA).
005: * Copyright (C) 2005 AmicoSoft, Inc. dba Emic Networks
006: * Contact: sequoia@continuent.org
007: *
008: * Licensed under the Apache License, Version 2.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: * Initial developer(s): Emmanuel Cecchet.
021: * Contributor(s): ______________________________________.
022: */package org.continuent.sequoia.controller.cache.result;
023:
024: import org.continuent.sequoia.common.i18n.Translate;
025: import org.continuent.sequoia.common.log.Trace;
026: import org.continuent.sequoia.common.sql.schema.DatabaseSchema;
027: import org.continuent.sequoia.common.xml.XmlComponent;
028: import org.continuent.sequoia.controller.backend.result.ControllerResultSet;
029: import org.continuent.sequoia.controller.cache.CacheException;
030: import org.continuent.sequoia.controller.cache.CacheStatistics;
031: import org.continuent.sequoia.controller.cache.result.entries.AbstractResultCacheEntry;
032: import org.continuent.sequoia.controller.requests.AbstractWriteRequest;
033: import org.continuent.sequoia.controller.requests.ParsingGranularities;
034: import org.continuent.sequoia.controller.requests.SelectRequest;
035: import org.continuent.sequoia.controller.requests.UpdateRequest;
036:
037: /**
038: * This class defines the minimal functionnalities that a request cache must
039: * provide.
040: * <p>
041: * Only read requests (<code>SELECT</code>s) can be cached, there is no
042: * sense to cache writes as they do not provide any result to cache. However,
043: * the cache must be notified of the write queries in order to maintain cache
044: * coherency.
045: *
046: * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
047: * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
048: * @version 1.0
049: */
050: public abstract class AbstractResultCache implements XmlComponent {
051: //
052: // How the code is organized?
053: //
054: // 1. Member variables
055: // 2. Getter/Setter (possibly in alphabetical order)
056: // 3. Cache management
057: // 4. Transaction management
058: // 5. Debug/Monitoring
059:
060: /**
061: * Parsing granularity. Default is:
062: * {@link org.continuent.sequoia.controller.requests.ParsingGranularities#NO_PARSING}.
063: */
064: protected int parsingGranularity = ParsingGranularities.NO_PARSING;
065:
066: /** Logger instance. */
067: protected static Trace logger = Trace
068: .getLogger("org.continuent.sequoia.controller.cache");
069:
070: /*
071: * Getter/Setter methods
072: */
073:
074: /**
075: * Gets the needed query parsing granularity.
076: *
077: * @return needed query parsing granularity
078: * @see #setParsingGranularity
079: */
080: public int getParsingGranularity() {
081: return parsingGranularity;
082: }
083:
084: /**
085: * Sets the needed query parsing granularity.
086: *
087: * @param parsingGranularity the query parsing granularity to set
088: * @see #getParsingGranularity
089: */
090: public void setParsingGranularity(int parsingGranularity) {
091: this .parsingGranularity = parsingGranularity;
092: }
093:
094: /**
095: * Sets the <code>DatabaseSchema</code> of the current virtual database.
096: *
097: * @param dbs a <code>DatabaseSchema</code> value
098: * @see org.continuent.sequoia.controller.cache.result.schema.CacheDatabaseSchema
099: */
100: public void setDatabaseSchema(DatabaseSchema dbs) {
101: if (logger.isInfoEnabled())
102: logger.info(Translate.get("cache.schemas.not.supported"));
103: }
104:
105: /**
106: * Merge the given <code>DatabaseSchema</code> with the current one.
107: *
108: * @param dbs a <code>DatabaseSchema</code> value
109: * @see org.continuent.sequoia.controller.cache.result.schema.CacheDatabaseSchema
110: */
111: public void mergeDatabaseSchema(DatabaseSchema dbs) {
112: if (logger.isInfoEnabled())
113: logger.info(Translate
114: .get("cache.scheduler.doesnt.support.schemas"));
115: }
116:
117: /*
118: * Cache Management
119: */
120:
121: /**
122: * Add precise management and configuration of the cache behavior. A cache
123: * rule contains information on a query pattern and how to act if that pattern
124: * was matched.
125: *
126: * @param rule of action for the cache
127: * @see org.continuent.sequoia.controller.cache.result.ResultCacheRule
128: */
129: public abstract void addCachingRule(ResultCacheRule rule);
130:
131: /**
132: * Return the default cache rule
133: *
134: * @return default query cache rule. Cannot be null
135: */
136: public abstract ResultCacheRule getDefaultRule();
137:
138: /**
139: * Set the default query rule
140: *
141: * @param defaultRule default rule to set
142: */
143: public abstract void setDefaultRule(ResultCacheRule defaultRule);
144:
145: /**
146: * Adds an entry request/reply to the cache. Note that if the request was
147: * already in the cache, its result must be updated in any case but the
148: * request must never appear twice in the cache.
149: *
150: * @param request the request
151: * @param result the result corresponding to the request
152: * @exception CacheException if an error occurs
153: */
154: public abstract void addToCache(SelectRequest request,
155: ControllerResultSet result) throws CacheException;
156:
157: /**
158: * Gets the result to the given request from the cache.
159: * <p>
160: * The returned <code>AbstractResultCacheEntry</code> is <code>null</code>
161: * if the request is not present in the cache.
162: * <p>
163: * An invalid <code>CacheEntry</code> may be returned (it means that the
164: * result is <code>null</code>) but the already parsed query can be
165: * retrieved from the cache entry.
166: *
167: * @param request an SQL select request
168: * @param addToPendingQueries true if the request must be added to the pending
169: * query list on a cache miss
170: * @return the <code>AbstractResultCacheEntry</code> if found, else null
171: */
172: public abstract AbstractResultCacheEntry getFromCache(
173: SelectRequest request, boolean addToPendingQueries);
174:
175: /**
176: * Removes an entry from the cache (both request and reply are dropped). The
177: * request is NOT removed from the pending query list, but it shouldn't be in
178: * this list.
179: *
180: * @param request a <code>SelectRequest</code>
181: */
182: public abstract void removeFromCache(SelectRequest request);
183:
184: /**
185: * Removes an entry from the pending query list.
186: *
187: * @param request a <code>SelectRequest</code>
188: */
189: public abstract void removeFromPendingQueries(SelectRequest request);
190:
191: /**
192: * Shutdown the result cache and all its threads.
193: */
194: public abstract void shutdown();
195:
196: /**
197: * Notifies the cache that the given write request has been issued, so that
198: * cache coherency can be maintained. If the cache is distributed, this method
199: * is reponsible for broadcasting this information to other caches.
200: *
201: * @param request an <code>AbstractWriteRequest</code> value
202: * @exception CacheException if an error occurs
203: */
204: public abstract void writeNotify(AbstractWriteRequest request)
205: throws CacheException;
206:
207: /**
208: * Returns true if the cache does not contain the values that are given in the
209: * update statement.
210: *
211: * @param request the update request that needs to be executed
212: * @return false if the request shouldn't be executed, true otherwise.
213: * @exception CacheException if an error occurs
214: */
215: public abstract boolean isUpdateNecessary(UpdateRequest request)
216: throws CacheException;
217:
218: /**
219: * Removes all entries from the cache.
220: */
221: public abstract void flushCache();
222:
223: //
224: // Transaction management
225: //
226:
227: /**
228: * Commit a transaction given its id.
229: *
230: * @param transactionId the transaction id
231: * @throws CacheException if an error occurs
232: */
233: public abstract void commit(long transactionId)
234: throws CacheException;
235:
236: /**
237: * Rollback a transaction given its id.
238: *
239: * @param transactionId the transaction id
240: * @throws CacheException if an error occurs
241: */
242: public abstract void rollback(long transactionId)
243: throws CacheException;
244:
245: /*
246: * Debug/Monitoring
247: */
248:
249: /**
250: * Gets information about the request cache in xml
251: *
252: * @return xml formatted <code>String</code> containing information
253: */
254: protected abstract String getXmlImpl();
255:
256: /**
257: * @see org.continuent.sequoia.common.xml.XmlComponent#getXml()
258: */
259: public String getXml()
260:
261: {
262: return getXmlImpl();
263: }
264:
265: /**
266: * Returns the content of the cache as displayable array of array of string
267: *
268: * @return the data
269: * @throws CacheException if fails
270: */
271: public abstract String[][] getCacheData() throws CacheException;
272:
273: /**
274: * Returns a bunch of stats collected by the cache, such as cache hits.
275: *
276: * @return the data
277: * @throws CacheException if fails to collect the data.
278: */
279: public abstract String[][] getCacheStatsData()
280: throws CacheException;
281:
282: /**
283: * Returns pointer to the stats collector
284: *
285: * @return <code>CacheStatistics</code> object
286: */
287: public abstract CacheStatistics getCacheStatistics();
288:
289: /**
290: * Returns number of entries in the cache
291: *
292: * @return integer value representing the total number of entries
293: */
294: public abstract long getCacheSize();
295:
296: }
|