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