/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 2004 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.openidex.search;

import java.util.Iterator;

/**
 * Defines which DataObjects should be searched.
 * Iterator returned by this interface's method enumerates
 * DataObjects that should be searched.
 *
 * @see  SearchInfoFactory
 * @see  DataObject
 * @since  org.openidex.util/3 3.2
 * @author  Marian Petras
 */
public interface SearchInfo {

    /**
     * Determines whether the object which provided this SearchInfo
     * can be searched.
     * This method determines whether the Find action should be enabled
     * for the object or not.
     * 

     * This method must be very quick as it may be called frequently and its
     * speed may influence responsiveness of the whole application. If the exact
     * algorithm for determination of the result value should be slow, it is
     * better to return true than make the method slow.
     *
     * @return  false if the object is known that it cannot be
     *          searched; true otherwise
     * @since  org.openidex.util/3 3.3
     */
    public boolean canSearch();

    /**
     * Specifies which DataObjects should be searched.
     * The returned Iterator needn't implement method
     * {@link java.util.Iterator#remove remove()} (i.e. it may throw
     * UnsupportedOperationException instead of actual
     * implementation).
     *
     * @return  iterator which iterates over DataObjects
     *          to be searched
     */
    public Iterator objectsToSearch();
    
}