com.googlecode.concurrenttrees.radixinverted.InvertedRadixTree Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of concurrent-trees Show documentation
Concurrent Radix Trees and Concurrent Suffix Trees for Java.
The newest version!
/**
 * Copyright 2012-2013 Niall Gallagher
 *
 * 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 com.googlecode.concurrenttrees.radixinverted;

import com.googlecode.concurrenttrees.common.KeyValuePair;
import com.googlecode.concurrenttrees.radix.RadixTree;

/**
 * API of an inverted radix tree, that is a radix tree which is set up to scan external documents for keys previously
 * added to the tree, rather than for data contained in the tree itself.
 * 
 * This method of scanning external documents for keys (or keywords) can be significantly faster than repeatedly
 * scanning the same document for each and every keyword using {@link String#contains(CharSequence)} on the document.
 * 

 * Time complexity is O(d) rather than O(dn), where d=length of document and n=number of keys/keywords.
 * 

 * This is an extension of {@link RadixTree} which provides additional traversal algorithms to implement this
 * functionality on top of the same tree structure. See documentation on each method for details.
 *
 * @param  The type of the values associated with keys in the tree
 *
 * @author Niall Gallagher
 */
public interface InvertedRadixTree extends RadixTree {

    /**
     * Associates the given value with the given key; replacing any previous value associated with the key.
     * Returns the previous value associated with the key, if any.
     * 

     * This operation is performed atomically.
     *
     * @param key The key with which the specified value should be associated
     * @param value The value to associate with the key, which cannot be null
     * @return The previous value associated with the key, if there was one, otherwise null
     */
    O put(CharSequence key, O value);

    /**
     * If a value is not already associated with the given key in the tree, associates the given value with the
     * key; otherwise if an existing value is already associated, returns the existing value and does not overwrite it.
     * 

     * This operation is performed atomically.
     *
     * @param key The key with which the specified value should be associated
     * @param value The value to associate with the key, which cannot be null
     * @return The existing value associated with the key, if there was one; otherwise null in which case the new
     * value was successfully associated
     */
    O putIfAbsent(CharSequence key, O value);

    /**
     * Removes the value associated with the given key (exact match).
     * If no value is associated with the key, does nothing.
     *
     * @param key The key for which an associated value should be removed
     * @return True if a value was removed (and therefore was associated with the key), false if no value was
     * associated/removed
     */
    boolean remove(CharSequence key);

    /**
     * Returns the value associated with the given key (exact match), or returns null if no such value
     * is associated with the key.
     *
     * @param key The key with which a sought value might be associated
     * @return The value associated with the given key (exact match), or null if no value was associated with the key
     */
    O getValueForExactKey(CharSequence key);

    /**
     * Returns a lazy iterable which returns the set of keys in the tree which prefix the given document.
     *
     * @param document A document to be scanned for keys contained in the tree which prefix the given document
     * @return The set of keys in the tree which prefix the given document
     */
    Iterable getKeysPrefixing(CharSequence document);

    /**
     * Returns a lazy iterable which returns the set of values associated with keys in the tree which prefix
     * the given document.
     *
     * @param document A document to be scanned for keys contained in the tree which prefix the given document
     * @return The set of values associated with keys in the tree which prefix the given document
     */
    Iterable getValuesForKeysPrefixing(CharSequence document);

    /**
     * Returns a lazy iterable which returns the set of {@link KeyValuePair}s for keys in the tree which prefix
     * the given document.
     *
     * @param document A document to be scanned for keys contained in the tree which prefix the given document
     * @return The set of {@link KeyValuePair}s for keys in the tree which prefix the given document
     */
    Iterable> getKeyValuePairsForKeysPrefixing(CharSequence document);

    /**
     * Returns the longest key in the tree which is a prefix of the given document.
     *
     * @param document A document to be scanned for a key contained in the tree which prefixes the given document
     * @return The longest key in the tree which is a prefix of the given document, or null if no such key is
     * contained in the tree
     */
    public CharSequence getLongestKeyPrefixing(CharSequence document);

    /**
     * Returns the value associated with the longest key in the tree which is a prefix of the given document.
     *
     * @param document A document to be scanned for a key contained in the tree which prefixes the given document
     * @return The value associated with longest key in the tree which is a prefix of the given document, or null if
     * no such key is contained in the tree
     */
    public O getValueForLongestKeyPrefixing(CharSequence document);

    /**
     * Returns the {@link KeyValuePair} for the longest key in the tree which is a prefix of the given document.
     *
     * @param document A document to be scanned for a key contained in the tree which prefixes the given document
     * @return The {@link KeyValuePair} for the longest key in the tree which is a prefix of the given document,
     * or null if no such key is contained in the tree
     */
    public KeyValuePair getKeyValuePairForLongestKeyPrefixing(CharSequence document);

    /**
     * Returns a lazy iterable which returns the set of keys in the tree which are contained in the given document.
     *
     * @param document A document to be scanned for keys contained in the tree
     * @return The set of keys in the tree which are contained in the given document
     */
    Iterable getKeysContainedIn(CharSequence document);

    /**
     * Returns a lazy iterable which returns the set of values associated with keys in the tree which are contained
     * in the given document.
     *
     * @param document A document to be scanned for keys contained in the tree
     * @return The set of values associated with keys in the tree which are contained in the given document
     */
    Iterable getValuesForKeysContainedIn(CharSequence document);

    /**
     * Returns a lazy iterable which returns the set of {@link KeyValuePair}s for keys in the tree which are contained
     * in the given document.
     *
     * @param document A document to be scanned for keys contained in the tree
     * @return The set of {@link KeyValuePair}s for keys in the tree which are contained in the given document
     */
    Iterable> getKeyValuePairsForKeysContainedIn(CharSequence document);

    /**
     * Counts the number of keys/values stored in the tree.
     * 
     * In the current implementation, this is an expensive operation, having O(n) time complexity.
     *
     * @return The number of keys/values stored in the tree
     */
    int size();
}