/*
 * Copyright (c) 2002-2009 "Neo Technology,"
 *     Network Engine for Objects in Lund AB [http://neotechnology.com]
 *
 * This file is part of Neo4j.
 * 
 * Neo4j is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 * 
 * This program 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.  See the
 * GNU Affero General Public License for more details.
 * 
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
package org.neo4j.index;

import org.neo4j.graphdb.Node;

/**
 * An index service can be used to index nodes with a key and a value.
 * Neo4j has no indexing features built-in. Instead you'll have to manage that
 * manually. IndexService is a means of providing those indexing capabilities
 * for a neo4j graph and integrate it as tightly as possible.
 * 
 * See more at http://wiki.neo4j.org/content/Indexing_with_IndexService
 */
public interface IndexService
{
    /**
     * Index <code>node</code> with <code>key</code> and <code>value</code>.
     * A node can be associated with any number of key-value pairs.
     * 
     * @param node node to index
     * @param key the key in the key-value pair to associate with {@code node}.
     * @param value the value in the key-value pair to associate with
     * {@code node}.
     */
    void index( Node node, String key, Object value );

    /**
     * Returns a single node indexed with associated with <code>key</code> and 
     * <code>value</code>. If no such node exist <code>null</code> is 
     * returned. If more then one node is found a runtime exception is 
     * thrown.
     * 
     * @param key the key for index
     * @param value the value for index
     * @return node that has been indexed with key and value or 
     * <code>null</code>
     */
    Node getSingleNode( String key, Object value );

    /**
     * Returns all nodes indexed with <code>key</code> and 
     * <code>value</code>.
     * 
     * @param key the key for index
     * @param value the value for index
     * @return nodes that have been indexed with key and value
     */
    IndexHits<Node> getNodes( String key, Object value );

    /**
     * Disassociates a key-value pair from {@code node}. If no such association
     * exist this method silently returns.
     * 
     * @param node the node to disassociate from the key-value pair.
     * @param key the key in the key-value pair.
     * @param value the value in the key-value pair.
     */
    void removeIndex( Node node, String key, Object value );
    
    /**
     * Changes isolation level for the running transaction. This method must
     * be invoked before any index ({@link #index(Node, String, Object)},
     * {@link #removeIndex(Node, String, Object)}) has been performed in the 
     * current transaction. Default isolation level is
     * {@link Isolation#SAME_TX}.
     * 
     * @param level new isolation level
     */
    void setIsolation( Isolation level );

    /**
     * Stops this indexing service comitting any asynchronous requests that 
     * are currently queued ({@link Isolation}). After this method has been
     * invoked any following method invoke on this instance is invalid.
     */
    void shutdown();
}