package prefuse.data.search;

import java.util.Iterator;

import prefuse.data.Tuple;
import prefuse.data.tuple.DefaultTupleSet;

/**
 * <p>Abstract base class for TupleSet implementations that support text
 * search. These sets provide search engine functionality -- Tuple data fields
 * can be indexed and then searched over using text queries, the results of
 * which populate the TupleSet. A range of search techniques are provided by
 * subclasses of this class.</p>
 * 
 * <p>
 * <b>NOTE:</b> The {@link #addTuple(Tuple)} and
 * {@link #removeTuple(Tuple)}, methods are not supported by this 
 * implementation or its derived classes. Calling these methods will result
 * in thrown exceptions. Instead, membership is determined by the search
 * matches found using the {@link #search(String) search} method, which
 * searches over the terms indexed using the {@link #index(Iterator, String)}
 * and {@link #index(Tuple, String)} methods.
 * </p>
 * 
 * @author <a href="http://jheer.org">jeffrey heer</a>
 * @see prefuse.data.query.SearchQueryBinding
 */
public abstract class SearchTupleSet extends DefaultTupleSet {
    
    /**
     * Returns the current search query, if any.
     * @return the currently active search query
     */
    public abstract String getQuery();
    
    /**
     * Searches the indexed fields of this TupleSet for matching
     * strings, adding the Tuple instances for each search match
     * to the TupleSet. The details of how the query is matched to
     * indexed fields is left to subclasses.
     * @param query the query string to search for. Indexed fields
     *  with matching text will be added to the TupleSet.
     */
    public abstract void search(String query);
    
    /**
     * Indexes the data values for the given field name for
     * each Tuple in the provided Iterator. These values are used
     * to construct an internal data structure allowing fast searches
     * over these attributes. To index multiple fields, simply call
     * this method multiple times with the desired field names.
     * @param tuples an Iterator over Tuple instances to index
     * @param field the name of the attribute to index
     * @throws ClassCastException is a non-Tuple instance is
     * encountered in the iteration.
     */
    public void index(Iterator tuples, String field) {
        while ( tuples.hasNext() ) {
            Tuple t = (Tuple)tuples.next();
            index(t, field);
        }
    }
    
    /**
     * Index an individual Tuple field, so that it can be searched for.
     * @param t the Tuple
     * @param field the data field to index
     */
    public abstract void index(Tuple t, String field);

    /**
     * Un-index an individual Tuple field, so that it can no longer be 
     * searched for.
     * @param t the Tuple
     * @param field the data field to unindex
     * @see #isUnindexSupported()
     */
    public abstract void unindex(Tuple t, String field);
    
    /**
     * Indicates if this TupleSearchSet supports the unindex operation.
     * @return true if unindex is supported, false otherwise.
     * @see #unindex(Tuple, String)
     */
    public abstract boolean isUnindexSupported();
    
    // ------------------------------------------------------------------------
    // Unsupported Operations
    
    /**
     * This method is not supported by this implementation. Don't call it!
     * Instead, use the {@link #search(String) search} or
     * {@link #clear() clear} methods.
     */
    public Tuple addTuple(Tuple t) {
        throw new UnsupportedOperationException();
    }
    /**
     * This method is not supported by this implementation. Don't call it!
     * Instead, use the {@link #search(String) search} or
     * {@link #clear() clear} methods.
     */
    public boolean removeTuple(Tuple t) {
        throw new UnsupportedOperationException();
    }
    
} // end of abstract class SearchTupleSet