Extend AbstractSearchProcessor#postSearch(...) for more information

The `org.eclipse.help.searchProcessor` extension point allows to modify
the help search results. This is done by calling the `postSearch(...)`
method of all implementations of
`org.eclipse.help.search.AbstractSearchProcessor` specified by this
extension point. In some cases, the search results to be modified and
the query that are passed as parameters to the `postSearch(...)` method
may not be enough. So this change adds another `postSearch(...)` method
with additional parameters like the locale and the scopes if any. The
simpler `postSearch(...)` is be kept for backward compatibility.

Additionally, if `preSearch(...)` returns a `SearchProcessorInfo` with
an empty, non-`null` query (`""`), no search will be executed, resulting
in no search results or in the search results that has been added via
`postSearch(...)`.

Author: howlger

ua/org.eclipse.help.base/src/org/eclipse/help/internal/search/SearchResults.java

@@ -19,6 +19,7 @@
 import java.util.Iterator;
 import java.util.List;
 
+import org.eclipse.help.IHelpResource;
 import org.eclipse.help.IToc;
 import org.eclipse.help.ITopic;
 import org.eclipse.help.base.AbstractHelpScope;
@@ -297,4 +298,9 @@ private ArrayList<CriterionResource> getCriteriaScopes(WorkingSet[] wSets){
 	public void addQTCException(QueryTooComplexException exception) throws QueryTooComplexException {
 		this.searchException = exception;
 	}
+
+	public IHelpResource[] getScopes() {
+		return scopes == null ? null : scopes.toArray(new IHelpResource[scopes.size()]);
+	}
+
 }

ua/org.eclipse.help.base/src/org/eclipse/help/internal/search/federated/LocalHelp.java

@@ -37,7 +37,9 @@ public class LocalHelp implements ISearchEngine2 {
 	public void run(String query, ISearchScope scope,
 			final ISearchEngineResultCollector collector,
 			IProgressMonitor monitor) throws CoreException {
+		final String originalQuery = query;
 
+		// Pre search
 		AbstractSearchProcessor processors[] = SearchManager.getSearchProcessors();
 		altList = new ArrayList<>();
 		for (AbstractSearchProcessor processor : processors) {
@@ -56,28 +58,30 @@ public void run(String query, ISearchScope scope,
 		}
 		altList.sort(null);
 
-
+		// Search
 		SearchQuery searchQuery = new SearchQuery();
 		searchQuery.setSearchWord(query);
 		WorkingSet[] workingSets = null;
 		LocalHelpScope localScope = (LocalHelpScope) scope;
 		if (localScope.getWorkingSet() != null)
 			workingSets = new WorkingSet[] { localScope.getWorkingSet() };
-		SearchResults localResults = new SearchResults(workingSets, MAX_HITS,
-				Platform.getNL());
+		SearchResults localResults = new SearchResults(workingSets, MAX_HITS, Platform.getNL());
 		// If the indexer has been started and is currently running,
 		// wait for it to finish.
 		try {
 			Job.getJobManager().join(IndexerJob.FAMILY, monitor);
 		} catch (InterruptedException e) {
 		}
-		BaseHelpSystem.getSearchManager().search(searchQuery, localResults,
-				monitor);
+		if (!"".equals(query)) { //$NON-NLS-1$
+			BaseHelpSystem.getSearchManager().search(searchQuery, localResults, monitor);
+		}
 
+		// Post search
 		ISearchResult results[] = SearchManager.convertHitsToResults(localResults.getSearchHits());
 		boolean reset = false;
 		for (AbstractSearchProcessor processor : processors) {
-			ISearchResult tmp[] = processor.postSearch(query, results);
+			ISearchResult tmp[] = processor.postSearch(query, originalQuery, results, searchQuery.getLocale(),
+					localResults.getScopes());
 			if (tmp!=null)
 			{
 				reset = true;

ua/org.eclipse.help.base/src/org/eclipse/help/search/AbstractSearchProcessor.java

@@ -14,6 +14,8 @@
 
 package org.eclipse.help.search;
 
+import org.eclipse.help.IHelpResource;
+
 /**
  * This class is responsible for handling any pre or post
  * search processing events, including query manipulation
@@ -34,20 +36,52 @@ public AbstractSearchProcessor()
 	 * See {@link SearchProcessorInfo} for types of information that can be used by
 	 * the search display.
 	 *
-	 * @return <code>SearchProcessorInfo</code>, or <code>null</code> for no changes.
+	 * If a {@link SearchProcessorInfo} with an empty, non-{@code null} query
+	 * ({@code ""}) is returned, no search will be executed, resulting in no search
+	 * results.
+	 *
+	 * @return {@link SearchProcessorInfo}, or {@code null} for no changes.
 	 */
 	public abstract SearchProcessorInfo preSearch(String query);
 
 	/**
 	 * This method is called after the search is performed.
 	 *
-	 * Results are stored as an array of ISearchResult containing
-	 * all available data.
+	 * This method can be used to return a modified result set. For example, one can
+	 * change the result score of an item, add new results to the top of the list,
+	 * or remove results.
 	 *
-	 * This method can be used to return a modified result set.  For example, one can change the
-	 * result score of an item, add new results to the top of the list, or remove results.
+	 * This method exists for backwards compatibility. Overwrite
+	 * {@link #postSearch(String, String, ISearchResult[], String, IHelpResource[])}
+	 * if more information like the locale, etc. is needed instead.
 	 *
-	 * @return <code>{@link ISearchResult}[]</code>, or <code>null</code> for no changes.
+	 * @return The modified results, or {@code null} for no changes.
 	 */
 	public abstract ISearchResult[] postSearch(String query, ISearchResult[] results);
+
+	/**
+	 * This method is called after the search is performed.
+	 *
+	 * This method can be used to return a modified result set. For example, one can
+	 * change the result score of an item, add new results to the top of the list,
+	 * or remove results.
+	 *
+	 * @param query         The actually query that was executed (after any changes
+	 *                      made by {@link #preSearch(String)}).
+	 * @param originalQuery The original query before any changes made by
+	 *                      {@link #preSearch(String)}.
+	 * @param results       The results of the executed query.
+	 * @param results       The locale.
+	 * @param results       The set scopes (might be {@code null}).
+	 *
+	 * @return The modified results, or {@code null} for no changes.
+	 *
+	 * @see #postSearch(String, ISearchResult[])
+	 *
+	 * @since 4.5
+	 */
+	public ISearchResult[] postSearch(String query, String originalQuery, ISearchResult[] results, String locale,
+			IHelpResource[] scopes) {
+		return postSearch(query, results);
+	}
 }

ua/org.eclipse.help.webapp/src/org/eclipse/help/internal/webapp/data/SearchData.java

@@ -135,6 +135,7 @@ private void readDisplayFlags(HttpServletRequest request, HttpServletResponse re
 	}
 
 	public void readSearchResults() {
+		final String originalSearchWord = searchWord;
 
 		// try loading search results or get the indexing progress info.
 		if (isSearchRequest() && !isScopeRequest()) {
@@ -167,7 +168,7 @@ public void readSearchResults() {
 			}
 			altList.sort(null);
 
-			loadSearchResults();
+			SearchResults searchResults = loadSearchResults();
 			if (queryException != null) {
 				return;
 			}
@@ -183,9 +184,9 @@ public void readSearchResults() {
 				ISearchResult results[] = SearchManager.convertHitsToResults(hits);
 				boolean reset= false;
 				for (AbstractSearchProcessor processor : processors) {
-					ISearchResult tmp[] = processor.postSearch(searchWord,results);
-					if (tmp!=null)
-					{
+					ISearchResult tmp[] = processor.postSearch(searchWord, originalSearchWord, results, getLocale(),
+							searchResults == null ? null : searchResults.getScopes());
+					if (tmp != null) {
 						reset = true;
 						results = tmp;
 					}
@@ -438,34 +439,36 @@ private void saveWorkingSet(String workingSet) {
 	 * Call the search engine, and get results or the percentage of indexed
 	 * documents.
 	 */
-	private void loadSearchResults() {
+	private SearchResults loadSearchResults() {
 		try {
 			SearchProgressMonitor pm = SearchProgressMonitor
 					.getProgressMonitor(getLocale());
 			if (pm.isDone()) {
 				this.indexCompletion = 100;
 				SearchResults results = createHitCollector();
-				BaseHelpSystem.getSearchManager().search(createSearchQuery(),
-						results, pm);
-				hits = results.getSearchHits();
+				if ("".equals(searchWord)) { //$NON-NLS-1$
+					hits = new SearchHit[0];
+				} else {
+					BaseHelpSystem.getSearchManager().search(createSearchQuery(), results, pm);
+					hits = results.getSearchHits();
+				}
 				if (hits == null) {
 					ILog.of(getClass()).warn("No search results returned.  Help index is in use."); //$NON-NLS-1$
 				}
-				return;
+				return results;
 			}
 			// progress
 			indexCompletion = pm.getPercentage();
 			if (indexCompletion >= 100) {
 				// 38573 We do not have results, so index cannot be 100
 				indexCompletion = 100 - 1;
 			}
-			return;
 		} catch (QueryTooComplexException qe) {
 			queryException = qe;
 		} catch (Exception e) {
 			this.indexCompletion = 0;
 		}
-
+		return null;
 	}
 
 	private ISearchQuery createSearchQuery() {