org.eclipse.jdt.core
Interface ICompilationUnit

All Superinterfaces:

IAdaptable, ICodeAssist, IJavaElement, IOpenable, IParent, ISourceManipulation, ISourceReference, IWorkingCopy

public interface ICompilationUnit

extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist

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.

Field Summary

Fields inherited from interface org.eclipse.jdt.core.IJavaElement

CLASS_FILE, COMPILATION_UNIT, FIELD, IMPORT_CONTAINER, IMPORT_DECLARATION, INITIALIZER, JAVA_MODEL, JAVA_PROJECT, METHOD, PACKAGE_DECLARATION, PACKAGE_FRAGMENT, PACKAGE_FRAGMENT_ROOT, TYPE

Method Summary

IImportDeclaration	createImport(String name, IJavaElement sibling, IProgressMonitor monitor) Creates and returns an import declaration in this compilation unit with the given name.
IPackageDeclaration	createPackageDeclaration(String name, IProgressMonitor monitor) Creates and returns a package declaration in this compilation unit with the given package name.
IType	createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) Creates and returns a type in this compilation unit with the given contents.
IType[]	getAllTypes() Returns all types declared in this compilation unit in the order in which they appear in the source.
IJavaElement	getElementAt(int position) Returns the smallest element within this compilation unit that includes the given source position (that is, a method, field, etc.), or 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.
IImportDeclaration	getImport(String name) Returns the first import declaration in this compilation unit with the given name.
IImportContainer	getImportContainer() Returns the import container for this compilation unit.
IImportDeclaration[]	getImports() Returns the import declarations in this compilation unit in the order in which they appear in the source.
IPackageDeclaration	getPackageDeclaration(String name) Returns the first package declaration in this compilation unit with the given package name (there normally is at most one package declaration).
IPackageDeclaration[]	getPackageDeclarations() Returns the package declarations in this compilation unit in the order in which they appear in the source.
IType	getType(String name) Returns the top-level type declared in this compilation unit with the given simple type name.
IType[]	getTypes() Returns the top-level types declared in this compilation unit in the order in which they appear in the source.

Methods inherited from interface org.eclipse.jdt.core.IJavaElement

exists, getAncestor, getCorrespondingResource, getElementName, getElementType, getHandleIdentifier, getJavaModel, getJavaProject, getOpenable, getParent, getPath, getResource, getUnderlyingResource, isReadOnly, isStructureKnown

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Methods inherited from interface org.eclipse.jdt.core.ISourceReference

exists, getSource, getSourceRange

Methods inherited from interface org.eclipse.jdt.core.IParent

getChildren, hasChildren

Methods inherited from interface org.eclipse.jdt.core.IOpenable

close, getBuffer, hasUnsavedChanges, isConsistent, isOpen, makeConsistent, open, save

Methods inherited from interface org.eclipse.jdt.core.IWorkingCopy

commit, destroy, findElements, findPrimaryType, findSharedWorkingCopy, getOriginal, getOriginalElement, getSharedWorkingCopy, getWorkingCopy, getWorkingCopy, isBasedOn, isWorkingCopy, reconcile, reconcile, restore

Methods inherited from interface org.eclipse.jdt.core.ISourceManipulation

copy, delete, move, rename

Methods inherited from interface org.eclipse.jdt.core.ICodeAssist

codeComplete, codeComplete, codeSelect

Method Detail

createImport

public IImportDeclaration createImport(String name,
                                       IJavaElement sibling,
                                       IProgressMonitor monitor)
                                throws JavaModelException

Creates and returns an import declaration in this compilation unit with the given name.

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.

Parameters:

name - the name of the import declaration to add as defined by JLS2 7.5. (For example: "java.io.File" or "java.awt.*")

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.

monitor - the progress monitor to notify

Returns:

the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate)

Throws:

JavaModelException - if the element could not be created. Reasons include:

• This Java element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)
• A CoreException occurred while updating an underlying resource
• The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
• The name is not a valid import name (INVALID_NAME)

createPackageDeclaration

public IPackageDeclaration createPackageDeclaration(String name,
                                                    IProgressMonitor monitor)
                                             throws JavaModelException

Creates and returns a package declaration in this compilation unit with the given package name.

If the compilation unit already includes the specified package declaration, it is not generated (it does not generate duplicates).

Parameters:

name - the name of the package declaration to add as defined by JLS2 7.4. (For example, "java.lang")

monitor - the progress monitor to notify

Returns:

the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate)

Throws:

JavaModelException - if the element could not be created. Reasons include:

• This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
• A CoreException occurred while updating an underlying resource
• The name is not a valid package name (INVALID_NAME)

createType

public IType createType(String contents,
                        IJavaElement sibling,
                        boolean force,
                        IProgressMonitor monitor)
                 throws JavaModelException

Creates and returns a type in this compilation unit with the given contents. If this compilation unit does not exist, one will be created with an appropriate package declaration.

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 contents
• false - in this case a JavaModelException is thrown

Parameters:

contents - the source contents of the type declaration to add.

sibling - the existing element which the type will be inserted immediately before (if null , then this type will be inserted as the last type declaration.

force - a boolean flag indicating how to deal with duplicates

monitor - the progress monitor to notify

Returns:

the newly inserted type

Throws:

JavaModelException - if the element could not be created. Reasons include:

• The specified sibling element does not exist (ELEMENT_DOES_NOT_EXIST)
• A CoreException occurred while updating an underlying resource
• The specified sibling is not a child of this compilation unit (INVALID_SIBLING)
• The contents could not be recognized as a type declaration (INVALID_CONTENTS)
• There was a naming collision with an existing type (NAME_COLLISION)

getAllTypes

public IType[] getAllTypes()
                    throws JavaModelException

Returns all types declared in this compilation unit in the order in which they appear in the source. This includes all top-level types and nested member types. It does NOT include local types (types defined in methods).

Returns:

the array of top-level and member types defined in a compilation unit, in declaration order.

Throws:

JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource

getElementAt

public IJavaElement getElementAt(int position)
                          throws JavaModelException

Returns the smallest element within this compilation unit that includes the given source position (that is, a method, field, etc.), or 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.

Parameters:

position - a source position inside the compilation unit

Returns:

the innermost Java element enclosing a given source position or null if none (excluding the compilation unit).

Throws:

JavaModelException - if the compilation unit does not exist or if an exception occurs while accessing its corresponding resource

getImport

public IImportDeclaration getImport(String name)

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.

Parameters:

name - the name of the import to find as defined by JLS2 7.5. (For example: "java.io.File" or "java.awt.*")

Returns:

a handle onto the corresponding import declaration. The import declaration may or may not exist.

getImportContainer

public IImportContainer getImportContainer()

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.

Returns:

a handle onto the corresponding import container. The import contain may or may not exist.

getImports

public IImportDeclaration[] getImports()
                                throws JavaModelException

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.

Throws:

JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource

getPackageDeclaration

public IPackageDeclaration getPackageDeclaration(String name)

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.

Parameters:

name - the name of the package declaration as defined by JLS2 7.4. (For example, "java.lang")

getPackageDeclarations

public IPackageDeclaration[] getPackageDeclarations()
                                             throws JavaModelException

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.

Returns:

an array of package declaration (normally of size one)

Throws:

JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource

getType

public IType getType(String name)

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.

Parameters:

name - the simple name of the requested type in the compilation unit

Returns:

a handle onto the corresponding type. The type may or may not exist.

See Also:

JavaConventions.validateCompilationUnitName(String name)

getTypes

public IType[] getTypes()
                 throws JavaModelException

Returns the top-level types declared in this compilation unit in the order in which they appear in the source.

Throws:

JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource