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 Running Java 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:

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.


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.


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.