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