001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.netbeans.modules.gsf.api;
042:
043: import java.net.URL;
044:
045: import java.util.ArrayList;
046: import java.util.Collections;
047: import java.util.List;
048: import javax.swing.text.Document;
049:
050: import org.netbeans.modules.gsf.api.annotations.CheckForNull;
051: import org.netbeans.modules.gsf.api.annotations.NonNull;
052: import org.openide.filesystems.FileObject;
053:
054: /**
055: *
056: * @author Tor Norbye
057: */
058: public interface DeclarationFinder {
059: /**
060: * Find the declaration for the program element that is under the caretOffset
061: * Return a Set of regions that should be renamed if the element under the caret offset is
062: * renamed.
063: *
064: * Return {@link Declaration.NONE} if the declaration can not be found, otherwise return
065: * a valid DeclarationLocation.
066: */
067: @NonNull
068: DeclarationLocation findDeclaration(@NonNull
069: CompilationInfo info, int caretOffset);
070:
071: /**
072: * Check the caret offset in the document and determine if it is over a span
073: * of text that should be hyperlinkable ("Go To Declaration" - in other words,
074: * locate the reference and return it. When the user drags the mouse with a modifier
075: * key held this will be hyperlinked, and so on.
076: * <p>
077: * Remember that when looking up tokens in the token hierarchy, you will get the token
078: * to the right of the caret offset, so check for these conditions
079: * {@code (sequence.move(offset); sequence.offset() == offset)} and check both
080: * sides such that placing the caret between two tokens will match either side.
081: *
082: * @return {@link OffsetRange.NONE} if the caret is not over a valid reference span,
083: * otherwise return the character range for the given hyperlink tokens
084: */
085: @NonNull
086: public OffsetRange getReferenceSpan(@NonNull
087: Document doc, int caretOffset);
088:
089: /**
090: * Holder object for return values from the DeclarationFinder#findDeclaration method.
091: * The constant NONE object should be returned when finding a declaration failed.
092: */
093: public final class DeclarationLocation {
094: /** DeclarationLocation representing no match or failure to find declaration */
095: public static final DeclarationLocation NONE = new DeclarationLocation(
096: null, -1);
097: private final FileObject fileObject;
098: private final int offset;
099: private final URL url;
100: private List<AlternativeLocation> alternatives;
101: /** Associated element, if any */
102: private ElementHandle element;
103: private String invalidMessage;
104:
105: public DeclarationLocation(@NonNull
106: final FileObject fileObject, final int offset) {
107: this .fileObject = fileObject;
108: this .offset = offset;
109: this .url = null;
110: }
111:
112: public DeclarationLocation(@NonNull
113: final FileObject fileObject, final int offset, @NonNull
114: ElementHandle element) {
115: this (fileObject, offset);
116: this .element = element;
117: }
118:
119: public DeclarationLocation(@NonNull
120: final URL url) {
121: this .url = url;
122: this .fileObject = null;
123: this .offset = -1;
124: }
125:
126: /** Mark this declaration location as an "invalid" location (for example,
127: * in Ruby or JavaScript, a builtin function that has no corresponding source.
128: * @param invalidMessage A message which will be displayed to the user on attempts to
129: * go to this declaration location.
130: */
131: public void setInvalidMessage(String invalidMessage) {
132: this .invalidMessage = invalidMessage;
133: }
134:
135: public void addAlternative(@NonNull
136: AlternativeLocation location) {
137: if (alternatives == null) {
138: alternatives = new ArrayList<AlternativeLocation>();
139: }
140:
141: alternatives.add(location);
142: }
143:
144: @CheckForNull
145: public List<AlternativeLocation> getAlternativeLocations() {
146: if (alternatives != null) {
147: return alternatives;
148: } else {
149: return Collections.emptyList();
150: }
151: }
152:
153: @CheckForNull
154: public URL getUrl() {
155: return url;
156: }
157:
158: @CheckForNull
159: public FileObject getFileObject() {
160: return fileObject;
161: }
162:
163: public int getOffset() {
164: return offset;
165: }
166:
167: @CheckForNull
168: public ElementHandle getElement() {
169: return element;
170: }
171:
172: @CheckForNull
173: public String getInvalidMessage() {
174: return invalidMessage;
175: }
176:
177: @Override
178: public String toString() {
179: if (this == NONE) {
180: return "NONE";
181: }
182:
183: if (url != null) {
184: return url.toExternalForm();
185: }
186:
187: return fileObject.getNameExt() + ":" + offset;
188: }
189: }
190:
191: public interface AlternativeLocation extends
192: Comparable<AlternativeLocation> {
193: ElementHandle getElement();
194:
195: String getDisplayHtml(HtmlFormatter formatter);
196:
197: DeclarationLocation getLocation();
198: }
199: }
|