KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > lexer > TokenValidator


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-2007 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.spi.lexer;
21
22 import org.netbeans.api.lexer.Token;
23 import org.netbeans.api.lexer.TokenId;
24
25 /**
26  * Token validator checks whether an existing token was affected
27  * by just performed input source modification so that it needs to be relexed.
28  * <br/>
29  * If the modification was limited to a single non-flyweight token and the token validator
30  * exists for a particular token id then the token validation is attempted.
31  * <br/>
32  * Token validator can refuse validation by returning null from its only method
33  * if the modification affects the token or if the validation is unsure.
34  *
35  * <p>
36  * Token validation is part of fine-tuning of the lexing
37  * and should be considered for all tokens that may have significant length
38  * such as whitespace or comments.
39  * <br/>
40  * The advantage of validation is that compared to lexing
41  * it typically only explores the modified characters and few adjacent characters.
42  *
43  * @author Miloslav Metelka
44  * @version 1.00
45  */
46
47 public interface TokenValidator<T extends TokenId> {
48     
49     /**
50      * This method is invoked in mutable environments prior lexer invocation
51      * to check whether token in which the text modification occurred
52      * was only slightly modified by the performed modification and the lexer's
53      * invocation is not necessary.
54      * <br/>
55      * Typically the token can be validated by returning the token with the same
56      * token id (just with different length that can be determined
57      * by <code>tokenText.length()</code>).
58      * <br/>
59      * But the validator can also return a token with different token id
60      * (e.g. the identifier can become a keyword after the modification).
61      *
62      * @param token non-null token affected by the modification. The token's text
63      * is undefined and must not be retrieved from the token at this time.
64      * @param factory non-null for producing of the new token to be returned.
65      * @param tokenText non-null text of the token already affected by the modification.
66      * @param modRelOffset &gt;0 offset of the text removal/insertion inside the token.
67      * @param insertedLength &gt;0 length of the inserted text.
68      * @return a new token instance produced by the token factory.
69      * <br/>
70      * Null should be returned if the token must be relexed or if the validator
71      * is unsure whether it's able to resolve the situation properly.
72      */
73     Token<T> validateToken(Token<T> token,
74     TokenFactory<T> factory,
75     CharSequence JavaDoc tokenText, int modRelOffset,
76     int removedLength, CharSequence JavaDoc removedText,
77     int insertedLength, CharSequence JavaDoc insertedText);
78
79 }
80
Popular Tags