001: package com.jofti.cache;
002:
003: import java.util.Map;
004:
005: import com.jofti.api.IndexQuery;
006: import com.jofti.core.IParsedQuery;
007: import com.jofti.core.InternalIndex;
008: import com.jofti.exception.JoftiException;
009: import com.jofti.introspect.ClassIntrospector;
010: import com.jofti.parser.ParserManager;
011:
012: public interface IBaseAdaptor {
013:
014: /**
015: * Gets a cache lock based on the mod of the hashcode of the key
016: * @param key
017: * @return - a lock Object
018: */
019: public abstract Object getCacheLock(Object key);
020:
021: /*
022: * (non-Javadoc)
023: *
024: * @see com.jofti.api.IndexCache#query(com.jofti.api.IndexQuery)
025: */
026: public abstract Map query(IndexQuery query) throws JoftiException;
027:
028: /**
029: * Takes a map containing the key values returned from the Index for the Query. The keys
030: * are the primary keys in the Cache.<p>
031: * This is the default implementation that loops through the returned keys and extracts the appropriate value
032: * from the Cache. This method is also responsible for checking if the value has changed since it was last
033: * indexed or if the value is no longer in the Cache excluding it from the returned results.<p>
034: *
035: * @param col A Map of result keys
036: * @return A Map of key/value results.
037: * @throws JoftiException Thrown if the retrieval from the cache throws an exception
038: */
039: public abstract Map getCacheValues(Map col,
040: final IParsedQuery query,
041: final ClassIntrospector introspector) throws JoftiException;
042:
043: /**
044: * Attempts to acquire an update lock for the cache. Multiple updates can run
045: * in parallel as the Index itself is threadsafe and the assumption is that the Cache is also.
046: * <p>
047: * However, queries and updates cannot run at the same time to prevent situations where if multiple
048: * nodes in the index are updated by one update then a query which runs at the same time may well misreport
049: * a match that should be returned if they were run in sequence.</p>
050: *
051: * @throws JoftiException
052: */
053: public abstract void acquireUpdateLock() throws JoftiException;
054:
055: /**
056: * Releases an update lock.
057: */
058: public abstract void releaseUpdateLock();
059:
060: /**
061: * Attempts to acquire a query lock for the cache. Multiple queries can run
062: * in parallel as the Index itself is threadsafe and the assumption is that the Cache is also.
063: * <p>
064: * However, queries and updates cannot run at the same time to prevent situations where if multiple
065: * nodes in the index are updated by one update then a query which runs at the same time may well misreport
066: * a match that should be returned if they were run in sequence.</p>
067: *
068: * @throws JoftiException
069: */
070: public abstract void acquireQueryLock() throws JoftiException;
071:
072: /**
073: * Releases a query lock.
074: */
075: public abstract void releaseQueryLock();
076:
077: /**
078: * A utility method that decorates a Cache key with a comparable wrapper if the key itself is not Comparable. This wrapper
079: * is not propogated into the Cache, but is used to wrap the key when placed in the Index.
080: *
081: * @param key
082: * @return Either an instance of a NonComparableKeyWrapper if the key is not Comparable or the original key object.
083: */
084: public abstract Object decorateKey(Object key);
085:
086: /**
087: * A utility method that strips a decorated Cache key of its comparable wrapper if it has been previously decorated by the decorate method.
088: *
089: * @param key
090: * @return The object wrapped in a NonComparableKeyWrapper if wrapped or the original object if not.
091: */
092: public abstract Object stripKey(Object key);
093:
094: /**
095: * Returns the Index instance from the adapter.
096: *
097: * @return the internal index implementation
098: */
099: public abstract InternalIndex getIndex();
100:
101: /**
102: * Normalises the query format for convenience queries or processes one the unparsed text query formats
103: * into its parsed form.
104: *
105: * @param query an unparsed query
106: * @param manager the Parser Manager that stores the mappings for the query
107: *
108: * @return the parsed query
109: */
110: public IndexQuery processQuery(IndexQuery query,
111: ParserManager manager) throws JoftiException;
112:
113: /**
114: * Takes a fully populated result set and applies any of the limiting steps defined in the
115: * maxResults or startResults. 0 for both values is considered a no-op. Negative values throw a runtime exception.
116: * a Start Value larger than the result original size will return no results, a maxResults large than the result size
117: * is reset to temp.size().
118: *
119: * @param temp the original result set
120: * @param startResult an int defining at which record the record set should begin
121: * @param maxResults an int defining the maximum number of records to return.
122: *
123: * @return the result set
124: */
125: public Map limitResults(Map temp, int startResult, int maxResults);
126:
127: }
|