KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > gsf > DeclarationFinder


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 package org.netbeans.api.gsf;
20
21 import java.net.URL JavaDoc;
22
23 import javax.swing.text.Document JavaDoc;
24
25 import org.netbeans.api.gsf.CompilationInfo;
26 import org.netbeans.api.gsf.OffsetRange;
27 import org.netbeans.api.gsf.annotations.CheckForNull;
28 import org.netbeans.api.gsf.annotations.NonNull;
29 import org.netbeans.api.lexer.Token;
30 import org.netbeans.api.lexer.TokenId;
31 import org.openide.filesystems.FileObject;
32
33
34 /**
35  *
36  * @author Tor Norbye
37  */
38 public interface DeclarationFinder {
39     /**
40      * Find the declaration for the program element that is under the caretOffset
41      * Return a Set of regions that should be renamed if the element under the caret offset is
42      * renamed.
43      *
44      * Return {@link Declaration.NONE} if the declaration can not be found, otherwise return
45      * a valid DeclarationLocation.
46      */
47     @NonNull
48     DeclarationLocation findDeclaration(@NonNull
49     CompilationInfo info, int caretOffset);
50
51     /**
52      * Check the caret offset in the document and determine if it is over a span
53      * of text that should be hyperlinkable ("Go To Declaration" - in other words,
54      * locate the reference and return it. When the user drags the mouse with a modifier
55      * key held this will be hyperlinked, and so on.
56      * <p>
57      * Remember that when looking up tokens in the token hiearchy, you will get the token
58      * to the right of the caret offset, so check for these conditions
59      * {@code (sequence.move(offset); sequence.offset() == offset)} and check both
60      * sides such that placing the caret between two tokens will match either side.
61      *
62      * @return {@link OffsetRange.NONE} if the caret is not over a valid reference span,
63      * otherwise return the character range for the given hyperlink tokens
64      */
65     @NonNull
66     public OffsetRange getReferenceSpan(@NonNull
67     Document JavaDoc doc, int caretOffset);
68
69     /**
70      * Holder object for return values from the DeclarationFinder#findDeclaration method.
71      * The constant NONE object should be returned when finding a declaration failed.
72      */
73     public final class DeclarationLocation {
74         /** DeclarationLocation representing no match or failure to find declaration */
75         public static final DeclarationLocation NONE = new DeclarationLocation(null, -1);
76         private final FileObject fileObject;
77         private final int offset;
78         private final URL JavaDoc url;
79
80         public DeclarationLocation(final FileObject fileObject, final int offset) {
81             this.fileObject = fileObject;
82             this.offset = offset;
83             this.url = null;
84         }
85
86         public DeclarationLocation(final URL JavaDoc url) {
87             this.url = url;
88             this.fileObject = null;
89             this.offset = -1;
90         }
91
92         public URL JavaDoc getUrl() {
93             return url;
94         }
95
96         public FileObject getFileObject() {
97             return fileObject;
98         }
99
100         public int getOffset() {
101             return offset;
102         }
103
104         public String JavaDoc toString() {
105             if (this == NONE) {
106                 return "NONE";
107             }
108
109             if (url != null) {
110                 return url.toExternalForm();
111             }
112
113             return fileObject.getNameExt() + ":" + offset;
114         }
115     }
116 }
117
Popular Tags