/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.lucene.facet.taxonomy.writercache;
import org.apache.lucene.facet.taxonomy.FacetLabel;
import org.apache.lucene.facet.taxonomy.directory.DirectoryTaxonomyWriter;
TaxonomyWriterCache is a relatively simple interface for a cache of category->ordinal mappings, used in TaxonomyWriter implementations (such as DirectoryTaxonomyWriter).
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 put(FacetLabel, int)'s return value).
NOTE: the cache may be accessed concurrently by multiple threads,
therefore cache implementations should take this into consideration.
@lucene.experimental
/**
* TaxonomyWriterCache is a relatively simple interface for a cache of
* category->ordinal mappings, used in TaxonomyWriter implementations (such as
* {@link DirectoryTaxonomyWriter}).
* <p>
* It basically has put() methods for adding a mapping, and get() for looking a
* mapping up the cache. The cache does <B>not</B> 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).
* <p>
* 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(FacetLabel, int)}'s return value).
* <p>
* <b>NOTE:</b> the cache may be accessed concurrently by multiple threads,
* therefore cache implementations should take this into consideration.
*
* @lucene.experimental
*/
public interface TaxonomyWriterCache {
Let go of whatever resources the cache is holding. After a close(),
this object can no longer be used.
/**
* 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.
/**
* Lookup a category in the cache, returning its ordinal, or a negative
* number if the category is not in the cache.
* <P>
* It is up to the caller to remember what a negative response means:
* If the caller knows the cache is <I>complete</I> (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(FacetLabel categoryPath);
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.
/**
* Add a category to the cache, with the given ordinal as the value.
* <P>
* 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 <code>true</code>. Otherwise, it should return
* <code>false</code>.
* <P>
* 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).
* <P>
* 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(FacetLabel categoryPath, int ordinal);
Returns true if the cache is full, such that the next put will evict entries from it, false otherwise. /**
* Returns true if the cache is full, such that the next {@link #put} will
* evict entries from it, false otherwise.
*/
public boolean isFull();
Clears the content of the cache. Unlike close(), the caller can assume that the cache is still operable after this method returns. /**
* Clears the content of the cache. Unlike {@link #close()}, the caller can
* assume that the cache is still operable after this method returns.
*/
public void clear();
How many labels are currently stored in the cache. /** How many labels are currently stored in the cache. */
public int size();
}