org.apache.cassandra.index.sasi.utils.trie.Trie Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cassandra-all Show documentation
A fork of the Apache Cassandra Project ready to embed Elasticsearch.
There is a newer version: 3.11.12.3
/*
 * Copyright 2005-2010 Roger Kapsi, Sam Berlin
 *
 *   Licensed 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.cassandra.index.sasi.utils.trie;

import java.util.Map;
import java.util.SortedMap;

import org.apache.cassandra.index.sasi.utils.trie.Cursor.Decision;

/**
 * This class is taken from https://github.com/rkapsi/patricia-trie (v0.6), and slightly modified
 * to correspond to Cassandra code style, as the only Patricia Trie implementation,
 * which supports pluggable key comparators (e.g. commons-collections PatriciaTrie (which is based
 * on rkapsi/patricia-trie project) only supports String keys)
 * but unfortunately is not deployed to the maven central as a downloadable artifact.
 */

/**
 * Defines the interface for a prefix tree, an ordered tree data structure. For
 * more information, see Tries.
 *
 * @author Roger Kapsi
 * @author Sam Berlin
 */
public interface Trie extends SortedMap
{
    /**
     * Returns the {@link Map.Entry} whose key is closest in a bitwise XOR
     * metric to the given key. This is NOT lexicographic closeness.
     * For example, given the keys:
     *
     * 
     * D = 1000100
     * 
H = 1001000
     * 
L = 1001100
     * 
     *
     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
     * return 'L', because the XOR distance between D & L is smaller
     * than the XOR distance between D & H.
     *
     * @return The {@link Map.Entry} whose key is closest in a bitwise XOR metric
     * to the provided key.
     */
    Map.Entry select(K key);

    /**
     * Returns the key that is closest in a bitwise XOR metric to the
     * provided key. This is NOT lexicographic closeness!
     *
     * For example, given the keys:
     *
     * 
     * D = 1000100
     * 
H = 1001000
     * 
L = 1001100
     * 
     *
     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
     * return 'L', because the XOR distance between D & L is smaller
     * than the XOR distance between D & H.
     *
     * @return The key that is closest in a bitwise XOR metric to the provided key.
     */
    @SuppressWarnings("unused")
    K selectKey(K key);

    /**
     * Returns the value whose key is closest in a bitwise XOR metric to
     * the provided key. This is NOT lexicographic closeness!
     *
     * For example, given the keys:
     *
     * 
     * D = 1000100
     * 
H = 1001000
     * 
L = 1001100
     * 
     *
     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
     * return 'L', because the XOR distance between D & L is smaller
     * than the XOR distance between D & H.
     *
     * @return The value whose key is closest in a bitwise XOR metric
     * to the provided key.
     */
    @SuppressWarnings("unused")
    V selectValue(K key);

    /**
     * Iterates through the {@link Trie}, starting with the entry whose bitwise
     * value is closest in an XOR metric to the given key. After the closest
     * entry is found, the {@link Trie} will call select on that entry and continue
     * calling select for each entry (traversing in order of XOR closeness,
     * NOT lexicographically) until the cursor returns {@link Decision#EXIT}.
     *
     * The cursor can return {@link Decision#CONTINUE} to continue traversing.
     *
     * 
{@link Decision#REMOVE_AND_EXIT} is used to remove the current element
     * and stop traversing.
     *
     * 
Note: The {@link Decision#REMOVE} operation is not supported.
     *
     * @return The entry the cursor returned {@link Decision#EXIT} on, or null
     * if it continued till the end.
     */
    Map.Entry select(K key, Cursor cursor);

    /**
     * Traverses the {@link Trie} in lexicographical order.
     * {@link Cursor#select(java.util.Map.Entry)} will be called on each entry.
     *
     * 
The traversal will stop when the cursor returns {@link Decision#EXIT},
     * {@link Decision#CONTINUE} is used to continue traversing and
     * {@link Decision#REMOVE} is used to remove the element that was selected
     * and continue traversing.
     *
     * 
{@link Decision#REMOVE_AND_EXIT} is used to remove the current element
     * and stop traversing.
     *
     * @return The entry the cursor returned {@link Decision#EXIT} on, or null
     * if it continued till the end.
     */
    Map.Entry traverse(Cursor cursor);

    /**
     * Returns a view of this {@link Trie} of all elements that are prefixed
     * by the given key.
     *
     * 
In a {@link Trie} with fixed size keys, this is essentially a
     * {@link #get(Object)} operation.
     *
     * For example, if the {@link Trie} contains 'Anna', 'Anael',
     * 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then
     * a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'.
     */
    SortedMap prefixMap(K prefix);
}