/* Copyright (C) 2009  CSE,IIT Bombay  http://www.cse.iitb.ac.in

This file is part of the ConStore open source storage facility for concept-nets.

ConStore is free software and distributed under the 
Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License;
you can copy, distribute and transmit the work
with the work attribution in the manner specified by the author or licensor.
You may not use this work for commercial purposes and may not alter, 
transform, or build upon this work.

Please refer the legal code of the license, available at
http://creativecommons.org/licenses/by-nc-nd/3.0/legalcode

ConStore is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  */

package iitb.con.indexing;

import iitb.con.ds.Node;
import iitb.con.util.KeyList;

import java.io.IOException;
import java.util.List;

/**
 * Interface for creating index structures for the instances.
 * 
 * @author Prathab K
 */

public interface IndexTree<K extends Comparable<K>> {
    
    /** Extension of non-leaf node of the index tree */
    public static final String NON_LEAF_EXT = ".nidx";
    
    /** Extension of leaf node of the index tree */
    public static final String LEAF_EXT = ".lidx";
    
    /**
     * Creates the index for given set of key-value pair.<p>
     * The key-value pair is represented as {@link Node}.  
     * @param nodes {@link Node} list
     * @throws IOException if the file operation fails
     */
    public void create(List<Node<K>> nodes) throws IOException;
    
    /**
     * Retrieves the values for the specified key
     * @param key key of the index structure
     * @return matched values for the given key
     * @throws IOException if the file operation fails
     */
    public int[] getValues(K key) throws IOException;
    
    /**
     * Returns the meta-index of the index structure.
     * The meta-index is a basically the non-leaf node of the index tree structure.
     * @param key key of the index structure
     * @return key-id list ; {@link KeyList}
     * @throws IOException if the file operation fails
     */
    public KeyList<K,Short> getMetaIndex(K key) throws IOException;
    
    /**
     * Closes the index structure files.
     * @throws IOException if the file operation fails
     */
    public void close() throws IOException;

}