lucene-java-3.4.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/TaxonomyWriterCache.java

   1 package org.apache.lucene.facet.taxonomy.writercache;
   2
   3 import org.apache.lucene.facet.taxonomy.CategoryPath;
   4 import org.apache.lucene.facet.taxonomy.lucene.LuceneTaxonomyWriter;
   5
   6 /**
   7  * Licensed to the Apache Software Foundation (ASF) under one or more
   8  * contributor license agreements.  See the NOTICE file distributed with
   9  * this work for additional information regarding copyright ownership.
  10  * The ASF licenses this file to You under the Apache License, Version 2.0
  11  * (the "License"); you may not use this file except in compliance with
  12  * the License.  You may obtain a copy of the License at
  13  *
  14  *     http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  * Unless required by applicable law or agreed to in writing, software
  17  * distributed under the License is distributed on an "AS IS" BASIS,
  18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  * See the License for the specific language governing permissions and
  20  * limitations under the License.
  21  */
  22
  23 /**
  24  * TaxonomyWriterCache is a relatively simple interface for a cache of
  25  * category->ordinal mappings, used in TaxonomyWriter implementations
  26  * (such as {@link LuceneTaxonomyWriter}).
  27  * <P>
  28  * It basically has put() methods for adding a mapping, and get() for looking
  29  * a mapping up the cache. The cache does <B>not</B> guarantee to hold
  30  * everything that has been put into it, and might in fact selectively
  31  * delete some of the mappings (e.g., the ones least recently used).
  32  * This means that if get() returns a negative response, it does not
  33  * necessarily mean that the category doesn't exist - just that it is not
  34  * in the cache. The caller can only infer that the category doesn't exist
  35  * if it knows the cache to be complete (because all the categories were
  36  * loaded into the cache, and since then no put() returned true).
  37  * <P> However,
  38  * if it does so, it should clear out large parts of the cache at once, because
  39  * the user will typically need to work hard to recover from every cache
  40  * cleanup (see {@link #put(CategoryPath, int)}'s return value).
  41  *
  42  * @lucene.experimental
  43  */
  44 public interface TaxonomyWriterCache {
  45
  46   /**
  47    * Let go of whatever resources the cache is holding. After a close(),
  48    * this object can no longer be used.
  49    */
  50   public void close();
  51
  52   /**
  53    * Lookup a category in the cache, returning its ordinal, or a negative
  54    * number if the category is not in the cache.
  55    * <P>
  56    * It is up to the caller to remember what a negative response means:
  57    * If the caller knows the cache is <I>complete</I> (it was initially
  58    * fed with all the categories, and since then put() never returned true)
  59    * it means the category does not exist. Otherwise, the category might
  60    * still exist, but just be missing from the cache.
  61    */
  62   public int get(CategoryPath categoryPath);
  63
  64   /**
  65    * Like {@link #get(CategoryPath)}, but for a given prefix of the
  66    * category path.
  67    * <P>
  68    * If the given length is negative or bigger than the path's actual
  69    * length, the full path is taken.
  70    */
  71   public int get(CategoryPath categoryPath, int length);
  72
  73   /**
  74    * Add a category to the cache, with the given ordinal as the value.
  75    * <P>
  76    * If the implementation keeps only a partial cache (e.g., an LRU cache)
  77    * and finds that its cache is full, it should clear up part of the cache
  78    * and return <code>true</code>. Otherwise, it should return
  79    * <code>false</code>.
  80    * <P>
  81    * The reason why the caller needs to know if part of the cache was
  82    * cleared is that in that case it will have to commit its on-disk index
  83    * (so that all the latest category additions can be searched on disk, if
  84    * we can't rely on the cache to contain them).
  85    * <P>
  86    * Ordinals should be non-negative. Currently there is no defined way to
  87    * specify that a cache should remember a category does NOT exist.
  88    * It doesn't really matter, because normally the next thing we do after
  89    * finding that a category does not exist is to add it.
  90    */
  91   public boolean put(CategoryPath categoryPath, int ordinal);
  92
  93   /**
  94    * Like {@link #put(CategoryPath, int)}, but for a given prefix of the
  95    * category path.
  96    * <P>
  97    * If the given length is negative or bigger than the path's actual
  98    * length, the full path is taken.
  99    */
 100   public boolean put(CategoryPath categoryPath, int prefixLen, int ordinal);
 101
 102   /**
 103    * Sometimes the cache is either unlimited in size, or limited by a very
 104    * big size, and in that case when we add a lot of categories it might
 105    * make sense to pre-load the cache with all the existing categories.
 106    * However, this pre-load does not make sense when the allowed cache
 107    * size is small. The hasRoom() method allows to differentiate between
 108    * these cases.
 109    * <P>
 110    * After hasRoom(n) returned <code>true</code>, the following n put()
 111    * should return false (meaning that the cache was not cleared).
 112    */
 113   public boolean hasRoom(int numberOfEntries);
 114
 115 }