net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICodeAssist.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 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 /**
  14  * Common protocol for Java elements that support source code assist and code
  15  * resolve.
  16  * <p>
  17  * This interface is not intended to be implemented by clients.
  18  * </p>
  19  */
  20 public interface ICodeAssist {
  21
  22         /**
  23          * Performs code completion at the given offset position in this compilation
  24          * unit, reporting results to the given completion requestor. The
  25          * <code>offset</code> is the 0-based index of the character, after which
  26          * code assist is desired. An <code>offset</code> of -1 indicates to code
  27          * assist at the beginning of this compilation unit.
  28          *
  29          * @param offset
  30          *            the given offset position
  31          * @param requestor
  32          *            the given completion requestor
  33          *
  34          * @exception JavaModelException
  35          *                if code assist could not be performed. Reasons include:
  36          *                <ul>
  37          *                <li>This Java element does not exist
  38          *                (ELEMENT_DOES_NOT_EXIST)</li>
  39          *                <li> The position specified is < -1 or is greater than
  40          *                this compilation unit's source length
  41          *                (INDEX_OUT_OF_BOUNDS)
  42          *                </ul>
  43          *
  44          * @exception IllegalArgumentException
  45          *                if <code>requestor</code> is <code>null</code>
  46          * @deprecated Use {@link #codeComplete(int, ICompletionRequestor)} instead.
  47          */
  48         void codeComplete(int offset, ICodeCompletionRequestor requestor)
  49                         throws JavaModelException;
  50
  51         /**
  52          * Performs code completion at the given offset position in this compilation
  53          * unit, reporting results to the given completion requestor. The
  54          * <code>offset</code> is the 0-based index of the character, after which
  55          * code assist is desired. An <code>offset</code> of -1 indicates to code
  56          * assist at the beginning of this compilation unit.
  57          *
  58          * @param offset
  59          *            the given offset position
  60          * @param requestor
  61          *            the given completion requestor
  62          * @exception JavaModelException
  63          *                if code assist could not be performed. Reasons include:
  64          *                <ul>
  65          *                <li>This Java element does not exist
  66          *                (ELEMENT_DOES_NOT_EXIST)</li>
  67          *                <li> The position specified is < -1 or is greater than
  68          *                this compilation unit's source length
  69          *                (INDEX_OUT_OF_BOUNDS)
  70          *                </ul>
  71          *
  72          * @exception IllegalArgumentException
  73          *                if <code>requestor</code> is <code>null</code>
  74          * @since 2.0
  75          */
  76         // TODO (jerome - once CompletionRequestor is working) @ deprecated Use
  77         // {@link #codeComplete(int, CompletionRequestor)} instead.
  78         void codeComplete(int offset, ICompletionRequestor requestor)
  79                         throws JavaModelException;
  80
  81         /**
  82          * <b>DO NOT USE</b>: This API element was added in anticipation of J2SE
  83          * 1.5 support, which is planned for the next release of Eclipse after 3.0.
  84          * It is currently unimplemented, and the API may change slightly before
  85          * reaching its final form.
  86          * <p>
  87          * Performs code completion at the given offset position in this compilation
  88          * unit, reporting results to the given completion requestor. The
  89          * <code>offset</code> is the 0-based index of the character, after which
  90          * code assist is desired. An <code>offset</code> of -1 indicates to code
  91          * assist at the beginning of this compilation unit.
  92          * <p>
  93          *
  94          * @param offset
  95          *            the given offset position
  96          * @param requestor
  97          *            the given completion requestor
  98          * @exception JavaModelException
  99          *                if code assist could not be performed. Reasons include:
 100          *                <ul>
 101          *                <li>This Java element does not exist
 102          *                (ELEMENT_DOES_NOT_EXIST)</li>
 103          *                <li> The position specified is < -1 or is greater than
 104          *                this compilation unit's source length
 105          *                (INDEX_OUT_OF_BOUNDS)
 106          *                </ul>
 107          *
 108          * @exception IllegalArgumentException
 109          *                if <code>requestor</code> is <code>null</code>
 110          * @since 3.0
 111          */
 112         void codeComplete(int offset, CompletionRequestor requestor)
 113                         throws JavaModelException;
 114
 115         /**
 116          * Performs code completion at the given offset position in this compilation
 117          * unit, reporting results to the given completion requestor. The
 118          * <code>offset</code> is the 0-based index of the character, after which
 119          * code assist is desired. An <code>offset</code> of -1 indicates to code
 120          * assist at the beginning of this compilation unit. It considers types in
 121          * the working copies with the given owner first. In other words, the
 122          * owner's working copies will take precedence over their original
 123          * compilation units in the workspace.
 124          * <p>
 125          * Note that if a working copy is empty, it will be as if the original
 126          * compilation unit had been deleted.
 127          * </p>
 128          *
 129          * @param offset
 130          *            the given offset position
 131          * @param requestor
 132          *            the given completion requestor
 133          * @param owner
 134          *            the owner of working copies that take precedence over their
 135          *            original compilation units
 136          * @exception JavaModelException
 137          *                if code assist could not be performed. Reasons include:
 138          *                <ul>
 139          *                <li>This Java element does not exist
 140          *                (ELEMENT_DOES_NOT_EXIST)</li>
 141          *                <li> The position specified is < -1 or is greater than
 142          *                this compilation unit's source length
 143          *                (INDEX_OUT_OF_BOUNDS)
 144          *                </ul>
 145          *
 146          * @exception IllegalArgumentException
 147          *                if <code>requestor</code> is <code>null</code>
 148          * @since 3.0
 149          */
 150         // TODO (jerome - once CompletionRequestor is working) @ deprecated Use
 151         // {@link #codeComplete(int, CompletionRequestor, WorkingCopyOwner)}
 152         // instead.
 153         void codeComplete(int offset, ICompletionRequestor requestor,
 154                         WorkingCopyOwner owner) throws JavaModelException;
 155
 156         /**
 157          * <b>DO NOT USE</b>: This API element was added in anticipation of J2SE
 158          * 1.5 support, which is planned for the next release of Eclipse after 3.0.
 159          * It is currently unimplemented, and the API may change slightly before
 160          * reaching its final form.
 161          * <p>
 162          * Performs code completion at the given offset position in this compilation
 163          * unit, reporting results to the given completion requestor. The
 164          * <code>offset</code> is the 0-based index of the character, after which
 165          * code assist is desired. An <code>offset</code> of -1 indicates to code
 166          * assist at the beginning of this compilation unit. It considers types in
 167          * the working copies with the given owner first. In other words, the
 168          * owner's working copies will take precedence over their original
 169          * compilation units in the workspace.
 170          * <p>
 171          * Note that if a working copy is empty, it will be as if the original
 172          * compilation unit had been deleted.
 173          * </p>
 174          *
 175          * @param offset
 176          *            the given offset position
 177          * @param requestor
 178          *            the given completion requestor
 179          * @param owner
 180          *            the owner of working copies that take precedence over their
 181          *            original compilation units
 182          * @exception JavaModelException
 183          *                if code assist could not be performed. Reasons include:
 184          *                <ul>
 185          *                <li>This Java element does not exist
 186          *                (ELEMENT_DOES_NOT_EXIST)</li>
 187          *                <li> The position specified is < -1 or is greater than
 188          *                this compilation unit's source length
 189          *                (INDEX_OUT_OF_BOUNDS)
 190          *                </ul>
 191          *
 192          * @exception IllegalArgumentException
 193          *                if <code>requestor</code> is <code>null</code>
 194          * @since 3.0
 195          */
 196         void codeComplete(int offset, CompletionRequestor requestor,
 197                         WorkingCopyOwner owner) throws JavaModelException;
 198
 199         /**
 200          * Returns the Java elements correspondiing to the given selected text in
 201          * this compilation unit. The <code>offset</code> is the 0-based index of
 202          * the first selected character. The <code>length</code> is the number of
 203          * selected characters.
 204          *
 205          * @param offset
 206          *            the given offset position
 207          * @param length
 208          *            the number of selected characters
 209          * @return the Java elements correspondiing to the given selected text
 210          *
 211          * @exception JavaModelException
 212          *                if code resolve could not be performed. Reasons include:
 213          *                <li>This Java element does not exist
 214          *                (ELEMENT_DOES_NOT_EXIST)</li>
 215          *                <li> The range specified is not within this element's
 216          *                source range (INDEX_OUT_OF_BOUNDS)
 217          *                </ul>
 218          *
 219          */
 220         IJavaElement[] codeSelect(int offset, int length) throws JavaModelException;
 221
 222         /**
 223          * Returns the Java elements correspondiing to the given selected text in
 224          * this compilation unit. The <code>offset</code> is the 0-based index of
 225          * the first selected character. The <code>length</code> is the number of
 226          * selected characters. It considers types in the working copies with the
 227          * given owner first. In other words, the owner's working copies will take
 228          * precedence over their original compilation units in the workspace.
 229          * <p>
 230          * Note that if a working copy is empty, it will be as if the original
 231          * compilation unit had been deleted.
 232          * </p>
 233          *
 234          * @param offset
 235          *            the given offset position
 236          * @param length
 237          *            the number of selected characters
 238          * @param owner
 239          *            the owner of working copies that take precedence over their
 240          *            original compilation units
 241          * @return the Java elements correspondiing to the given selected text
 242          *
 243          * @exception JavaModelException
 244          *                if code resolve could not be performed. Reasons include:
 245          *                <li>This Java element does not exist
 246          *                (ELEMENT_DOES_NOT_EXIST)</li>
 247          *                <li> The range specified is not within this element's
 248          *                source range (INDEX_OUT_OF_BOUNDS)
 249          *                </ul>
 250          * @since 3.0
 251          */
 252         IJavaElement[] codeSelect(int offset, int length, WorkingCopyOwner owner)
 253                         throws JavaModelException;
 254 }