org.eclipse.jdt.core
Interface IJavaProject

All Superinterfaces:

IAdaptable, IJavaElement, IOpenable, IParent

public interface IJavaProject

extends IParent, IJavaElement, IOpenable

A Java project represents a view of a project resource in terms of Java elements such as package fragments, types, methods and fields. A project may contain several package roots, which contain package fragments. A package root corresponds to an underlying folder or JAR.

Each Java project has a classpath, defining which folders contain source code and where required libraries are located. Each Java project also has an output location, defining where the builder writes .class files. A project that references packages in another project can access the packages by including the required project in a classpath entry. The Java model will present the source elements in the required project, and when building, the compiler will use the binaries from that project (that is, the output location of the required project is used as a library). The classpath format is a sequence of classpath entries describing the location and contents of package fragment roots.

Java project elements need to be opened before they can be navigated or manipulated. The children of a Java project are the package fragment roots that are defined by the classpath and contained in this project (in other words, it does not include package fragment roots for other projects).

This interface is not intended to be implemented by clients. An instance of one of these handles can be created via JavaCore.create(project).

See Also:

JavaCore.create(org.eclipse.core.resources.IProject), IClasspathEntry

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

IJavaElement	findElement(IPath path) Returns the IJavaElement corresponding to the given classpath-relative path, or null if no such IJavaElement is found.
IPackageFragment	findPackageFragment(IPath path) Returns the first existing package fragment on this project's classpath whose path matches the given (absolute) path, or null if none exist.
IPackageFragmentRoot	findPackageFragmentRoot(IPath path) Returns the existing package fragment root on this project's classpath whose path matches the given (absolute) path, or null if one does not exist.
IType	findType(String fullyQualifiedName) Returns the first type found following this project's classpath with the given fully qualified name or null if none is found.
IType	findType(String packageName, String typeQualifiedName) Returns the first type found following this project's classpath with the given package name and type qualified name or null if none is found.
IPackageFragmentRoot[]	getAllPackageFragmentRoots() Returns all of the existing package fragment roots that exist on the classpath, in the order they are defined by the classpath.
Object[]	getNonJavaResources() Returns an array of non-Java resources directly contained in this project.
IPath	getOutputLocation() Returns the full path to the location where the builder writes .class files.
IPackageFragmentRoot	getPackageFragmentRoot(IResource resource) Returns a package fragment root for the given resource, which must either be a folder representing the top of a package hierarchy, or a .jar or .zip file.
IPackageFragmentRoot	getPackageFragmentRoot(String jarPath) Returns a package fragment root for the JAR at the specified file system path.
IPackageFragmentRoot[]	getPackageFragmentRoots() Returns all of the package fragment roots contained in this project, identified on this project's resolved classpath.
IPackageFragmentRoot[]	getPackageFragmentRoots(IClasspathEntry entry) Returns the existing package fragment roots identified by the given entry.
IPackageFragment[]	getPackageFragments() Returns all package fragments in all package fragment roots contained in this project.
IProject	getProject() Returns the IProject on which this IJavaProject was created.
IClasspathEntry[]	getRawClasspath() Returns the raw classpath for the project, as a list of classpath entries.
String[]	getRequiredProjectNames() Returns the names of the projects that are directly required by this project.
IClasspathEntry[]	getResolvedClasspath(boolean ignoreUnresolvedVariable) This is a helper method returning the resolved classpath for the project, as a list of classpath entries, where all classpath variable entries have been resolved and substituted with their final target entries.
boolean	hasBuildState() Returns whether this project has been built at least once and thus whether it has a build state.
boolean	hasClasspathCycle(IClasspathEntry[] entries) Returns whether setting this project's classpath to the given classpath entries would result in a cycle.
boolean	isOnClasspath(IJavaElement element) Returns whether the given element is on the classpath of this project.
IEvaluationContext	newEvaluationContext() Creates a new evaluation context.
ITypeHierarchy	newTypeHierarchy(IRegion region, IProgressMonitor monitor) Creates and returns a type hierarchy for all types in the given region, considering subtypes within that region.
ITypeHierarchy	newTypeHierarchy(IType type, IRegion region, IProgressMonitor monitor) Creates and returns a type hierarchy for the given type considering subtypes in the specified region.
void	setOutputLocation(IPath path, IProgressMonitor monitor) Sets the output location of this project to the location described by the given absolute path.
void	setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, IProgressMonitor monitor) Sets the both the classpath of this project and its output location at once.
void	setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor) Sets the classpath of this project using a list of classpath entries.

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

getChildren, hasChildren

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.IOpenable

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

Method Detail

findElement

public IJavaElement findElement(IPath path)
                         throws JavaModelException

Returns the IJavaElement corresponding to the given classpath-relative path, or null if no such IJavaElement is found. The result is one of an ICompilationUnit, IClassFile, or IPackageFragment.

When looking for a package fragment, there might be several potential matches; only one of them is returned.

For example, the path "java/lang/Object.java", would result in the ICompilationUnit or IClassFile corresponding to "java.lang.Object". The path "java/lang" would result in the IPackageFragment for "java.lang".

Parameters:

path - the given classpath-relative path

Returns:

the IJavaElement corresponding to the given classpath-relative path, or null if no such IJavaElement is found

Throws:

JavaModelException - if the given path is null or absolute

findPackageFragment

public IPackageFragment findPackageFragment(IPath path)
                                     throws JavaModelException

Returns the first existing package fragment on this project's classpath whose path matches the given (absolute) path, or null if none exist. The path can be: - internal to the workbench: "/Project/src" - external to the workbench: "c:/jdk/classes.zip/java/lang"

Parameters:

path - the given absolute path

Returns:

the first existing package fragment on this project's classpath whose path matches the given (absolute) path, or null if none exist

Throws:

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

findPackageFragmentRoot

public IPackageFragmentRoot findPackageFragmentRoot(IPath path)
                                             throws JavaModelException

Returns the existing package fragment root on this project's classpath whose path matches the given (absolute) path, or null if one does not exist. The path can be: - internal to the workbench: "/Compiler/src" - external to the workbench: "c:/jdk/classes.zip"

Parameters:

path - the given absolute path

Returns:

the existing package fragment root on this project's classpath whose path matches the given (absolute) path, or null if one does not exist

Throws:

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

findType

public IType findType(String fullyQualifiedName)
               throws JavaModelException

Returns the first type found following this project's classpath with the given fully qualified name or null if none is found. The fully qualified name is a dot-separated name. For example, a class B defined as a member type of a class A in package x.y should have a the fully qualified name "x.y.A.B".

Parameters:

fullyQualifiedName - the given fully qualified name

Returns:

the first type found following this project's classpath with the given fully qualified name or null if none is found

Throws:

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

Since:

2.0

See Also:

IType.getFullyQualifiedName(char)

findType

public IType findType(String packageName,
                      String typeQualifiedName)
               throws JavaModelException

Returns the first type found following this project's classpath with the given package name and type qualified name or null if none is found. The package name is a dot-separated name. The type qualified name is also a dot-separated name. For example, a class B defined as a member type of a class A should have the type qualified name "A.B".

Parameters:

packageName - the given package name

typeQualifiedName - the given type qualified name

Returns:

the first type found following this project's classpath with the given package name and type qualified name or null if none is found

Throws:

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

Since:

2.0

See Also:

IType.getTypeQualifiedName(char)

getAllPackageFragmentRoots

public IPackageFragmentRoot[] getAllPackageFragmentRoots()
                                                  throws JavaModelException

Returns all of the existing package fragment roots that exist on the classpath, in the order they are defined by the classpath.

Returns:

all of the existing package fragment roots that exist on the classpath

Throws:

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

getNonJavaResources

public Object[] getNonJavaResources()
                             throws JavaModelException

Returns an array of non-Java resources directly contained in this project. It does not transitively answer non-Java resources contained in folders; these would have to be explicitly iterated over.

Returns:

an array of non-Java resources directly contained in this project

JavaModelException

getOutputLocation

public IPath getOutputLocation()
                        throws JavaModelException

Returns the full path to the location where the builder writes .class files.

Returns:

the full path to the location where the builder writes .class files

Throws:

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

getPackageFragmentRoot

public IPackageFragmentRoot getPackageFragmentRoot(String jarPath)

Returns a package fragment root for the JAR at the specified file system path. This is a handle-only method. The underlying java.io.File may or may not exist. No resource is associated with this local JAR package fragment root.

Parameters:

jarPath - the jars's file system path

Returns:

a package fragment root for the JAR at the specified file system path

getPackageFragmentRoot

public IPackageFragmentRoot getPackageFragmentRoot(IResource resource)

Returns a package fragment root for the given resource, which must either be a folder representing the top of a package hierarchy, or a .jar or .zip file. This is a handle-only method. The underlying resource may or may not exist.

Parameters:

resource - the given resource

Returns:

a package fragment root for the given resource, which must either be a folder representing the top of a package hierarchy, or a .jar or .zip file

getPackageFragmentRoots

public IPackageFragmentRoot[] getPackageFragmentRoots()
                                               throws JavaModelException

Returns all of the package fragment roots contained in this project, identified on this project's resolved classpath. The result does not include package fragment roots in other projects referenced on this project's classpath.

NOTE: This is equivalent to getChildren().

Returns:

all of the package fragment roots contained in this project, identified on this project's resolved classpath

Throws:

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

getPackageFragmentRoots

public IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry)

Returns the existing package fragment roots identified by the given entry. Note that a classpath entry that refers to another project may have more than one root (if that project has more than on root containing source), and classpath entries within the current project identify a single root.

If the classpath entry denotes a variable, it will be resolved and return the roots of the target entry (empty if not resolvable).

If the classpath entry denotes a container, it will be resolved and return the roots corresponding to the set of container entries (empty if not resolvable).

Parameters:

entry - the given entry

Returns:

the existing package fragment roots identified by the given entry

See Also:

IClasspathContainer

getPackageFragments

public IPackageFragment[] getPackageFragments()
                                       throws JavaModelException

Returns all package fragments in all package fragment roots contained in this project. This is a convenience method. Note that the package fragment roots corresponds to the resolved classpath of the project.

Returns:

all package fragments in all package fragment roots contained in this project

Throws:

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

getProject

public IProject getProject()

Returns the IProject on which this IJavaProject was created. This is handle-only method.

Returns:

the IProject on which this IJavaProject was created

getRawClasspath

public IClasspathEntry[] getRawClasspath()
                                  throws JavaModelException

Returns the raw classpath for the project, as a list of classpath entries. This corresponds to the exact set of entries which were assigned using setRawClasspath, in particular such a classpath may contain classpath variable entries. Classpath variable entries can be resolved individually (see JavaCore#getClasspathVariable), or the full classpath can be resolved at once using the helper method getResolvedClasspath.

A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows a classpath to no longer refer directly to external JARs located in some user specific location. The classpath can simply refer to some variables defining the proper locations of these external JARs.

Note that in case the project isn't yet opened, the classpath will directly be read from the associated .classpath file.

Returns:

the raw classpath for the project, as a list of classpath entries

Throws:

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

See Also:

IClasspathEntry

getRequiredProjectNames

public String[] getRequiredProjectNames()
                                 throws JavaModelException

Returns the names of the projects that are directly required by this project. A project is required if it is in its classpath.

Returns:

the names of the projects that are directly required by this project

Throws:

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

getResolvedClasspath

public IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedVariable)
                                       throws JavaModelException

This is a helper method returning the resolved classpath for the project, as a list of classpath entries, where all classpath variable entries have been resolved and substituted with their final target entries.

A resolved classpath corresponds to a particular instance of the raw classpath bound in the context of the current values of the referred variables, and thus should not be persisted.

A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows a classpath to no longer refer directly to external JARs located in some user specific location. The classpath can simply refer to some variables defining the proper locations of these external JARs.

The boolean argument ignoreUnresolvedVariable allows to specify how to handle unresolvable variables, when set to true, missing variables are simply ignored, the resulting path is then only formed of the resolvable entries, without any indication about which variable(s) was ignored. When set to false, a JavaModelException will be thrown for the first unresolved variable (from left to right).

Parameters:

ignoreUnresolvedVariable - specify how to handle unresolvable variables

Returns:

the resolved classpath for the project, as a list of classpath entries, where all classpath variable entries have been resolved and substituted with their final target entries

Throws:

JavaModelException - in one of the corresponding situation:

• this element does not exist
• an exception occurs while accessing its corresponding resource
• a classpath variable was not resolvable and ignoreUnresolvedVariable was set to false.

See Also:

IClasspathEntry

hasBuildState

public boolean hasBuildState()

Returns whether this project has been built at least once and thus whether it has a build state.

Returns:

true if this project has been built at least once, false otherwise

hasClasspathCycle

public boolean hasClasspathCycle(IClasspathEntry[] entries)

Returns whether setting this project's classpath to the given classpath entries would result in a cycle. If the set of entries contains some variables, those are resolved in order to determine cycles.

Parameters:

entries - the given classpath entries

Returns:

true if the given classpath entries would result in a cycle, false otherwise

isOnClasspath

public boolean isOnClasspath(IJavaElement element)
                      throws JavaModelException

Returns whether the given element is on the classpath of this project.

Parameters:

element - the given element

Returns:

true if the given element is on the classpath of this project, false otherwise

Throws:

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

Since:

2.0

newEvaluationContext

public IEvaluationContext newEvaluationContext()

Creates a new evaluation context.

Returns:

a new evaluation context.

newTypeHierarchy

public ITypeHierarchy newTypeHierarchy(IRegion region,
                                       IProgressMonitor monitor)
                                throws JavaModelException

Creates and returns a type hierarchy for all types in the given region, considering subtypes within that region.

Parameters:

monitor - the given progress monitor

region - the given region

Returns:

a type hierarchy for all types in the given region, considering subtypes within that region

Throws:

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

IllegalArgumentException - if region is null

newTypeHierarchy

public ITypeHierarchy newTypeHierarchy(IType type,
                                       IRegion region,
                                       IProgressMonitor monitor)
                                throws JavaModelException

Creates and returns a type hierarchy for the given type considering subtypes in the specified region.

Parameters:

monitor - the given monitor

region - the given region

type - the given type

Returns:

a type hierarchy for the given type considering subtypes in the specified region

Throws:

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

IllegalArgumentException - if type or region is null

setOutputLocation

public void setOutputLocation(IPath path,
                              IProgressMonitor monitor)
                       throws JavaModelException

Sets the output location of this project to the location described by the given absolute path.

Parameters:

path - the given absolute path

monitor - the given progress monitor

Throws:

JavaModelException - if the classpath could not be set. Reasons include:

• This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
• The path refers to a location not contained in this project (PATH_OUTSIDE_PROJECT)
• The path is not an absolute path (RELATIVE_PATH)
• The path is nested inside a package fragment root of this project (INVALID_PATH)
• The output location is being modified during resource change event notification (CORE_EXCEPTION)

setRawClasspath

public void setRawClasspath(IClasspathEntry[] entries,
                            IProgressMonitor monitor)
                     throws JavaModelException

Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain classpath variable entries. Classpath variable entries can be resolved individually (see JavaCore#getClasspathVariable), or the full classpath can be resolved at once using the helper method getResolvedClasspath.

A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows a classpath to no longer refer directly to external JARs located in some user specific location. The classpath can simply refer to some variables defining the proper locations of these external JARs.

Setting the classpath to null specifies a default classpath (the project root). Setting the classpath to an empty array specifies an empty classpath.

If a cycle is detected while setting this classpath, an error marker will be added to the project closing the cycle. To avoid this problem, use hasClasspathCycle(IClasspathEntry[] entries) before setting the classpath.

Parameters:

entries - a list of classpath entries

monitor - the given progress monitor

Throws:

JavaModelException - if the classpath could not be set. Reasons include:

• This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
• The classpath is being modified during resource change event notification (CORE_EXCEPTION)
• The classpath failed the validation check as defined by JavaConventions#validateClasspath

See Also:

IClasspathEntry

setRawClasspath

public void setRawClasspath(IClasspathEntry[] entries,
                            IPath outputLocation,
                            IProgressMonitor monitor)
                     throws JavaModelException

Sets the both the classpath of this project and its output location at once. The classpath is defined using a list of classpath entries. In particular such a classpath may contain classpath variable entries. Classpath variable entries can be resolved individually (see JavaCore#getClasspathVariable), or the full classpath can be resolved at once using the helper method getResolvedClasspath.

A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows a classpath to no longer refer directly to external JARs located in some user specific location. The classpath can simply refer to some variables defining the proper locations of these external JARs.

Setting the classpath to null specifies a default classpath (the project root). Setting the classpath to an empty array specifies an empty classpath.

If a cycle is detected while setting this classpath, an error marker will be added to the project closing the cycle. To avoid this problem, use hasClasspathCycle(IClasspathEntry[] entries) before setting the classpath.

Parameters:

entries - a list of classpath entries

monitor - the given progress monitor

outputLocation - the given output location

Throws:

JavaModelException - if the classpath could not be set. Reasons include:

• This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
• Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
• A entry of kind CPE_PROJECT refers to this project (INVALID_PATH)
• This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
• The output location path refers to a location not contained in this project (PATH_OUTSIDE_PROJECT)
• The output location path is not an absolute path (RELATIVE_PATH)
• The output location path is nested inside a package fragment root of this project (INVALID_PATH)
• The classpath is being modified during resource change event notification (CORE_EXCEPTION)

Since:

2.0

See Also:

IClasspathEntry