| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML> |
| <HEAD> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Setting the Java build path</title> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY> |
| <h2> |
| Setting the Java build path</h2> |
| <P> |
| |
| This section describes how to set the Java build path. The build path is |
| the classpath that is used for building a Java project (<b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html">IJavaProject</a></b>). |
| </p> |
| <P> |
| A classpath is simply an array of classpath entries (<b><a href="../reference/api/org/eclipse/jdt/core/IClasspathEntry.html">IClassPathEntry</a></b>) |
| 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. |
| </p> |
| |
| <P> |
| The Java build path is reflected in the structure of a Java project |
| element. You can query a project for its package fragment roots (<b><a href="../reference/api/org/eclipse/jdt/core/IPackageFragmentRoot.html">IPackageFragmentRoot</a></b>). |
| Each classpath entry maps to one or more package fragment roots, each of which |
| further contains a set of package fragments.</p> |
| <P>This discussion of the |
| build path does not involve the Java runtime path, which can be defined |
| separately from the build path. (See <b><a href="../guide/jdt_api_run.htm">Running |
| Java code</a></b> for a discussion of the runtime classpath.</p> |
| |
| <h3> |
| Changing the build path</h3> |
| <P> |
| You can programmatically change a project's build path using <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#setRawClasspath(org.eclipse.jdt.core.IClasspathEntry[], org.eclipse.core.runtime.IProgressMonitor)"> |
| setRawClasspath</a></b> on the corresponding project's Java element. The |
| following code sets the classpath for a project resource: |
| |
| <font color='#4444CC'><pre> |
| IProject project = ... // get some project resource |
| IJavaProject javaProject = JavaCore.create(project); |
| IClasspathEntry[] newClasspath = ...; |
| javaProject.setRawClasspath(newClasspath, someProgressMonitor); |
| </pre></font> |
| </p> |
| <P>(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.) |
| </p> |
| <P> |
| 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. |
| </p> |
| <H3> |
| Classpath entries</H3> |
| <P> |
| Classpath entries can be defined using factory methods defined on <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html">JavaCore</a></b>. |
| Classpath entries can reference any of the following:</p> |
| |
| <ul> |
| <li><b>a source folder</b> - |
| 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 |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#newSourceEntry(org.eclipse.core.runtime.IPath)">newSourceEntry</a></b>. |
| 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 <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#setOutputLocation(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IProgressMonitor)">IJavaProject.setOutputLocation</a></b>).<P>The |
| following is an example classpath entry that denotes the source folder 'src' of project |
| 'MyProject': |
| <font color='#4444CC'><pre> IClassPathEntry srcEntry = JavaCore.newSourceEntry(new Path("/MyProject/src"));</pre></font></p> |
| </li> |
| <li><b>a binary library</b> - either a class file folder (contained inside 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 (<b><a href="../reference/api/org/eclipse/jdt/core/ISourceReference.html#getSource()">getSource</a></b>). |
| The factory method for libraries is |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#newLibraryEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, boolean)">newLibraryEntry</a></b>. |
| <P> |
| The following is an example classpath entry that denotes the class file folder 'lib' of 'MyProject': |
| <font color='#4444CC'><pre> |
| IClassPathEntry libEntry = JavaCore.newLibraryEntry( |
| new Path("/MyProject/lib"), |
| null, //no source |
| null, //no source |
| false); //not exported |
| </pre></font> |
| The following classpath entry has a source attachment: |
| <font color='#4444CC'><pre> |
| 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 |
| </pre></font></p><p>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.</p> |
| <br></li> |
| <li><b>a prerequisite project</b> - 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 |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#newProjectEntry(org.eclipse.core.runtime.IPath, boolean)">newProjectEntry</a></b>. |
| <P> |
| The following classpath entry denotes a prerequisite project 'MyFramework'. |
| <font color='#4444CC'><pre> |
| IClassPathEntry prjEntry = JavaCore.newProjectEntry(new Path("/MyFramework"), true); //exported |
| </pre></font> </p> |
| </li> |
| <li><b>an indirect reference to a project or library, using some classpath variable</b> - |
| 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 rest of the entry path is then appended to the resolved variable path. |
| The factory method for a classpath variable is |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#newVariableEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)">newVariableEntry</a></b>. |
| Classpath variables are global to the workspace, and can be manipulated through JavaCore methods |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#getClasspathVariable(java.lang.String)">getClasspathVariable</a></b> and |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#setClasspathVariable(java.lang.String, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IProgressMonitor)">setClasspathVariable</a></b>. |
| <p> |
| It is possible to register an automatic <b><a href="../reference/api/org/eclipse/jdt/core/ClasspathVariableInitializer.html">classpath variable initializer</a></b> |
| which is invoked through the extension point <b><a href="../reference/extension-points/org_eclipse_jdt_core_classpathVariableInitializer.html">org.eclipse.jdt.core.classpathVariableInitializer</a></b> |
| when the workspace is started.</p> |
| <P> |
| 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' : |
| <font color='#4444CC'><pre> |
| 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 |
| </pre></font> </p> |
| </li> |
| <li><b>entry denoting a classpath container</b> - 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 <b><a href="../reference/api/org/eclipse/jdt/core/IClasspathContainer.html">(IClasspathContainer)</a></b> |
| 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.) Classpath containers can be manipulated through JavaCore methods |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#getClasspathContainer(org.eclipse.core.runtime.IPath, org.eclipse.jdt.core.IJavaProject)">getClasspathContainer</a></b> and |
| <b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#setClasspathContainer(org.eclipse.core.runtime.IPath, org.eclipse.jdt.core.IJavaProject[], org.eclipse.jdt.core.IClasspathContainer[], org.eclipse.core.runtime.IProgressMonitor)">setClasspathContainer</a></b>. |
| <p> |
| It is possible to register an automatic <b><a href="../reference/api/org/eclipse/jdt/core/ClasspathContainerInitializer.html">classpath container initializer</a></b> |
| which is lazily invoked through the extension point <b><a href="../reference/extension-points/org_eclipse_jdt_core_classpathContainerInitializer.html">org.eclipse.jdt.core.classpathContainerInitializer</a></b> |
| when the container needs to be bound.</p> |
| <P>The following classpath entry denotes a system class library container: |
| <font color='#4444CC'><pre> |
| 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); |
| </pre></font></p> |
| </li> |
| </ul> |
| |
| <h3> |
| Exclusion patterns</h3> |
| |
| <p>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.</p> |
| |
| <p> See <b><a href="../reference/api/org/eclipse/jdt/core/IClasspathEntry.html#getExclusionPatterns()">getExclusionPatterns()</b></a> for |
| more detail on exclusion patterns.</p> |
| |
| <p> |
| The Java project API <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#isOnClasspath(org.eclipse.core.resources.IResource)">isOnClasspath</a> |
| </b> checks both inclusion and exclusion patterns before determining |
| whether a particular resource is on the classpath.</p> |
| |
| <P> |
| Remarks: |
| <ul> |
| <li> |
| Exclusion patterns have higher precedence than inclusion patterns; in other |
| words, exclusion patterns can remove files for the ones that are to be included, not the |
| other way around. |
| </li> |
| <li> |
| 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: |
| <font color='#4444CC'><pre> |
| 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 |
| </pre></font> |
| </li> |
| </ul> |
| </p> |
| <h3> |
| Inclusion patterns</h3> |
| |
| <p>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.</p> |
| |
| <p> See <b><a href="../reference/api/org/eclipse/jdt/core/IClasspathEntry.html#getExclusionPatterns()">getExclusionPatterns()</b></a> |
| 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 <code>**</code>.</p> |
| |
| <p> |
| The Java project API <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#isOnClasspath(org.eclipse.core.resources.IResource)">isOnClasspath</a> |
| </b> checks both inclusion and exclusion patterns before determining |
| whether a particular resource is on the classpath.</p> |
| |
| <p> |
| Examples: |
| <ul> |
| <li> |
| The inclusion pattern <code>src/**</code> by itself includes all files under a root |
| folder named <code>src</code>. |
| </li> |
| <li> |
| The inclusion patterns <code>src/**</code> and <code>tests/**</code> |
| includes all files under the root folders named <code>src</code> and <code>tests</code>. |
| </li> |
| <li> |
| The inclusion pattern <code>src/**</code> together with the exclusion pattern |
| <code>src/**/Foo.java</code> includes all files under a root folder named |
| <code>src</code> except for ones named <code>Foo.java</code>. |
| </li> |
| </ul> |
| </p> |
| |
| <H2> |
| Classpath resolution</H2> |
| |
| 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 |
| <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#setRawClasspath(org.eclipse.jdt.core.IClasspathEntry[], org.eclipse.core.runtime.IProgressMonitor)">setRawClasspath</a></b>, |
| and can be further queried by asking the project for |
| <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#getRawClasspath()">getRawClasspath</a></b>. |
| The resolved classpath can be queried using |
| <b><a href="../reference/api/org/eclipse/jdt/core/IJavaProject.html#getResolvedClasspath(boolean)">getResolvedClasspath</a></b>. |
| 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. |
| |
| |
| </BODY> |
| </HTML> |
