dbaf2d9e1449e2ea2495d2540c32bfaa5e0315d1
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / CompletionProposal.java
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
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package net.sourceforge.phpdt.core;
12
13 import org.eclipse.core.runtime.IProgressMonitor;
14 import net.sourceforge.phpdt.core.compiler.CharOperation;
15
16 /**
17  * Completion proposal.
18  * <p>
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
28  * to make a choice.
29  * </p>
30  * <p>
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.
43  * </p>
44  * <p>
45  * The completion engine creates instances of this class; it is not
46  * intended to be used by other clients.
47  * </p>
48  * 
49  * @see ICodeAssist#codeComplete(int, CompletionRequestor)
50  * @since 3.0
51  */
52 public final class CompletionProposal {
53
54         /**
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>.
59          * <p>
60          * The following additional context information is available
61          * for this kind of completion proposal at little extra cost:
62          * <ul>
63          * <li>{@link #getDeclarationSignature()} -
64          * the type signature of the type being implemented or subclassed
65          * </li>
66          * </li>
67          * <li>{@link #getSignature()} -
68          * the method signature of the constructor that is referenced
69          * </li>
70          * <li>{@link #getFlags()} -
71          * the modifiers flags of the constructor that is referenced
72          * </li>
73          * </ul>
74          * </p>
75          * 
76          * @see #getKind()
77          */
78         public static final int ANONYMOUS_CLASS_DECLARATION = 1;
79
80         /**
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>.
85          * <p>
86          * The following additional context information is available
87          * for this kind of completion proposal at little extra cost:
88          * <ul>
89          * <li>{@link #getDeclarationSignature()} -
90          * the type signature of the type that declares the field that is referenced
91          * </li>
92          * <li>{@link #getFlags()} -
93          * the modifiers flags (including ACC_ENUM) of the field that is referenced
94          * </li>
95          * <li>{@link #getName()} -
96          * the simple name of the field that is referenced
97          * </li>
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
101          * is declared)
102          * </li>
103          * </ul>
104          * </p>
105          * 
106          * @see #getKind()
107          */
108         public static final int FIELD_REF = 2;
109
110         /**
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>.
115          * <p>
116          * The following additional context information is available
117          * for this kind of completion proposal at little extra cost:
118          * <ul>
119          * <li>{@link #getName()} -
120          * the keyword token
121          * </li>
122          * <li>{@link #getFlags()} -
123          * the corresponding modifier flags if the keyword is a modifier
124          * </li>
125          * </ul>
126          * </p>
127          * 
128          * @see #getKind()
129          */
130         public static final int KEYWORD = 3;
131
132         /**
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>.
137          * <p>
138          * The following additional context information is available
139          * for this kind of completion proposal at little extra cost:
140          * <ul>
141          * <li>{@link #getName()} -
142          * the simple name of the label that is referenced
143          * </li>
144          * </ul>
145          * </p>
146          * 
147          * @see #getKind()
148          */
149         public static final int LABEL_REF = 4;
150
151         /**
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>.
156          * <p>
157          * The following additional context information is available
158          * for this kind of completion proposal at little extra cost:
159          * <ul>
160          * <li>{@link #getFlags()} -
161          * the modifiers flags of the local variable that is referenced
162          * </li>
163          * <li>{@link #getName()} -
164          * the simple name of the local variable that is referenced
165          * </li>
166          * <li>{@link #getSignature()} -
167          * the type signature of the local variable's type
168          * </li>
169          * </ul>
170          * </p>
171          * 
172          * @see #getKind()
173          */
174         public static final int LOCAL_VARIABLE_REF = 5;
175
176         /**
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>.
181          * <p>
182          * The following additional context information is available
183          * for this kind of completion proposal at little extra cost:
184          * <ul>
185          * <li>{@link #getDeclarationSignature()} -
186          * the type signature of the type that declares the method that is referenced
187          * </li>
188          * <li>{@link #getFlags()} -
189          * the modifiers flags of the method that is referenced
190          * </li>
191          * <li>{@link #getName()} -
192          * the simple name of the method that is referenced
193          * </li>
194          * <li>{@link #getSignature()} -
195          * the method signature of the method that is referenced
196          * </li>
197          * </ul>
198          * </p>
199          * 
200          * @see #getKind()
201          */
202         public static final int METHOD_REF = 6;
203
204         /**
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>.
209          * <p>
210          * The following additional context information is available
211          * for this kind of completion proposal at little extra cost:
212          * <ul>
213          * <li>{@link #getDeclarationSignature()} -
214          * the type signature of the type that declares the
215          * method that is being overridden or implemented
216          * </li>
217          * <li>{@link #getName()} -
218          * the simple name of the method that is being overridden
219          * or implemented
220          * </li>
221          * <li>{@link #getSignature()} -
222          * the method signature of the method that is being
223          * overridden or implemented
224          * </li>
225          * <li>{@link #getFlags()} -
226          * the modifiers flags of the method that is being
227          * overridden or implemented
228          * </li>
229          * </ul>
230          * </p>
231          * 
232          * @see #getKind()
233          */
234         public static final int METHOD_DECLARATION = 7;
235
236         /**
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>.
241          * <p>
242          * The following additional context information is available
243          * for this kind of completion proposal at little extra cost:
244          * <ul>
245          * <li>{@link #getDeclarationSignature()} -
246          * the dot-based package signature of the package that is referenced
247          * </li>
248          * </ul>
249          * </p>
250          * 
251          * @see #getKind()
252          */
253         public static final int PACKAGE_REF = 8;
254
255         /**
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>.
262          * <p>
263          * The following additional context information is available
264          * for this kind of completion proposal at little extra cost:
265          * <ul>
266          * <li>{@link #getDeclarationSignature()} -
267          * the dot-based package signature of the package that contains
268          * the type that is referenced
269          * </li>
270          * <li>{@link #getSignature()} -
271          * the type signature of the type that is referenced
272          * </li>
273          * <li>{@link #getFlags()} -
274          * the modifiers flags (including Flags.AccInterface, AccEnum,
275          * and AccAnnotation) of the type that is referenced
276          * </li>
277          * </ul>
278          * </p>
279          * 
280          * @see #getKind()
281          */
282         public static final int TYPE_REF = 9;
283
284         /**
285          * Completion is a declaration of a variable (locals, parameters,
286          * fields, etc.).
287          * <p>
288          * The following additional context information is available
289          * for this kind of completion proposal at little extra cost:
290          * <ul>
291          * <li>{@link #getName()} -
292          * the simple name of the variable being declared
293          * </li>
294          * <li>{@link #getSignature()} -
295          * the type signature of the type of the variable
296          * being declared
297          * </li>
298          * <li>{@link #getFlags()} -
299          * the modifiers flags of the variable being declared
300          * </li>
301          * </ul>
302          * </p>
303          * @see #getKind()
304          */
305         public static final int VARIABLE_DECLARATION = 10;
306         
307         /**
308          * Kind of completion request.
309          */
310         private int completionKind;
311         
312         /**
313          * Offset in original buffer where ICodeAssist.codeComplete() was
314          * requested.
315          */
316         private int completionLocation;
317         
318         /**
319          * Start position (inclusive) of source range in original buffer 
320          * containing the relevant token
321          * defaults to empty subrange at [0,0).
322          */
323         private int tokenStart = 0;
324         
325         /**
326          * End position (exclusive) of source range in original buffer 
327          * containing the relevant token;
328          * defaults to empty subrange at [0,0).
329          */
330         private int tokenEnd = 0;
331         
332         /**
333          * Completion string; defaults to empty string.
334          */
335         private char[] completion = CharOperation.NO_CHAR;
336         
337         /**
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).
341          */
342         private int replaceStart = 0;
343         
344         /**
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).
348          */
349         private int replaceEnd = 0;
350         
351         /**
352          * Relevance rating; positive; higher means better;
353          * defaults to minimum rating.
354          */
355         private int relevance = 1;
356         
357         /**
358          * Signature of the relevant package or type declaration
359          * in the context, or <code>null</code> if none.
360          * Defaults to null.
361          */
362         private char[] declarationSignature = null;
363         
364         /**
365          * Simple name of the method, field,
366          * member, or variable relevant in the context, or
367          * <code>null</code> if none.
368          * Defaults to null.
369          */
370         private char[] name = null;
371         
372         /**
373          * Signature of the method, field type, member type,
374          * relevant in the context, or <code>null</code> if none.
375          * Defaults to null.
376          */
377         private char[] signature = null;
378         
379         /**
380          * Modifier flags relevant in the context, or
381          * <code>Flags.AccDefault</code> if none.
382          * Defaults to <code>Flags.AccDefault</code>.
383          */
384         private int flags = Flags.AccDefault;
385         
386         /**
387          * Parameter names (for method completions), or
388          * <code>null</code> if none. Lazily computed.
389          * Defaults to <code>null</code>.
390          */
391         private char[][] parameterNames = null;
392         
393         /**
394          * Indicates whether parameter names have been computed.
395          */
396         private boolean parameterNamesComputed = false;
397         
398         /**
399          * Creates a basic completion proposal. All instance
400          * field have plausible default values unless otherwise noted.
401          * <p>
402          * Note that the constructors for this class are internal to the
403          * Java model implementation. Clients cannot directly create
404          * CompletionProposal objects.
405          * </p>
406          * 
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
410          */
411         public static CompletionProposal create(int kind, int completionOffset) {
412                 return new CompletionProposal(kind, completionOffset);
413         }
414         
415         /**
416          * Creates a basic completion proposal. All instance
417          * field have plausible default values unless otherwise noted.
418          * <p>
419          * Note that the constructors for this class are internal to the
420          * Java model implementation. Clients cannot directly create
421          * CompletionProposal objects.
422          * </p>
423          * 
424          * @param kind one of the kind constants declared on this class
425          * @param completionLocation original offset of code completion request
426          */
427         CompletionProposal(int kind, int completionLocation) {
428                 if ((kind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION)
429                                 || (kind > CompletionProposal.VARIABLE_DECLARATION)) {
430                         throw new IllegalArgumentException();
431                 }
432                 if (this.completion == null || completionLocation < 0) {
433                         throw new IllegalArgumentException();
434                 }
435                 this.completionKind = kind;
436                 this.completionLocation = completionLocation;
437         }
438         
439         /**
440          * Returns the kind of completion being proposed.
441          * <p>
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.
447          * </p>
448          * 
449          * @return the kind; one of the kind constants
450          * declared on this class, or possibly a kind unknown
451          * to the caller
452          */
453         public int getKind() {
454                 return this.completionKind;
455         }
456         
457         /**
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>.
462          * 
463          * @return character index in source file buffer
464          * @see ICodeAssist#codeComplete(int,CompletionRequestor)
465          */
466         public int getCompletionLocation() {
467                 return this.completionLocation;
468         }
469         
470         /**
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.
480          * 
481          * @return character index of token start position (inclusive)
482          */
483         public int getTokenStart() {
484                 return this.tokenStart;
485         }
486         
487         /**
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
491          * range is empty
492          * (<code>getEndToken() == getStartToken()</code>).
493          * 
494          * @return character index of token end position (exclusive)
495          */
496         public int getTokenEnd() {
497                 return this.tokenEnd;
498         }
499         
500         /**
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.
509          * <p>
510          * If not set, defaults to empty subrange at [0,0).
511          * </p>
512          * 
513          * @param startIndex character index of token start position (inclusive)
514          * @param endIndex character index of token end position (exclusive)
515          */
516         public void setTokenRange(int startIndex, int endIndex) {
517                 if (startIndex < 0 || endIndex < startIndex) {
518                         throw new IllegalArgumentException();
519                 }
520                 this.tokenStart = startIndex;
521                 this.tokenEnd = endIndex;
522         }
523         
524         /**
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.
529          * <p>
530          * The client must not modify the array returned.
531          * </p>
532          * 
533          * @return the completion string
534          */
535         public char[] getCompletion() {
536                 return this.completion;
537         }
538         
539         /**
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.
544          * <p>
545          * If not set, defaults to an empty character array.
546          * </p>
547          * <p>
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.
550          * </p>
551          * 
552          * @param completion the completion string
553          */
554         public void setCompletion(char[] completion) {
555                 this.completion = completion;
556         }
557         
558         /**
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
564          * index.
565          * <p>
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.
575          * </p>
576          * 
577          * @return replacement start position (inclusive)
578          */
579         public int getReplaceStart() {
580                 return this.replaceStart;
581         }
582         
583         /**
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
589          * index.
590          * 
591          * @return replacement end position (exclusive)
592          */
593         public int getReplaceEnd() {
594                 return this.replaceEnd;
595         }
596         
597         /**
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
603          * index.
604          * <p>
605          * If not set, defaults to empty subrange at [0,0).
606          * </p>
607          * <p>
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.
610          * </p>
611          * 
612          * @param startIndex character index of replacement start position (inclusive)
613          * @param endIndex character index of replacement end position (exclusive)
614          */
615         public void setReplaceRange(int startIndex, int endIndex) {
616                 if (startIndex < 0 || endIndex < startIndex) {
617                         throw new IllegalArgumentException();
618                 }
619                 this.replaceStart = startIndex;
620                 this.replaceEnd = endIndex;
621         }
622         
623         /**
624          * Returns the relative relevance rating of this proposal.
625          * 
626          * @return relevance rating of this proposal; ratings are positive; higher means better
627          */
628         public int getRelevance() {
629                 return this.relevance;
630         }
631         
632         /**
633          * Sets the relative relevance rating of this proposal.
634          * <p>
635          * If not set, defaults to the lowest possible rating (1).
636          * </p>
637          * <p>
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.
640          * </p>
641          * 
642          * @param rating relevance rating of this proposal; ratings are positive; higher means better
643          */
644         public void setRelevance(int rating) {
645                 if (rating <= 0) {
646                         throw new IllegalArgumentException();
647                 }
648                 this.relevance = rating;
649         }
650         
651         /**
652          * Returns the type or package signature of the relevant
653          * declaration in the context, or <code>null</code> if none.
654          * <p>
655          * This field is available for the following kinds of
656          * completion proposals:
657          * <ul>
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>
671          * </ul>
672          * For kinds of completion proposals, this method returns
673          * <code>null</code>. Clients must not modify the array
674          * returned.
675          * </p>
676          * 
677          * @return the declaration signature, or
678          * <code>null</code> if none
679          * @see Signature
680          */
681         public char[] getDeclarationSignature() {
682                 return this.declarationSignature;
683         }
684         
685         /**
686          * Sets the type or package signature of the relevant
687          * declaration in the context, or <code>null</code> if none.
688          * <p>
689          * If not set, defaults to none.
690          * </p>
691          * <p>
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.
694          * </p>
695          * 
696          * @param signature the type or package signature, or
697          * <code>null</code> if none
698          */
699         public void setDeclarationSignature(char[] signature) {
700                 this.declarationSignature = signature;
701         }
702         
703         /**
704          * Returns the simple name of the method, field,
705          * member, or variable relevant in the context, or
706          * <code>null</code> if none.
707          * <p>
708          * This field is available for the following kinds of
709          * completion proposals:
710          * <ul>
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>
718          * </ul>
719          * For kinds of completion proposals, this method returns
720          * <code>null</code>. Clients must not modify the array
721          * returned.
722          * </p>
723          * 
724          * @return the keyword, field, method, local variable, or member
725          * name, or <code>null</code> if none
726          */
727         public char[] getName() {
728                 return this.name;
729         }
730         
731         
732         /**
733          * Sets the simple name of the method, field,
734          * member, or variable relevant in the context, or
735          * <code>null</code> if none.
736          * <p>
737          * If not set, defaults to none.
738          * </p>
739          * <p>
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.
742          * </p>
743          * 
744          * @param name the keyword, field, method, local variable,
745          * or member name, or <code>null</code> if none
746          */
747         public void setName(char[] name) {
748                 this.name = name;
749         }
750         
751         /**
752          * Returns the signature of the method or type
753          * relevant in the context, or <code>null</code> if none.
754          * <p>
755          * This field is available for the following kinds of
756          * completion proposals:
757          * <ul>
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>
772          * </ul>
773          * For kinds of completion proposals, this method returns
774          * <code>null</code>. Clients must not modify the array
775          * returned.
776          * </p>
777          * 
778          * @return the signature, or <code>null</code> if none
779          * @see Signature
780          */
781         public char[] getSignature() {
782                 return this.signature;
783         }
784         
785         /**
786          * Sets the signature of the method, field type, member type,
787          * relevant in the context, or <code>null</code> if none.
788          * <p>
789          * If not set, defaults to none.
790          * </p>
791          * <p>
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.
794          * </p>
795          * 
796          * @param signature the signature, or <code>null</code> if none
797          */
798         public void setSignature(char[] signature) {
799                 this.signature = signature;
800         }
801         
802         /**
803          * Returns the modifier flags relevant in the context, or
804          * <code>Flags.AccDefault</code> if none.
805          * <p>
806          * This field is available for the following kinds of
807          * completion proposals:
808          * <ul>
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
815          * </li>
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
824          * </li>
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
832          * </li>
833          *      <li><code>VARIABLE_DECLARATION</code> - modifier flags
834          * for the variable being declared</li>
835          * </ul>
836          * For kinds of completion proposals, this method returns
837          * <code>Flags.AccDefault</code>.
838          * </p>
839          * 
840          * @return the modifier flags, or
841          * <code>Flags.AccDefault</code> if none
842          * @see Flags
843          */
844         public int getFlags() {
845                 return this.flags;
846         }
847         
848         /**
849          * Sets the modifier flags relevant in the context.
850          * <p>
851          * If not set, defaults to none.
852          * </p>
853          * <p>
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.
856          * </p>
857          * 
858          * @param flags the modifier flags, or
859          * <code>Flags.AccDefault</code> if none
860          */
861         public void setFlags(int flags) {
862                 this.flags = flags;
863         }
864         
865         /**
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.
870          * <p>
871          * The client must not modify the array returned.
872          * </p>
873          * <p>
874          * <b>Note that this is an expensive thing to compute, which may require
875          * parsing Java source files, etc. Use sparingly.
876          * </p>
877          * 
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
881          */
882         public char[][] findParameterNames(IProgressMonitor monitor) {
883                 if (!this.parameterNamesComputed) {
884                         this.parameterNamesComputed = true;
885                         // TODO (jerome) - Missing implementation
886                 }
887                 return this.parameterNames;
888         }
889         
890         /**
891          * Sets the method parameter names.
892          * This information is relevant to method reference (and
893          * method declaration proposals).
894          * <p>
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.
897          * </p>
898          * 
899          * @param parameterNames the parameter names, or <code>null</code> if none
900          */
901         public void setParameterNames(char[][] parameterNames) {
902                 this.parameterNames = parameterNames;
903                 this.parameterNamesComputed = true;
904         }
905 }