1 /*******************************************************************************
2 * Copyright (c) 2004 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.runtime.IProgressMonitor;
14 import net.sourceforge.phpdt.core.compiler.CharOperation;
17 * Completion proposal.
19 * In typical usage, the user working in a Java code editor issues
20 * a code assist command. This command results in a call to
21 * <code>ICodeAssist.codeComplete(position, completionRequestor)</code>
22 * passing the current position in the source code. The code assist
23 * engine analyzes the code in the buffer, determines what kind of
24 * Java language construct is at that position, and proposes ways
25 * to complete that construct. These proposals are instances of
26 * subclasses of <code>CompletionProposal</code>. These proposals,
27 * perhaps after sorting and filtering, are presented to the user
31 * The proposal is as follows: insert
32 * the {@linkplain #getCompletion() completion string} into the
33 * source file buffer, replacing the characters between
34 * {@linkplain #getReplaceStart() the start}
35 * and {@linkplain #getReplaceEnd() end}. The string
36 * can be arbitrary; for example, it might include not only the
37 * name of a method but a set of parentheses. Moreover, the source
38 * range may include source positions before or after the source
39 * position where <code>ICodeAssist.codeComplete</code> was invoked.
40 * The rest of the information associated with the proposal is
41 * to provide context that may help a user to choose from among
42 * competing proposals.
45 * The completion engine creates instances of this class; it is not
46 * intended to be used by other clients.
49 * @see ICodeAssist#codeComplete(int, CompletionRequestor)
52 public final class CompletionProposal {
55 * Completion is a declaration of an anonymous class.
56 * This kind of completion might occur in a context like
57 * <code>"new List^;"</code> and complete it to
58 * <code>"new List() {}"</code>.
60 * The following additional context information is available
61 * for this kind of completion proposal at little extra cost:
63 * <li>{@link #getDeclarationSignature()} -
64 * the type signature of the type being implemented or subclassed
67 * <li>{@link #getSignature()} -
68 * the method signature of the constructor that is referenced
70 * <li>{@link #getFlags()} -
71 * the modifiers flags of the constructor that is referenced
78 public static final int ANONYMOUS_CLASS_DECLARATION = 1;
81 * Completion is a reference to a field.
82 * This kind of completion might occur in a context like
83 * <code>"this.ref^ = 0;"</code> and complete it to
84 * <code>"this.refcount = 0;"</code>.
86 * The following additional context information is available
87 * for this kind of completion proposal at little extra cost:
89 * <li>{@link #getDeclarationSignature()} -
90 * the type signature of the type that declares the field that is referenced
92 * <li>{@link #getFlags()} -
93 * the modifiers flags (including ACC_ENUM) of the field that is referenced
95 * <li>{@link #getName()} -
96 * the simple name of the field that is referenced
98 * <li>{@link #getSignature()} -
99 * the type signature of the field's type (as opposed to the
100 * signature of the type in which the referenced field
108 public static final int FIELD_REF = 2;
111 * Completion is a keyword.
112 * This kind of completion might occur in a context like
113 * <code>"public cl^ Foo {}"</code> and complete it to
114 * <code>"public class Foo {}"</code>.
116 * The following additional context information is available
117 * for this kind of completion proposal at little extra cost:
119 * <li>{@link #getName()} -
122 * <li>{@link #getFlags()} -
123 * the corresponding modifier flags if the keyword is a modifier
130 public static final int KEYWORD = 3;
133 * Completion is a reference to a label.
134 * This kind of completion might occur in a context like
135 * <code>"break lo^;"</code> and complete it to
136 * <code>"break loop;"</code>.
138 * The following additional context information is available
139 * for this kind of completion proposal at little extra cost:
141 * <li>{@link #getName()} -
142 * the simple name of the label that is referenced
149 public static final int LABEL_REF = 4;
152 * Completion is a reference to a local variable.
153 * This kind of completion might occur in a context like
154 * <code>"ke^ = 4;"</code> and complete it to
155 * <code>"keys = 4;"</code>.
157 * The following additional context information is available
158 * for this kind of completion proposal at little extra cost:
160 * <li>{@link #getFlags()} -
161 * the modifiers flags of the local variable that is referenced
163 * <li>{@link #getName()} -
164 * the simple name of the local variable that is referenced
166 * <li>{@link #getSignature()} -
167 * the type signature of the local variable's type
174 public static final int LOCAL_VARIABLE_REF = 5;
177 * Completion is a reference to a method.
178 * This kind of completion might occur in a context like
179 * <code>"System.out.pr^();"</code> and complete it to
180 * <code>""System.out.println();"</code>.
182 * The following additional context information is available
183 * for this kind of completion proposal at little extra cost:
185 * <li>{@link #getDeclarationSignature()} -
186 * the type signature of the type that declares the method that is referenced
188 * <li>{@link #getFlags()} -
189 * the modifiers flags of the method that is referenced
191 * <li>{@link #getName()} -
192 * the simple name of the method that is referenced
194 * <li>{@link #getSignature()} -
195 * the method signature of the method that is referenced
202 public static final int METHOD_REF = 6;
205 * Completion is a declaration of a method.
206 * This kind of completion might occur in a context like
207 * <code>"new List() {si^};"</code> and complete it to
208 * <code>"new List() {public int size() {} };"</code>.
210 * The following additional context information is available
211 * for this kind of completion proposal at little extra cost:
213 * <li>{@link #getDeclarationSignature()} -
214 * the type signature of the type that declares the
215 * method that is being overridden or implemented
217 * <li>{@link #getName()} -
218 * the simple name of the method that is being overridden
221 * <li>{@link #getSignature()} -
222 * the method signature of the method that is being
223 * overridden or implemented
225 * <li>{@link #getFlags()} -
226 * the modifiers flags of the method that is being
227 * overridden or implemented
234 public static final int METHOD_DECLARATION = 7;
237 * Completion is a reference to a package.
238 * This kind of completion might occur in a context like
239 * <code>"import java.u^.*;"</code> and complete it to
240 * <code>"import java.util.*;"</code>.
242 * The following additional context information is available
243 * for this kind of completion proposal at little extra cost:
245 * <li>{@link #getDeclarationSignature()} -
246 * the dot-based package signature of the package that is referenced
253 public static final int PACKAGE_REF = 8;
256 * Completion is a reference to a type. Any kind of type
257 * is allowed, including primitive types, reference types,
258 * array types, parameterized types, and type variables.
259 * This kind of completion might occur in a context like
260 * <code>"public static Str^ key;"</code> and complete it to
261 * <code>"public static String key;"</code>.
263 * The following additional context information is available
264 * for this kind of completion proposal at little extra cost:
266 * <li>{@link #getDeclarationSignature()} -
267 * the dot-based package signature of the package that contains
268 * the type that is referenced
270 * <li>{@link #getSignature()} -
271 * the type signature of the type that is referenced
273 * <li>{@link #getFlags()} -
274 * the modifiers flags (including Flags.AccInterface, AccEnum,
275 * and AccAnnotation) of the type that is referenced
282 public static final int TYPE_REF = 9;
285 * Completion is a declaration of a variable (locals, parameters,
288 * The following additional context information is available
289 * for this kind of completion proposal at little extra cost:
291 * <li>{@link #getName()} -
292 * the simple name of the variable being declared
294 * <li>{@link #getSignature()} -
295 * the type signature of the type of the variable
298 * <li>{@link #getFlags()} -
299 * the modifiers flags of the variable being declared
305 public static final int VARIABLE_DECLARATION = 10;
308 * Kind of completion request.
310 private int completionKind;
313 * Offset in original buffer where ICodeAssist.codeComplete() was
316 private int completionLocation;
319 * Start position (inclusive) of source range in original buffer
320 * containing the relevant token
321 * defaults to empty subrange at [0,0).
323 private int tokenStart = 0;
326 * End position (exclusive) of source range in original buffer
327 * containing the relevant token;
328 * defaults to empty subrange at [0,0).
330 private int tokenEnd = 0;
333 * Completion string; defaults to empty string.
335 private char[] completion = CharOperation.NO_CHAR;
338 * Start position (inclusive) of source range in original buffer
339 * to be replaced by completion string;
340 * defaults to empty subrange at [0,0).
342 private int replaceStart = 0;
345 * End position (exclusive) of source range in original buffer
346 * to be replaced by completion string;
347 * defaults to empty subrange at [0,0).
349 private int replaceEnd = 0;
352 * Relevance rating; positive; higher means better;
353 * defaults to minimum rating.
355 private int relevance = 1;
358 * Signature of the relevant package or type declaration
359 * in the context, or <code>null</code> if none.
362 private char[] declarationSignature = null;
365 * Simple name of the method, field,
366 * member, or variable relevant in the context, or
367 * <code>null</code> if none.
370 private char[] name = null;
373 * Signature of the method, field type, member type,
374 * relevant in the context, or <code>null</code> if none.
377 private char[] signature = null;
380 * Modifier flags relevant in the context, or
381 * <code>Flags.AccDefault</code> if none.
382 * Defaults to <code>Flags.AccDefault</code>.
384 private int flags = Flags.AccDefault;
387 * Parameter names (for method completions), or
388 * <code>null</code> if none. Lazily computed.
389 * Defaults to <code>null</code>.
391 private char[][] parameterNames = null;
394 * Indicates whether parameter names have been computed.
396 private boolean parameterNamesComputed = false;
399 * Creates a basic completion proposal. All instance
400 * field have plausible default values unless otherwise noted.
402 * Note that the constructors for this class are internal to the
403 * Java model implementation. Clients cannot directly create
404 * CompletionProposal objects.
407 * @param kind one of the kind constants declared on this class
408 * @param completionOffset original offset of code completion request
409 * @return a new completion proposal
411 public static CompletionProposal create(int kind, int completionOffset) {
412 return new CompletionProposal(kind, completionOffset);
416 * Creates a basic completion proposal. All instance
417 * field have plausible default values unless otherwise noted.
419 * Note that the constructors for this class are internal to the
420 * Java model implementation. Clients cannot directly create
421 * CompletionProposal objects.
424 * @param kind one of the kind constants declared on this class
425 * @param completionLocation original offset of code completion request
427 CompletionProposal(int kind, int completionLocation) {
428 if ((kind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION)
429 || (kind > CompletionProposal.VARIABLE_DECLARATION)) {
430 throw new IllegalArgumentException();
432 if (this.completion == null || completionLocation < 0) {
433 throw new IllegalArgumentException();
435 this.completionKind = kind;
436 this.completionLocation = completionLocation;
440 * Returns the kind of completion being proposed.
442 * The set of different kinds of completion proposals is
443 * expected to change over time. It is strongly recommended
444 * that clients do <b>not</b> assume that the kind is one of the
445 * ones they know about, and code defensively for the
446 * possibility of unexpected future growth.
449 * @return the kind; one of the kind constants
450 * declared on this class, or possibly a kind unknown
453 public int getKind() {
454 return this.completionKind;
458 * Returns the character index in the source file buffer
459 * where source completion was requested (the
460 * <code>offset</code>parameter to
461 * <code>ICodeAssist.codeComplete</code>.
463 * @return character index in source file buffer
464 * @see ICodeAssist#codeComplete(int,CompletionRequestor)
466 public int getCompletionLocation() {
467 return this.completionLocation;
471 * Returns the character index of the start of the
472 * subrange in the source file buffer containing the
473 * relevant token being completed. This
474 * token is either the identifier or Java language keyword
475 * under, or immediately preceding, the original request
476 * offset. If the original request offset is not within
477 * or immediately after an identifier or keyword, then the
478 * position returned is original request offset and the
479 * token range is empty.
481 * @return character index of token start position (inclusive)
483 public int getTokenStart() {
484 return this.tokenStart;
488 * Returns the character index of the end (exclusive) of the subrange
489 * in the source file buffer containing the
490 * relevant token. When there is no relevant token, the
492 * (<code>getEndToken() == getStartToken()</code>).
494 * @return character index of token end position (exclusive)
496 public int getTokenEnd() {
497 return this.tokenEnd;
501 * Sets the character indices of the subrange in the
502 * source file buffer containing the relevant token being
503 * completed. This token is either the identifier or
504 * Java language keyword under, or immediately preceding,
505 * the original request offset. If the original request
506 * offset is not within or immediately after an identifier
507 * or keyword, then the source range begins at original
508 * request offset and is empty.
510 * If not set, defaults to empty subrange at [0,0).
513 * @param startIndex character index of token start position (inclusive)
514 * @param endIndex character index of token end position (exclusive)
516 public void setTokenRange(int startIndex, int endIndex) {
517 if (startIndex < 0 || endIndex < startIndex) {
518 throw new IllegalArgumentException();
520 this.tokenStart = startIndex;
521 this.tokenEnd = endIndex;
525 * Returns the proposed sequence of characters to insert into the
526 * source file buffer, replacing the characters at the specified
527 * source range. The string can be arbitrary; for example, it might
528 * include not only the name of a method but a set of parentheses.
530 * The client must not modify the array returned.
533 * @return the completion string
535 public char[] getCompletion() {
536 return this.completion;
540 * Sets the proposed sequence of characters to insert into the
541 * source file buffer, replacing the characters at the specified
542 * source range. The string can be arbitrary; for example, it might
543 * include not only the name of a method but a set of parentheses.
545 * If not set, defaults to an empty character array.
548 * The completion engine creates instances of this class and sets
549 * its properties; this method is not intended to be used by other clients.
552 * @param completion the completion string
554 public void setCompletion(char[] completion) {
555 this.completion = completion;
559 * Returns the character index of the start of the
560 * subrange in the source file buffer to be replaced
561 * by the completion string. If the subrange is empty
562 * (<code>getReplaceEnd() == getReplaceStart()</code>),
563 * the completion string is to be inserted at this
566 * Note that while the token subrange is precisely
567 * specified, the replacement range is loosely
568 * constrained and may not bear any direct relation
569 * to the original request offset. For example, a
570 * it would be possible for a type completion to
571 * propose inserting an import declaration at the
572 * top of the compilation unit; or the completion
573 * might include trailing parentheses and
574 * punctuation for a method completion.
577 * @return replacement start position (inclusive)
579 public int getReplaceStart() {
580 return this.replaceStart;
584 * Returns the character index of the end of the
585 * subrange in the source file buffer to be replaced
586 * by the completion string. If the subrange is empty
587 * (<code>getReplaceEnd() == getReplaceStart()</code>),
588 * the completion string is to be inserted at this
591 * @return replacement end position (exclusive)
593 public int getReplaceEnd() {
594 return this.replaceEnd;
598 * Sets the character indices of the subrange in the
599 * source file buffer to be replaced by the completion
600 * string. If the subrange is empty
601 * (<code>startIndex == endIndex</code>),
602 * the completion string is to be inserted at this
605 * If not set, defaults to empty subrange at [0,0).
608 * The completion engine creates instances of this class and sets
609 * its properties; this method is not intended to be used by other clients.
612 * @param startIndex character index of replacement start position (inclusive)
613 * @param endIndex character index of replacement end position (exclusive)
615 public void setReplaceRange(int startIndex, int endIndex) {
616 if (startIndex < 0 || endIndex < startIndex) {
617 throw new IllegalArgumentException();
619 this.replaceStart = startIndex;
620 this.replaceEnd = endIndex;
624 * Returns the relative relevance rating of this proposal.
626 * @return relevance rating of this proposal; ratings are positive; higher means better
628 public int getRelevance() {
629 return this.relevance;
633 * Sets the relative relevance rating of this proposal.
635 * If not set, defaults to the lowest possible rating (1).
638 * The completion engine creates instances of this class and sets
639 * its properties; this method is not intended to be used by other clients.
642 * @param rating relevance rating of this proposal; ratings are positive; higher means better
644 public void setRelevance(int rating) {
646 throw new IllegalArgumentException();
648 this.relevance = rating;
652 * Returns the type or package signature of the relevant
653 * declaration in the context, or <code>null</code> if none.
655 * This field is available for the following kinds of
656 * completion proposals:
658 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - type signature
659 * of the type that is being subclassed or implemented</li>
660 * <li><code>FIELD_REF</code> - type signature
661 * of the type that declares the field that is referenced</li>
662 * <li><code>METHOD_REF</code> - type signature
663 * of the type that declares the method that is referenced</li>
664 * <li><code>METHOD_DECLARATION</code> - type signature
665 * of the type that declares the method that is being
666 * implemented or overridden</li>
667 * <li><code>PACKAGE_REF</code> - dot-based package
668 * signature of the package that is referenced</li>
669 * <li><code>TYPE_REF</code> - dot-based package
670 * signature of the package containing the type that is referenced</li>
672 * For kinds of completion proposals, this method returns
673 * <code>null</code>. Clients must not modify the array
677 * @return the declaration signature, or
678 * <code>null</code> if none
681 public char[] getDeclarationSignature() {
682 return this.declarationSignature;
686 * Sets the type or package signature of the relevant
687 * declaration in the context, or <code>null</code> if none.
689 * If not set, defaults to none.
692 * The completion engine creates instances of this class and sets
693 * its properties; this method is not intended to be used by other clients.
696 * @param signature the type or package signature, or
697 * <code>null</code> if none
699 public void setDeclarationSignature(char[] signature) {
700 this.declarationSignature = signature;
704 * Returns the simple name of the method, field,
705 * member, or variable relevant in the context, or
706 * <code>null</code> if none.
708 * This field is available for the following kinds of
709 * completion proposals:
711 * <li><code>FIELD_REF</code> - the name of the field</li>
712 * <li><code>KEYWORD</code> - the keyword</li>
713 * <li><code>LABEL_REF</code> - the name of the label</li>
714 * <li><code>LOCAL_VARIABLE_REF</code> - the name of the local variable</li>
715 * <li><code>METHOD_REF</code> - the name of the method</li>
716 * <li><code>METHOD_DECLARATION</code> - the name of the method</li>
717 * <li><code>VARIABLE_DECLARATION</code> - the name of the variable</li>
719 * For kinds of completion proposals, this method returns
720 * <code>null</code>. Clients must not modify the array
724 * @return the keyword, field, method, local variable, or member
725 * name, or <code>null</code> if none
727 public char[] getName() {
733 * Sets the simple name of the method, field,
734 * member, or variable relevant in the context, or
735 * <code>null</code> if none.
737 * If not set, defaults to none.
740 * The completion engine creates instances of this class and sets
741 * its properties; this method is not intended to be used by other clients.
744 * @param name the keyword, field, method, local variable,
745 * or member name, or <code>null</code> if none
747 public void setName(char[] name) {
752 * Returns the signature of the method or type
753 * relevant in the context, or <code>null</code> if none.
755 * This field is available for the following kinds of
756 * completion proposals:
758 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - method signature
759 * of the constructor that is being invoked</li>
760 * <li><code>FIELD_REF</code> - the type signature
761 * of the referenced field's type</li>
762 * <li><code>LOCAL_VARIABLE_REF</code> - the type signature
763 * of the referenced local variable's type</li>
764 * <li><code>METHOD_REF</code> - method signature
765 * of the method that is referenced</li>
766 * <li><code>METHOD_DECLARATION</code> - method signature
767 * of the method that is being implemented or overridden</li>
768 * <li><code>TYPE_REF</code> - type signature
769 * of the type that is referenced</li>
770 * <li><code>VARIABLE_DECLARATION</code> - the type signature
771 * of the type of the variable being declared</li>
773 * For kinds of completion proposals, this method returns
774 * <code>null</code>. Clients must not modify the array
778 * @return the signature, or <code>null</code> if none
781 public char[] getSignature() {
782 return this.signature;
786 * Sets the signature of the method, field type, member type,
787 * relevant in the context, or <code>null</code> if none.
789 * If not set, defaults to none.
792 * The completion engine creates instances of this class and sets
793 * its properties; this method is not intended to be used by other clients.
796 * @param signature the signature, or <code>null</code> if none
798 public void setSignature(char[] signature) {
799 this.signature = signature;
803 * Returns the modifier flags relevant in the context, or
804 * <code>Flags.AccDefault</code> if none.
806 * This field is available for the following kinds of
807 * completion proposals:
809 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - modifier flags
810 * of the constructor that is referenced</li>
811 * <li><code>FIELD_REF</code> - modifier flags
812 * of the field that is referenced;
813 * <code>Flags.AccEnum</code> can be used to recognize
814 * references to enum constants
816 * <li><code>KEYWORD</code> - modifier flag
817 * corrresponding to the modifier keyword</li>
818 * <li><code>LOCAL_VARIABLE_REF</code> - modifier flags
819 * of the local variable that is referenced</li>
820 * <li><code>METHOD_REF</code> - modifier flags
821 * of the method that is referenced;
822 * <code>Flags.AccAnnotation</code> can be used to recognize
823 * references to annotation type members
825 * <li><code>METHOD_DECLARATION</code> - modifier flags
826 * for the method that is being implemented or overridden</li>
827 * <li><code>TYPE_REF</code> - modifier flags
828 * of the type that is referenced; <code>Flags.AccInterface</code>
829 * can be used to recognize references to interfaces,
830 * <code>Flags.AccEnum</code> enum types,
831 * and <code>Flags.AccAnnotation</code> annotation types
833 * <li><code>VARIABLE_DECLARATION</code> - modifier flags
834 * for the variable being declared</li>
836 * For kinds of completion proposals, this method returns
837 * <code>Flags.AccDefault</code>.
840 * @return the modifier flags, or
841 * <code>Flags.AccDefault</code> if none
844 public int getFlags() {
849 * Sets the modifier flags relevant in the context.
851 * If not set, defaults to none.
854 * The completion engine creates instances of this class and sets
855 * its properties; this method is not intended to be used by other clients.
858 * @param flags the modifier flags, or
859 * <code>Flags.AccDefault</code> if none
861 public void setFlags(int flags) {
866 * Finds the method parameter names.
867 * This information is relevant to method reference (and
868 * method declaration proposals). Returns <code>null</code>
869 * if not available or not relevant.
871 * The client must not modify the array returned.
874 * <b>Note that this is an expensive thing to compute, which may require
875 * parsing Java source files, etc. Use sparingly.
878 * @param monitor the progress monitor, or <code>null</code> if none
879 * @return the parameter names, or <code>null</code> if none
880 * or not available or not relevant
882 public char[][] findParameterNames(IProgressMonitor monitor) {
883 if (!this.parameterNamesComputed) {
884 this.parameterNamesComputed = true;
885 // TODO (jerome) - Missing implementation
887 return this.parameterNames;
891 * Sets the method parameter names.
892 * This information is relevant to method reference (and
893 * method declaration proposals).
895 * The completion engine creates instances of this class and sets
896 * its properties; this method is not intended to be used by other clients.
899 * @param parameterNames the parameter names, or <code>null</code> if none
901 public void setParameterNames(char[][] parameterNames) {
902 this.parameterNames = parameterNames;
903 this.parameterNamesComputed = true;