Eclipse classpath file format

经常遇到eclipse中jar依赖问题，每次都需要看eclipse生成的classpath文件，为了有个权威的说明，故找来了这个文件的格式说明（真不好找>_^），为了确保内容以后不丢失，我先放一份在blog里。

 

 

转载自：http://www.ibm.com/developerworks/opensource/tutorials/os-eclipse-classpath/section2.html

 

 

 

Simplify Eclipse classpaths using classpath containers

 

Introduction to classpath containers

Classpath containers are an effective way to organize project resources by grouping them under one logical classpath entry. Whether you realize it or not, you may have used a classpath container. The most recognized classpath container among Java developers is the JRE System Library. Every Java project has a JRE System Library in the classpath. Other notable classpath containers are the JUnit and Plug-in Dependencies containers included in the base Eclipse project, as well as the Web App Libraries container, which is part of the dynamic Web project type in the Web Tools Project (WTP). Before we start implementing our own classpath container, let's start by reviewing the different types of classpath entries.

Kinds of classpath entries

Every Java project includes a .classpath file that defines the classpath of the project. This file is generally not edited by hand but created and modified by the JDT plug-in as the user changes the Java build path properties of a project. Each entry in the classpath has a kind attribute and a path attribute, along with various other optional attributes depending on the kind. The order the entries appear in the file from top to bottom determines their order in the project's classpath. Before continuing, it is a good exercise to create a Java project and experiment with that project by changing the Java build path properties, creating entries and modifying the initial default entries to arrive at the .classpath file shown in Listing 1.

Listing 1. Sample .classpath file showing all entry kinds

                    
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
    <classpathentry kind="src" path="src"/>
    <classpathentry kind="lib" path="lib/derby.jar" sourcepath="lib/derby-src.jar"/>
    <classpathentry kind="var" path="ECLIPSE_HOME/startup.jar"/>
    <classpathentry combineaccessrules="false" kind="src" path="/bar"/>    
    <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
    <classpathentry kind="output" path="bin"/>
</classpath>

Listing 1 shows six classpath entries marked by five kinds. In the underlying Eclipse Java model, each of these is represented by an org.eclipse.jdt.core.IClasspathEntry type, which categorizes the entry-by-entry kind and content kind. A content kind is defined for most entry kinds and is either source (org.eclipse.jdt.core.IPackageFragmentRoot.K_SOURCE) or binary (IPackageFragmentRoot.K_BINARY). In Eclipse V3.2, the IClasspathEntry interface defines five constants to refer to the classpath entry kind, but these are not the same five marked in Listing 1. In fact, one shown in this file — namely output — is not defined as a constant in IClasspathEntry, and another — src — is shown twice in Listing 1 because the two are represented as separate constants in IClasspathEntry. This makes it a little confusing, but let's ignore that for now and start from the top of the file.

Project source folders

The first entry in Listing 1 has kind="src" with path="src". This indicates that the project has a source folder located in a directory relative to the project root called src. This will have several implications for the project — most notably, it tells the Java builder that it needs to compile the source located in the src directory. This entry kind is represented by the constantIClasspathEntry.CPE_SOURCE and has a content kind of IPackageFragmentRoot.K_BINARY. When Java projects are created, they inherit default source and output folders from workspace preferences (in Eclipse see Window > Preferences > Java > Build Path). In a fresh Eclipse installation, the source and output folders will be set to the root project folder. The first src entry in Listing 1 has a path="src" because the workspace default source folder was changed to src.

Binary libraries

The second entry in Listing 1 has kind="lib" with path="lib/derby.jar". This indicates that there is a binary classpath entry located at lib/derby.jar relative to the project root. lib entries refer to a set of class files with the path attribute specifying a directory of .class files or an archive file that includes .class files. This entry also includes the optional sourcepath attribute, which refers to the location of the source attachment. The lib kind entry is represented by the entry kind constantIClasspathEntry.CPE_LIBRARY and has a content kind of IPackageFragmentRoot.K_BINARY.

Classpath variable extensions

The third entry in Listing 1 has kind="var" with path="ECLIPSE_HOME/startup.jar". In this entry, ECLIPSE_HOME is a variable. This built-in variable provided by Eclipse refers to the Eclipse installation directory. Custom variables can also be defined by the user for a workspace. Paths to classpath files are always relative to the project directory or absolute. So it's good practice to use variables for referencing files outside the project directory to avoid absolute paths, which will make the project difficult to share across different environments. See Window > Preferences > Java > Build Path > Classpath Variables for a list of the variables defined in your workspace. After a variable is defined, it can be used in the build path settings by extending it to refer to a file that is located relative to the variable.

In this case, it was extended by adding the Eclipse startup.jar. var entries are similar to lib entries, except that the first element in the path is evaluated before using it in the classpath. Another difference between var and lib entries is that lib entries can reference an archive or a folder of classes, whereas var entries can only reference an archive. The var kind is a binary type of entry represented by the constant IClasspathEntry.CPE_VARIABLE and the content kind is undefined. So, you should never usegetContentKind() when referring to an IClasspathEntry with kind="var". It is interesting to note, however, that one can only add binary variable extensions to the classpath, and to make it confusing, getContentKind() always returnsIPackageFragmentRoot.K_SOURCE for variable entries.

Prerequisite projects

The fourth entry in Listing 1 has kind="src" with path="/bar". This entry references the source of another project in the workspace (notice that the path starts with /, which refers to the workspace root directory). This will, in effect, add the configured output folder for the /bar project to the compilation classpath, as well as any classpath entries exported from the project. While the kind attribute is equal to "src", as it is with IClasspathEntry.CPE_SOURCE above, this entry is represented by a different entrykind constant, IClasspathEntry.CPE_PROJECT, and it has a content kind of IPackageFragmentRoot.K_SOURCE. The only difference in the .classpath entry is that the path attribute is relative to the workspace, instead of the project.

Classpath containers

The fifth entry in Listing 1 has kind="con" with path="org.eclipse.jdt.launching.JRE_CONTAINER". This type of entry is the subject of this tutorial. The kind constant for this entry is IClasspathEntry.CPE_CONTAINER, and the content kind is undefined. A container entry is a logical reference to an implementation of org.eclipse.jdt.core.IClasspathContainer. The implementation aggregates a set of concrete entries, either of type IClasspathEntry.CPE_LIBRARY or IClasspathEntry.CPE_PROJECT.

Summary of classpath entries

A summary of the classpath entry types is provided below. The example entries are taken from the .classpath file shown inListing 1.

Table 1. Summary classification of classpath entries in Listing 1

Example entry Icon Entry kind Content kind <classpathentry kind="src" path="src"/> <classpathentry kind="lib" path="lib/derby.jar" sourcepath="lib/derby-src.jar"/> <classpathentry kind="var" path="ECLIPSE_HOME/startup.jar"/> <classpathentry combineaccessrules="false" kind="src" path="/bar"/> <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>

	CPE_SOURCE	K_SOURCE
	CPE_LIBRARY	K_BINARY
	CPE_VARIABLE	undefined
	CPE_PROJECT	K_SOURCE
	CPE_CONTAINER	undefined

More information

For a detailed explanation of the different classpath entries, read the Javadoc for org.eclipse.jdt.core.IClasspathEntry, and for a good lesson on setting the build path programmatically with these different kinds, read the Eclipse help topic "Setting the Java Build Path."

Back to top

What are classpath containers?

In this tutorial, the term classpath container refers to an implementation of org.eclipse.jdt.core.IClasspathContainer. Classpath containers are logical references to a set of classpath resources. Their entry sets can be defined per project by theIClasspathContainer implementation. Since the entry set is defined by the IClasspathContainer, it can be dynamic or static. As an example of the static case, a container could return a fixed set of JARs that are located in a well-known directory (e.g., the JRE System Library). Or, in a more dynamic case, a container might return a set of runtime JARs that changes depending on server deployment.

Back to top

Why use classpath containers?

There are many reasons why one might want to use a classpath container. Here are the more important ones:

Reducing clutter

Instead of having several individual JARs under one project, you can group them into a container that can be expanded to see the individual JARs. This conserves screen real estate in the Java Package Explorer view.

And the number of entries needed in the .classpath file is reduced from several to one.

Portability

Since the paths for container entries are logical names, there is no information about the file system included. This makes the classpath entry portable to different machines and, thus, makes it easy to share projects through source control management (SCM) systems, such as CVS or SVN. Variable entries also have this benefit.

Easier management

If a classpath container page is defined for the container type, the user can edit the properties of the container through the UI.

Dynamicity

This is probably the most important benefit, since it cannot be achieved through any of the other classpath entry types. Since the container entries are retrieved at the time they are needed, they can be very dynamic. No information about the container entries persists in the workspace or project metadata. The entries are retrieved when they are needed for operations like compiling and running. This provides a means for redefining the project's classpath dependencies based on practically any factor. In a simple case, a container could add all the JARs in a project directory to the classpath. In fact, this is the function of the Web App Libraries classpath container provided by the Web Tools Project (WTP) for a Web project's WEB-INF/lib folder.