Class Path Container Enhancement

Last Modified April 23, 2002

Background

JDT supports to switch the JDK that is used for building. It is currently implemented as follows:

org.eclipse.jdt.launching maintains the following JDK/VM information in its plugin metadata:

a set of VM install types: a description of a VM install. It knows how to find the location of the binary JAR and the source JARs.
VM installs: the location/home of a VM install on the file system. A VM install has an internal ID that is not visible to the user.
one of the VM installs is marked as the default VM install.

org.eclipse.jdt.launching defines a JRE_LIB, JRE_SRC, JRE_SRCROOT variables that binds to the default VM install:

JRE_LIB: the binary JAR (e.g. rt.jar)
JRE_SRC: the source JAR/zip (e.g. src.jar)
JRE_SRCROOT: the prefix in the source JAR (e.g. "src")

The Java project creation wizard adds a JRE_LIB classpath variable on a project's build class path.
org.eclipse.jdt.debug.ui contributes a preference page to define new VM installs and to set the default VM install. When the default VM install changes, then the bindings of the JRE_* variables are changed accordingly.
org.eclipse.jdt.ui contributes a class path variable preference page. It "knows" that the JRE_* variables are reserved and doesn't allow the user to edit them.
The packages view shows the resolved JRE_LIB contents as a referenced library.

Characteristics of the current implementation:

Class path stability: changing the default JRE/VM install doesn't affect the build class path since the JRE_LIB variable is not affected by this change. In other words, when a user changes the JRE for building then the .classpath file is not affected.
JDK switching at the workspace level for all projects is straightforward by the user, only the default VM install needs to be changed and all projects in the workspace switch to use this VM install.
Since class path variables can only bind to a single JAR, the JRE_LIB variable can only bind to a single JAR (for the standard SUN JRE this is rt.jar).
There is some magic involved with regard to the handling of JRE_* variables that is not obvious to the user:

on the build class path the user sees JRE_LIB but when defining a launch configuration then the user sees VM Installs. The user has to know that JRE_LIB is indirectly bound to the VM install via the JRE installed preference settings.
The user also has to understand that the reserved variables cannot be edited like the other class path variables, etc.

Build class path ordering - users can control the order of the build class path in a simple way. For example, to do JCL development, to do so users can put their source folders in front of the JRE_LIB class path entry.
Java Core is not affected by the JDK switching support and is independent of launching concerns.

Motivation for enhancing the current implementation

New Requirements

There are new requirements with regard to the handling of the JRE/JDK on the build class path that need to be addressed by 2.0:

Multiple JARs per JDK

Workspaces with a different JDK per project

Existing characteristics to be preserved in the new implementation

Class path stability, it has to be possible to switch a JDK locally in a workspace without affecting the .classpath file.
Easy JDK switching at the workspace level, i.e., a single setting can be changed to change the build class path of all projects.
Java Core is independent of the VM install infrastructure

Proposal

The proposal affects core, launching, java debug UI, and the Java UI components.

JavaCore

JavaCore provides a new type of classpath entry "CPE_CONTAINER", which is just a named reference to a set of other classpath entries. A container entry refers to a container path, which can be resolved by a ClasspathContainerInitializer through an extension point, or explicitly assigned using a setter method. The actual binding from the CPE_Container entry to the target classpath entries is implemented in term of an extension point to keep Java Core independent of VM install concerns:

   <!ELEMENT classpathContainerInitializer EMPTY>
   <!ATTLIST classpathContainerInitializer
      id      CDATA #REQUIRED
      class   CDATA #REQUIRED
   >

id - the container unique name for which this resolver will be activated.
class - the class that implements this container initializer. The class must implement a public subclass of org.eclipse.jdt.core.ClasspathContainerInitializer with a public 0-argument constructor.

   abstract class ClasspathContainerResolver {
        void initialize(IPath containerPath, IJavaProject project) throws CoreException;
      }

The initialize call passes in a project, this enables to resolve a classpath container in the context of a particular project. The initialize method should only be called once to resolve the class path entry (in case of failure, the container will not be considered as having been resolved).

It is possible to register an initializer per container ID. The full container path being passed along to the initializer. Its first segment is the container ID for which an initializer should be registered. The remaining segments can be used to provide additional hints for the container expansion. In case multiple resolvers are registered on the same container ID, the first registered one will be used).

JavaCore provides a method to perform explicit modifications of a container:

JavaCore#setClasspathContainer(
	IPath containerPath, 
	IJavaProject[] affectedProjects, 
	IClasspathContainer[] respectiveContainers, 
	IProgressMonitor monitor)

In particular, this method is to be used in the context of a classpath initializer so as to perform the actual initialization. Note that it allows to modify the value of a container for a set of projects at once. In reaction to invoking this method, the JavaModel will be refreshed and corresponding Java element changes will be notified.

A classpath container implements org.eclipse.jdt.core.IClasspathContainer and can be queried through a JavaCore API: JavaCore#getClasspathContainer(IPath containerPath, IJavaProject project) . There is no assumption that the returned container must answer the exact same containerPath when requested IClasspathContainer#getPath. Indeed, the containerPath is just an indication for resolving it to an actual container object.

Classpath container values are persisted locally to the workspace, but are not preserved from a session to another. It is thus highly recommended to register a ClasspathContainerInitializer for each referenced container (through the extension point "org.eclipse.jdt.core.ClasspathContainerInitializer").

public interface IClasspathContainer {
	
	/**
	 * Kind for a container mapping to an application library
	 */
	int K_APPLICATION = 1;

	/**
	 * Kind for a container mapping to a system library
	 */
	int K_SYSTEM = 2;

	/**
	 * Kind for a container mapping to a default system library, implicitly contributed by the runtime
	 */
	int K_DEFAULT_SYSTEM = 3;
	
	/**
	 * Answers the set of classpath entries this container is mapping to.
	 * The set of entries associated with a classpath container may contain any of the following:
	 * - library entries (CPE_LIBRARY) 
	 * - project entries (CPE_PROJECT) 
	 * A classpath container can neither reference further classpath containers or classpath variables.
	 */	
    IClasspathEntry[] getClasspathEntries();

	/**
	 * Answers a readable description of this container
	 */	
    String getDescription();

	/**
	 * Answers the kind of this container. Can be either:
	 * - K_APPLICATION  if this container maps to an application library
	 * - K_SYSTEM  if this container maps to a system library
	 * Typically, system containers should be placed first on a build path.
	 */	
    int getKind();

	/**
	 * Answers the container path identifying this container.
	 * A container path is formed by a first ID segment followed with extra segments.
	 * which can provide additional hint for resolving.
	 * This container ID is used in conjunction with the hints for resolving to this container.
	 * The container ID is also used to identify a ClasspathContainerInitializer 
	 * registered on the extension point "org.eclipse.jdt.core.classpathContainerInitializer", which can
	 * be invoked if needing to resolve the container before it is explicitely set.
	 */	
    IPath getPath();
}

Issue: The Mac OS X JDK install is an interesting case. There the rt.jar is split into two binary JARs (classes.jar, ui.jar), but there is still a single src.jar. This cases needs to be handled by the source lookup. For example, when src.jar is attached to classes.jar then when looking up java.awt.Frame out of ui.jar, the source attachment of classes.jar needs to searched as well.

Example

The class path of a project will look as follows:

In the case where the user didn't override the VM install at the project level. Then the Java launching contributed container resolver (registered for container prefixes: "JDK") would resolve "JDK/1.3" using the default VM install, using "1.3" as an hint, and may expand it into the following: