/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package net.sourceforge.phpdt.core;
import org.eclipse.core.runtime.IProgressMonitor;
/**
* Represents an entire Java compilation unit (.java
source
* file). Compilation unit elements need to be opened before they can be
* navigated or manipulated. The children are of type
* IPackageDeclaration
, IImportContainer
, and
* IType
, and appear in the order in which they are declared in
* the source. If a .java
file cannot be parsed, its structure
* remains unknown. Use IJavaElement.isStructureKnown
to
* determine whether this is the case.
*
* This interface is not intended to be implemented by clients. *
*/ public interface ICompilationUnit extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation { // extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, // ISourceManipulation, ICodeAssist { /** * Constant indicating that a reconcile operation should not return an AST. * * @since 3.0 */ public static final int NO_AST = 0; /** * Changes this compilation unit handle into a working copy. A new *IBuffer
is created using this compilation unit handle's
* owner. Uses the primary owner is none was specified when this compilation
* unit handle was created.
*
* When switching to working copy mode, problems are reported to given
* IProblemRequestor
.
*
* Once in working copy mode, changes to this compilation unit or its
* children are done in memory. Only the new buffer is affected. Using
* commitWorkingCopy(boolean, IProgressMonitor)
will bring
* the underlying resource in sync with this compilation unit.
*
* If this compilation unit was already in working copy mode, an internal
* counter is incremented and no other action is taken on this compilation
* unit. To bring this compilation unit back into the original mode (where
* it reflects the underlying resource), discardWorkingCopy
* must be call as many times as becomeWorkingCopy
.
*
null
indicating that the client is
* not interested in problems.
* @param monitor
* a progress monitor used to report progress while opening this
* compilation unit or null
if no progress should
* be reported
* @throws JavaModelException
* if this compilation unit could not become a working copy.
* @see #discardWorkingCopy()
* @since 3.0
*/
void becomeWorkingCopy(IProblemRequestor problemRequestor,
IProgressMonitor monitor) throws JavaModelException;
/**
* Commits the contents of this working copy to its underlying resource.
*
*
* It is possible that the contents of the original resource have changed
* since this working copy was created, in which case there is an update
* conflict. The value of the force
parameter effects the
* resolution of such a conflict:
*
true
- in this case the contents of this working copy
* are applied to the underlying resource even though this working copy was
* created before a subsequent change in the resourcefalse
- in this case a
* JavaModelException
is thrown* Since 2.1, a working copy can be created on a not-yet existing * compilation unit. In particular, such a working copy can then be * committed in order to create the corresponding compilation unit. *
* * @param force * a flag to handle the cases when the contents of the original * resource have changed since this working copy was created * @param monitor * the given progress monitor * @throws JavaModelException * if this working copy could not commit. Reasons include: *CoreException
occurred while updating
* an underlying resource
* * This has no effect if this compilation unit was not in working copy mode. *
*
* If becomeWorkingCopy
was called several times on this
* compilation unit, discardWorkingCopy
must be called as
* many times before it switches back to the original mode.
*
* Optionally, the new element can be positioned before the specified * sibling. If no sibling is specified, the element will be inserted as the * last import declaration in this compilation unit. *
* If the compilation unit already includes the specified import
* declaration, the import is not generated (it does not generate
* duplicates). Note that it is valid to specify both a single-type import
* and an on-demand import for the same package, for example
* "java.io.File"
and "java.io.*"
, in which
* case both are preserved since the semantics of this are not the same as
* just importing "java.io.*"
. Importing
* "java.lang.*"
, or the package in which the compilation
* unit is defined, are not treated as special cases. If they are specified,
* they are included in the result.
*
* @param name
* the name of the import declaration to add as defined by JLS2
* 7.5. (For example: "java.io.File"
or
* "java.awt.*"
)
* @param sibling
* the existing element which the import declaration will be
* inserted immediately before (if null
, then
* this import will be inserted as the last import declaration.
* @param monitor
* the progress monitor to notify
* @return the newly inserted import declaration (or the previously existing
* one in case attempting to create a duplicate)
*
* @exception JavaModelException
* if the element could not be created. Reasons include:
*
CoreException
occurred while
* updating an underlying resource
*
* If the compilation unit already includes the specified package
* declaration, it is not generated (it does not generate duplicates).
*
* @param name
* the name of the package declaration to add as defined by JLS2
* 7.4. (For example, "java.lang"
)
* @param monitor
* the progress monitor to notify
* @return the newly inserted package declaration (or the previously
* existing one in case attempting to create a duplicate)
*
* @exception JavaModelException
* if the element could not be created. Reasons include:
*
CoreException
occurred while
* updating an underlying resource
*
* Optionally, the new type can be positioned before the specified sibling.
* If sibling
is null
, the type will be
* appended to the end of this compilation unit.
*
*
* It is possible that a type with the same name already exists in this
* compilation unit. The value of the force
parameter effects
* the resolution of such a conflict:
*
true
- in this case the type is created with the new
* contentsfalse
- in this case a
* JavaModelException
is thrown null
, then this type
* will be inserted as the last type declaration.
* @param force
* a boolean
flag indicating how to deal with
* duplicates
* @param monitor
* the progress monitor to notify
* @return the newly inserted type
*
* @exception JavaModelException
* if the element could not be created. Reasons include:
* CoreException
occurred while
* updating an underlying resource
* null
if there is no element other than the compilation
* unit itself at the given position, or if the given position is not within
* the source range of this compilation unit.
*
* @param position
* a source position inside the compilation unit
* @return the innermost Java element enclosing a given source position or
* null
if none (excluding the compilation unit).
* @exception JavaModelException
* if the compilation unit does not exist or if an exception
* occurs while accessing its corresponding resource
*/
IJavaElement getElementAt(int position) throws JavaModelException;
/**
* Returns the first import declaration in this compilation unit with the
* given name. This is a handle-only method. The import declaration may or
* may not exist. This is a convenience method - imports can also be
* accessed from a compilation unit's import container.
*
* @param name
* the name of the import to find as defined by JLS2 7.5. (For
* example: "java.io.File"
or
* "java.awt.*"
)
* @return a handle onto the corresponding import declaration. The import
* declaration may or may not exist.
*/
IImportDeclaration getImport(String name);
/**
* Returns the import declarations in this compilation unit in the order in
* which they appear in the source. This is a convenience method - import
* declarations can also be accessed from a compilation unit's import
* container.
*
* @return the import declarations in this compilation unit
* @throws JavaModelException
* if this element does not exist or if an exception occurs
* while accessing its corresponding resource
*/
IImportDeclaration[] getImports() throws JavaModelException;
/**
* Returns the import container for this compilation unit. This is a
* handle-only method. The import container may or may not exist. The import
* container can used to access the imports.
*
* @return a handle onto the corresponding import container. The import
* contain may or may not exist.
*/
IImportContainer getImportContainer();
/**
* Returns the import declarations in this compilation unit in the order in
* which they appear in the source. This is a convenience method - import
* declarations can also be accessed from a compilation unit's import
* container.
*
* @exception JavaModelException
* if this element does not exist or if an exception occurs
* while accessing its corresponding resource
*/
// IImportDeclaration[] getImports() throws JavaModelException;
/**
* Returns the first package declaration in this compilation unit with the
* given package name (there normally is at most one package declaration).
* This is a handle-only method. The package declaration may or may not
* exist.
*
* @param name
* the name of the package declaration as defined by JLS2 7.4.
* (For example, "java.lang"
)
*/
IPackageDeclaration getPackageDeclaration(String name);
/**
* Returns the package declarations in this compilation unit in the order in
* which they appear in the source. There normally is at most one package
* declaration.
*
* @return an array of package declaration (normally of size one)
*
* @exception JavaModelException
* if this element does not exist or if an exception occurs
* while accessing its corresponding resource
*/
IPackageDeclaration[] getPackageDeclarations() throws JavaModelException;
/**
* Returns the primary compilation unit (whose owner is the primary owner)
* this working copy was created from, or this compilation unit if this a
* primary compilation unit.
* * Note that the returned primary compilation unit can be in working copy * mode. *
* * @return the primary compilation unit this working copy was created from, * or this compilation unit if it is primary * @since 3.0 */ ICompilationUnit getPrimary(); /** * Returns the top-level type declared in this compilation unit with the * given simple type name. The type name has to be a valid compilation unit * name. This is a handle-only method. The type may or may not exist. * * @param name * the simple name of the requested type in the compilation unit * @return a handle onto the corresponding type. The type may or may not * exist. * @see JavaConventions#validateCompilationUnitName(String name) */ IType getType(String name); /** * Returns the top-level types declared in this compilation unit in the * order in which they appear in the source. * * @exception JavaModelException * if this element does not exist or if an exception occurs * while accessing its corresponding resource */ IType[] getTypes() throws JavaModelException; }