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

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 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
  15
  16
  17 /**
  18  * Represents an entire Java compilation unit (<code>.java</code> source file).
  19  * Compilation unit elements need to be opened before they can be navigated or manipulated.
  20  * The children are of type <code>IPackageDeclaration</code>,
  21  * <code>IImportContainer</code>, and <code>IType</code>,
  22  * and appear in the order in which they are declared in the source.
  23  * If a <code>.java</code> file cannot be parsed, its structure remains unknown.
  24  * Use <code>IJavaElement.isStructureKnown</code> to determine whether this is
  25  * the case.
  26  * <p>
  27  * This interface is not intended to be implemented by clients.
  28  * </p>
  29  */
  30 public interface ICompilationUnit extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation {
  31 //extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist {
  32
  33         /**
  34          * Constant indicating that a reconcile operation should not return an AST.
  35          * @since 3.0
  36          */
  37         public static final int NO_AST = 0;
  38
  39         /**
  40          * Changes this compilation unit handle into a working copy. A new <code>IBuffer</code> is
  41          * created using this compilation unit handle's owner. Uses the primary owner is none was
  42          * specified when this compilation unit handle was created.
  43          * <p>
  44          * When switching to working copy mode, problems are reported to given
  45          * <code>IProblemRequestor</code>.
  46          * </p>
  47          * <p>
  48          * Once in working copy mode, changes to this compilation unit or its children are done in memory.
  49          * Only the new buffer is affected. Using <code>commitWorkingCopy(boolean, IProgressMonitor)</code>
  50          * will bring the underlying resource in sync with this compilation unit.
  51          * </p>
  52          * <p>
  53          * If this compilation unit was already in working copy mode, an internal counter is incremented and no
  54          * other action is taken on this compilation unit. To bring this compilation unit back into the original mode
  55          * (where it reflects the underlying resource), <code>discardWorkingCopy</code> must be call as many
  56          * times as <code>becomeWorkingCopy</code>.
  57          * </p>
  58          *
  59          * @param problemRequestor a requestor which will get notified of problems detected during
  60          *      reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
  61          *      that the client is not interested in problems.
  62          * @param monitor a progress monitor used to report progress while opening this compilation unit
  63          *      or <code>null</code> if no progress should be reported
  64          * @throws JavaModelException if this compilation unit could not become a working copy.
  65          * @see #discardWorkingCopy()
  66          * @since 3.0
  67          */
  68         void becomeWorkingCopy(IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException;
  69         /**
  70          * Commits the contents of this working copy to its underlying resource.
  71          *
  72          * <p>It is possible that the contents of the original resource have changed
  73          * since this working copy was created, in which case there is an update conflict.
  74          * The value of the <code>force</code> parameter effects the resolution of
  75          * such a conflict:<ul>
  76          * <li> <code>true</code> - in this case the contents of this working copy are applied to
  77          *      the underlying resource even though this working copy was created before
  78          *              a subsequent change in the resource</li>
  79          * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
  80          * </ul>
  81          * <p>
  82          * Since 2.1, a working copy can be created on a not-yet existing compilation
  83          * unit. In particular, such a working copy can then be committed in order to create
  84          * the corresponding compilation unit.
  85          * </p>
  86          * @param force a flag to handle the cases when the contents of the original resource have changed
  87          * since this working copy was created
  88          * @param monitor the given progress monitor
  89          * @throws JavaModelException if this working copy could not commit. Reasons include:
  90          * <ul>
  91          * <li> A <code>CoreException</code> occurred while updating an underlying resource
  92          * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
  93          * <li> A update conflict (described above) (UPDATE_CONFLICT)
  94          * </ul>
  95          * @since 3.0
  96          */
  97         void commitWorkingCopy(boolean force, IProgressMonitor monitor) throws JavaModelException;
  98         /**
  99          * Changes this compilation unit in working copy mode back to its original mode.
 100          * <p>
 101          * This has no effect if this compilation unit was not in working copy mode.
 102          * </p>
 103          * <p>
 104          * If <code>becomeWorkingCopy</code> was called several times on this
 105          * compilation unit, <code>discardWorkingCopy</code> must be called as
 106          * many times before it switches back to the original mode.
 107          * </p>
 108          *
 109          * @throws JavaModelException if this working copy could not return in its original mode.
 110          * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
 111          * @since 3.0
 112          */
 113         void discardWorkingCopy() throws JavaModelException;
 114 /**
 115  * Creates and returns an import declaration in this compilation unit
 116  * with the given name.
 117  * <p>
 118  * Optionally, the new element can be positioned before the specified
 119  * sibling. If no sibling is specified, the element will be inserted
 120  * as the last import declaration in this compilation unit.
 121  * <p>
 122  * If the compilation unit already includes the specified import declaration,
 123  * the import is not generated (it does not generate duplicates).
 124  * Note that it is valid to specify both a single-type import and an on-demand import
 125  * for the same package, for example <code>"java.io.File"</code> and
 126  * <code>"java.io.*"</code>, in which case both are preserved since the semantics
 127  * of this are not the same as just importing <code>"java.io.*"</code>.
 128  * Importing <code>"java.lang.*"</code>, or the package in which the compilation unit
 129  * is defined, are not treated as special cases.  If they are specified, they are
 130  * included in the result.
 131  *
 132  * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> or
 133  *  <code>"java.awt.*"</code>)
 134  * @param sibling the existing element which the import declaration will be inserted immediately before (if
 135  *      <code> null </code>, then this import will be inserted as the last import declaration.
 136  * @param monitor the progress monitor to notify
 137  * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)
 138  *
 139  * @exception JavaModelException if the element could not be created. Reasons include:
 140  * <ul>
 141  * <li> This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 142  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 143  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
 144  * <li> The name is not a valid import name (INVALID_NAME)
 145  * </ul>
 146  */
 147 //IImportDeclaration createImport(String name, IJavaElement sibling, IProgressMonitor monitor) throws JavaModelException;
 148 /**
 149  * Creates and returns a package declaration in this compilation unit
 150  * with the given package name.
 151  *
 152  * <p>If the compilation unit already includes the specified package declaration,
 153  * it is not generated (it does not generate duplicates).
 154  *
 155  * @param name the name of the package declaration to add as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
 156  * @param monitor the progress monitor to notify
 157  * @return the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate)
 158  *
 159  * @exception JavaModelException if the element could not be created. Reasons include:
 160  * <ul>
 161  * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 162  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 163  * <li> The name is not a valid package name (INVALID_NAME)
 164  * </ul>
 165  */
 166 // IPackageDeclaration createPackageDeclaration(String name, IProgressMonitor monitor) throws JavaModelException;
 167 /**
 168  * Creates and returns a type in this compilation unit with the
 169  * given contents. If this compilation unit does not exist, one
 170  * will be created with an appropriate package declaration.
 171  * <p>
 172  * Optionally, the new type can be positioned before the specified
 173  * sibling. If <code>sibling</code> is <code>null</code>, the type will be appended
 174  * to the end of this compilation unit.
 175  *
 176  * <p>It is possible that a type with the same name already exists in this compilation unit.
 177  * The value of the <code>force</code> parameter effects the resolution of
 178  * such a conflict:<ul>
 179  * <li> <code>true</code> - in this case the type is created with the new contents</li>
 180  * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
 181  * </ul>
 182  *
 183  * @param contents the source contents of the type declaration to add.
 184  * @param sibling the existing element which the type will be inserted immediately before (if
 185  *      <code> null </code>, then this type will be inserted as the last type declaration.
 186  * @param force a <code> boolean </code> flag indicating how to deal with duplicates
 187  * @param monitor the progress monitor to notify
 188  * @return the newly inserted type
 189  *
 190  * @exception JavaModelException if the element could not be created. Reasons include:
 191  * <ul>
 192  * <li>The specified sibling element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 193  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 194  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
 195  * <li> The contents could not be recognized as a type declaration (INVALID_CONTENTS)
 196  * <li> There was a naming collision with an existing type (NAME_COLLISION)
 197  * </ul>
 198  */
 199 //IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) throws JavaModelException;
 200 /**
 201  * Returns all types declared in this compilation unit in the order
 202  * in which they appear in the source.
 203  * This includes all top-level types and nested member types.
 204  * It does NOT include local types (types defined in methods).
 205  *
 206  * @return the array of top-level and member types defined in a compilation unit, in declaration order.
 207  * @exception JavaModelException if this element does not exist or if an
 208  *              exception occurs while accessing its corresponding resource
 209  */
 210 IType[] getAllTypes() throws JavaModelException;
 211 /**
 212  * Returns the smallest element within this compilation unit that
 213  * includes the given source position (that is, a method, field, etc.), or
 214  * <code>null</code> if there is no element other than the compilation
 215  * unit itself at the given position, or if the given position is not
 216  * within the source range of this compilation unit.
 217  *
 218  * @param position a source position inside the compilation unit
 219  * @return the innermost Java element enclosing a given source position or <code>null</code>
 220  *      if none (excluding the compilation unit).
 221  * @exception JavaModelException if the compilation unit does not exist or if an
 222  *              exception occurs while accessing its corresponding resource
 223  */
 224 IJavaElement getElementAt(int position) throws JavaModelException;
 225 /**
 226  * Returns the first import declaration in this compilation unit with the given name.
 227  * This is a handle-only method. The import declaration may or may not exist. This
 228  * is a convenience method - imports can also be accessed from a compilation unit's
 229  * import container.
 230  *
 231  * @param name the name of the import to find as defined by JLS2 7.5. (For example: <code>"java.io.File"</code>
 232  *      or <code>"java.awt.*"</code>)
 233  * @return a handle onto the corresponding import declaration. The import declaration may or may not exist.
 234  */
 235 IImportDeclaration getImport(String name) ;
 236 /**
 237  * Returns the import declarations in this compilation unit
 238  * in the order in which they appear in the source. This is
 239  * a convenience method - import declarations can also be
 240  * accessed from a compilation unit's import container.
 241  *
 242  * @return the import declarations in this compilation unit
 243  * @throws JavaModelException if this element does not exist or if an
 244  *              exception occurs while accessing its corresponding resource
 245  */
 246 IImportDeclaration[] getImports() throws JavaModelException;
 247 /**
 248  * Returns the import container for this compilation unit.
 249  * This is a handle-only method. The import container may or
 250  * may not exist. The import container can used to access the
 251  * imports.
 252  * @return a handle onto the corresponding import container. The
 253  *              import contain may or may not exist.
 254  */
 255 IImportContainer getImportContainer();
 256 /**
 257  * Returns the import declarations in this compilation unit
 258  * in the order in which they appear in the source. This is
 259  * a convenience method - import declarations can also be
 260  * accessed from a compilation unit's import container.
 261  *
 262  * @exception JavaModelException if this element does not exist or if an
 263  *              exception occurs while accessing its corresponding resource
 264  */
 265 //IImportDeclaration[] getImports() throws JavaModelException;
 266 /**
 267  * Returns the first package declaration in this compilation unit with the given package name
 268  * (there normally is at most one package declaration).
 269  * This is a handle-only method. The package declaration may or may not exist.
 270  *
 271  * @param name the name of the package declaration as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
 272  */
 273 IPackageDeclaration getPackageDeclaration(String name);
 274 /**
 275  * Returns the package declarations in this compilation unit
 276  * in the order in which they appear in the source.
 277  * There normally is at most one package declaration.
 278  *
 279  * @return an array of package declaration (normally of size one)
 280  *
 281  * @exception JavaModelException if this element does not exist or if an
 282  *              exception occurs while accessing its corresponding resource
 283  */
 284 IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
 285 /**
 286  * Returns the primary compilation unit (whose owner is the primary owner)
 287  * this working copy was created from, or this compilation unit if this a primary
 288  * compilation unit.
 289  * <p>
 290  * Note that the returned primary compilation unit can be in working copy mode.
 291  * </p>
 292  *
 293  * @return the primary compilation unit this working copy was created from,
 294  * or this compilation unit if it is primary
 295  * @since 3.0
 296  */
 297 ICompilationUnit getPrimary();
 298 /**
 299  * Returns the top-level type declared in this compilation unit with the given simple type name.
 300  * The type name has to be a valid compilation unit name.
 301  * This is a handle-only method. The type may or may not exist.
 302  *
 303  * @param name the simple name of the requested type in the compilation unit
 304  * @return a handle onto the corresponding type. The type may or may not exist.
 305  * @see JavaConventions#validateCompilationUnitName(String name)
 306  */
 307 IType getType(String name);
 308 /**
 309  * Returns the top-level types declared in this compilation unit
 310  * in the order in which they appear in the source.
 311  *
 312  * @exception JavaModelException if this element does not exist or if an
 313  *              exception occurs while accessing its corresponding resource
 314  */
 315 IType[] getTypes() throws JavaModelException;
 316
 317 }