/*******************************************************************************
* 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 net.sourceforge.phpdt.internal.core.ImportContainer;
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 newIBuffer
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 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.
*/
ImportContainer 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; }