FileTextSearchRequestor.java

package com.aptana.ide.search.epl.filesystem.text;

import java.io.File;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.search.core.text.TextSearchRequestor;

/**
 * Collects the results from a search engine query. Clients implement a subclass to pass to
 * {@link FileTextSearchEngine#search(FileSystemTextSearchScope, FileTextSearchRequestor, java.util.regex.Pattern,
 * org.eclipse.core.runtime.IProgressMonitor)} and implement the {@link #acceptPatternMatch(FileTextSearchMatchAccess)}
 * method, and possibly override other life cycle methods.
 * <p>
 * The search engine calls {@link #beginReporting()} when a search starts, then calls {@link #acceptFile(IFile)} for a
 * file visited. If {@link #acceptFile(IFile)} returns <code>true</code> {@link #reportBinaryFile(IFile)} is called if
 * the file could be binary followed by {@link #acceptPatternMatch(FileTextSearchMatchAccess)} for each pattern match
 * found in this file. The end of the search is signaled with a call to {@link #endReporting()}. Note that
 * {@link #acceptFile(IFile)} is called for all files in the search scope, even if no match can be found.
 * </p>
 * <p>
 * The order of the search results is unspecified and may vary from request to request; when displaying results, clients
 * should not rely on the order but should instead arrange the results in an order that would be more meaningful to the
 * user.
 * </p>
 * 
 * @see FileTextSearchEngine
 */
public abstract class FileTextSearchRequestor extends TextSearchRequestor
{

	/**
	 * Notification sent before search starts in the given file. This method is called for all files that are contained
	 * in the search scope. Implementors can decide if the file content should be searched for search matches or not.
	 * <p>
	 * The default behaviour is to search the file for matches.
	 * </p>
	 * 
	 * @param file
	 *            the file resource to be searched.
	 * @return If false, no pattern matches will be reported for the content of this file.
	 * @throws CoreException
	 *             implementors can throw a {@link CoreException} if accessing the resource fails or another problem
	 *             prevented the processing of the search match.
	 */
	public boolean acceptFile(File file) throws CoreException
	{
		return true;
	}

	/**
	 * Notification sent that a file might contain binary context. It is the choice of the search engine to report
	 * binary files and it is the heuristic of the search engine to decide that a file could be binary. Implementors can
	 * decide if the file content should be searched for search matches or not.
	 * <p>
	 * This call is sent after calls {link {@link #acceptFile(IFile)} that return <code>true</code> and before any
	 * matches reported for this file with {@link #acceptPatternMatch(FileTextSearchMatchAccess)}.
	 * </p>
	 * <p>
	 * The default behaviour is to skip binary files
	 * </p>
	 * 
	 * @param file
	 *            the file that might be binary
	 * @return If false, no pattern matches will be reported for the content of this file.
	 */
	public boolean reportBinaryFile(File file)
	{
		return false;
	}

	/**
	 * Accepts the given search match and decides if the search should continue for this file.
	 * 
	 * @param matchAccess
	 *            gives access to information of the match found. The matchAccess is not a value object. Its value might
	 *            change after this method is finished, and the element might be reused.
	 * @return If false is returned no further matches will be reported for this file.
	 * @throws CoreException
	 *             implementors can throw a {@link CoreException} if accessing the resource fails or another problem
	 *             prevented the processing of the search match.
	 */
	public boolean acceptPatternMatch(FileTextSearchMatchAccess matchAccess) throws CoreException
	{
		return true;
	}

}