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:

• 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