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;
13 import org.eclipse.core.runtime.IProgressMonitor;
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
27 * This interface is not intended to be implemented by clients.
30 public interface ICompilationUnit extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation {
31 //extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist {
34 * Constant indicating that a reconcile operation should not return an AST.
37 public static final int NO_AST = 0;
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.
44 * When switching to working copy mode, problems are reported to given
45 * <code>IProblemRequestor</code>.
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.
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>.
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()
68 void becomeWorkingCopy(IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException;
70 * Commits the contents of this working copy to its underlying resource.
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>
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.
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:
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)
97 void commitWorkingCopy(boolean force, IProgressMonitor monitor) throws JavaModelException;
99 * Changes this compilation unit in working copy mode back to its original mode.
101 * This has no effect if this compilation unit was not in working copy mode.
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.
109 * @throws JavaModelException if this working copy could not return in its original mode.
110 * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
113 void discardWorkingCopy() throws JavaModelException;
115 * Creates and returns an import declaration in this compilation unit
116 * with the given name.
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.
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.
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)
139 * @exception JavaModelException if the element could not be created. Reasons include:
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)
147 //IImportDeclaration createImport(String name, IJavaElement sibling, IProgressMonitor monitor) throws JavaModelException;
149 * Creates and returns a package declaration in this compilation unit
150 * with the given package name.
152 * <p>If the compilation unit already includes the specified package declaration,
153 * it is not generated (it does not generate duplicates).
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)
159 * @exception JavaModelException if the element could not be created. Reasons include:
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)
166 // IPackageDeclaration createPackageDeclaration(String name, IProgressMonitor monitor) throws JavaModelException;
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.
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.
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>
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
190 * @exception JavaModelException if the element could not be created. Reasons include:
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)
199 //IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) throws JavaModelException;
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).
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
210 IType[] getAllTypes() throws JavaModelException;
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.
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
224 IJavaElement getElementAt(int position) throws JavaModelException;
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
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.
235 IImportDeclaration getImport(String name) ;
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.
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
246 IImportDeclaration[] getImports() throws JavaModelException;
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
252 * @return a handle onto the corresponding import container. The
253 * import contain may or may not exist.
255 IImportContainer getImportContainer();
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.
262 * @exception JavaModelException if this element does not exist or if an
263 * exception occurs while accessing its corresponding resource
265 //IImportDeclaration[] getImports() throws JavaModelException;
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.
271 * @param name the name of the package declaration as defined by JLS2 7.4. (For example, <code>"java.lang"</code>)
273 IPackageDeclaration getPackageDeclaration(String name);
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.
279 * @return an array of package declaration (normally of size one)
281 * @exception JavaModelException if this element does not exist or if an
282 * exception occurs while accessing its corresponding resource
284 IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
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
290 * Note that the returned primary compilation unit can be in working copy mode.
293 * @return the primary compilation unit this working copy was created from,
294 * or this compilation unit if it is primary
297 ICompilationUnit getPrimary();
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.
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)
307 IType getType(String name);
309 * Returns the top-level types declared in this compilation unit
310 * in the order in which they appear in the source.
312 * @exception JavaModelException if this element does not exist or if an
313 * exception occurs while accessing its corresponding resource
315 IType[] getTypes() throws JavaModelException;