net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/CompletionRequestor.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.IProblem;
  14
  15 /**
  16  * Abstract base class for a completion requestor which is passed completion
  17  * proposals as they are generated in response to a code assist request.
  18  * <p>
  19  * This class is intended to be subclassed by clients.
  20  * </p>
  21  * <p>
  22  * The code assist engine normally invokes methods on completion requestors in
  23  * the following sequence:
  24  *
  25  * <pre>
  26  *  requestor.beginReporting();
  27  *  requestor.accept(proposal_1);
  28  *  requestor.accept(proposal_2);
  29  *  ...
  30  *  requestor.endReporting();
  31  * </pre>
  32  *
  33  * If, however, the engine is unable to offer completion proposals for whatever
  34  * reason, <code>completionFailure</code> is called with a problem object
  35  * describing why completions were unavailable. In this case, the sequence of
  36  * calls is:
  37  *
  38  * <pre>
  39  * requestor.beginReporting();
  40  * requestor.completionFailure(problem);
  41  * requestor.endReporting();
  42  * </pre>
  43  *
  44  * In either case, the bracketing <code>beginReporting</code>
  45  * <code>endReporting</code>
  46  * calls are always made.
  47  * </p>
  48  * <p>
  49  * The class was introduced in 3.0 as a more evolvable replacement for the
  50  * <code>ICompletionRequestor</code> interface.
  51  * </p>
  52  *
  53  * @see ICodeAssist
  54  * @since 3.0
  55  */
  56 public abstract class CompletionRequestor {
  57
  58         /**
  59          * The set of CompletionProposal kinds that this requestor ignores;
  60          * <code>0</code> means the set is empty. 1 << completionProposalKind
  61          */
  62         private int ignoreSet = 0;
  63
  64         /**
  65          * Creates a new completion requestor. The requestor is interested in all
  66          * kinds of completion proposals; none will be ignored.
  67          */
  68         public CompletionRequestor() {
  69                 // do nothing
  70         }
  71
  72         /**
  73          * Returns whether the given kind of completion proposal is ignored.
  74          *
  75          * @param completionProposalKind
  76          *            one of the kind constants declared on
  77          *            <code>CompletionProposal</code>
  78          * @return <code>true</code> if the given kind of completion proposal is
  79          *         ignored by this requestor, and <code>false</code> if it is of
  80          *         interest
  81          * @see #setIgnored(int, boolean)
  82          * @see CompletionProposal#getKind()
  83          */
  84         public final boolean isIgnored(int completionProposalKind) {
  85                 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
  86                                 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
  87                         throw new IllegalArgumentException();
  88                 }
  89                 return 0 != (this.ignoreSet & (1 << completionProposalKind));
  90         }
  91
  92         /**
  93          * Sets whether the given kind of completion proposal is ignored.
  94          *
  95          * @param completionProposalKind
  96          *            one of the kind constants declared on
  97          *            <code>CompletionProposal</code>
  98          * @param ignore
  99          *            <code>true</code> if the given kind of completion proposal
 100          *            is ignored by this requestor, and <code>false</code> if it
 101          *            is of interest
 102          * @see #isIgnored(int)
 103          * @see CompletionProposal#getKind()
 104          */
 105         public final void setIgnored(int completionProposalKind, boolean ignore) {
 106                 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
 107                                 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
 108                         throw new IllegalArgumentException();
 109                 }
 110                 if (ignore) {
 111                         this.ignoreSet |= (1 << completionProposalKind);
 112                 } else {
 113                         this.ignoreSet &= ~(1 << completionProposalKind);
 114                 }
 115         }
 116
 117         /**
 118          * Pro forma notification sent before reporting a batch of completion
 119          * proposals.
 120          * <p>
 121          * The default implementation of this method does nothing. Clients may
 122          * override.
 123          * </p>
 124          */
 125         public void beginReporting() {
 126                 // do nothing
 127         }
 128
 129         /**
 130          * Pro forma notification sent after reporting a batch of completion
 131          * proposals.
 132          * <p>
 133          * The default implementation of this method does nothing. Clients may
 134          * override.
 135          * </p>
 136          */
 137         public void endReporting() {
 138                 // do nothing
 139         }
 140
 141         /**
 142          * Notification of failure to produce any completions. The problem object
 143          * explains what prevented completing.
 144          * <p>
 145          * The default implementation of this method does nothing. Clients may
 146          * override to receive this kind of notice.
 147          * </p>
 148          *
 149          * @param problem
 150          *            the problem object
 151          */
 152         public void completionFailure(IProblem problem) {
 153                 // default behavior is to ignore
 154         }
 155
 156         /**
 157          * Proposes a completion. Has no effect if the kind of proposal is being
 158          * ignored by this requestor. Callers should consider checking
 159          * {@link #isIgnored(int)} before avoid creating proposal objects that would
 160          * only be ignored.
 161          * <p>
 162          * Similarly, implementers should check
 163          * {@link #isIgnored(int) isIgnored(proposal.getKind())} and ignore
 164          * proposals that have been declared as uninteresting. The proposal object
 165          * passed in only valid for the duration of this call; implementors must not
 166          * hang on to these objects.
 167          *
 168          * @param proposal
 169          *            the completion proposal
 170          * @exception IllegalArgumentException
 171          *                if the proposal is null
 172          */
 173         public abstract void accept(CompletionProposal proposal);
 174 }