SearchMatch


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  package org.eclipse.jdt.core.search;
12  
13  import org.eclipse.core.resources.IResource;
14  import org.eclipse.jdt.core.IJavaElement;
15  import org.eclipse.jdt.internal.core.JavaElement;
16  
17  /**
18   * A search match represents the result of a search query.
19   * 
20   * Search matches may be accurate (<code>A_ACCURATE</code>) or they might be
21   * merely potential matches (<code>A_INACCURATE</code>). The latter occurs when
22   * a compile-time problem prevents the search engine from completely resolving
23   * the match.
24   * <p>
25   * This class is intended to be instantiated and subclassed by clients.
26   * </p>
27   * 
28   * @see SearchEngine#search(SearchPattern, SearchParticipant[], IJavaSearchScope, SearchRequestor, org.eclipse.core.runtime.IProgressMonitor)
29   * @since 3.0
30   */
31  public class SearchMatch {
32      
33      /**
34       * The search result corresponds an exact match of the search pattern.
35       * 
36       * @see #getAccuracy()
37       */
38      public static final int A_ACCURATE = 0;
39  
40      /**
41       * The search result is potentially a match for the search pattern,
42       * but the search engine is unable to fully check it (for example, because
43       * there are errors in the code or the classpath are not correctly set).
44       * 
45       * @see #getAccuracy()
46       */
47      public static final int A_INACCURATE = 1;
48  
49      private Object   element;
50      private int length;
51      private int offset;
52  
53      private int accuracy;
54      private SearchParticipant participant;  
55      private IResource resource;
56  
57      private boolean insideDocComment = false;
58      
59      // store the rule used while reporting the match
60      private final static int ALL_GENERIC_FLAVORS = SearchPattern.R_FULL_MATCH |
61                                  SearchPattern.R_EQUIVALENT_MATCH |
62                                  SearchPattern.R_ERASURE_MATCH;
63      private int rule = ALL_GENERIC_FLAVORS;
64      
65      // store other necessary information
66      private boolean raw = false;
67      private boolean implicit = false;
68  
69      /**
70       * Creates a new search match.
71       * <p>
72       * Note that <code>isInsideDocComment()</code> defaults to false.
73       * </p>
74       * 
75       * @param element the element that encloses or corresponds to the match,
76       * or <code>null</code> if none
77       * @param accuracy one of {@link #A_ACCURATE} or {@link #A_INACCURATE}
78       * @param offset the offset the match starts at, or -1 if unknown
79       * @param length the length of the match, or -1 if unknown
80       * @param participant the search participant that created the match
81       * @param resource the resource of the element, or <code>null</code> if none
82       */
83      public SearchMatch(
84              IJavaElement element,
85              int accuracy,
86              int offset,  
87              int length,
88              SearchParticipant participant, 
89              IResource resource) {
90          this.element = element;
91          this.offset = offset;
92          this.length = length;
93          this.accuracy = accuracy & A_INACCURATE;
94          if (accuracy > A_INACCURATE) {
95              int genericFlavors = accuracy & ALL_GENERIC_FLAVORS;
96              if (genericFlavors > 0) {
97                  this.rule &= ~ALL_GENERIC_FLAVORS; // reset generic flavors
98              }
99              this.rule |= accuracy & ~A_INACCURATE; // accuracy may have also some rule information
100         }
101         this.participant = participant;
102         this.resource = resource;
103     }
104 
105     /**
106      * Returns the accuracy of this search match.
107      * 
108      * @return one of {@link #A_ACCURATE} or {@link #A_INACCURATE}
109      */
110     public final int getAccuracy() {
111         return this.accuracy;
112     }
113 
114     /**
115      * Returns the element of this search match.
116      * In case of a reference match, this is the inner-most enclosing element of the reference.
117      * In case of a declaration match, this is the declaration.
118      * 
119      * @return the element of the search match, or <code>null</code> if none
120      */
121     public final Object   getElement() {
122         return this.element;
123     }
124 
125     /**
126      * Returns the length of this search match.
127      * 
128      * @return the length of this search match, or -1 if unknown
129      */
130     public final int getLength() {
131         return this.length;
132     }
133     
134     /**
135      * Returns the offset of this search match.
136      * 
137      * @return the offset of this search match, or -1 if unknown
138      */
139     public final int getOffset() {
140         return this.offset;
141     }
142     
143     /**
144      * Returns the search participant which issued this search match.
145      * 
146      * @return the participant which issued this search match
147      */
148     public final SearchParticipant getParticipant() {
149         return this.participant;
150     }
151     
152     /**
153      * Returns the resource containing this search match.
154      * 
155      * @return the resource of the match, or <code>null</code> if none
156      */
157     public final IResource getResource() {
158         return this.resource;
159     }
160 
161     /**
162      * Returns the rule used while creating the match.
163      * 
164      * @return one of {@link SearchPattern#R_FULL_MATCH}, {@link SearchPattern#R_EQUIVALENT_MATCH}
165      *  or {@link SearchPattern#R_ERASURE_MATCH}
166      * @since 3.1
167      */
168     public final int getRule() {
169         return this.rule;
170     }
171 
172     /**
173      * Returns whether match element is compatible with searched pattern or not.
174      * Note that equivalent matches are also erasure ones.
175      * 
176      * @return <code>true</code> if match element is compatible 
177      *              <code>false</code> otherwise
178      * @since 3.1
179      */
180     public final boolean isEquivalent() {
181         return isErasure() && (this.rule & SearchPattern.R_EQUIVALENT_MATCH) != 0;
182     }
183 
184     /**
185      * Returns whether match element only has same erasure than searched pattern or not.
186      * Note that this is always true for both generic and non-generic element as soon
187      * as the accuracy is accurate.
188      * 
189      * @return <code>true</code> if match element has same erasure
190      *              <code>false</code> otherwise
191      * @since 3.1
192      */
193     public final boolean isErasure() {
194         return (this.rule & SearchPattern.R_ERASURE_MATCH) != 0;
195     }
196 
197     /**
198      * Returns whether element matches exactly searched pattern or not.
199      * Note that exact matches are also erasure and equivalent ones.
200      * 
201      * @return <code>true</code> if match is exact
202      *              <code>false</code> otherwise
203      * @since 3.1
204      */
205     public final boolean isExact() {
206         return isEquivalent() && (this.rule & SearchPattern.R_FULL_MATCH) != 0;
207     }
208 
209     /**
210      * Returns whether the associated element is implicit or not.
211      * 
212      * Note that this piece of information is currently only implemented
213      * for implicit member pair value in annotation.
214      * 
215      * @return <code>true</code> if this match is associated to an implicit
216      * element and <code>false</code> otherwise
217      * @since 3.1
218      */
219     public final boolean isImplicit() {
220         return this.implicit;
221     }
222 
223     /**
224      * Returns whether the associated element is a raw type/method or not.
225      * 
226      * @return <code>true</code> if this match is associated to a raw
227      * type or method and <code>false</code> otherwise
228      * @since 3.1
229      */
230     public final boolean isRaw() {
231         return this.raw;
232     }
233 
234     /**
235      * Returns whether this search match is inside a doc comment of a Java
236      * source file.
237      * 
238      * @return <code>true</code> if this search match is inside a doc
239      * comment, and <code>false</code> otherwise
240      */
241     public final boolean isInsideDocComment() {
242         // default is outside a doc comment
243         return this.insideDocComment;
244     }
245 
246     /**
247      * Sets the accuracy of this match.
248      * 
249      * @param accuracy one of {@link #A_ACCURATE} or {@link #A_INACCURATE}
250      */
251     public final void setAccuracy (int accuracy) {
252         this.accuracy = accuracy;
253     }
254 
255     /**
256      * Sets the element of this search match.
257      * 
258      * @param element the element that encloses or corresponds to the match,
259      * or <code>null</code> if none
260      */
261     public final void setElement (Object   element) {
262         this.element = element;
263     }
264 
265     /**
266      * Sets whether this search match is inside a doc comment of a Java
267      * source file.
268      * 
269      * @param insideDoc <code>true</code> if this search match is inside a doc
270      * comment, and <code>false</code> otherwise
271      */
272     public final void setInsideDocComment (boolean insideDoc) {
273         this.insideDocComment = insideDoc;
274     }
275 
276     /**
277      * Sets whether the associated element is implicit or not.
278      * Typically, this is the case when match is on an implicit constructor
279      * or an implicit member pair value in annotation.
280      * 
281      * @param implicit <code>true</code> if this match is associated to an implicit
282      * element and <code>false</code> otherwise
283      * @since 3.1
284      */
285     public final void setImplicit(boolean implicit) {
286         this.implicit = implicit;
287     }
288 
289     /**
290      * Sets the length of this search match.
291      * 
292      * @param length the length of the match, or -1 if unknown
293      */
294     public final void setLength(int length) {
295         this.length = length;
296     }
297     
298     /**
299      * Sets the offset of this search match.
300      * 
301      * @param offset the offset the match starts at, or -1 if unknown
302      */
303     public final void setOffset(int offset) {
304         this.offset = offset;
305     }
306 
307     /**
308      * Sets the participant of this match.
309      * 
310      * @param participant the search participant that created this match
311      */
312     public final void setParticipant (SearchParticipant participant) {
313         this.participant = participant;
314     }
315 
316     /**
317      * Sets the resource of this match.
318      * 
319      * @param resource the resource of the match, or <code>null</code> if none
320      */
321     public final void setResource (IResource resource) {
322         this.resource = resource;
323     }
324 
325     /**
326      * Set the rule used while reporting the match.
327      * 
328      * @param rule one of {@link SearchPattern#R_FULL_MATCH}, {@link SearchPattern#R_EQUIVALENT_MATCH}
329      *  or {@link SearchPattern#R_ERASURE_MATCH}
330      * @since 3.1
331      */
332     public final void setRule(int rule) {
333         this.rule = rule;
334     }
335 
336     /**
337      * Set whether the associated element is a raw type/method or not.
338      * 
339      * @param raw <code>true</code> if this search match is associated to a raw
340      * type or method and <code>false</code> otherwise
341      * @since 3.1
342      */
343     public final void setRaw(boolean raw) {
344         this.raw = raw;
345     }
346 
347     /* (non-javadoc)
348      * @see java.lang.Object#toString()
349      */
350     public String   toString() {
351         StringBuffer   buffer = new StringBuffer  ();
352         buffer.append("Search match"); //$NON-NLS-1$
353         buffer.append("\n  accuracy="); //$NON-NLS-1$
354         buffer.append(this.accuracy == A_ACCURATE ? "ACCURATE" : "INACCURATE"); //$NON-NLS-1$ //$NON-NLS-2$
355         buffer.append("\n  rule="); //$NON-NLS-1$
356         if ((this.rule & SearchPattern.R_FULL_MATCH) != 0) {
357             buffer.append("EXACT"); //$NON-NLS-1$
358         } else if ((this.rule & SearchPattern.R_EQUIVALENT_MATCH) != 0) {
359             buffer.append("EQUIVALENT"); //$NON-NLS-1$
360         } else if ((this.rule & SearchPattern.R_ERASURE_MATCH) != 0) {
361             buffer.append("ERASURE"); //$NON-NLS-1$
362         }
363         buffer.append("\n  raw="); //$NON-NLS-1$
364         buffer.append(this.raw);
365         buffer.append("\n  offset="); //$NON-NLS-1$
366         buffer.append(this.offset);
367         buffer.append("\n  length="); //$NON-NLS-1$
368         buffer.append(this.length);
369         if (this.element != null) {
370             buffer.append("\n  element="); //$NON-NLS-1$
371             buffer.append(((JavaElement)getElement()).toStringWithAncestors());
372         }
373         buffer.append("\n"); //$NON-NLS-1$
374         return buffer.toString();
375     }
376 }
377
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags