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 net.sourceforge.phpdt.core.compiler.CharOperation;
  14
  15 import org.eclipse.core.runtime.IProgressMonitor;
  16
  17 /**
  18  * Completion proposal.
  19  * <p>
  20  * In typical usage, the user working in a Java code editor issues a code assist
  21  * 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 engine
  24  * analyzes the code in the buffer, determines what kind of Java language
  25  * construct is at that position, and proposes ways to complete that construct.
  26  * These proposals are instances of subclasses of
  27  * <code>CompletionProposal</code>. These proposals, perhaps after sorting
  28  * and filtering, are presented to the user to make a choice.
  29  * </p>
  30  * <p>
  31  * The proposal is as follows: insert the
  32  * {@linkplain #getCompletion() completion string} into the source file buffer,
  33  * replacing the characters between {@linkplain #getReplaceStart() the start}
  34  * and {@linkplain #getReplaceEnd() end}. The string can be arbitrary; for
  35  * example, it might include not only the name of a method but a set of
  36  * parentheses. Moreover, the source range may include source positions before
  37  * or after the source position where <code>ICodeAssist.codeComplete</code>
  38  * was invoked. The rest of the information associated with the proposal is to
  39  * provide context that may help a user to choose from among competing
  40  * proposals.
  41  * </p>
  42  * <p>
  43  * The completion engine creates instances of this class; it is not intended to
  44  * be used by other clients.
  45  * </p>
  46  *
  47  * @see ICodeAssist#codeComplete(int, CompletionRequestor)
  48  * @since 3.0
  49  */
  50 public final class CompletionProposal {
  51
  52         /**
  53          * Completion is a declaration of an anonymous class. This kind of
  54          * completion might occur in a context like <code>"new List^;"</code> and
  55          * complete it to <code>"new List() {}"</code>.
  56          * <p>
  57          * The following additional context information is available for this kind
  58          * of completion proposal at little extra cost:
  59          * <ul>
  60          * <li>{@link #getDeclarationSignature()} - the type signature of the type
  61          * being implemented or subclassed </li>
  62          * </li>
  63          * <li>{@link #getSignature()} - the method signature of the constructor
  64          * that is referenced </li>
  65          * <li>{@link #getFlags()} - the modifiers flags of the constructor that is
  66          * referenced </li>
  67          * </ul>
  68          * </p>
  69          *
  70          * @see #getKind()
  71          */
  72         public static final int ANONYMOUS_CLASS_DECLARATION = 1;
  73
  74         /**
  75          * Completion is a reference to a field. This kind of completion might occur
  76          * in a context like <code>"this.ref^ = 0;"</code> and complete it to
  77          * <code>"this.refcount = 0;"</code>.
  78          * <p>
  79          * The following additional context information is available for this kind
  80          * of completion proposal at little extra cost:
  81          * <ul>
  82          * <li>{@link #getDeclarationSignature()} - the type signature of the type
  83          * that declares the field that is referenced </li>
  84          * <li>{@link #getFlags()} - the modifiers flags (including ACC_ENUM) of
  85          * the field that is referenced </li>
  86          * <li>{@link #getName()} - the simple name of the field that is referenced
  87          * </li>
  88          * <li>{@link #getSignature()} - the type signature of the field's type (as
  89          * opposed to the signature of the type in which the referenced field is
  90          * declared) </li>
  91          * </ul>
  92          * </p>
  93          *
  94          * @see #getKind()
  95          */
  96         public static final int FIELD_REF = 2;
  97
  98         /**
  99          * Completion is a keyword. This kind of completion might occur in a context
 100          * like <code>"public cl^ Foo {}"</code> and complete it to
 101          * <code>"public class Foo {}"</code>.
 102          * <p>
 103          * The following additional context information is available for this kind
 104          * of completion proposal at little extra cost:
 105          * <ul>
 106          * <li>{@link #getName()} - the keyword token </li>
 107          * <li>{@link #getFlags()} - the corresponding modifier flags if the
 108          * keyword is a modifier </li>
 109          * </ul>
 110          * </p>
 111          *
 112          * @see #getKind()
 113          */
 114         public static final int KEYWORD = 3;
 115
 116         /**
 117          * Completion is a reference to a label. This kind of completion might occur
 118          * in a context like <code>"break lo^;"</code> and complete it to
 119          * <code>"break loop;"</code>.
 120          * <p>
 121          * The following additional context information is available for this kind
 122          * of completion proposal at little extra cost:
 123          * <ul>
 124          * <li>{@link #getName()} - the simple name of the label that is referenced
 125          * </li>
 126          * </ul>
 127          * </p>
 128          *
 129          * @see #getKind()
 130          */
 131         public static final int LABEL_REF = 4;
 132
 133         /**
 134          * Completion is a reference to a local variable. This kind of completion
 135          * might occur in a context like <code>"ke^ = 4;"</code> and complete it
 136          * to <code>"keys = 4;"</code>.
 137          * <p>
 138          * The following additional context information is available for this kind
 139          * of completion proposal at little extra cost:
 140          * <ul>
 141          * <li>{@link #getFlags()} - the modifiers flags of the local variable that
 142          * is referenced </li>
 143          * <li>{@link #getName()} - the simple name of the local variable that is
 144          * referenced </li>
 145          * <li>{@link #getSignature()} - the type signature of the local variable's
 146          * type </li>
 147          * </ul>
 148          * </p>
 149          *
 150          * @see #getKind()
 151          */
 152         public static final int LOCAL_VARIABLE_REF = 5;
 153
 154         /**
 155          * Completion is a reference to a method. This kind of completion might
 156          * occur in a context like <code>"System.out.pr^();"</code> and complete
 157          * it to <code>""System.out.println();"</code>.
 158          * <p>
 159          * The following additional context information is available for this kind
 160          * of completion proposal at little extra cost:
 161          * <ul>
 162          * <li>{@link #getDeclarationSignature()} - the type signature of the type
 163          * that declares the method that is referenced </li>
 164          * <li>{@link #getFlags()} - the modifiers flags of the method that is
 165          * referenced </li>
 166          * <li>{@link #getName()} - the simple name of the method that is
 167          * referenced </li>
 168          * <li>{@link #getSignature()} - the method signature of the method that is
 169          * referenced </li>
 170          * </ul>
 171          * </p>
 172          *
 173          * @see #getKind()
 174          */
 175         public static final int METHOD_REF = 6;
 176
 177         /**
 178          * Completion is a declaration of a method. This kind of completion might
 179          * occur in a context like <code>"new List() {si^};"</code> and complete
 180          * it to <code>"new List() {public int size() {} };"</code>.
 181          * <p>
 182          * The following additional context information is available for this kind
 183          * of completion proposal at little extra cost:
 184          * <ul>
 185          * <li>{@link #getDeclarationSignature()} - the type signature of the type
 186          * that declares the method that is being overridden or implemented </li>
 187          * <li>{@link #getName()} - the simple name of the method that is being
 188          * overridden or implemented </li>
 189          * <li>{@link #getSignature()} - the method signature of the method that is
 190          * being overridden or implemented </li>
 191          * <li>{@link #getFlags()} - the modifiers flags of the method that is
 192          * being overridden or implemented </li>
 193          * </ul>
 194          * </p>
 195          *
 196          * @see #getKind()
 197          */
 198         public static final int METHOD_DECLARATION = 7;
 199
 200         /**
 201          * Completion is a reference to a package. This kind of completion might
 202          * occur in a context like <code>"import java.u^.*;"</code> and complete
 203          * it to <code>"import java.util.*;"</code>.
 204          * <p>
 205          * The following additional context information is available for this kind
 206          * of completion proposal at little extra cost:
 207          * <ul>
 208          * <li>{@link #getDeclarationSignature()} - the dot-based package signature
 209          * of the package that is referenced </li>
 210          * </ul>
 211          * </p>
 212          *
 213          * @see #getKind()
 214          */
 215         public static final int PACKAGE_REF = 8;
 216
 217         /**
 218          * Completion is a reference to a type. Any kind of type is allowed,
 219          * including primitive types, reference types, array types, parameterized
 220          * types, and type variables. This kind of completion might occur in a
 221          * context like <code>"public static Str^ key;"</code> and complete it to
 222          * <code>"public static String key;"</code>.
 223          * <p>
 224          * The following additional context information is available for this kind
 225          * of completion proposal at little extra cost:
 226          * <ul>
 227          * <li>{@link #getDeclarationSignature()} - the dot-based package signature
 228          * of the package that contains the type that is referenced </li>
 229          * <li>{@link #getSignature()} - the type signature of the type that is
 230          * referenced </li>
 231          * <li>{@link #getFlags()} - the modifiers flags (including
 232          * Flags.AccInterface, AccEnum, and AccAnnotation) of the type that is
 233          * referenced </li>
 234          * </ul>
 235          * </p>
 236          *
 237          * @see #getKind()
 238          */
 239         public static final int TYPE_REF = 9;
 240
 241         /**
 242          * Completion is a declaration of a variable (locals, parameters, fields,
 243          * etc.).
 244          * <p>
 245          * The following additional context information is available for this kind
 246          * of completion proposal at little extra cost:
 247          * <ul>
 248          * <li>{@link #getName()} - the simple name of the variable being declared
 249          * </li>
 250          * <li>{@link #getSignature()} - the type signature of the type of the
 251          * variable being declared </li>
 252          * <li>{@link #getFlags()} - the modifiers flags of the variable being
 253          * declared </li>
 254          * </ul>
 255          * </p>
 256          *
 257          * @see #getKind()
 258          */
 259         public static final int VARIABLE_DECLARATION = 10;
 260
 261         /**
 262          * Kind of completion request.
 263          */
 264         private int completionKind;
 265
 266         /**
 267          * Offset in original buffer where ICodeAssist.codeComplete() was requested.
 268          */
 269         private int completionLocation;
 270
 271         /**
 272          * Start position (inclusive) of source range in original buffer containing
 273          * the relevant token defaults to empty subrange at [0,0).
 274          */
 275         private int tokenStart = 0;
 276
 277         /**
 278          * End position (exclusive) of source range in original buffer containing
 279          * the relevant token; defaults to empty subrange at [0,0).
 280          */
 281         private int tokenEnd = 0;
 282
 283         /**
 284          * Completion string; defaults to empty string.
 285          */
 286         private char[] completion = CharOperation.NO_CHAR;
 287
 288         /**
 289          * Start position (inclusive) of source range in original buffer to be
 290          * replaced by completion string; defaults to empty subrange at [0,0).
 291          */
 292         private int replaceStart = 0;
 293
 294         /**
 295          * End position (exclusive) of source range in original buffer to be
 296          * replaced by completion string; defaults to empty subrange at [0,0).
 297          */
 298         private int replaceEnd = 0;
 299
 300         /**
 301          * Relevance rating; positive; higher means better; defaults to minimum
 302          * rating.
 303          */
 304         private int relevance = 1;
 305
 306         /**
 307          * Signature of the relevant package or type declaration in the context, or
 308          * <code>null</code> if none. Defaults to null.
 309          */
 310         private char[] declarationSignature = null;
 311
 312         /**
 313          * Simple name of the method, field, member, or variable relevant in the
 314          * context, or <code>null</code> if none. Defaults to null.
 315          */
 316         private char[] name = null;
 317
 318         /**
 319          * Signature of the method, field type, member type, relevant in the
 320          * context, or <code>null</code> if none. Defaults to null.
 321          */
 322         private char[] signature = null;
 323
 324         /**
 325          * Modifier flags relevant in the context, or <code>Flags.AccDefault</code>
 326          * if none. Defaults to <code>Flags.AccDefault</code>.
 327          */
 328         private int flags = Flags.AccDefault;
 329
 330         /**
 331          * Parameter names (for method completions), or <code>null</code> if none.
 332          * Lazily computed. Defaults to <code>null</code>.
 333          */
 334         private char[][] parameterNames = null;
 335
 336         /**
 337          * Indicates whether parameter names have been computed.
 338          */
 339         private boolean parameterNamesComputed = false;
 340
 341         /**
 342          * Creates a basic completion proposal. All instance field have plausible
 343          * default values unless otherwise noted.
 344          * <p>
 345          * Note that the constructors for this class are internal to the Java model
 346          * implementation. Clients cannot directly create CompletionProposal
 347          * objects.
 348          * </p>
 349          *
 350          * @param kind
 351          *            one of the kind constants declared on this class
 352          * @param completionOffset
 353          *            original offset of code completion request
 354          * @return a new completion proposal
 355          */
 356         public static CompletionProposal create(int kind, int completionOffset) {
 357                 return new CompletionProposal(kind, completionOffset);
 358         }
 359
 360         /**
 361          * Creates a basic completion proposal. All instance field have plausible
 362          * default values unless otherwise noted.
 363          * <p>
 364          * Note that the constructors for this class are internal to the Java model
 365          * implementation. Clients cannot directly create CompletionProposal
 366          * objects.
 367          * </p>
 368          *
 369          * @param kind
 370          *            one of the kind constants declared on this class
 371          * @param completionLocation
 372          *            original offset of code completion request
 373          */
 374         CompletionProposal(int kind, int completionLocation) {
 375                 if ((kind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION)
 376                                 || (kind > CompletionProposal.VARIABLE_DECLARATION)) {
 377                         throw new IllegalArgumentException();
 378                 }
 379                 if (this.completion == null || completionLocation < 0) {
 380                         throw new IllegalArgumentException();
 381                 }
 382                 this.completionKind = kind;
 383                 this.completionLocation = completionLocation;
 384         }
 385
 386         /**
 387          * Returns the kind of completion being proposed.
 388          * <p>
 389          * The set of different kinds of completion proposals is expected to change
 390          * over time. It is strongly recommended that clients do <b>not</b> assume
 391          * that the kind is one of the ones they know about, and code defensively
 392          * for the possibility of unexpected future growth.
 393          * </p>
 394          *
 395          * @return the kind; one of the kind constants declared on this class, or
 396          *         possibly a kind unknown to the caller
 397          */
 398         public int getKind() {
 399                 return this.completionKind;
 400         }
 401
 402         /**
 403          * Returns the character index in the source file buffer where source
 404          * completion was requested (the <code>offset</code>parameter to
 405          * <code>ICodeAssist.codeComplete</code>.
 406          *
 407          * @return character index in source file buffer
 408          * @see ICodeAssist#codeComplete(int,CompletionRequestor)
 409          */
 410         public int getCompletionLocation() {
 411                 return this.completionLocation;
 412         }
 413
 414         /**
 415          * Returns the character index of the start of the subrange in the source
 416          * file buffer containing the relevant token being completed. This token is
 417          * either the identifier or Java language keyword under, or immediately
 418          * preceding, the original request offset. If the original request offset is
 419          * not within or immediately after an identifier or keyword, then the
 420          * position returned is original request offset and the token range is
 421          * empty.
 422          *
 423          * @return character index of token start position (inclusive)
 424          */
 425         public int getTokenStart() {
 426                 return this.tokenStart;
 427         }
 428
 429         /**
 430          * Returns the character index of the end (exclusive) of the subrange in the
 431          * source file buffer containing the relevant token. When there is no
 432          * relevant token, the range is empty (<code>getEndToken() == getStartToken()</code>).
 433          *
 434          * @return character index of token end position (exclusive)
 435          */
 436         public int getTokenEnd() {
 437                 return this.tokenEnd;
 438         }
 439
 440         /**
 441          * Sets the character indices of the subrange in the source file buffer
 442          * containing the relevant token being completed. This token is either the
 443          * identifier or Java language keyword under, or immediately preceding, the
 444          * original request offset. If the original request offset is not within or
 445          * immediately after an identifier or keyword, then the source range begins
 446          * at original request offset and is empty.
 447          * <p>
 448          * If not set, defaults to empty subrange at [0,0).
 449          * </p>
 450          *
 451          * @param startIndex
 452          *            character index of token start position (inclusive)
 453          * @param endIndex
 454          *            character index of token end position (exclusive)
 455          */
 456         public void setTokenRange(int startIndex, int endIndex) {
 457                 if (startIndex < 0 || endIndex < startIndex) {
 458                         throw new IllegalArgumentException();
 459                 }
 460                 this.tokenStart = startIndex;
 461                 this.tokenEnd = endIndex;
 462         }
 463
 464         /**
 465          * Returns the proposed sequence of characters to insert into the source
 466          * file buffer, replacing the characters at the specified source range. The
 467          * string can be arbitrary; for example, it might include not only the name
 468          * of a method but a set of parentheses.
 469          * <p>
 470          * The client must not modify the array returned.
 471          * </p>
 472          *
 473          * @return the completion string
 474          */
 475         public char[] getCompletion() {
 476                 return this.completion;
 477         }
 478
 479         /**
 480          * Sets the proposed sequence of characters to insert into the source file
 481          * buffer, replacing the characters at the specified source range. The
 482          * string can be arbitrary; for example, it might include not only the name
 483          * of a method but a set of parentheses.
 484          * <p>
 485          * If not set, defaults to an empty character array.
 486          * </p>
 487          * <p>
 488          * The completion engine creates instances of this class and sets its
 489          * properties; this method is not intended to be used by other clients.
 490          * </p>
 491          *
 492          * @param completion
 493          *            the completion string
 494          */
 495         public void setCompletion(char[] completion) {
 496                 this.completion = completion;
 497         }
 498
 499         /**
 500          * Returns the character index of the start of the subrange in the source
 501          * file buffer to be replaced by the completion string. If the subrange is
 502          * empty (<code>getReplaceEnd() == getReplaceStart()</code>), the
 503          * completion string is to be inserted at this index.
 504          * <p>
 505          * Note that while the token subrange is precisely specified, the
 506          * replacement range is loosely constrained and may not bear any direct
 507          * relation to the original request offset. For example, a it would be
 508          * possible for a type completion to propose inserting an import declaration
 509          * at the top of the compilation unit; or the completion might include
 510          * trailing parentheses and punctuation for a method completion.
 511          * </p>
 512          *
 513          * @return replacement start position (inclusive)
 514          */
 515         public int getReplaceStart() {
 516                 return this.replaceStart;
 517         }
 518
 519         /**
 520          * Returns the character index of the end of the subrange in the source file
 521          * buffer to be replaced by the completion string. If the subrange is empty (<code>getReplaceEnd() == getReplaceStart()</code>),
 522          * the completion string is to be inserted at this index.
 523          *
 524          * @return replacement end position (exclusive)
 525          */
 526         public int getReplaceEnd() {
 527                 return this.replaceEnd;
 528         }
 529
 530         /**
 531          * Sets the character indices of the subrange in the source file buffer to
 532          * be replaced by the completion string. If the subrange is empty (<code>startIndex == endIndex</code>),
 533          * the completion string is to be inserted at this index.
 534          * <p>
 535          * If not set, defaults to empty subrange at [0,0).
 536          * </p>
 537          * <p>
 538          * The completion engine creates instances of this class and sets its
 539          * properties; this method is not intended to be used by other clients.
 540          * </p>
 541          *
 542          * @param startIndex
 543          *            character index of replacement start position (inclusive)
 544          * @param endIndex
 545          *            character index of replacement end position (exclusive)
 546          */
 547         public void setReplaceRange(int startIndex, int endIndex) {
 548                 if (startIndex < 0 || endIndex < startIndex) {
 549                         throw new IllegalArgumentException();
 550                 }
 551                 this.replaceStart = startIndex;
 552                 this.replaceEnd = endIndex;
 553         }
 554
 555         /**
 556          * Returns the relative relevance rating of this proposal.
 557          *
 558          * @return relevance rating of this proposal; ratings are positive; higher
 559          *         means better
 560          */
 561         public int getRelevance() {
 562                 return this.relevance;
 563         }
 564
 565         /**
 566          * Sets the relative relevance rating of this proposal.
 567          * <p>
 568          * If not set, defaults to the lowest possible rating (1).
 569          * </p>
 570          * <p>
 571          * The completion engine creates instances of this class and sets its
 572          * properties; this method is not intended to be used by other clients.
 573          * </p>
 574          *
 575          * @param rating
 576          *            relevance rating of this proposal; ratings are positive;
 577          *            higher means better
 578          */
 579         public void setRelevance(int rating) {
 580                 if (rating <= 0) {
 581                         throw new IllegalArgumentException();
 582                 }
 583                 this.relevance = rating;
 584         }
 585
 586         /**
 587          * Returns the type or package signature of the relevant declaration in the
 588          * context, or <code>null</code> if none.
 589          * <p>
 590          * This field is available for the following kinds of completion proposals:
 591          * <ul>
 592          * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - type signature of the
 593          * type that is being subclassed or implemented</li>
 594          * <li><code>FIELD_REF</code> - type signature of the type that declares
 595          * the field that is referenced</li>
 596          * <li><code>METHOD_REF</code> - type signature of the type that declares
 597          * the method that is referenced</li>
 598          * <li><code>METHOD_DECLARATION</code> - type signature of the type that
 599          * declares the method that is being implemented or overridden</li>
 600          * <li><code>PACKAGE_REF</code> - dot-based package signature of the
 601          * package that is referenced</li>
 602          * <li><code>TYPE_REF</code> - dot-based package signature of the package
 603          * containing the type that is referenced</li>
 604          * </ul>
 605          * For kinds of completion proposals, this method returns <code>null</code>.
 606          * Clients must not modify the array returned.
 607          * </p>
 608          *
 609          * @return the declaration signature, or <code>null</code> if none
 610          * @see Signature
 611          */
 612         public char[] getDeclarationSignature() {
 613                 return this.declarationSignature;
 614         }
 615
 616         /**
 617          * Sets the type or package signature of the relevant declaration in the
 618          * context, or <code>null</code> if none.
 619          * <p>
 620          * If not set, defaults to none.
 621          * </p>
 622          * <p>
 623          * The completion engine creates instances of this class and sets its
 624          * properties; this method is not intended to be used by other clients.
 625          * </p>
 626          *
 627          * @param signature
 628          *            the type or package signature, or <code>null</code> if none
 629          */
 630         public void setDeclarationSignature(char[] signature) {
 631                 this.declarationSignature = signature;
 632         }
 633
 634         /**
 635          * Returns the simple name of the method, field, member, or variable
 636          * relevant in the context, or <code>null</code> if none.
 637          * <p>
 638          * This field is available for the following kinds of completion proposals:
 639          * <ul>
 640          * <li><code>FIELD_REF</code> - the name of the field</li>
 641          * <li><code>KEYWORD</code> - the keyword</li>
 642          * <li><code>LABEL_REF</code> - the name of the label</li>
 643          * <li><code>LOCAL_VARIABLE_REF</code> - the name of the local variable</li>
 644          * <li><code>METHOD_REF</code> - the name of the method</li>
 645          * <li><code>METHOD_DECLARATION</code> - the name of the method</li>
 646          * <li><code>VARIABLE_DECLARATION</code> - the name of the variable</li>
 647          * </ul>
 648          * For kinds of completion proposals, this method returns <code>null</code>.
 649          * Clients must not modify the array returned.
 650          * </p>
 651          *
 652          * @return the keyword, field, method, local variable, or member name, or
 653          *         <code>null</code> if none
 654          */
 655         public char[] getName() {
 656                 return this.name;
 657         }
 658
 659         /**
 660          * Sets the simple name of the method, field, member, or variable relevant
 661          * in the context, or <code>null</code> if none.
 662          * <p>
 663          * If not set, defaults to none.
 664          * </p>
 665          * <p>
 666          * The completion engine creates instances of this class and sets its
 667          * properties; this method is not intended to be used by other clients.
 668          * </p>
 669          *
 670          * @param name
 671          *            the keyword, field, method, local variable, or member name, or
 672          *            <code>null</code> if none
 673          */
 674         public void setName(char[] name) {
 675                 this.name = name;
 676         }
 677
 678         /**
 679          * Returns the signature of the method or type relevant in the context, or
 680          * <code>null</code> if none.
 681          * <p>
 682          * This field is available for the following kinds of completion proposals:
 683          * <ul>
 684          * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - method signature of the
 685          * constructor that is being invoked</li>
 686          * <li><code>FIELD_REF</code> - the type signature of the referenced
 687          * field's type</li>
 688          * <li><code>LOCAL_VARIABLE_REF</code> - the type signature of the
 689          * referenced local variable's type</li>
 690          * <li><code>METHOD_REF</code> - method signature of the method that is
 691          * referenced</li>
 692          * <li><code>METHOD_DECLARATION</code> - method signature of the method
 693          * that is being implemented or overridden</li>
 694          * <li><code>TYPE_REF</code> - type signature of the type that is
 695          * referenced</li>
 696          * <li><code>VARIABLE_DECLARATION</code> - the type signature of the type
 697          * of the variable being declared</li>
 698          * </ul>
 699          * For kinds of completion proposals, this method returns <code>null</code>.
 700          * Clients must not modify the array returned.
 701          * </p>
 702          *
 703          * @return the signature, or <code>null</code> if none
 704          * @see Signature
 705          */
 706         public char[] getSignature() {
 707                 return this.signature;
 708         }
 709
 710         /**
 711          * Sets the signature of the method, field type, member type, relevant in
 712          * the context, or <code>null</code> if none.
 713          * <p>
 714          * If not set, defaults to none.
 715          * </p>
 716          * <p>
 717          * The completion engine creates instances of this class and sets its
 718          * properties; this method is not intended to be used by other clients.
 719          * </p>
 720          *
 721          * @param signature
 722          *            the signature, or <code>null</code> if none
 723          */
 724         public void setSignature(char[] signature) {
 725                 this.signature = signature;
 726         }
 727
 728         /**
 729          * Returns the modifier flags relevant in the context, or
 730          * <code>Flags.AccDefault</code> if none.
 731          * <p>
 732          * This field is available for the following kinds of completion proposals:
 733          * <ul>
 734          * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - modifier flags of the
 735          * constructor that is referenced</li>
 736          * <li><code>FIELD_REF</code> - modifier flags of the field that is
 737          * referenced; <code>Flags.AccEnum</code> can be used to recognize
 738          * references to enum constants </li>
 739          * <li><code>KEYWORD</code> - modifier flag corrresponding to the
 740          * modifier keyword</li>
 741          * <li><code>LOCAL_VARIABLE_REF</code> - modifier flags of the local
 742          * variable that is referenced</li>
 743          * <li><code>METHOD_REF</code> - modifier flags of the method that is
 744          * referenced; <code>Flags.AccAnnotation</code> can be used to recognize
 745          * references to annotation type members </li>
 746          * <li><code>METHOD_DECLARATION</code> - modifier flags for the method
 747          * that is being implemented or overridden</li>
 748          * <li><code>TYPE_REF</code> - modifier flags of the type that is
 749          * referenced; <code>Flags.AccInterface</code> can be used to recognize
 750          * references to interfaces, <code>Flags.AccEnum</code> enum types, and
 751          * <code>Flags.AccAnnotation</code> annotation types </li>
 752          * <li><code>VARIABLE_DECLARATION</code> - modifier flags for the
 753          * variable being declared</li>
 754          * </ul>
 755          * For kinds of completion proposals, this method returns
 756          * <code>Flags.AccDefault</code>.
 757          * </p>
 758          *
 759          * @return the modifier flags, or <code>Flags.AccDefault</code> if none
 760          * @see Flags
 761          */
 762         public int getFlags() {
 763                 return this.flags;
 764         }
 765
 766         /**
 767          * Sets the modifier flags relevant in the context.
 768          * <p>
 769          * If not set, defaults to none.
 770          * </p>
 771          * <p>
 772          * The completion engine creates instances of this class and sets its
 773          * properties; this method is not intended to be used by other clients.
 774          * </p>
 775          *
 776          * @param flags
 777          *            the modifier flags, or <code>Flags.AccDefault</code> if none
 778          */
 779         public void setFlags(int flags) {
 780                 this.flags = flags;
 781         }
 782
 783         /**
 784          * Finds the method parameter names. This information is relevant to method
 785          * reference (and method declaration proposals). Returns <code>null</code>
 786          * if not available or not relevant.
 787          * <p>
 788          * The client must not modify the array returned.
 789          * </p>
 790          * <p>
 791          * <b>Note that this is an expensive thing to compute, which may require
 792          * parsing Java source files, etc. Use sparingly.
 793          * </p>
 794          *
 795          * @param monitor
 796          *            the progress monitor, or <code>null</code> if none
 797          * @return the parameter names, or <code>null</code> if none or not
 798          *         available or not relevant
 799          */
 800         public char[][] findParameterNames(IProgressMonitor monitor) {
 801                 if (!this.parameterNamesComputed) {
 802                         this.parameterNamesComputed = true;
 803                         // TODO (jerome) - Missing implementation
 804                 }
 805                 return this.parameterNames;
 806         }
 807
 808         /**
 809          * Sets the method parameter names. This information is relevant to method
 810          * reference (and method declaration proposals).
 811          * <p>
 812          * The completion engine creates instances of this class and sets its
 813          * properties; this method is not intended to be used by other clients.
 814          * </p>
 815          *
 816          * @param parameterNames
 817          *            the parameter names, or <code>null</code> if none
 818          */
 819         public void setParameterNames(char[][] parameterNames) {
 820                 this.parameterNames = parameterNames;
 821                 this.parameterNamesComputed = true;
 822         }
 823 }