plugins/org.eclipse.wst.common.core/src-search/org/eclipse/wst/common/core/search/SearchParticipant.java

/*******************************************************************************
 * Copyright (c) 2004, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - Initial API and implementation
 *******************************************************************************/

package org.eclipse.wst.common.core.search;

import java.util.Map;

import org.eclipse.core.resources.IFile;
import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.Platform;
import org.eclipse.wst.common.core.search.document.SearchDocument;
import org.eclipse.wst.common.core.search.document.SearchDocumentSet;
import org.eclipse.wst.common.core.search.pattern.SearchPattern;
import org.eclipse.wst.common.core.search.scope.SearchScope;

/**
 * <p>
 * A search participant describes a particular extension to a generic search
 * mechanism, permitting combined search actions which will involve all required
 * participants.
 * </p>
 * <p>
 * When there is a need to search a document that has some mixed content, then
 * using a one participant will not be enough. E.g. for the searching of the JSP
 * content, a JSP participant needs to create {@link SearchDocument} that
 * contain Java compilation unit and then pass it to the default Java search
 * participant of the Java Search Engine. The same with XML: when there is an
 * XML content that default search participant could not process, but it is
 * required to be search on, a new search participant needs to be defined. That
 * search participant would know how create search document from the content and
 * then it can call default XML search participant.
 * </p>
 * <p>
 * Passing its own {@link SearchRequestor} this participant can then map the
 * match positions back to the original contents, create its own matches and
 * report them to the original requestor.
 * </p>
 * <p>
 * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
 * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
 * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
 * (repeatedly) as the API evolves.
 * </p>
 * 
 */
public abstract class SearchParticipant implements ISearchOptions 
{

	protected static final boolean debugPerf = "true".equalsIgnoreCase(Platform.getDebugOption("org.eclipse.wst.common.core/perf")); //$NON-NLS-1$ //$NON-NLS-2$

	protected String id;
	/**
	 * Creates a new search participant.
	 */
	protected SearchParticipant()
	{
		// do nothing
	}

	/**
	 * Callback method allowing a search participant to indicate whether it supports
	 * the specified search pattern and options.
	 * <p>
	 * If this method returns <code>true</code>, the participant will participate in
	 * finding matches for the search defined by the search pattern. In this case, the
	 * search pattern and options will be passed to the following methods of the
	 * search participant:
	 * <ol>
	 * <li>{@link #beginSearching(SearchPattern, Map)}
	 * <li>{@link #selectDocumentLocations(SearchPattern, SearchScope, Map, IProgressMonitor)}
	 * <li>{@link #createSearchDocuments(SearchDocumentSet, SearchPattern, SearchScope, Map, IProgressMonitor)}
	 * <li>{@link #locateMatches(SearchDocumentSet, SearchPattern, SearchScope, SearchRequestor, Map, IProgressMonitor)}
	 * <li>{@link #doneSearching(SearchPattern, Map)}
	 * </ol>
	 * <p>
	 * If this method returns <code>false</code>, none of the above methods will be
	 * called, and the search participant contributes no matches for the search
	 * requrest.
	 * <p>
	 * A search participant should only participate in a search when in understands
	 * the search pattern. Unrecognized search options, however, can be ignored.
	 * <p>
	 * This method returns <code>false</code> by default. As a result, subclasses must
	 * override this method to participate in any searches.
	 * @param pattern The pattern describing the information to search for
	 * @param searchOptions Map of options and values defining behavior of the search;
	 *         <code>null</code> if no options are specified;
	 *         some options and values are provided by {@link ISearchOptions}
	 * @return <code>true</code> if the search participant will participate in the
	 *         search request; <code>false</code> otherwise
	 */
	 public abstract boolean isApplicable(SearchPattern pattern, Map searchOptions);

	/**
	 * Notification that this participant's help is needed in a search.
	 * <p>
	 * This method should be re-implemented in subclasses that need to do
	 * something when the participant is needed in a search.
	 * </p>
	 * @param pattern The pattern describing the information to search for
	 * @param searchOptions Map of options and values defining behavior of the search;
	 *         <code>null</code> if no options are specified;
	 *         some options and values are provided by {@link ISearchOptions}
	 */
	public void beginSearching(SearchPattern pattern, Map searchOptions)
	{
		// do nothing
	}

	/**
	 * Notification that this participant's help is no longer needed.
	 * <p>
	 * This method should be re-implemented in subclasses that need to do
	 * something when the participant is no longer needed in a search.
	 * </p>
	 * @param pattern
	 *            The pattern describing the information to search for
	 * @param searchOptions
	 *            Map of options and values defining behavior of the search;
	 *            <code>null</code> if no options are specified;
	 *            some options and values are provided by {@link ISearchOptions}
	 */
	public void doneSearching(SearchPattern pattern, Map searchOptions)
	{
		// do nothing
	}
	
	/**
	 * Returns a displayable name of this search participant.
	 * <p>
	 * This method should be re-implemented in subclasses that need to display a
	 * meaningfull name.
	 * </p>
	 * 
	 * @return the displayable name of this search participant
	 */
	public String getDescription()
	{
		return "Search participant"; //$NON-NLS-1$
	}

	/**
	 * Returns a search document for the given path. The given document path is
	 * a string that uniquely identifies the document. Most of the time it is a
	 * workspace-relative path, but it can also be a file system path, or a path
	 * inside a zip file.
	 * <p>
	 * Implementors of this method can either create an instance of their own
	 * subclass of {@link SearchDocument} or return an existing instance of such
	 * a subclass.
	 * </p>
	 * 
	 * @param documentPath
	 *            the path of the document.
	 * @return a search document
	 */
	public abstract SearchDocument createSearchDocument(String documentPath);

	/**
	 * Locates the matches in the given documents. This method should be called
	 * by the other search participant or search client once it has
	 * pre-processed documents and delegating search to this search participant.
	 * @param documentSet
	 *            The documents to locate matches in
	 * @param pattern
	 *            The pattern describing the information to search for
	 * @param scope
	 *            Search scope to limit the source of search candidates;
	 *            <code>null</code> indicates that the entire workspace is to be
	 *            searched
	 * @param requestor
	 *            Callback object to notify with the results of the search (each match
	 *            is reported to {@link SearchRequestor#acceptSearchMatch(SearchMatch)})
	 * @param searchOptions
	 *            Map of options and values defining behavior of the search;
	 *            <code>null</code> if no options are specified;
	 *            some options and values are provided by {@link ISearchOptions}
	 * @param monitor
	 *            Progress monitor used to report work completed; <code>null</code>
	 *            if no progress needs to be reported
	 * @throws CoreException
	 *            If the requestor had problem accepting one of the matches
	 */
	public abstract void locateMatches(SearchDocumentSet documentSet,
			SearchPattern pattern, SearchScope scope,
			SearchRequestor requestor, Map searchOptions, IProgressMonitor monitor)
			throws CoreException;

	/**
	 * 
	 * @param document
	 * @param pattern
	 */
	public abstract void populateSearchDocument(SearchDocument document,
			SearchPattern pattern);

	/**
	 * Returns the collection of document locations to consider when performing
	 * the given search query in the given scope. The search engine calls this
	 * method before locating matches.
	 * <p>
	 * An document location represents a path workspace to the file with the
	 * content that has potential matches
	 * </p>
	 * <p>
	 * Clients are not expected to call this method.
	 * </p>
	 * @param pattern
	 *            The pattern describing the information to search for
	 * @param scope
	 *            Search scope to limit the source of search candidates;
	 *            <code>null</code> indicates that the entire workspace is to be
	 *            searched
	 * @param searchOptions
	 *            Map of options and values defining behavior of the search;
	 *            <code>null</code> if no options are specified;
	 *            some options and values are provided by {@link ISearchOptions}
	 * @param monitor
	 *            Progress monitor used to report work completed; <code>null</code>
	 *            if no progress needs to be reported
	 * @return the collection of document paths to consider
	 */
	public SearchScope selectDocumentLocations(SearchPattern pattern,
			SearchScope scope, Map searchOptions, IProgressMonitor monitor)
	{	
		return scope;
	}

	/**
	 * <p>
	 * This method calls the following methods for each file in the search scope:
	 * <ol>
	 * <li>{@link #createSearchDocument(String)}
	 * <li>{@link #populateSearchDocument(SearchDocument, SearchPattern)}
	 * </ol>
	 * @param documentSet
	 *            The documents to locate matches in
	 * @param pattern
	 *            The pattern describing the information to search for
	 * @param scope
	 *            Search scope to limit the source of search candidates;
	 *            <code>null</code> indicates that the entire workspace is to be
	 *            searched
	 * @param searchOptions
	 *            Map of options and values defining behavior of the search;
	 *            <code>null</code> if no options are specified;
	 *            some options and values are provided by {@link ISearchOptions}
	 * @param monitor
	 *            Progress monitor used to report work completed; <code>null</code>
	 *            if no progress needs to be reported
	 */
	public void createSearchDocuments(SearchDocumentSet documentSet,
			SearchPattern pattern, SearchScope scope, Map searchOptions,
			IProgressMonitor monitor)
	{
		Assert.isNotNull(id, "The SearchPartipants id has not been initalized");
		IFile[] files = scope.enclosingFiles();
		
		for (int i = 0; i < files.length; i++)
		{
			String location = files[i].getLocation().toString();
			SearchDocument document = documentSet.getSearchDocument(location, id);
			if(document == null && id != null){
				documentSet.putSearchDocument(id, document = createSearchDocument(location));
			}
			populateSearchDocument(document, pattern); 
			
		}

	}	
}