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
  14
  15 /**
  16  * Represents an entire Java compilation unit (<code>.java</code> source file).
  17  * Compilation unit elements need to be opened before they can be navigated or manipulated.
  18  * The children are of type <code>IPackageDeclaration</code>,
  19  * <code>IImportContainer</code>, and <code>IType</code>,
  20  * and appear in the order in which they are declared in the source.
  21  * If a <code>.java</code> file cannot be parsed, its structure remains unknown.
  22  * Use <code>IJavaElement.isStructureKnown</code> to determine whether this is
  23  * 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, IParent, IOpenable, IWorkingCopy, ISourceManipulation {
  29 //extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist {
  30 /**
  31  * Creates and returns an import declaration in this compilation unit
  32  * with the given name.
  33  * <p>
  34  * Optionally, the new element can be positioned before the specified
  35  * sibling. If no sibling is specified, the element will be inserted
  36  * as the last import declaration in this compilation unit.
  37  * <p>
  38  * If the compilation unit already includes the specified import declaration,
  39  * the import is not generated (it does not generate duplicates).
  40  * Note that it is valid to specify both a single-type import and an on-demand import
  41  * for the same package, for example <code>"java.io.File"</code> and
  42  * <code>"java.io.*"</code>, in which case both are preserved since the semantics
  43  * of this are not the same as just importing <code>"java.io.*"</code>.
  44  * Importing <code>"java.lang.*"</code>, or the package in which the compilation unit
  45  * is defined, are not treated as special cases.  If they are specified, they are
  46  * included in the result.
  47  *
  48  * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: <code>"java.io.File"</code> or
  49  *  <code>"java.awt.*"</code>)
  50  * @param sibling the existing element which the import declaration will be inserted immediately before (if
  51  *      <code> null </code>, then this import will be inserted as the last import declaration.
  52  * @param monitor the progress monitor to notify
  53  * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)
  54  *
  55  * @exception JavaModelException if the element could not be created. Reasons include:
  56  * <ul>
  57  * <li> This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  58  * <li> A <code>CoreException</code> occurred while updating an underlying resource
  59  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
  60  * <li> The name is not a valid import name (INVALID_NAME)
  61  * </ul>
  62  */
  63 //IImportDeclaration createImport(String name, IJavaElement sibling, IProgressMonitor monitor) throws JavaModelException;
  64 /**
  65  * Creates and returns a package declaration in this compilation unit
  66  * with the given package name.
  67  *
  68  * <p>If the compilation unit already includes the specified package declaration,
  69  * it is not generated (it does not generate duplicates).
  70  *
  71  * @param name the name of the package declaration to add as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
  72  * @param monitor the progress monitor to notify
  73  * @return the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate)
  74  *
  75  * @exception JavaModelException if the element could not be created. Reasons include:
  76  * <ul>
  77  * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  78  * <li> A <code>CoreException</code> occurred while updating an underlying resource
  79  * <li> The name is not a valid package name (INVALID_NAME)
  80  * </ul>
  81  */
  82 // IPackageDeclaration createPackageDeclaration(String name, IProgressMonitor monitor) throws JavaModelException;
  83 /**
  84  * Creates and returns a type in this compilation unit with the
  85  * given contents. If this compilation unit does not exist, one
  86  * will be created with an appropriate package declaration.
  87  * <p>
  88  * Optionally, the new type can be positioned before the specified
  89  * sibling. If <code>sibling</code> is <code>null</code>, the type will be appended
  90  * to the end of this compilation unit.
  91  *
  92  * <p>It is possible that a type with the same name already exists in this compilation unit.
  93  * The value of the <code>force</code> parameter effects the resolution of
  94  * such a conflict:<ul>
  95  * <li> <code>true</code> - in this case the type is created with the new contents</li>
  96  * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
  97  * </ul>
  98  *
  99  * @param contents the source contents of the type declaration to add.
 100  * @param sibling the existing element which the type will be inserted immediately before (if
 101  *      <code> null </code>, then this type will be inserted as the last type declaration.
 102  * @param force a <code> boolean </code> flag indicating how to deal with duplicates
 103  * @param monitor the progress monitor to notify
 104  * @return the newly inserted type
 105  *
 106  * @exception JavaModelException if the element could not be created. Reasons include:
 107  * <ul>
 108  * <li>The specified sibling element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 109  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 110  * <li> The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
 111  * <li> The contents could not be recognized as a type declaration (INVALID_CONTENTS)
 112  * <li> There was a naming collision with an existing type (NAME_COLLISION)
 113  * </ul>
 114  */
 115 //IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) throws JavaModelException;
 116 /**
 117  * Returns all types declared in this compilation unit in the order
 118  * in which they appear in the source.
 119  * This includes all top-level types and nested member types.
 120  * It does NOT include local types (types defined in methods).
 121  *
 122  * @return the array of top-level and member types defined in a compilation unit, in declaration order.
 123  * @exception JavaModelException if this element does not exist or if an
 124  *              exception occurs while accessing its corresponding resource
 125  */
 126 IType[] getAllTypes() throws JavaModelException;
 127 /**
 128  * Returns the smallest element within this compilation unit that
 129  * includes the given source position (that is, a method, field, etc.), or
 130  * <code>null</code> if there is no element other than the compilation
 131  * unit itself at the given position, or if the given position is not
 132  * within the source range of this compilation unit.
 133  *
 134  * @param position a source position inside the compilation unit
 135  * @return the innermost Java element enclosing a given source position or <code>null</code>
 136  *      if none (excluding the compilation unit).
 137  * @exception JavaModelException if the compilation unit does not exist or if an
 138  *              exception occurs while accessing its corresponding resource
 139  */
 140 IJavaElement getElementAt(int position) throws JavaModelException;
 141 /**
 142  * Returns the first import declaration in this compilation unit with the given name.
 143  * This is a handle-only method. The import declaration may or may not exist. This
 144  * is a convenience method - imports can also be accessed from a compilation unit's
 145  * import container.
 146  *
 147  * @param name the name of the import to find as defined by JLS2 7.5. (For example: <code>"java.io.File"</code>
 148  *      or <code>"java.awt.*"</code>)
 149  * @return a handle onto the corresponding import declaration. The import declaration may or may not exist.
 150  */
 151 //IImportDeclaration getImport(String name) ;
 152 /**
 153  * Returns the import container for this compilation unit.
 154  * This is a handle-only method. The import container may or
 155  * may not exist. The import container can used to access the
 156  * imports.
 157  * @return a handle onto the corresponding import container. The
 158  *              import contain may or may not exist.
 159  */
 160 //IImportContainer getImportContainer();
 161 /**
 162  * Returns the import declarations in this compilation unit
 163  * in the order in which they appear in the source. This is
 164  * a convenience method - import declarations can also be
 165  * accessed from a compilation unit's import container.
 166  *
 167  * @exception JavaModelException if this element does not exist or if an
 168  *              exception occurs while accessing its corresponding resource
 169  */
 170 //IImportDeclaration[] getImports() throws JavaModelException;
 171 /**
 172  * Returns the first package declaration in this compilation unit with the given package name
 173  * (there normally is at most one package declaration).
 174  * This is a handle-only method. The package declaration may or may not exist.
 175  *
 176  * @param name the name of the package declaration as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
 177  */
 178 IPackageDeclaration getPackageDeclaration(String name);
 179 /**
 180  * Returns the package declarations in this compilation unit
 181  * in the order in which they appear in the source.
 182  * There normally is at most one package declaration.
 183  *
 184  * @return an array of package declaration (normally of size one)
 185  *
 186  * @exception JavaModelException if this element does not exist or if an
 187  *              exception occurs while accessing its corresponding resource
 188  */
 189 //IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
 190 /**
 191  * Returns the top-level type declared in this compilation unit with the given simple type name.
 192  * The type name has to be a valid compilation unit name.
 193  * This is a handle-only method. The type may or may not exist.
 194  *
 195  * @param name the simple name of the requested type in the compilation unit
 196  * @return a handle onto the corresponding type. The type may or may not exist.
 197  * @see JavaConventions#validateCompilationUnitName(String name)
 198  */
 199 IType getType(String name);
 200 /**
 201  * Returns the top-level types declared in this compilation unit
 202  * in the order in which they appear in the source.
 203  *
 204  * @exception JavaModelException if this element does not exist or if an
 205  *              exception occurs while accessing its corresponding resource
 206  */
 207 IType[] getTypes() throws JavaModelException;
 208
 209 }