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