KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > editor > Finder


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.editor;
21
22 /**
23 * Finders are used to find some information in document without
24 * creating copy of the data. They are used as arguments for
25 * <CODE>DocCache.find()</CODE>. During the find operation
26 * the <CODE>find()</CODE> method of the finder is called
27 * with some buffer of character data and some additional information.
28 * There are two possible search directions and therefore there
29 * are two finder types: Forward Finders (FwdFinder)
30 * and Backward Finders (BwdFinder)
31 *
32 * @author Miloslav Metelka
33 * @version 1.00
34 */
35
36 public interface Finder {
37
38     /** Reset method is used to initialize finder.
39     * It is called once at the begining of find. To be most effective
40     * <CODE>reset()</CODE> is called after both <CODE>setForward()</CODE>
41     * and <CODE>setLimitPos()</CODE> had been called.
42     */
43     public void reset();
44
45     /** This is the most important function in finder. It can be called several
46     * times if the whole search area doesn't fit in the cache buffer.
47     * Usual forward search should look like this: <CODE>
48     * int offset = reqPos - bufferStartPos;
49     * while (offset &lt; offset2) {
50     * if (buffer[offset]-meets-condition) {
51     * set-found-flag
52     * return offset + bufferStartPos;
53     * }
54     * offset++;
55     * }
56     * return offset + bufferStartPos;</CODE>
57     * Bakward search follows: <CODE>
58     * int offset = reqPos - bufferStartPos
59     * while (offset &gt;= offset1) {
60     * if (buffer[offset]-meets-condition) {
61     * set-found-flag
62     * return offset + bufferStartPos;
63     * }
64     * offset--;
65     * }
66     * return offset + bufferStartPos;</CODE>
67     * Caution! Nothing can be written to the data comming in buffer to
68     * <CODE>find()</CODE> method because of performance reasons
69     * these are primary document data, not a copy.
70     * Buffer is always guaranteed to have at least one char - it is
71     * char standing at reqPos. However there can be calls to <CODE>find()</CODE>
72     * when there will be only that one character, so <CODE>find()</CODE> must
73     * must be prepared for this.
74     * Unlike calling <CODE>DocCache.find()</CODE> the offset1 &lt; offset2 even
75     * for backward searches.
76     * @param bufferStartPos begining position of the buffer (not search area).
77     * @param buffer buffer with chars to be searched
78     * @param offset1 offset of begining of searchable area in buffer.
79     * No searching below this offset can be performed.
80     * @param offset2 offset of end of searchable area in buffer.
81     * No searching beyond this offset can be performed.
82     * @param reqPos required position. Initially it is the begining
83     * search position requested by caller. In subsequent calls
84     * it is the same value as returned from previous call
85     * to <CODE>find()</CODE> method.
86     * @param limitPos is filled with position beyond which search cannot go.
87     * (i.e. forward: pos &lt; limitPos and backward: pos &gt;= limitPos)
88     * Some finders i.e. finder that tries to find some word with
89     * whole-words-only flag turned on can benefit
90     * from this information. If the searched word is at the very end of
91     * the document the finder wouldn't normally find it as it would request
92     * the next buffer even when the whole word was matched because the finder
93     * needs to find white space to know the word ended there. However this
94     * would be beyond the search area so EOT exception would be raised.
95     * To correctly manage this situation finder must care for limitPos.
96     * When it sees the word and knows this is the last text in document
97     * it signals that it found the word.
98     * @return in case the string was found, <CODE>find()</CODE>
99     * method returns the position (not offset) where the string starts
100     * (and must also set some flag resulting to that <CODE>isFound()</CODE>
101     * method will return true).
102     * If the string was not yet found, the function should return
103     * position (not offset) where the next search should continue. If this
104     * position is greater or equal than limit position
105     * (lower than limit position for backward search),
106     * searching will stop resulting in -1 as returned position.
107     * The position returned will be passed as <CODE>reqPos</CODE> in next
108     * call to <CODE>find()</CODE> method.
109     */
110     public int find(int bufferStartPos, char buffer[], int offset1,
111                     int offset2, int reqPos, int limitPos);
112
113     /** Using this function caller determines if finder found
114     * desired string. The returned position of <CODE>find</CODE> method
115     * gives the position where the string occurs.
116     */
117     public boolean isFound();
118
119 }
120
Popular Tags