/* 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.ds;

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

/**
 * ItemTable is table like structure to have key-value pairs.
 * It has two keys : Super Key (K1) and Sub Key (K2). The implementor can use 
 * this according to their need. Basically is will be implemented with Hash structure.
 * It provides operations to put and get the objects based on their keys.
 * 
 * @author Prathab K
 *
 */
public interface ItemTable<K1,K2,V> {
    
    /** Puts the object into the table */
    public void put(V v);
    
    /**
     * Puts the object based on the super key
     * @param k1 super key
     * @param v value
     */
    public void put(K1 k1, V v);
    
    /**
     * Puts the object based on the super and sub key
     * @param k1 super key
     * @param k2 sub key
     * @param v value
     */
    public void put(K1 k1, K2 k2, V v);
    
    /**
     * Gets the object from the table. 
     * This is generic method allowing user to use custom key to get the value object
     * @param o key object
     * @return value object
     */
    public Object getObject(Object o);
    
    /**
     * Gets the object based on sub key
     * @param k1 super key
     * @return value object
     */
    public Map<K2, V> get(K1 k1);
    
    /**
     * Gets the object based on sub key
     * @param k2 sub key
     * @return value object
     */
    public V get(K2 k2);
    
    /**
     * Gets the object based on super and sub key
     * @param k1 super key
     * @param k2 sub key
     * @return value object
     */
    public V get(K1 k1, K2 k2);
    
    /**
     * Returns all the items in the table
     * @return Value objects as <tt>List</tt>
     */
    public List<V> getAllItems();
    
    /**
     * Removes the item based on the sub key
     * @param k2 sub key
     * @return <tt>true</tt> on success
     */
    public boolean remove(K2 k2);
    
    /**
     * Removes the item based on the super and sub key
     * @param k1 super key
     * @param k2 sub key
     * @return <tt>true</tt> on success
     */
    public boolean remove(K1 k1, K2 k2);

    /**
     * Commits the table contents to the file
     * @throws IOException if file operations fail
     */
    public void commit() throws IOException;
    
    /**
     * Close the file associate with the table
     * @throws IOException if file operations fail
     */
    public void close() throws IOException;
    
    /**
     * Size of the table (number items in the table)
     * @return table size
     */
    public int size();

}