CompletionProposal


1   /*******************************************************************************
2    * Copyright (c) 2004, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.core;
12  
13  import org.eclipse.core.runtime.IProgressMonitor;
14  import org.eclipse.jdt.core.compiler.CharOperation;
15  import org.eclipse.jdt.internal.codeassist.InternalCompletionProposal;
16  
17  /**
18   * Completion proposal.
19   * <p>
20   * In typical usage, the user working in a Java code editor issues
21   * a code assist command. This command results in a call to
22   * <code>ICodeAssist.codeComplete(position, completionRequestor)</code>
23   * passing the current position in the source code. The code assist
24   * engine analyzes the code in the buffer, determines what kind of
25   * Java language construct is at that position, and proposes ways
26   * to complete that construct. These proposals are instances of
27   * the class <code>CompletionProposal</code>. These proposals,
28   * perhaps after sorting and filtering, are presented to the user
29   * to make a choice.
30   * </p>
31   * <p>
32   * The proposal is as follows: insert
33   * the {@linkplain #getCompletion() completion string} into the
34   * source file buffer, replacing the characters between 
35   * {@linkplain #getReplaceStart() the start}
36   * and {@linkplain #getReplaceEnd() end}. The string
37   * can be arbitrary; for example, it might include not only the 
38   * name of a method but a set of parentheses. Moreover, the source
39   * range may include source positions before or after the source
40   * position where <code>ICodeAssist.codeComplete</code> was invoked.
41   * The rest of the information associated with the proposal is
42   * to provide context that may help a user to choose from among
43   * competing proposals.
44   * </p>
45   * <p>
46   * The completion engine creates instances of this class; it is not intended 
47   * to be instantiated or subclassed by clients.
48   * </p>
49   * 
50   * @see ICodeAssist#codeComplete(int, CompletionRequestor)
51   * @since 3.0
52   */
53  public final class CompletionProposal extends InternalCompletionProposal {
54      private boolean updateCompletion = false;
55  
56      /**
57       * Completion is a declaration of an anonymous class.
58       * This kind of completion might occur in a context like
59       * <code>"new List^;"</code> and complete it to
60       * <code>"new List() {}"</code>.
61       * <p>
62       * The following additional context information is available
63       * for this kind of completion proposal at little extra cost:
64       * <ul>
65       * <li>{@link #getDeclarationSignature()} -
66       * the type signature of the type being implemented or subclassed
67       * </li>
68       * <li>{@link #getDeclarationKey()} -
69       * the type unique key of the type being implemented or subclassed
70       * </li>
71       * <li>{@link #getSignature()} -
72       * the method signature of the constructor that is referenced
73       * </li>
74       * <li>{@link #getKey()} -
75       * the method unique key of the constructor that is referenced
76       * if the declaring type is not an interface
77       * </li>
78       * <li>{@link #getFlags()} -
79       * the modifiers flags of the constructor that is referenced
80       * </li>
81       * </ul>
82       * </p>
83       * 
84       * @see #getKind()
85       */
86      public static final int ANONYMOUS_CLASS_DECLARATION = 1;
87  
88      /**
89       * Completion is a reference to a field.
90       * This kind of completion might occur in a context like
91       * <code>"this.ref^ = 0;"</code> and complete it to
92       * <code>"this.refcount = 0;"</code>.
93       * <p>
94       * The following additional context information is available
95       * for this kind of completion proposal at little extra cost:
96       * <ul>
97       * <li>{@link #getDeclarationSignature()} -
98       * the type signature of the type that declares the field that is referenced
99       * </li>
100      * <li>{@link #getFlags()} -
101      * the modifiers flags (including ACC_ENUM) of the field that is referenced
102      * </li>
103      * <li>{@link #getName()} -
104      * the simple name of the field that is referenced
105      * </li>
106      * <li>{@link #getSignature()} -
107      * the type signature of the field's type (as opposed to the
108      * signature of the type in which the referenced field
109      * is declared)
110      * </li>
111      * </ul>
112      * </p>
113      * 
114      * @see #getKind()
115      */
116     public static final int FIELD_REF = 2;
117 
118     /**
119      * Completion is a keyword.
120      * This kind of completion might occur in a context like
121      * <code>"public cl^ Foo {}"</code> and complete it to
122      * <code>"public class Foo {}"</code>.
123      * <p>
124      * The following additional context information is available
125      * for this kind of completion proposal at little extra cost:
126      * <ul>
127      * <li>{@link #getName()} -
128      * the keyword token
129      * </li>
130      * <li>{@link #getFlags()} -
131      * the corresponding modifier flags if the keyword is a modifier
132      * </li>
133      * </ul>
134      * </p>
135      * 
136      * @see #getKind()
137      */
138     public static final int KEYWORD = 3;
139 
140     /**
141      * Completion is a reference to a label.
142      * This kind of completion might occur in a context like
143      * <code>"break lo^;"</code> and complete it to
144      * <code>"break loop;"</code>.
145      * <p>
146      * The following additional context information is available
147      * for this kind of completion proposal at little extra cost:
148      * <ul>
149      * <li>{@link #getName()} -
150      * the simple name of the label that is referenced
151      * </li>
152      * </ul>
153      * </p>
154      * 
155      * @see #getKind()
156      */
157     public static final int LABEL_REF = 4;
158 
159     /**
160      * Completion is a reference to a local variable.
161      * This kind of completion might occur in a context like
162      * <code>"ke^ = 4;"</code> and complete it to
163      * <code>"keys = 4;"</code>.
164      * <p>
165      * The following additional context information is available
166      * for this kind of completion proposal at little extra cost:
167      * <ul>
168      * <li>{@link #getFlags()} -
169      * the modifiers flags of the local variable that is referenced
170      * </li>
171      * <li>{@link #getName()} -
172      * the simple name of the local variable that is referenced
173      * </li>
174      * <li>{@link #getSignature()} -
175      * the type signature of the local variable's type
176      * </li>
177      * </ul>
178      * </p>
179      * 
180      * @see #getKind()
181      */
182     public static final int LOCAL_VARIABLE_REF = 5;
183 
184     /**
185      * Completion is a reference to a method.
186      * This kind of completion might occur in a context like
187      * <code>"System.out.pr^();"</code> and complete it to
188      * <code>""System.out.println();"</code>.
189      * <p>
190      * The following additional context information is available
191      * for this kind of completion proposal at little extra cost:
192      * <ul>
193      * <li>{@link #getDeclarationSignature()} -
194      * the type signature of the type that declares the method that is referenced
195      * </li>
196      * <li>{@link #getFlags()} -
197      * the modifiers flags of the method that is referenced
198      * </li>
199      * <li>{@link #getName()} -
200      * the simple name of the method that is referenced
201      * </li>
202      * <li>{@link #getSignature()} -
203      * the method signature of the method that is referenced
204      * </li>
205      * </ul>
206      * </p>
207      * 
208      * @see #getKind()
209      */
210     public static final int METHOD_REF = 6;
211 
212     /**
213      * Completion is a declaration of a method.
214      * This kind of completion might occur in a context like
215      * <code>"new List() {si^};"</code> and complete it to
216      * <code>"new List() {public int size() {} };"</code>.
217      * <p>
218      * The following additional context information is available
219      * for this kind of completion proposal at little extra cost:
220      * <ul>
221      * <li>{@link #getDeclarationSignature()} -
222      * the type signature of the type that declares the
223      * method that is being overridden or implemented
224      * </li>
225      * <li>{@link #getDeclarationKey()} -
226      * the unique of the type that declares the
227      * method that is being overridden or implemented
228      * </li>
229      * <li>{@link #getName()} -
230      * the simple name of the method that is being overridden
231      * or implemented
232      * </li>
233      * <li>{@link #getSignature()} -
234      * the method signature of the method that is being
235      * overridden or implemented
236      * </li>
237      * <li>{@link #getKey()} -
238      * the method unique key of the method that is being
239      * overridden or implemented
240      * </li>
241      * <li>{@link #getFlags()} -
242      * the modifiers flags of the method that is being
243      * overridden or implemented
244      * </li>
245      * </ul>
246      * </p>
247      * 
248      * @see #getKind()
249      */
250     public static final int METHOD_DECLARATION = 7;
251 
252     /**
253      * Completion is a reference to a package.
254      * This kind of completion might occur in a context like
255      * <code>"import java.u^.*;"</code> and complete it to
256      * <code>"import java.util.*;"</code>.
257      * <p>
258      * The following additional context information is available
259      * for this kind of completion proposal at little extra cost:
260      * <ul>
261      * <li>{@link #getDeclarationSignature()} -
262      * the dot-based package name of the package that is referenced
263      * </li>
264      * </ul>
265      * </p>
266      * 
267      * @see #getKind()
268      */
269     public static final int PACKAGE_REF = 8;
270 
271     /**
272      * Completion is a reference to a type. Any kind of type
273      * is allowed, including primitive types, reference types,
274      * array types, parameterized types, and type variables.
275      * This kind of completion might occur in a context like
276      * <code>"public static Str^ key;"</code> and complete it to
277      * <code>"public static String key;"</code>.
278      * <p>
279      * The following additional context information is available
280      * for this kind of completion proposal at little extra cost:
281      * <ul>
282      * <li>{@link #getDeclarationSignature()} -
283      * the dot-based package name of the package that contains
284      * the type that is referenced
285      * </li>
286      * <li>{@link #getSignature()} -
287      * the type signature of the type that is referenced
288      * </li>
289      * <li>{@link #getFlags()} -
290      * the modifiers flags (including Flags.AccInterface, AccEnum,
291      * and AccAnnotation) of the type that is referenced
292      * </li>
293      * </ul>
294      * </p>
295      * 
296      * @see #getKind()
297      */
298     public static final int TYPE_REF = 9;
299 
300     /**
301      * Completion is a declaration of a variable (locals, parameters,
302      * fields, etc.).
303      * <p>
304      * The following additional context information is available
305      * for this kind of completion proposal at little extra cost:
306      * <ul>
307      * <li>{@link #getName()} -
308      * the simple name of the variable being declared
309      * </li>
310      * <li>{@link #getSignature()} -
311      * the type signature of the type of the variable
312      * being declared
313      * </li>
314      * <li>{@link #getFlags()} -
315      * the modifiers flags of the variable being declared
316      * </li>
317      * </ul>
318      * </p>
319      * @see #getKind()
320      */
321     public static final int VARIABLE_DECLARATION = 10;
322 
323     /**
324      * Completion is a declaration of a new potential method.
325      * This kind of completion might occur in a context like
326      * <code>"new List() {si^};"</code> and complete it to
327      * <code>"new List() {public int si() {} };"</code>.
328      * <p>
329      * The following additional context information is available
330      * for this kind of completion proposal at little extra cost:
331      * <ul>
332      * <li>{@link #getDeclarationSignature()} -
333      * the type signature of the type that declares the
334      * method that is being created
335      * </li>
336      * <li>{@link #getName()} -
337      * the simple name of the method that is being created
338      * </li>
339      * <li>{@link #getSignature()} -
340      * the method signature of the method that is being
341      * created
342      * </li>
343      * <li>{@link #getFlags()} -
344      * the modifiers flags of the method that is being
345      * created
346      * </li>
347      * </ul>
348      * </p>
349      * 
350      * @see #getKind()
351      * @since 3.1
352      */
353     public static final int POTENTIAL_METHOD_DECLARATION = 11;
354     
355     /**
356      * Completion is a reference to a method name.
357      * This kind of completion might occur in a context like
358      * <code>"import p.X.fo^"</code> and complete it to
359      * <code>"import p.X.foo;"</code>.
360      * <p>
361      * The following additional context information is available
362      * for this kind of completion proposal at little extra cost:
363      * <ul>
364      * <li>{@link #getDeclarationSignature()} -
365      * the type signature of the type that declares the method that is referenced
366      * </li>
367      * <li>{@link #getFlags()} -
368      * the modifiers flags of the method that is referenced
369      * </li>
370      * <li>{@link #getName()} -
371      * the simple name of the method that is referenced
372      * </li>
373      * <li>{@link #getSignature()} -
374      * the method signature of the method that is referenced
375      * </li>
376      * </ul>
377      * </p>
378      * 
379      * @see #getKind()
380      * @since 3.1
381      */
382     public static final int METHOD_NAME_REFERENCE = 12;
383     
384     /**
385      * Completion is a reference to annotation's attribute.
386      * This kind of completion might occur in a context like
387      * <code>"@Annot(attr^=value)"</code> and complete it to
388      * <code>"@Annot(attribute^=value)"</code>.
389      * <p>
390      * The following additional context information is available
391      * for this kind of completion proposal at little extra cost:
392      * <ul>
393      * <li>{@link #getDeclarationSignature()} -
394      * the type signature of the annotation that declares the attribute that is referenced
395      * </li>
396      * <li>{@link #getFlags()} -
397      * the modifiers flags of the attribute that is referenced
398      * </li>
399      * <li>{@link #getName()} -
400      * the simple name of the attribute that is referenced
401      * </li>
402      * <li>{@link #getSignature()} -
403      * the type signature of the attribute's type (as opposed to the
404      * signature of the type in which the referenced attribute
405      * is declared)
406      * </li>
407      * </ul>
408      * </p>
409      * 
410      * @see #getKind()
411      * @since 3.1
412      */
413     public static final int ANNOTATION_ATTRIBUTE_REF = 13;
414 
415     /**
416      * Completion is a link reference to a field in a javadoc text.
417      * This kind of completion might occur in a context like
418      * <code>"  * blabla System.o^ blabla"</code> and complete it to
419      * <code>"  * blabla {&#64;link System#out } blabla"</code>.
420      * <p>
421      * The following additional context information is available
422      * for this kind of completion proposal at little extra cost:
423      * <ul>
424      * <li>{@link #getDeclarationSignature()} -
425      * the type signature of the type that declares the field that is referenced
426      * </li>
427      * <li>{@link #getFlags()} -
428      * the modifiers flags (including ACC_ENUM) of the field that is referenced
429      * </li>
430      * <li>{@link #getName()} -
431      * the simple name of the field that is referenced
432      * </li>
433      * <li>{@link #getSignature()} -
434      * the type signature of the field's type (as opposed to the
435      * signature of the type in which the referenced field
436      * is declared)
437      * </li>
438      * </ul>
439      * </p>
440      * 
441      * @see #getKind()
442      * @since 3.2
443      */
444     public static final int JAVADOC_FIELD_REF = 14;
445 
446     /**
447      * Completion is a link reference to a method in a javadoc text.
448      * This kind of completion might occur in a context like
449      * <code>"  * blabla Runtime#get^ blabla"</code> and complete it to
450      * <code>"  * blabla {&#64;link Runtime#getRuntime() }"</code>.
451      * <p>
452      * The following additional context information is available
453      * for this kind of completion proposal at little extra cost:
454      * <ul>
455      * <li>{@link #getDeclarationSignature()} -
456      * the type signature of the type that declares the method that is referenced
457      * </li>
458      * <li>{@link #getFlags()} -
459      * the modifiers flags of the method that is referenced
460      * </li>
461      * <li>{@link #getName()} -
462      * the simple name of the method that is referenced
463      * </li>
464      * <li>{@link #getSignature()} -
465      * the method signature of the method that is referenced
466      * </li>
467      * </ul>
468      * </p>
469      * 
470      * @see #getKind()
471      * @since 3.2
472      */
473     public static final int JAVADOC_METHOD_REF = 15;
474 
475     /**
476      * Completion is a link reference to a type in a javadoc text.
477      * Any kind of type is allowed, including primitive types, reference types,
478      * array types, parameterized types, and type variables.
479      * This kind of completion might occur in a context like
480      * <code>"  * blabla Str^ blabla"</code> and complete it to
481      * <code>"  * blabla {&#64;link String } blabla"</code>.
482      * <p>
483      * The following additional context information is available
484      * for this kind of completion proposal at little extra cost:
485      * <ul>
486      * <li>{@link #getDeclarationSignature()} -
487      * the dot-based package name of the package that contains
488      * the type that is referenced
489      * </li>
490      * <li>{@link #getSignature()} -
491      * the type signature of the type that is referenced
492      * </li>
493      * <li>{@link #getFlags()} -
494      * the modifiers flags (including Flags.AccInterface, AccEnum,
495      * and AccAnnotation) of the type that is referenced
496      * </li>
497      * </ul>
498      * </p>
499      * 
500      * @see #getKind()
501      * @since 3.2
502      */
503     public static final int JAVADOC_TYPE_REF = 16;
504 
505     /**
506      * Completion is a value reference to a static field in a javadoc text.
507      * This kind of completion might occur in a context like
508      * <code>"  * blabla System.o^ blabla"</code> and complete it to
509      * <code>"  * blabla {&#64;value System#out } blabla"</code>.
510      * <p>
511      * The following additional context information is available
512      * for this kind of completion proposal at little extra cost:
513      * <ul>
514      * <li>{@link #getDeclarationSignature()} -
515      * the type signature of the type that declares the field that is referenced
516      * </li>
517      * <li>{@link #getFlags()} -
518      * the modifiers flags (including ACC_ENUM) of the field that is referenced
519      * </li>
520      * <li>{@link #getName()} -
521      * the simple name of the field that is referenced
522      * </li>
523      * <li>{@link #getSignature()} -
524      * the type signature of the field's type (as opposed to the
525      * signature of the type in which the referenced field
526      * is declared)
527      * </li>
528      * </ul>
529      * </p>
530      * 
531      * @see #getKind()
532      * @since 3.2
533      */
534     public static final int JAVADOC_VALUE_REF = 17;
535 
536     /**
537      * Completion is a method argument or a class/method type parameter
538      * in javadoc param tag.
539      * This kind of completion might occur in a context like
540      * <code>"  * @param arg^ blabla"</code> and complete it to
541      * <code>"  * @param argument blabla"</code>.
542      * or
543      * <code>"  * @param &lt;T^ blabla"</code> and complete it to
544      * <code>"  * @param &lt;TT&gt; blabla"</code>.
545      * <p>
546      * The following additional context information is available
547      * for this kind of completion proposal at little extra cost:
548      * <ul>
549      * <li>{@link #getDeclarationSignature()} -
550      * the type signature of the type that declares the field that is referenced
551      * </li>
552      * <li>{@link #getFlags()} -
553      * the modifiers flags (including ACC_ENUM) of the field that is referenced
554      * </li>
555      * <li>{@link #getName()} -
556      * the simple name of the field that is referenced
557      * </li>
558      * <li>{@link #getSignature()} -
559      * the type signature of the field's type (as opposed to the
560      * signature of the type in which the referenced field
561      * is declared)
562      * </li>
563      * </ul>
564      * </p>
565      * 
566      * @see #getKind()
567      * @since 3.2
568      */
569     public static final int JAVADOC_PARAM_REF = 18;
570 
571     /**
572      * Completion is a javadoc block tag.
573      * This kind of completion might occur in a context like
574      * <code>"  * @s^ blabla"</code> and complete it to
575      * <code>"  * @see blabla"</code>.
576      * <p>
577      * The following additional context information is available
578      * for this kind of completion proposal at little extra cost:
579      * <ul>
580      * <li>{@link #getDeclarationSignature()} -
581      * the type signature of the type that declares the field that is referenced
582      * </li>
583      * <li>{@link #getFlags()} -
584      * the modifiers flags (including ACC_ENUM) of the field that is referenced
585      * </li>
586      * <li>{@link #getName()} -
587      * the simple name of the field that is referenced
588      * </li>
589      * <li>{@link #getSignature()} -
590      * the type signature of the field's type (as opposed to the
591      * signature of the type in which the referenced field
592      * is declared)
593      * </li>
594      * </ul>
595      * </p>
596      * 
597      * @see #getKind()
598      * @since 3.2
599      */
600     public static final int JAVADOC_BLOCK_TAG = 19;
601 
602     /**
603      * Completion is a javadoc inline tag.
604      * This kind of completion might occur in a context like
605      * <code>"  * Insert @l^ Object"</code> and complete it to
606      * <code>"  * Insert {&#64;link Object }"</code>.
607      * <p>
608      * The following additional context information is available
609      * for this kind of completion proposal at little extra cost:
610      * <ul>
611      * <li>{@link #getDeclarationSignature()} -
612      * the type signature of the type that declares the field that is referenced
613      * </li>
614      * <li>{@link #getFlags()} -
615      * the modifiers flags (including ACC_ENUM) of the field that is referenced
616      * </li>
617      * <li>{@link #getName()} -
618      * the simple name of the field that is referenced
619      * </li>
620      * <li>{@link #getSignature()} -
621      * the type signature of the field's type (as opposed to the
622      * signature of the type in which the referenced field
623      * is declared)
624      * </li>
625      * </ul>
626      * </p>
627      * 
628      * @see #getKind()
629      * @since 3.2
630      */
631     public static final int JAVADOC_INLINE_TAG = 20;
632 
633     /**
634      * Completion is an import of reference to a static field.
635      * <p>
636      * The following additional context information is available
637      * for this kind of completion proposal at little extra cost:
638      * <ul>
639      * <li>{@link #getDeclarationSignature()} -
640      * the type signature of the type that declares the field that is imported
641      * </li>
642      * <li>{@link #getFlags()} -
643      * the modifiers flags (including ACC_ENUM) of the field that is imported
644      * </li>
645      * <li>{@link #getName()} -
646      * the simple name of the field that is imported
647      * </li>
648      * <li>{@link #getSignature()} -
649      * the type signature of the field's type (as opposed to the
650      * signature of the type in which the referenced field
651      * is declared)
652      * </li>
653      * <li>{@link #getAdditionalFlags()} -
654      * the completion flags (including ComletionFlags.StaticImport)
655      * of the proposed import
656      * </li>
657      * </ul>
658      * </p>
659      * 
660      * @see #getKind()
661      * 
662      * @since 3.3
663      */
664     public static final int FIELD_IMPORT = 21;
665     
666     /**
667      * Completion is an import of reference to a static method.
668      * <p>
669      * The following additional context information is available
670      * for this kind of completion proposal at little extra cost:
671      * <ul>
672      * <li>{@link #getDeclarationSignature()} -
673      * the type signature of the type that declares the method that is imported
674      * </li>
675      * <li>{@link #getFlags()} -
676      * the modifiers flags of the method that is imported
677      * </li>
678      * <li>{@link #getName()} -
679      * the simple name of the method that is imported
680      * </li>
681      * <li>{@link #getSignature()} -
682      * the method signature of the method that is imported
683      * </li>
684      * <li>{@link #getAdditionalFlags()} -
685      * the completion flags (including ComletionFlags.StaticImport)
686      * of the proposed import
687      * </li>
688      * </ul>
689      * </p>
690      * 
691      * @see #getKind()
692      * 
693      * @since 3.3
694      */
695     public static final int METHOD_IMPORT = 22;
696     
697     /**
698      * Completion is an import of reference to a type.
699      * Only reference to reference types are allowed.
700      * <p>
701      * The following additional context information is available
702      * for this kind of completion proposal at little extra cost:
703      * <ul>
704      * <li>{@link #getDeclarationSignature()} -
705      * the dot-based package name of the package that contains
706      * the type that is imported
707      * </li>
708      * <li>{@link #getSignature()} -
709      * the type signature of the type that is imported
710      * </li>
711      * <li>{@link #getFlags()} -
712      * the modifiers flags (including Flags.AccInterface, AccEnum,
713      * and AccAnnotation) of the type that is imported
714      * </li>
715      * <li>{@link #getAdditionalFlags()} -
716      * the completion flags (including ComletionFlags.StaticImport)
717      * of the proposed import
718      * </li>
719      * </ul>
720      * </p>
721      * 
722      * @see #getKind()
723      * 
724      * @since 3.3
725      */
726     public static final int TYPE_IMPORT = 23;
727     
728     /**
729      * First valid completion kind.
730      * 
731      * @since 3.1
732      */
733     protected static final int FIRST_KIND = ANONYMOUS_CLASS_DECLARATION;
734     
735     /**
736      * Last valid completion kind.
737      * 
738      * @since 3.1
739      */
740     protected static final int LAST_KIND = TYPE_IMPORT;
741     
742     /**
743      * Kind of completion request.
744      */
745     private int completionKind;
746     
747     /**
748      * Offset in original buffer where ICodeAssist.codeComplete() was
749      * requested.
750      */
751     private int completionLocation;
752     
753     /**
754      * Start position (inclusive) of source range in original buffer 
755      * containing the relevant token
756      * defaults to empty subrange at [0,0).
757      */
758     private int tokenStart = 0;
759     
760     /**
761      * End position (exclusive) of source range in original buffer 
762      * containing the relevant token;
763      * defaults to empty subrange at [0,0).
764      */
765     private int tokenEnd = 0;
766     
767     /**
768      * Completion string; defaults to empty string.
769      */
770     private char[] completion = CharOperation.NO_CHAR;
771     
772     /**
773      * Start position (inclusive) of source range in original buffer 
774      * to be replaced by completion string; 
775      * defaults to empty subrange at [0,0).
776      */
777     private int replaceStart = 0;
778     
779     /**
780      * End position (exclusive) of source range in original buffer 
781      * to be replaced by completion string;
782      * defaults to empty subrange at [0,0).
783      */
784     private int replaceEnd = 0;
785     
786     /**
787      * Relevance rating; positive; higher means better;
788      * defaults to minimum rating.
789      */
790     private int relevance = 1;
791     
792     /**
793      * Signature of the relevant package or type declaration
794      * in the context, or <code>null</code> if none.
795      * Defaults to null.
796      */
797     private char[] declarationSignature = null;
798     
799     /**
800      * Unique key of the relevant package or type declaration
801      * in the context, or <code>null</code> if none.
802      * Defaults to null.
803      */
804     private char[] declarationKey = null;
805     
806     /**
807      * Simple name of the method, field,
808      * member, or variable relevant in the context, or
809      * <code>null</code> if none.
810      * Defaults to null.
811      */
812     private char[] name = null;
813     
814     /**
815      * Signature of the method, field type, member type,
816      * relevant in the context, or <code>null</code> if none.
817      * Defaults to null.
818      */
819     private char[] signature = null;
820     
821     /**
822      * Unique of the method, field type, member type,
823      * relevant in the context, or <code>null</code> if none.
824      * Defaults to null.
825      */
826     private char[] key = null;
827     
828     /**
829      * Array of required completion proposals, or <code>null</code> if none.
830      * The proposal can not be applied if the required proposals aren't applied.
831      * Defaults to <code>null</code>.
832      */
833     private CompletionProposal[] requiredProposals;
834     
835     /**
836      * Modifier flags relevant in the context, or
837      * <code>Flags.AccDefault</code> if none.
838      * Defaults to <code>Flags.AccDefault</code>.
839      */
840     private int flags = Flags.AccDefault;
841     
842     /**
843      * Completion flags relevant in the context, or
844      * <code>CompletionFlags.Default</code> if none.
845      * Defaults to <code>CompletionFlags.Default</code>.
846      */
847     private int additionalFlags = CompletionFlags.Default;
848     
849     /**
850      * Parameter names (for method completions), or
851      * <code>null</code> if none. Lazily computed.
852      * Defaults to <code>null</code>.
853      */
854     private char[][] parameterNames = null;
855     
856     /**
857      * Indicates whether parameter names have been computed.
858      */
859     private boolean parameterNamesComputed = false;
860     
861     /**
862      * Creates a basic completion proposal. All instance
863      * field have plausible default values unless otherwise noted.
864      * <p>
865      * Note that the constructors for this class are internal to the
866      * Java model implementation. Clients cannot directly create
867      * CompletionProposal objects.
868      * </p>
869      * 
870      * @param kind one of the kind constants declared on this class
871      * @param completionOffset original offset of code completion request
872      * @return a new completion proposal
873      */
874     public static CompletionProposal create(int kind, int completionOffset) {
875         return new CompletionProposal(kind, completionOffset);
876     }
877     
878     /**
879      * Creates a basic completion proposal. All instance
880      * field have plausible default values unless otherwise noted.
881      * <p>
882      * Note that the constructors for this class are internal to the
883      * Java model implementation. Clients cannot directly create
884      * CompletionProposal objects.
885      * </p>
886      * 
887      * @param kind one of the kind constants declared on this class
888      * @param completionLocation original offset of code completion request
889      */
890     CompletionProposal(int kind, int completionLocation) {
891         if ((kind < CompletionProposal.FIRST_KIND)
892                 || (kind > CompletionProposal.LAST_KIND)) {
893             throw new IllegalArgumentException  ();
894         }
895         if (this.completion == null || completionLocation < 0) {
896             // Work around for bug 132558 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=132558).
897             // completionLocation can be -1 if the completion occur at the start of a file or
898             // the start of a code snippet but this API isn't design to support negative position.
899             if(this.completion == null || completionLocation != -1) {
900                 throw new IllegalArgumentException  ();
901             }
902             completionLocation = 0;
903         }
904         this.completionKind = kind;
905         this.completionLocation = completionLocation;
906     }
907     
908     /**
909      * Returns the completion flags relevant in the context, or
910      * <code>CompletionFlags.Default</code> if none.
911      * <p>
912      * This field is available for the following kinds of
913      * completion proposals:
914      * <ul>
915      * <li><code>FIELD_IMPORT</code> - completion flags
916      * of the attribute that is referenced. Completion flags for
917      * this proposal kind can only include <code>CompletionFlags.StaticImport</code></li>
918      * <li><code>METHOD_IMPORT</code> - completion flags
919      * of the attribute that is referenced. Completion flags for
920      * this proposal kind can only include <code>CompletionFlags.StaticImport</code></li>
921      * <li><code>TYPE_IMPORT</code> - completion flags
922      * of the attribute that is referenced. Completion flags for
923      * this proposal kind can only include <code>CompletionFlags.StaticImport</code></li>
924      * </ul>
925      * For other kinds of completion proposals, this method returns
926      * <code>CompletionFlags.Default</code>.
927      * </p>
928      * 
929      * @return the completion flags, or
930      * <code>CompletionFlags.Default</code> if none
931      * @see CompletionFlags
932      * 
933      * @since 3.3
934      */
935     public int getAdditionalFlags() {
936         return this.additionalFlags;
937     }
938 
939     /**
940      * Sets the completion flags relevant in the context.
941      * <p>
942      * If not set, defaults to none.
943      * </p>
944      * <p>
945      * The completion engine creates instances of this class and sets
946      * its properties; this method is not intended to be used by other clients.
947      * </p>
948      * 
949      * @param additionalFlags the completion flags, or
950      * <code>CompletionFlags.Default</code> if none
951      * 
952      * @since 3.3
953      */
954     public void setAdditionalFlags(int additionalFlags) {
955         this.additionalFlags = additionalFlags;
956     }
957     
958     /**
959      * Returns the kind of completion being proposed.
960      * <p>
961      * The set of different kinds of completion proposals is
962      * expected to change over time. It is strongly recommended
963      * that clients do <b>not</b> assume that the kind is one of the
964      * ones they know about, and code defensively for the
965      * possibility of unexpected future growth.
966      * </p>
967      * 
968      * @return the kind; one of the kind constants
969      * declared on this class, or possibly a kind unknown
970      * to the caller
971      */
972     public int getKind() {
973         return this.completionKind;
974     }
975     
976     /**
977      * Returns the character index in the source file buffer
978      * where source completion was requested (the 
979      * <code>offset</code> parameter to
980      * <code>ICodeAssist.codeComplete</code> minus one).
981      * 
982      * @return character index in source file buffer
983      * @see ICodeAssist#codeComplete(int,CompletionRequestor)
984      */
985     // TODO (david) https://bugs.eclipse.org/bugs/show_bug.cgi?id=132558
986     public int getCompletionLocation() {
987         return this.completionLocation;
988     }
989     
990     /**
991      * Returns the character index of the start of the
992      * subrange in the source file buffer containing the
993      * relevant token being completed. This
994      * token is either the identifier or Java language keyword
995      * under, or immediately preceding, the original request 
996      * offset. If the original request offset is not within
997      * or immediately after an identifier or keyword, then the
998      * position returned is original request offset and the
999      * token range is empty.
1000     * 
1001     * @return character index of token start position (inclusive)
1002     */
1003    public int getTokenStart() {
1004        return this.tokenStart;
1005    }
1006    
1007    /**
1008     * Returns the character index of the end (exclusive) of the subrange
1009     * in the source file buffer containing the
1010     * relevant token. When there is no relevant token, the
1011     * range is empty
1012     * (<code>getEndToken() == getStartToken()</code>).
1013     * 
1014     * @return character index of token end position (exclusive)
1015     */
1016    public int getTokenEnd() {
1017        return this.tokenEnd;
1018    }
1019    
1020    /**
1021     * Sets the character indices of the subrange in the
1022     * source file buffer containing the relevant token being
1023     * completed. This token is either the identifier or
1024     * Java language keyword under, or immediately preceding,
1025     * the original request offset. If the original request
1026     * offset is not within or immediately after an identifier
1027     * or keyword, then the source range begins at original
1028     * request offset and is empty.
1029     * <p>
1030     * If not set, defaults to empty subrange at [0,0).
1031     * </p>
1032     * 
1033     * @param startIndex character index of token start position (inclusive)
1034     * @param endIndex character index of token end position (exclusive)
1035     */
1036    public void setTokenRange(int startIndex, int endIndex) {
1037        if (startIndex < 0 || endIndex < startIndex) {
1038            throw new IllegalArgumentException  ();
1039        }
1040        this.tokenStart = startIndex;
1041        this.tokenEnd = endIndex;
1042    }
1043    
1044    /**
1045     * Returns the proposed sequence of characters to insert into the
1046     * source file buffer, replacing the characters at the specified
1047     * source range. The string can be arbitrary; for example, it might
1048     * include not only the name of a method but a set of parentheses.
1049     * <p>
1050     * The client must not modify the array returned.
1051     * </p>
1052     * 
1053     * @return the completion string
1054     */
1055    public char[] getCompletion() {
1056        if(this.completionKind == METHOD_DECLARATION) {
1057            this.findParameterNames(null);
1058            if(this.updateCompletion) {
1059                this.updateCompletion = false;
1060                
1061                if(this.parameterNames != null) {
1062                    int length = this.parameterNames.length;
1063                    StringBuffer   completionBuffer = new StringBuffer  (this.completion.length);
1064                        
1065                    int start = 0;
1066                    int end = CharOperation.indexOf('%', this.completion);
1067    
1068                    completionBuffer.append(this.completion, start, end - start);
1069                    
1070                    for(int i = 0 ; i < length ; i++){
1071                        completionBuffer.append(this.parameterNames[i]);
1072                        start = end + 1;
1073                        end = CharOperation.indexOf('%', this.completion, start);
1074                        if(end > -1){
1075                            completionBuffer.append(this.completion, start, end - start);
1076                        } else {
1077                            completionBuffer.append(this.completion, start, this.completion.length - start);
1078                        }
1079                    }
1080                    int nameLength = completionBuffer.length();
1081                    this.completion = new char[nameLength];
1082                    completionBuffer.getChars(0, nameLength, this.completion, 0);
1083                }
1084            }
1085        }
1086        return this.completion;
1087    }
1088    
1089    /**
1090     * Sets the proposed sequence of characters to insert into the
1091     * source file buffer, replacing the characters at the specified
1092     * source range. The string can be arbitrary; for example, it might
1093     * include not only the name of a method but a set of parentheses.
1094     * <p>
1095     * If not set, defaults to an empty character array.
1096     * </p>
1097     * <p>
1098     * The completion engine creates instances of this class and sets
1099     * its properties; this method is not intended to be used by other clients.
1100     * </p>
1101     * 
1102     * @param completion the completion string
1103     */
1104    public void setCompletion(char[] completion) {
1105        this.completion = completion;
1106    }
1107    
1108    /**
1109     * Returns the character index of the start of the
1110     * subrange in the source file buffer to be replaced
1111     * by the completion string. If the subrange is empty
1112     * (<code>getReplaceEnd() == getReplaceStart()</code>),
1113     * the completion string is to be inserted at this
1114     * index.
1115     * <p>
1116     * Note that while the token subrange is precisely 
1117     * specified, the replacement range is loosely
1118     * constrained and may not bear any direct relation
1119     * to the original request offset. For example,
1120     * it would be possible for a type completion to 
1121     * propose inserting an import declaration at the
1122     * top of the compilation unit; or the completion
1123     * might include trailing parentheses and
1124     * punctuation for a method completion.
1125     * </p>
1126     * 
1127     * @return replacement start position (inclusive)
1128     */
1129    public int getReplaceStart() {
1130        return this.replaceStart;
1131    }
1132    
1133    /**
1134     * Returns the character index of the end of the
1135     * subrange in the source file buffer to be replaced
1136     * by the completion string. If the subrange is empty
1137     * (<code>getReplaceEnd() == getReplaceStart()</code>),
1138     * the completion string is to be inserted at this
1139     * index.
1140     * 
1141     * @return replacement end position (exclusive)
1142     */
1143    public int getReplaceEnd() {
1144        return this.replaceEnd;
1145    }
1146    
1147    /**
1148     * Sets the character indices of the subrange in the
1149     * source file buffer to be replaced by the completion
1150     * string. If the subrange is empty
1151     * (<code>startIndex == endIndex</code>),
1152     * the completion string is to be inserted at this
1153     * index.
1154     * <p>
1155     * If not set, defaults to empty subrange at [0,0).
1156     * </p>
1157     * <p>
1158     * The completion engine creates instances of this class and sets
1159     * its properties; this method is not intended to be used by other clients.
1160     * </p>
1161     * 
1162     * @param startIndex character index of replacement start position (inclusive)
1163     * @param endIndex character index of replacement end position (exclusive)
1164     */
1165    public void setReplaceRange(int startIndex, int endIndex) {
1166        if (startIndex < 0 || endIndex < startIndex) {
1167            throw new IllegalArgumentException  ();
1168        }
1169        this.replaceStart = startIndex;
1170        this.replaceEnd = endIndex;
1171    }
1172    
1173    /**
1174     * Returns the relative relevance rating of this proposal.
1175     * 
1176     * @return relevance rating of this proposal; ratings are positive; higher means better
1177     */
1178    public int getRelevance() {
1179        return this.relevance;
1180    }
1181    
1182    /**
1183     * Sets the relative relevance rating of this proposal.
1184     * <p>
1185     * If not set, defaults to the lowest possible rating (1).
1186     * </p>
1187     * <p>
1188     * The completion engine creates instances of this class and sets
1189     * its properties; this method is not intended to be used by other clients.
1190     * </p>
1191     * 
1192     * @param rating relevance rating of this proposal; ratings are positive; higher means better
1193     */
1194    public void setRelevance(int rating) {
1195        if (rating <= 0) {
1196            throw new IllegalArgumentException  ();
1197        }
1198        this.relevance = rating;
1199    }
1200    
1201    /**
1202     * Returns the type signature or package name of the relevant
1203     * declaration in the context, or <code>null</code> if none.
1204     * <p>
1205     * This field is available for the following kinds of
1206     * completion proposals:
1207     * <ul>
1208     *  <li><code>ANNOTATION_ATTRIBUT_REF</code> - type signature
1209     * of the annotation that declares the attribute that is referenced</li>
1210     * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - type signature
1211     * of the type that is being subclassed or implemented</li>
1212     *  <li><code>FIELD_IMPORT</code> - type signature
1213     * of the type that declares the field that is imported</li>
1214     *  <li><code>FIELD_REF</code> - type signature
1215     * of the type that declares the field that is referenced</li>
1216     *  <li><code>METHOD_IMPORT</code> - type signature
1217     * of the type that declares the method that is imported</li>
1218     *  <li><code>METHOD_REF</code> - type signature
1219     * of the type that declares the method that is referenced</li>
1220     *  <li><code>METHOD_DECLARATION</code> - type signature
1221     * of the type that declares the method that is being
1222     * implemented or overridden</li>
1223     *  <li><code>PACKAGE_REF</code> - dot-based package 
1224     * name of the package that is referenced</li>
1225     *  <li><code>TYPE_IMPORT</code> - dot-based package 
1226     * name of the package containing the type that is imported</li>
1227     *  <li><code>TYPE_REF</code> - dot-based package 
1228     * name of the package containing the type that is referenced</li>
1229     *  <li><code>POTENTIAL_METHOD_DECLARATION</code> - type signature
1230     * of the type that declares the method that is being created</li>
1231     * </ul>
1232     * For kinds of completion proposals, this method returns
1233     * <code>null</code>. Clients must not modify the array
1234     * returned.
1235     * </p>
1236     * 
1237     * @return a type signature or a package name (depending
1238     * on the kind of completion), or <code>null</code> if none
1239     * @see Signature
1240     */
1241    public char[] getDeclarationSignature() {
1242        return this.declarationSignature;
1243    }
1244    
1245    /**
1246     * Returns the key of the relevant
1247     * declaration in the context, or <code>null</code> if none.
1248     * <p>
1249     * This field is available for the following kinds of
1250     * completion proposals:
1251     * <ul>
1252     * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - key
1253     * of the type that is being subclassed or implemented</li>
1254     *  <li><code>METHOD_DECLARATION</code> - key
1255     * of the type that declares the method that is being
1256     * implemented or overridden</li>
1257     * </ul>
1258     * For kinds of completion proposals, this method returns
1259     * <code>null</code>. Clients must not modify the array
1260     * returned.
1261     * </p>
1262     * 
1263     * @return a key, or <code>null</code> if none
1264     * @see org.eclipse.jdt.core.dom.ASTParser#createASTs(ICompilationUnit[], String[], org.eclipse.jdt.core.dom.ASTRequestor, IProgressMonitor)
1265     * @since 3.1
1266     */
1267    public char[] getDeclarationKey() {
1268        return this.declarationKey;
1269    }
1270    
1271    /**
1272     * Sets the type or package signature of the relevant
1273     * declaration in the context, or <code>null</code> if none.
1274     * <p>
1275     * If not set, defaults to none.
1276     * </p>
1277     * <p>
1278     * The completion engine creates instances of this class and sets
1279     * its properties; this method is not intended to be used by other clients.
1280     * </p>
1281     * 
1282     * @param signature the type or package signature, or
1283     * <code>null</code> if none
1284     */
1285    public void setDeclarationSignature(char[] signature) {
1286        this.declarationSignature = signature;
1287    }
1288    
1289    /**
1290     * Sets the type or package key of the relevant
1291     * declaration in the context, or <code>null</code> if none.
1292     * <p>
1293     * If not set, defaults to none.
1294     * </p>
1295     * <p>
1296     * The completion engine creates instances of this class and sets
1297     * its properties; this method is not intended to be used by other clients.
1298     * </p>
1299     * 
1300     * @param key the type or package key, or
1301     * <code>null</code> if none
1302     * @since 3.1
1303     */
1304    public void setDeclarationKey(char[] key) {
1305        this.declarationKey = key;
1306    }
1307    
1308    /**
1309     * Returns the simple name of the method, field,
1310     * member, or variable relevant in the context, or
1311     * <code>null</code> if none.
1312     * <p>
1313     * This field is available for the following kinds of
1314     * completion proposals:
1315     * <ul>
1316     *  <li><code>ANNOTATION_ATTRIBUT_REF</code> - the name of the attribute</li>
1317     *  <li><code>FIELD_IMPORT</code> - the name of the field</li>
1318     *  <li><code>FIELD_REF</code> - the name of the field</li>
1319     *  <li><code>KEYWORD</code> - the keyword</li>
1320     *  <li><code>LABEL_REF</code> - the name of the label</li>
1321     *  <li><code>LOCAL_VARIABLE_REF</code> - the name of the local variable</li>
1322     *  <li><code>METHOD_IMPORT</code> - the name of the method</li>
1323     *  <li><code>METHOD_REF</code> - the name of the method (the type simple name for constructor)</li>
1324     *  <li><code>METHOD_DECLARATION</code> - the name of the method (the type simple name for constructor)</li>
1325     *  <li><code>VARIABLE_DECLARATION</code> - the name of the variable</li>
1326     *  <li><code>POTENTIAL_METHOD_DECLARATION</code> - the name of the method</li>
1327     * </ul>
1328     * For kinds of completion proposals, this method returns
1329     * <code>null</code>. Clients must not modify the array
1330     * returned.
1331     * </p>
1332     * 
1333     * @return the keyword, field, method, local variable, or member
1334     * name, or <code>null</code> if none
1335     */
1336    public char[] getName() {
1337        return this.name;
1338    }
1339    
1340    
1341    /**
1342     * Sets the simple name of the method (type simple name for constructor), field,
1343     * member, or variable relevant in the context, or
1344     * <code>null</code> if none.
1345     * <p>
1346     * If not set, defaults to none.
1347     * </p>
1348     * <p>
1349     * The completion engine creates instances of this class and sets
1350     * its properties; this method is not intended to be used by other clients.
1351     * </p>
1352     * 
1353     * @param name the keyword, field, method, local variable,
1354     * or member name, or <code>null</code> if none
1355     */
1356    public void setName(char[] name) {
1357        this.name = name;
1358    }
1359    
1360    /**
1361     * Returns the signature of the method or type
1362     * relevant in the context, or <code>null</code> if none.
1363     * <p>
1364     * This field is available for the following kinds of
1365     * completion proposals:
1366     * <ul>
1367     * <li><code>ANNOTATION_ATTRIBUT_REF</code> - the type signature
1368     * of the referenced attribute's type</li>
1369     * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - method signature
1370     * of the constructor that is being invoked</li>
1371     *  <li><code>FIELD_IMPORT</code> - the type signature
1372     * of the referenced field's type</li>
1373     *  <li><code>FIELD_REF</code> - the type signature
1374     * of the referenced field's type</li>
1375     *  <li><code>LOCAL_VARIABLE_REF</code> - the type signature
1376     * of the referenced local variable's type</li>
1377     *  <li><code>METHOD_IMPORT</code> - method signature
1378     * of the method that is imported</li>
1379     *  <li><code>METHOD_REF</code> - method signature
1380     * of the method that is referenced</li>
1381     *  <li><code>METHOD_DECLARATION</code> - method signature
1382     * of the method that is being implemented or overridden</li>
1383     *  <li><code>TYPE_IMPORT</code> - type signature
1384     * of the type that is imported</li>
1385     *  <li><code>TYPE_REF</code> - type signature
1386     * of the type that is referenced</li>
1387     *  <li><code>VARIABLE_DECLARATION</code> - the type signature
1388     * of the type of the variable being declared</li>
1389     *  <li><code>POTENTIAL_METHOD_DECLARATION</code> - method signature
1390     * of the method that is being created</li>
1391     * </ul>
1392     * For kinds of completion proposals, this method returns
1393     * <code>null</code>. Clients must not modify the array
1394     * returned.
1395     * </p>
1396     * 
1397     * @return the signature, or <code>null</code> if none
1398     * @see Signature
1399     */
1400    public char[] getSignature() {
1401        return this.signature;
1402    }
1403    
1404    /**
1405     * Returns the key relevant in the context,
1406     * or <code>null</code> if none.
1407     * <p>
1408     * This field is available for the following kinds of
1409     * completion proposals:
1410     * <ul>
1411     * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - method key
1412     * of the constructor that is being invoked, or <code>null</code> if
1413     * the declaring type is an interface</li>
1414     *  <li><code>METHOD_DECLARATION</code> - method key
1415     * of the method that is being implemented or overridden</li>
1416     * </ul>
1417     * For kinds of completion proposals, this method returns
1418     * <code>null</code>. Clients must not modify the array
1419     * returned.
1420     * </p>
1421     * 
1422     * @return the key, or <code>null</code> if none
1423     * @see org.eclipse.jdt.core.dom.ASTParser#createASTs(ICompilationUnit[], String[], org.eclipse.jdt.core.dom.ASTRequestor, IProgressMonitor)
1424     * @since 3.1
1425     */
1426    public char[] getKey() {
1427        return this.key;
1428    }
1429    
1430//  /**
1431//   * Returns the package name of the relevant
1432//   * declaration in the context, or <code>null</code> if none.
1433//   * <p>
1434//   * This field is available for the following kinds of
1435//   * completion proposals:
1436//   * <ul>
1437//   * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - the dot-based package name
1438//   * of the type that is being subclassed or implemented</li>
1439//   *  <li><code>FIELD_REF</code> - the dot-based package name
1440//   * of the type that declares the field that is referenced</li>
1441//   *  <li><code>METHOD_REF</code> - the dot-based package name
1442//   * of the type that declares the method that is referenced</li>
1443//   *  <li><code>METHOD_DECLARATION</code> - the dot-based package name
1444//   * of the type that declares the method that is being
1445//   * implemented or overridden</li>
1446//   * </ul>
1447//   * For kinds of completion proposals, this method returns
1448//   * <code>null</code>. Clients must not modify the array
1449//   * returned.
1450//   * </p>
1451//   * 
1452//   * @return the dot-based package name, or
1453//   * <code>null</code> if none
1454//   * @see #getDeclarationSignature()
1455//   * @see #getSignature()
1456//   * 
1457//   * @since 3.1
1458//   */
1459//  public char[] getDeclarationPackageName() {
1460//      return this.declarationPackageName;
1461//  }
1462//  
1463//  /**
1464//   * Returns the type name of the relevant
1465//   * declaration in the context without the package fragment,
1466//   * or <code>null</code> if none. 
1467//   * <p>
1468//   * This field is available for the following kinds of
1469//   * completion proposals:
1470//   * <ul>
1471//   * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - the dot-based type name
1472//   * of the type that is being subclassed or implemented</li>
1473//   *  <li><code>FIELD_REF</code> - the dot-based type name
1474//   * of the type that declares the field that is referenced
1475//   * or an anonymous type instantiation ("new X(){}") if it is an anonymous type</li>
1476//   *  <li><code>METHOD_REF</code> - the dot-based type name
1477//   * of the type that declares the method that is referenced
1478//   * or an anonymous type instantiation ("new X(){}") if it is an anonymous type</li>
1479//   *  <li><code>METHOD_DECLARATION</code> - the dot-based type name
1480//   * of the type that declares the method that is being
1481//   * implemented or overridden</li>
1482//   * </ul>
1483//   * For kinds of completion proposals, this method returns
1484//   * <code>null</code>. Clients must not modify the array
1485//   * returned.
1486//   * </p>
1487//   * 
1488//   * @return the dot-based package name, or
1489//   * <code>null</code> if none
1490//   * @see #getDeclarationSignature()
1491//   * @see #getSignature()
1492//   * 
1493//   * @since 3.1
1494//   */
1495//  public char[] getDeclarationTypeName() {
1496//      return this.declarationTypeName;
1497//  }
1498//  
1499//  /**
1500//   * Returns the package name of the method or type
1501//   * relevant in the context, or <code>null</code> if none.
1502//   * <p>
1503//   * This field is available for the following kinds of
1504//   * completion proposals:
1505//   * <ul>
1506//   *  <li><code>FIELD_REF</code> - the dot-based package name
1507//   * of the referenced field's type</li>
1508//   *  <li><code>LOCAL_VARIABLE_REF</code> - the dot-based package name
1509//   * of the referenced local variable's type</li>
1510//   *  <li><code>METHOD_REF</code> -  the dot-based package name
1511//   * of the return type of the method that is referenced</li>
1512//   *  <li><code>METHOD_DECLARATION</code> - the dot-based package name
1513//   * of the return type of the method that is being implemented
1514//   * or overridden</li>
1515//   *  <li><code>PACKAGE_REF</code> - the dot-based package name
1516//   * of the package that is referenced</li>
1517//   *  <li><code>TYPE_REF</code> - the dot-based package name
1518//   * of the type that is referenced</li>
1519//   *  <li><code>VARIABLE_DECLARATION</code> - the dot-based package name
1520//   * of the type of the variable being declared</li>
1521//   * </ul>
1522//   * For kinds of completion proposals, this method returns
1523//   * <code>null</code>. Clients must not modify the array
1524//   * returned.
1525//   * </p>
1526//   * 
1527//   * @return the package name, or <code>null</code> if none
1528//   * 
1529//   * @see #getDeclarationSignature()
1530//   * @see #getSignature()
1531//   * 
1532//   * @since 3.1
1533//   */
1534//  public char[] getPackageName() {
1535//      return this.packageName;
1536//  }
1537//  
1538//  /**
1539//   * Returns the type name without the package fragment of the method or type
1540//   * relevant in the context, or <code>null</code> if none.
1541//   * <p>
1542//   * This field is available for the following kinds of
1543//   * completion proposals:
1544//   * <ul>
1545//   *  <li><code>FIELD_REF</code> - the dot-based type name
1546//   * of the referenced field's type</li>
1547//   *  <li><code>LOCAL_VARIABLE_REF</code> - the dot-based type name
1548//   * of the referenced local variable's type</li>
1549//   *  <li><code>METHOD_REF</code> -  the dot-based type name
1550//   * of the return type of the method that is referenced</li>
1551//   *  <li><code>METHOD_DECLARATION</code> - the dot-based type name
1552//   * of the return type of the method that is being implemented
1553//   * or overridden</li>
1554//   *  <li><code>TYPE_REF</code> - the dot-based type name
1555//   * of the type that is referenced</li>
1556//   *  <li><code>VARIABLE_DECLARATION</code> - the dot-based package name
1557//   * of the type of the variable being declared</li>
1558//   * </ul>
1559//   * For kinds of completion proposals, this method returns
1560//   * <code>null</code>. Clients must not modify the array
1561//   * returned.
1562//   * </p>
1563//   * 
1564//   * @return the package name, or <code>null</code> if none
1565//   * 
1566//   * @see #getDeclarationSignature()
1567//   * @see #getSignature()
1568//   * 
1569//   * @since 3.1
1570//   */
1571//  public char[] getTypeName() {
1572//      return this.typeName;
1573//  }
1574//  
1575//  /**
1576//   * Returns the parameter package names of the method 
1577//   * relevant in the context, or <code>null</code> if none.
1578//   * <p>
1579//   * This field is available for the following kinds of
1580//   * completion proposals:
1581//   * <ul>
1582//   *  <li><code>ANONYMOUS_CLASS_DECLARATION</code> - parameter package names
1583//   * of the constructor that is being invoked</li>
1584//   *  <li><code>METHOD_REF</code> - parameter package names
1585//   * of the method that is referenced</li>
1586//   *  <li><code>METHOD_DECLARATION</code> - parameter package names
1587//   * of the method that is being implemented or overridden</li>
1588//   * </ul>
1589//   * For kinds of completion proposals, this method returns
1590//   * <code>null</code>. Clients must not modify the array
1591//   * returned.
1592//   * </p>
1593//   * 
1594//   * @return the package name, or <code>null</code> if none
1595//   * 
1596//   * @see #getDeclarationSignature()
1597//   * @see #getSignature()
1598//   * 
1599//   * @since 3.1
1600//   */
1601//  public char[][] getParameterPackageNames() {
1602//      return this.parameterPackageNames;
1603//  }
1604//  
1605//  /**
1606//   * Returns the parameter type names without the package fragment of
1607//   * the method relevant in the context, or <code>null</code> if none.
1608//   * <p>
1609//   * This field is available for the following kinds of
1610//   * completion proposals:
1611//   * <ul>
1612//   *  <li><code>ANONYMOUS_CLASS_DECLARATION</code> - parameter type names
1613//   * of the constructor that is being invoked</li>
1614//   *  <li><code>METHOD_REF</code> - parameter type names
1615//   * of the method that is referenced</li>
1616//   *  <li><code>METHOD_DECLARATION</code> - parameter type names
1617//   * of the method that is being implemented or overridden</li>
1618//   * </ul>
1619//   * For kinds of completion proposals, this method returns
1620//   * <code>null</code>. Clients must not modify the array
1621//   * returned.
1622//   * </p>
1623//   * 
1624//   * @return the package name, or <code>null</code> if none
1625//   * 
1626//   * @see #getDeclarationSignature()
1627//   * @see #getSignature()
1628//   * 
1629//   * @since 3.1
1630//   */
1631//  public char[][] getParameterTypeNames() {
1632//      return this.parameterTypeNames;
1633//  }
1634    
1635    /**
1636     * Sets the signature of the method, field type, member type,
1637     * relevant in the context, or <code>null</code> if none.
1638     * <p>
1639     * If not set, defaults to none.
1640     * </p>
1641     * <p>
1642     * The completion engine creates instances of this class and sets
1643     * its properties; this method is not intended to be used by other clients.
1644     * </p>
1645     * 
1646     * @param signature the signature, or <code>null</code> if none
1647     */
1648    public void setSignature(char[] signature) {
1649        this.signature = signature;
1650    }
1651    
1652    /**
1653     * Sets the key of the method, field type, member type,
1654     * relevant in the context, or <code>null</code> if none.
1655     * <p>
1656     * If not set, defaults to none.
1657     * </p>
1658     * <p>
1659     * The completion engine creates instances of this class and sets
1660     * its properties; this method is not intended to be used by other clients.
1661     * </p>
1662     * 
1663     * @param key the key, or <code>null</code> if none
1664     * @since 3.1
1665     */
1666    public void setKey(char[] key) {
1667        this.key = key;
1668    }
1669    
1670    /**
1671     * Returns the modifier flags relevant in the context, or
1672     * <code>Flags.AccDefault</code> if none.
1673     * <p>
1674     * This field is available for the following kinds of
1675     * completion proposals:
1676     * <ul>
1677     * <li><code>ANNOTATION_ATTRIBUT_REF</code> - modifier flags
1678     * of the attribute that is referenced; 
1679     * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - modifier flags
1680     * of the constructor that is referenced</li>
1681     *  <li><code>FIELD_IMPORT</code> - modifier flags
1682     * of the field that is imported.</li>
1683     *  <li><code>FIELD_REF</code> - modifier flags
1684     * of the field that is referenced; 
1685     * <code>Flags.AccEnum</code> can be used to recognize
1686     * references to enum constants
1687     * </li>
1688     *  <li><code>KEYWORD</code> - modifier flag
1689     * corresponding to the modifier keyword</li>
1690     *  <li><code>LOCAL_VARIABLE_REF</code> - modifier flags
1691     * of the local variable that is referenced</li>
1692     *  <li><code>METHOD_IMPORT</code> - modifier flags
1693     * of the method that is imported;
1694     *  </li>
1695     *  <li><code>METHOD_REF</code> - modifier flags
1696     * of the method that is referenced;
1697     * <code>Flags.AccAnnotation</code> can be used to recognize
1698     * references to annotation type members
1699     * </li>
1700     * <li><code>METHOD_DECLARATION</code> - modifier flags
1701     * for the method that is being implemented or overridden</li>
1702     * <li><code>TYPE_IMPORT</code> - modifier flags
1703     * of the type that is imported; <code>Flags.AccInterface</code>
1704     * can be used to recognize references to interfaces, 
1705     * <code>Flags.AccEnum</code> enum types,
1706     * and <code>Flags.AccAnnotation</code> annotation types</li>
1707     * <li><code>TYPE_REF</code> - modifier flags
1708     * of the type that is referenced; <code>Flags.AccInterface</code>
1709     * can be used to recognize references to interfaces, 
1710     * <code>Flags.AccEnum</code> enum types,
1711     * and <code>Flags.AccAnnotation</code> annotation types
1712     * </li>
1713     *  <li><code>VARIABLE_DECLARATION</code> - modifier flags
1714     * for the variable being declared</li>
1715     *  <li><code>POTENTIAL_METHOD_DECLARATION</code> - modifier flags
1716     * for the method that is being created</li>
1717     * </ul>
1718     * For other kinds of completion proposals, this method returns
1719     * <code>Flags.AccDefault</code>.
1720     * </p>
1721     * 
1722     * @return the modifier flags, or
1723     * <code>Flags.AccDefault</code> if none
1724     * @see Flags
1725     */
1726    public int getFlags() {
1727        return this.flags;
1728    }
1729    
1730    /**
1731     * Sets the modifier flags relevant in the context.
1732     * <p>
1733     * If not set, defaults to none.
1734     * </p>
1735     * <p>
1736     * The completion engine creates instances of this class and sets
1737     * its properties; this method is not intended to be used by other clients.
1738     * </p>
1739     * 
1740     * @param flags the modifier flags, or
1741     * <code>Flags.AccDefault</code> if none
1742     */
1743    public void setFlags(int flags) {
1744        this.flags = flags;
1745    }
1746    
1747    /**
1748     * Returns the required completion proposals.
1749     * The proposal can be apply only if these required completion proposals are also applied.
1750     * If the required proposal aren't applied the completion could create completion problems.
1751     * 
1752     * <p>
1753     * This field is available for the following kinds of
1754     * completion proposals:
1755     * <ul>
1756     *  <li><code>FIELD_REF</code> - The allowed required proposals for this kind are:
1757     *   <ul>
1758     *    <li><code>TYPE_REF</code></li>
1759     *    <li><code>TYPE_IMPORT</code></li>
1760     *    <li><code>FIELD_IMPORT</code></li>
1761     *   </ul>
1762     * </li>
1763     *  <li><code>METHOD_REF</code> - The allowed required proposals for this kind are:
1764     *   <ul>
1765     *    <li><code>TYPE_REF</code></li>
1766     *    <li><code>TYPE_IMPORT</code></li>
1767     *    <li><code>METHOD_IMPORT</code></li>
1768     *   </ul>
1769     *  </li>
1770     * </ul>
1771     * </p>
1772     * <p>
1773     * Other kinds of required proposals will be returned in the future, therefore clients of this
1774     * API must allow with {@link CompletionRequestor#setAllowsRequiredProposals(int, int, boolean)} 
1775     * only kinds which are in this list to avoid unexpected results in the future.
1776     * </p>
1777     * <p>
1778     * A required completion proposal cannot have required completion proposals.
1779     * </p>
1780     * 
1781     * @return the required completion proposals, or <code>null</code> if none.
1782     * 
1783     * @see CompletionRequestor#setAllowsRequiredProposals(int, int,boolean)
1784     * 
1785     * @since 3.3
1786     */
1787    public CompletionProposal[] getRequiredProposals() {
1788        return this.requiredProposals;
1789    }
1790    
1791    
1792    /**
1793     * Sets the list of required completion proposals, or <code>null</code> if none.
1794     * <p>
1795     * If not set, defaults to none.
1796     * </p>
1797     * <p>
1798     * The completion engine creates instances of this class and sets
1799     * its properties; this method is not intended to be used by other clients.
1800     * </p>
1801     * 
1802     * @param proposals the list of required completion proposals, or
1803     * <code>null</code> if none
1804     * @since 3.3
1805     */
1806    public void setRequiredProposals(CompletionProposal[] proposals) {
1807        this.requiredProposals = proposals;
1808    }
1809    
1810    /**
1811     * Finds the method parameter names.
1812     * This information is relevant to method reference (and
1813     * method declaration proposals). Returns <code>null</code>
1814     * if not available or not relevant.
1815     * <p>
1816     * The client must not modify the array returned.
1817     * </p>
1818     * <p>
1819     * <b>Note that this is an expensive thing to compute, which may require
1820     * parsing Java source files, etc. Use sparingly.</b>
1821     * </p>
1822     * 
1823     * @param monitor the progress monitor, or <code>null</code> if none
1824     * @return the parameter names, or <code>null</code> if none
1825     * or not available or not relevant
1826     */
1827    public char[][] findParameterNames(IProgressMonitor monitor) {
1828        if (!this.parameterNamesComputed) {
1829            this.parameterNamesComputed = true;
1830            
1831            switch(this.completionKind) {
1832                case ANONYMOUS_CLASS_DECLARATION:
1833                    try {
1834                        this.parameterNames = this.findMethodParameterNames(
1835                                this.declarationPackageName,
1836                                this.declarationTypeName,
1837                                CharOperation.lastSegment(this.declarationTypeName, '.'),
1838                                Signature.getParameterTypes(this.originalSignature == null ? this.signature : this.originalSignature));
1839                    } catch(IllegalArgumentException   e) {
1840                        // protection for invalid signature
1841                        if(this.parameterTypeNames != null) {
1842                            this.parameterNames =  this.createDefaultParameterNames(this.parameterTypeNames.length);
1843                        } else {
1844                            this.parameterNames = null;
1845                        }
1846                    }
1847                    break;
1848                case METHOD_REF:
1849                    try {
1850                        this.parameterNames = this.findMethodParameterNames(
1851                                this.declarationPackageName,
1852                                this.declarationTypeName,
1853                                this.name,
1854                                Signature.getParameterTypes(this.originalSignature == null ? this.signature : this.originalSignature));
1855                    } catch(IllegalArgumentException   e) {
1856                        // protection for invalid signature
1857                        if(this.parameterTypeNames != null) {
1858                            this.parameterNames =  this.createDefaultParameterNames(this.parameterTypeNames.length);
1859                        } else {
1860                            this.parameterNames = null;
1861                        }
1862                    }
1863                    break;
1864                case METHOD_DECLARATION:
1865                    try {
1866                        this.parameterNames = this.findMethodParameterNames(
1867                                this.declarationPackageName,
1868                                this.declarationTypeName,
1869                                this.name,
1870                                Signature.getParameterTypes(this.originalSignature == null ? this.signature : this.originalSignature));
1871                    } catch(IllegalArgumentException   e) {
1872                        // protection for invalid signature
1873                        if(this.parameterTypeNames != null) {
1874                            this.parameterNames =  this.createDefaultParameterNames(this.parameterTypeNames.length);
1875                        } else {
1876                            this.parameterNames = null;
1877                        }
1878                    }
1879                    if(this.parameterNames != null) {
1880                        this.updateCompletion = true;
1881                    }
1882                    break;
1883            }           
1884        }
1885        return this.parameterNames;
1886    }
1887    
1888    /**
1889     * Sets the method parameter names.
1890     * This information is relevant to method reference (and
1891     * method declaration proposals).
1892     * <p>
1893     * The completion engine creates instances of this class and sets
1894     * its properties; this method is not intended to be used by other clients.
1895     * </p>
1896     * 
1897     * @param parameterNames the parameter names, or <code>null</code> if none
1898     */
1899    public void setParameterNames(char[][] parameterNames) {
1900        this.parameterNames = parameterNames;
1901        this.parameterNamesComputed = true;
1902    }
1903    
1904    /**
1905     * Returns the accessibility of the proposal.
1906     * <p>
1907     * This field is available for the following kinds of
1908     * completion proposals:
1909     * <ul>
1910     *  <li><code>TYPE_REF</code> - accessibility of the type</li>
1911     * </ul>
1912     * For these kinds of completion proposals, this method returns
1913     * {@link IAccessRule#K_ACCESSIBLE} or {@link IAccessRule#K_DISCOURAGED}
1914     * or {@link IAccessRule#K_NON_ACCESSIBLE}.
1915     * By default this method return {@link IAccessRule#K_ACCESSIBLE}.
1916     * </p>
1917     * 
1918     * @see IAccessRule
1919     * 
1920     * @return the accessibility of the proposal
1921     * 
1922     * @since 3.1
1923     */
1924    public int getAccessibility() {
1925        return this.accessibility;
1926    }
1927    
1928    /**
1929     * Returns whether this proposal is a constructor.
1930     * <p>
1931     * This field is available for the following kinds of
1932     * completion proposals:
1933     * <ul>
1934     * <li><code>METHOD_REF</code> - return <code>true</code>
1935     * if the referenced method is a constructor</li>
1936     *  <li><code>METHOD_DECLARATION</code> - return <code>true</code>
1937     * if the declared method is a constructor</li>
1938     * </ul>
1939     * For kinds of completion proposals, this method returns
1940     * <code>false</code>.
1941     * </p>
1942     * 
1943     * @return <code>true</code> if the proposal is a constructor.
1944     * @since 3.1
1945     */
1946    public boolean isConstructor() {
1947        return this.isConstructor;
1948    }
1949    
1950    public String   toString() {
1951        StringBuffer   buffer = new StringBuffer  ();
1952        buffer.append('[');
1953        switch(this.completionKind) {
1954            case CompletionProposal.ANONYMOUS_CLASS_DECLARATION :
1955                buffer.append("ANONYMOUS_CLASS_DECLARATION"); //$NON-NLS-1$
1956                break;
1957            case CompletionProposal.FIELD_REF :
1958                buffer.append("FIELD_REF"); //$NON-NLS-1$
1959                break;
1960            case CompletionProposal.KEYWORD :
1961                buffer.append("KEYWORD"); //$NON-NLS-1$
1962                break;
1963            case CompletionProposal.LABEL_REF :
1964                buffer.append("LABEL_REF"); //$NON-NLS-1$
1965                break;
1966            case CompletionProposal.LOCAL_VARIABLE_REF :
1967                buffer.append("LOCAL_VARIABLE_REF"); //$NON-NLS-1$
1968                break;
1969            case CompletionProposal.METHOD_DECLARATION :
1970                buffer.append("METHOD_DECLARATION"); //$NON-NLS-1$
1971                if(this.isConstructor) {
1972                    buffer.append("<CONSTRUCTOR>"); //$NON-NLS-1$
1973                }
1974                break;
1975            case CompletionProposal.METHOD_REF :
1976                buffer.append("METHOD_REF"); //$NON-NLS-1$
1977                if(this.isConstructor) {
1978                    buffer.append("<CONSTRUCTOR>"); //$NON-NLS-1$
1979                }
1980                break;
1981            case CompletionProposal.PACKAGE_REF :
1982                buffer.append("PACKAGE_REF"); //$NON-NLS-1$
1983                break;
1984            case CompletionProposal.TYPE_REF :
1985                buffer.append("TYPE_REF"); //$NON-NLS-1$
1986                break;
1987            case CompletionProposal.VARIABLE_DECLARATION :
1988                buffer.append("VARIABLE_DECLARATION"); //$NON-NLS-1$
1989                break;
1990            case CompletionProposal.POTENTIAL_METHOD_DECLARATION :
1991                buffer.append("POTENTIAL_METHOD_DECLARATION"); //$NON-NLS-1$
1992                break;
1993            case CompletionProposal.METHOD_NAME_REFERENCE :
1994                buffer.append("METHOD_IMPORT"); //$NON-NLS-1$
1995                break;
1996            case CompletionProposal.ANNOTATION_ATTRIBUTE_REF :
1997                buffer.append("ANNOTATION_ATTRIBUTE_REF"); //$NON-NLS-1$
1998                break;
1999            case CompletionProposal.JAVADOC_BLOCK_TAG :
2000                buffer.append("JAVADOC_BLOCK_TAG"); //$NON-NLS-1$
2001                break;
2002            case CompletionProposal.JAVADOC_INLINE_TAG :
2003                buffer.append("JAVADOC_INLINE_TAG"); //$NON-NLS-1$
2004                break;
2005            case CompletionProposal.JAVADOC_FIELD_REF:
2006                buffer.append("JAVADOC_FIELD_REF"); //$NON-NLS-1$
2007                break;
2008            case CompletionProposal.JAVADOC_METHOD_REF :
2009                buffer.append("JAVADOC_METHOD_REF"); //$NON-NLS-1$
2010                break;
2011            case CompletionProposal.JAVADOC_TYPE_REF :
2012                buffer.append("JAVADOC_TYPE_REF"); //$NON-NLS-1$
2013                break;
2014            case CompletionProposal.JAVADOC_PARAM_REF :
2015                buffer.append("JAVADOC_PARAM_REF"); //$NON-NLS-1$
2016                break;
2017            case CompletionProposal.JAVADOC_VALUE_REF :
2018                buffer.append("JAVADOC_VALUE_REF"); //$NON-NLS-1$
2019                break;
2020            case CompletionProposal.FIELD_IMPORT :
2021                buffer.append("FIELD_IMPORT"); //$NON-NLS-1$
2022                break;
2023            case CompletionProposal.METHOD_IMPORT :
2024                buffer.append("METHOD_IMPORT"); //$NON-NLS-1$
2025                break;
2026            case CompletionProposal.TYPE_IMPORT :
2027                buffer.append("TYPE_IMPORT"); //$NON-NLS-1$
2028                break;
2029            default :
2030                buffer.append("PROPOSAL"); //$NON-NLS-1$
2031                break;
2032                
2033        }
2034        buffer.append("]{completion:"); //$NON-NLS-1$
2035        if (this.completion != null) buffer.append(this.completion);
2036        buffer.append(", declSign:"); //$NON-NLS-1$
2037        if (this.declarationSignature != null) buffer.append(this.declarationSignature);  
2038        buffer.append(", sign:"); //$NON-NLS-1$
2039        if (this.signature != null) buffer.append(this.signature);
2040        buffer.append(", declKey:"); //$NON-NLS-1$
2041        if (this.declarationKey != null) buffer.append(this.declarationKey);
2042        buffer.append(", key:"); //$NON-NLS-1$
2043        if (this.key != null) buffer.append(key);
2044        buffer.append(", name:"); //$NON-NLS-1$
2045        if (this.name != null) buffer.append(this.name);
2046        buffer.append(", ["); //$NON-NLS-1$
2047        buffer.append(this.replaceStart);
2048        buffer.append(',');
2049        buffer.append(this.replaceEnd);
2050        buffer.append("], relevance="); //$NON-NLS-1$
2051        buffer.append(this.relevance);
2052        buffer.append('}');
2053        return buffer.toString();
2054    }
2055}
2056
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags