Setting the Java build path
This section describes how to set the Java build path. The build path is
the classpath that is used for building a Java project (
IJavaProject
).
A classpath is simply an array of classpath entries (
IClasspathEntry
)
that describe the types that are available. The types can appear in source
or binary form and the ordering of the entries on the path defines the lookup
order for resolving types during a build.
The Java build path is reflected in the structure of a Java project
element. You can query a project for its package fragment roots (
IPackageFragmentRoot
).
Each classpath entry maps to one or more package fragment roots, each of which
further contains a set of package fragments.
This discussion of the
build path does not involve the Java runtime path, which can be defined
separately from the build path. (See
RunningJava code
for a discussion of the runtime classpath.)
Changing the build path
You can programmatically change a project's build path using
setRawClasspath
on the corresponding project's Java element. The
following code sets the classpath for a project resource:
IProject project = ... // get some project resource
IJavaProject javaProject = JavaCore.create(project);
IClasspathEntry[] newClasspath = ...;
javaProject.setRawClasspath(newClasspath, someProgressMonitor);
(Note: The use of the term "raw" classpath is used to
emphasize the fact that any variables used to describe entry locations have not
been resolved.)
The Java build path is persisted into a file named '.classpath' in the project's
file structure. The purpose of this file is to provide a way to share Java build path settings with others through
some source code repository. In particular, this file should not be manually edited, since it may get corrupted.
Classpath entries
Classpath entries can be defined using factory methods defined on
JavaCore
.
Classpath entries can reference any of the following:
-
a source folder -
a folder containing source compilation units organized under their corresponding package directory structure. Source folders are used to better structure
source files in large projects, and may only be referenced within the containing project.
The corresponding factory method is
newSourceEntry
.
Inside a given source folder, each compilation unit is expected to be nested in the appropriate folder structure according to its package
statement. For example, compilation unit 'X.java' in package 'p1'
must be located inside sub-folder 'p1' of a source folder.
It is possible to use multiple source folders, as long as they don't overlap. A
source folder may be assigned its own output location which determines where
generated class files should be placed. If none is specified, then class
files will be placed in the containing project's output location
(see
IJavaProject.setOutputLocation
).
The
following is an example classpath entry that denotes the source folder 'src' of project
'MyProject':
IClasspathEntry srcEntry = JavaCore.newSourceEntry(new Path("/MyProject/src"));
-
a binary library - either a class file folder (contained inside or outside the workspace) or a class file archive file (contained inside or outside the workspace).
Archive libraries can have attached source archives, which are extracted when asking a class file element for
its source (
getSource
).
The factory method for libraries is
newLibraryEntry
.
The following is an example classpath entry that denotes the class file folder 'lib' of 'MyProject':
IClasspathEntry libEntry = JavaCore.newLibraryEntry(
new Path("/MyProject/lib"),
null, // no source
null, // no source
false); // not exported
The following classpath entry has a source attachment:
IClasspathEntry libEntry = JavaCore.newLibraryEntry(
new Path("d:/lib/foo.jar"), // library location
new Path("d:/lib/foo_src.zip"), // source archive location
new Path("src"), // source archive root path
true); // exported
The source archive root path describes the location of the
root within the source archive. If set to null, the root of the archive
will be inferred dynamically.
-
a prerequisite project - another Java project. A prerequisite project always contributes its source folders to dependent projects.
It can also optionally contribute any of its classpath entries which are tagged as exported (see factory methods supporting
the extra boolean argument 'isExported').
This means that in addition to contributing its source to its dependents, a project will also export all classpath entries tagged as
such. This allows prerequisite projects to better hide their own
structure changes. For example, a given project may choose to switch from using a source folder to exporting a library.
This can be done without requiring its dependent projects to change their classpath.
The factory method for a project prerequisite is
newProjectEntry
.
The following classpath entry denotes a prerequisite project 'MyFramework'.
IClasspathEntry prjEntry = JavaCore.newProjectEntry(new Path("/MyFramework"), true); // exported
-
an indirect reference to a project or library, using some classpath variable -
The location of projects or libraries can be dynamically resolved relative to a
classpath variable, which is specified as the first segment of the entry path. The remainder of the entry path is then appended to the resolved variable path.
The factory method for a classpath variable is
newVariableEntry
.
Classpath variables are global to the workspace, and can be manipulated through JavaCore methods
getClasspathVariable
and
setClasspathVariable
.
It is possible to register an automatic
classpath variable initializer
which is invoked through the extension point
org.eclipse.jdt.core.classpathVariableInitializer
when the workspace is started.
The following classpath entry denotes a library whose location is kept in the
variable 'HOME'. The source attachment is defined using the
variables 'SRC_HOME' and 'SRC_ROOT' :
IClasspathEntry varEntry = JavaCore.newVariableEntry(
new Path("HOME/foo.jar"), // library location
new Path("SRC_HOME/foo_src.zip"), // source archive location
new Path("SRC_ROOT"), // source archive root path
true); // exported
JavaCore.setClasspathVariable("HOME", new Path("d:/myInstall"), null); // no progress monitor
-
entry denoting a classpath container - an indirect reference to a structured set of project or libraries.
Classpath containers are used to refer to a set of classpath entries that
describe a complex library structure. Like classpath variables,
classpath containers
(IClasspathContainer)
are dynamically resolved. Classpath containers may be used by different
projects, causing their path entries to resolve to distinct values per
project. They also provide meta information about the library that they
represent (name, kind, description of library.)
The factory method for a classpath variable is
newContainerEntry
.
Classpath containers can be manipulated through JavaCore methods
getClasspathContainer
and
setClasspathContainer
.
It is possible to register an automatic
classpath container initializer
which is lazily invoked through the extension point
org.eclipse.jdt.core.classpathContainerInitializer
when the container needs to be bound.
The following classpath entry denotes a system class library container:
IClasspathEntry varEntry = JavaCore.newContainerEntry(
new Path("JDKLIB/default"), // container 'JDKLIB' + hint 'default'
false); // not exported
JavaCore.setClasspathContainer(
new Path("JDKLIB/default"),
new IJavaProject[]{ myProject }, // value for 'myProject'
new IClasspathContainer[] {
new IClasspathContainer() {
public IClasspathEntry[] getClasspathEntries() {
return new IClasspathEntry[]{
JavaCore.newLibraryEntry(new Path("d:/rt.jar"), null, null, false);
};
}
public String getDescription() { return "Basic JDK library container"; }
public int getKind() { return IClasspathContainer.K_SYSTEM; }
public IPath getPath() { return new Path("JDKLIB/basic"); }
}
},
null);
Exclusion patterns
A classpath source entry may be assigned an exclusion pattern, which prevents
certain resources in a source folder from being visible on the classpath.
Using a pattern allows
specified portions of the resource tree to be filtered out. Each exclusion
pattern path is relative to the classpath entry and uses a pattern mechanism
similar to Ant. Exclusion patterns can be used to specify nested source
folders as long as the outer pattern excludes the inner pattern.
See
getExclusionPatterns
for
more detail on exclusion patterns.
The Java project API
isOnClasspath
checks both inclusion and exclusion patterns before determining
whether a particular resource is on the classpath.
Remarks:
-
Exclusion patterns have higher precedence than inclusion patterns; in other
words, exclusion patterns can remove files from the ones that are to be included, not the
other way around.
-
A nested source folder excluded from build path can be set as an output location.
The following is an example classpath entry that denotes the source folder 'src' of project
'MyProject' with an excluded nested source folder used as an output location:
IPath sourceFolder = new Path("/MyProject/src");
IPath outputLocation = sourceFolder.append("bin");
IClasspathEntry srcEntry = JavaCore.newSourceEntry(
sourceFolder, // source folder location
new Path[] { outputLocation }, // excluded nested folder
outputLocation); // output location
Inclusion patterns
A classpath source entry may also be assigned an inclusion pattern, which explicitly
defines resources to be visible on the classpath.
When no inclusion patterns are specified, the source entry includes all relevant files
in the resource tree rooted at this source entry's path.
Specifying one or more inclusion patterns means that only the specified portions of
the resource tree are to be included. Each path specified must be a relative path,
and will be interpreted relative to this source entry's path. File patterns are
case-sensitive. A file matched by one or more of these patterns is included in
the corresponding package fragment root unless it is excluded by one or more of
this entry's exclusion patterns.
See
getExclusionPatterns
for a discussion of the syntax and semantics of path patterns. The absence of any inclusion patterns
is semantically equivalent to the explicit inclusion pattern **
.
The Java project API
isOnClasspath
checks both inclusion and exclusion patterns before determining
whether a particular resource is on the classpath.
Examples:
-
The inclusion pattern
src/**
by itself includes all files under a root
folder named src
.
-
The inclusion patterns
src/**
and tests/**
includes all files under the root folders named src
and tests
.
-
The inclusion pattern
src/**
together with the exclusion pattern
src/**/Foo.java
includes all files under a root folder named
src
except for ones named Foo.java
.
Classpath resolution
Since classpath variables and containers allow you to define dynamically bound
classpath entries, the classpath API distinguishes between a raw and a resolved
classpath. The raw classpath is the one originally
set on the Java project using
setRawClasspath
,
and can be further queried by asking the project for
getRawClasspath
.
The resolved classpath can be queried using
getResolvedClasspath
.
This operation triggers initialization of any variables and containers necessary
to resolve the classpath. Many Java Model operations
implicitly cause the Java build path to be resolved. For example,
computing a project's package fragment roots requires the build path to be
resolved.