HGIndex.java

/* 
 * This file is part of the HyperGraphDB source distribution. This is copyrighted 
 * software. For permitted uses, licensing options and redistribution, please see  
 * the LicensingInformation file at the root level of the distribution.  
 * 
 * Copyright (c) 2005-2010 Kobrix Software, Inc.  All rights reserved. 
 */
package org.hypergraphdb;


/**
 * <p>The <code>HGIndex</code> interface represents an user-created index in the HyperGraph 
 * data structure.</p>
 * 
 * <p>
 * Note that taking advantage of the fact that Java allows overriding methods to
 * further specialize on the return type (i.e. allowing contra-variant return types),
 * the <code>find</code> method of the super-interface is redeclared to return a 
 * <code>HGRandomAccessResult</code>. 
 * </p> 
 * 
 * @author Borislav Iordanov
 */
public interface HGIndex<KeyType, ValueType> extends HGSearchable<KeyType, ValueType>
{    
    /**
     * <p>
     * Add an entry to the index. If that entry is already present, calling this
     * method should have no effect.
     * </p>
     * 
     * @param key The entry's key part.
     * @param value The entry's value part.
     */
    void addEntry(KeyType key, ValueType value);

    /**
     * <p>Remove a specific entry in the index. If an entry
     * with this key and value does not exist, the method does not nothing.
     * </p>
     * 
     * @param key The key part of the entry.
     * @param value The value part of the entry.
     */
    void removeEntry(KeyType key, ValueType value);

    /**
     * <p>Remove all entries in the index with a given key. If an entry
     * with this key does not exist, the method does not nothing.
     * </p>
     * 
     * @param key The key all of whose corresponding entries will be removed.
     */
    void removeAllEntries(KeyType key);
    
    /**
     * <p>
     * Find the first indexed entry corresponding to the given key. The first
     * entry will generally be the one that was firstly added for that key. However,
     * this is by no means guaranteed. This method is meant for indices where
     * only a single value corresponds to a key. That is, in mathematical terms, indices
     * that can be seen as functions.
     * </p>
     * 
     * @param key The key whose value is sought.
     * @return The first entry for that key.
     */
    ValueType findFirst(KeyType key);
    
    /**
     * <p>
     * Retrieve all entries corresponding to the given key. The order in 
     * which the entries are returned is not necessarily the order in 
     * which they were originally added.
     * </p>
     * 
     * @param key The key whose values are sought.
     * @return A <code>HGRandomAccessResult</code> over all <code>HGPersistentHandle</code>s under that key.
     */
    HGRandomAccessResult<ValueType> find(KeyType key);
    
    /**
     * <p>
     * Open the index for use. Entries may be added to the index only when it
     * has been explicitly opened. To determine whether an index is currently
     * opened, use the <code>isOpen</code> method. Note that an index may be
     * temporarily opened by the HyperGraph querying mechanism.
     * </p> 
     */
    public void open();
    
    /**
     * <p>
     * Close this index. This method closes any run-time resources associated with
     * the index, and invalidates it for use until reopened. It does not remove
     * the index permanently from the database.
     * </p> 
     */
    void close();
    
    /**
     * <p>Return <code>true</code> if the index is currently opened and
     * <code>false</code> otherwise.
     * </p> 
     */
    boolean isOpen();
    
    /**
     * <p>Return a result set containing all keys in this index.</p>
     */
    HGRandomAccessResult<KeyType> scanKeys();
    
    /**
     * <p>Return a result set containing all values in this index.</p>
     */
    HGRandomAccessResult<ValueType> scanValues();
    
    /**
     * <p>Return the number of keys in this index. This operation must run
     * in constant time, regardless of the number of keys.</p>
     */
    long count();

    /**
     * <p>Return the number of values for the key. This operation must run 
     * constant time regardless of the key or the number returned.</p>
     * @param key The key whose values must be counted.
     */
    long count(KeyType key);
}