KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > search > core > text > TextSearchRequestor


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11
12 package org.eclipse.search.core.text;
13
14 import org.eclipse.core.runtime.CoreException;
15
16 import org.eclipse.core.resources.IFile;
17
18 /**
19  * Collects the results from a search engine query.
20  * Clients implement a subclass to pass to {@link TextSearchEngine#search(TextSearchScope,
21  * TextSearchRequestor, java.util.regex.Pattern, org.eclipse.core.runtime.IProgressMonitor)}
22  * and implement the {@link #acceptPatternMatch(TextSearchMatchAccess)}
23  * method, and possibly override other life cycle methods.
24  * <p>
25  * The search engine calls {@link #beginReporting()} when a search starts,
26  * then calls {@link #acceptFile(IFile)} for a file visited.
27  * If {@link #acceptFile(IFile)} returns <code>true</code> {@link #reportBinaryFile(IFile)} is
28  * called if the file could be binary followed by
29  * {@link #acceptPatternMatch(TextSearchMatchAccess)} for each pattern match found
30  * in this file. The end of the search is signaled with a call to {@link #endReporting()}.
31  * Note that {@link #acceptFile(IFile)} is called for all files in the search scope,
32  * even if no match can be found.
33  * </p>
34  * <p>
35  * The order of the search results is unspecified and may vary from request to request;
36  * when displaying results, clients should not rely on the order but should instead arrange the results
37  * in an order that would be more meaningful to the user.
38  * </p>
39  *
40  * @see TextSearchEngine
41  * @since 3.2
42  */
43 public abstract class TextSearchRequestor {
44     
45     /**
46      * Notification sent before starting the search action.
47      * Typically, this would tell a search requestor to clear previously
48      * recorded search results.
49      * <p>
50      * The default implementation of this method does nothing. Subclasses
51      * may override.
52      * </p>
53      */
54     public void beginReporting() {
55         // do nothing
56 }
57
58     /**
59      * Notification sent after having completed the search action.
60      * Typically, this would tell a search requestor collector that no more
61      * results will be forthcoming in this search.
62      * <p>
63      * The default implementation of this method does nothing. Subclasses
64      * may override.
65      * </p>
66      */
67     public void endReporting() {
68         // do nothing
69 }
70     
71     /**
72      * Notification sent before search starts in the given file. This method is called for all files that are contained
73      * in the search scope.
74      * Implementors can decide if the file content should be searched for search matches or not.
75      * <p>
76      * The default behaviour is to search the file for matches.
77      * </p>
78      * @param file the file resource to be searched.
79      * @return If false, no pattern matches will be reported for the content of this file.
80      * @throws CoreException implementors can throw a {@link CoreException} if accessing the resource fails or another
81      * problem prevented the processing of the search match.
82      */
83     public boolean acceptFile(IFile file) throws CoreException {
84         return true;
85     }
86     
87     /**
88      * Notification sent that a file might contain binary context.
89      * It is the choice of the search engine to report binary files and it is the heuristic of the search engine to decide
90      * that a file could be binary.
91      * Implementors can decide if the file content should be searched for search matches or not.
92      * <p>
93      * This call is sent after calls {link {@link #acceptFile(IFile)} that return <code>true</code> and before any matches
94      * reported for this file with {@link #acceptPatternMatch(TextSearchMatchAccess)}.
95      * </p>
96      * <p>
97      * The default behaviour is to skip binary files
98      * </p>
99      *
100      * @param file the file that might be binary
101      * @return If false, no pattern matches will be reported for the content of this file.
102      */
103     public boolean reportBinaryFile(IFile file) {
104         return false;
105     }
106     
107     /**
108      * Accepts the given search match and decides if the search should continue for this file.
109      *
110      * @param matchAccess gives access to information of the match found. The matchAccess is not a value
111      * object. Its value might change after this method is finished, and the element might be reused.
112      * @return If false is returned no further matches will be reported for this file.
113      * @throws CoreException implementors can throw a {@link CoreException} if accessing the resource fails or another
114      * problem prevented the processing of the search match.
115      */
116     public boolean acceptPatternMatch(TextSearchMatchAccess matchAccess) throws CoreException {
117         return true;
118     }
119
120 }
121
Popular Tags