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;
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.
25 * This interface is not intended to be implemented by clients.
28 public interface ICompilationUnit extends IJavaElement, ISourceReference,
29 IParent, IOpenable, IWorkingCopy, ISourceManipulation {
30 // extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy,
31 // ISourceManipulation, ICodeAssist {
34 * Constant indicating that a reconcile operation should not return an AST.
38 public static final int NO_AST = 0;
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.
46 * When switching to working copy mode, problems are reported to given
47 * <code>IProblemRequestor</code>.
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.
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>.
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.
69 * a progress monitor used to report progress while opening this
70 * compilation unit or <code>null</code> if no progress should
72 * @throws JavaModelException
73 * if this compilation unit could not become a working copy.
74 * @see #discardWorkingCopy()
77 void becomeWorkingCopy(IProblemRequestor problemRequestor,
78 IProgressMonitor monitor) throws JavaModelException;
81 * Commits the contents of this working copy to its underlying resource.
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:
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>
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.
102 * a flag to handle the cases when the contents of the original
103 * resource have changed since this working copy was created
105 * the given progress monitor
106 * @throws JavaModelException
107 * if this working copy could not commit. Reasons include:
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)
117 void commitWorkingCopy(boolean force, IProgressMonitor monitor)
118 throws JavaModelException;
121 * Changes this compilation unit in working copy mode back to its original
124 * This has no effect if this compilation unit was not in working copy mode.
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.
132 * @throws JavaModelException
133 * if this working copy could not return in its original mode.
134 * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
137 void discardWorkingCopy() throws JavaModelException;
140 * Creates and returns an import declaration in this compilation unit with
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.
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.
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>)
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.
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)
171 * @exception JavaModelException
172 * if the element could not be created. Reasons include:
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)
183 // IImportDeclaration createImport(String name, IJavaElement sibling,
184 // IProgressMonitor monitor) throws JavaModelException;
186 * Creates and returns a package declaration in this compilation unit with
187 * the given package name.
190 * If the compilation unit already includes the specified package
191 * declaration, it is not generated (it does not generate duplicates).
194 * the name of the package declaration to add as defined by JLS2
195 * 7.4. (For example, <code>"java.lang"</code>)
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)
201 * @exception JavaModelException
202 * if the element could not be created. Reasons include:
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)
211 // IPackageDeclaration createPackageDeclaration(String name,
212 // IProgressMonitor monitor) throws JavaModelException;
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.
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.
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:
227 * <li> <code>true</code> - in this case the type is created with the new
229 * <li> <code>false</code> - in this case a
230 * <code>JavaModelException</code> is thrown</li>
234 * the source contents of the type declaration to add.
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.
240 * a <code> boolean </code> flag indicating how to deal with
243 * the progress monitor to notify
244 * @return the newly inserted type
246 * @exception JavaModelException
247 * if the element could not be created. Reasons include:
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
261 // IType createType(String contents, IJavaElement sibling, boolean force,
262 // IProgressMonitor monitor) throws JavaModelException;
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).
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
274 IType[] getAllTypes() throws JavaModelException;
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.
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
291 IJavaElement getElementAt(int position) throws JavaModelException;
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.
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.
306 IImportDeclaration getImport(String name);
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
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
319 IImportDeclaration[] getImports() throws JavaModelException;
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.
326 * @return a handle onto the corresponding import container. The import
327 * contain may or may not exist.
329 IImportContainer getImportContainer();
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
337 * @exception JavaModelException
338 * if this element does not exist or if an exception occurs
339 * while accessing its corresponding resource
341 // IImportDeclaration[] getImports() throws JavaModelException;
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
349 * the name of the package declaration as defined by JLS2 7.4.
350 * (For example, <code>"java.lang"</code>)
352 IPackageDeclaration getPackageDeclaration(String name);
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
359 * @return an array of package declaration (normally of size one)
361 * @exception JavaModelException
362 * if this element does not exist or if an exception occurs
363 * while accessing its corresponding resource
365 IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
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.
372 * Note that the returned primary compilation unit can be in working copy
376 * @return the primary compilation unit this working copy was created from,
377 * or this compilation unit if it is primary
380 ICompilationUnit getPrimary();
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.
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
391 * @see JavaConventions#validateCompilationUnitName(String name)
393 IType getType(String name);
396 * Returns the top-level types declared in this compilation unit in the
397 * order in which they appear in the source.
399 * @exception JavaModelException
400 * if this element does not exist or if an exception occurs
401 * while accessing its corresponding resource
403 IType[] getTypes() throws JavaModelException;