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 Running Java code for a discussion of the runtime classpath.
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 can be defined using factory methods defined on JavaCore. Classpath entries can reference any of the following:
The
following is an example classpath entry that denotes the source folder 'src' of project
'MyProject':
IClassPathEntry srcEntry = JavaCore.newSourceEntry(new Path("/MyProject/src");
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.
The following classpath entry denotes a prerequisite project 'MyFramework'.
IClassPathEntry prjEntry = JavaCore.newProjectEntry(new Path("/MyFramework"), true); //exported
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
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);
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 the exclusion patterns before determining whether a particular resource is on the classpath.