+ * It basically has put() methods for adding a mapping, and get() for looking + * a mapping up the cache. The cache does not guarantee to hold + * everything that has been put into it, and might in fact selectively + * delete some of the mappings (e.g., the ones least recently used). + * This means that if get() returns a negative response, it does not + * necessarily mean that the category doesn't exist - just that it is not + * in the cache. The caller can only infer that the category doesn't exist + * if it knows the cache to be complete (because all the categories were + * loaded into the cache, and since then no put() returned true). + *
However, + * if it does so, it should clear out large parts of the cache at once, because + * the user will typically need to work hard to recover from every cache + * cleanup (see {@link #put(CategoryPath, int)}'s return value). + * + * @lucene.experimental + */ +public interface TaxonomyWriterCache { + + /** + * Let go of whatever resources the cache is holding. After a close(), + * this object can no longer be used. + */ + public void close(); + + /** + * Lookup a category in the cache, returning its ordinal, or a negative + * number if the category is not in the cache. + *
+ * It is up to the caller to remember what a negative response means: + * If the caller knows the cache is complete (it was initially + * fed with all the categories, and since then put() never returned true) + * it means the category does not exist. Otherwise, the category might + * still exist, but just be missing from the cache. + */ + public int get(CategoryPath categoryPath); + + /** + * Like {@link #get(CategoryPath)}, but for a given prefix of the + * category path. + *
+ * If the given length is negative or bigger than the path's actual + * length, the full path is taken. + */ + public int get(CategoryPath categoryPath, int length); + + /** + * Add a category to the cache, with the given ordinal as the value. + *
+ * If the implementation keeps only a partial cache (e.g., an LRU cache)
+ * and finds that its cache is full, it should clear up part of the cache
+ * and return true. Otherwise, it should return
+ * false.
+ *
+ * The reason why the caller needs to know if part of the cache was + * cleared is that in that case it will have to commit its on-disk index + * (so that all the latest category additions can be searched on disk, if + * we can't rely on the cache to contain them). + *
+ * Ordinals should be non-negative. Currently there is no defined way to + * specify that a cache should remember a category does NOT exist. + * It doesn't really matter, because normally the next thing we do after + * finding that a category does not exist is to add it. + */ + public boolean put(CategoryPath categoryPath, int ordinal); + + /** + * Like {@link #put(CategoryPath, int)}, but for a given prefix of the + * category path. + *
+ * If the given length is negative or bigger than the path's actual + * length, the full path is taken. + */ + public boolean put(CategoryPath categoryPath, int prefixLen, int ordinal); + + /** + * Sometimes the cache is either unlimited in size, or limited by a very + * big size, and in that case when we add a lot of categories it might + * make sense to pre-load the cache with all the existing categories. + * However, this pre-load does not make sense when the allowed cache + * size is small. The hasRoom() method allows to differentiate between + * these cases. + *
+ * After hasRoom(n) returned true, the following n put()
+ * should return false (meaning that the cache was not cleared).
+ */
+ public boolean hasRoom(int numberOfEntries);
+
+}