Eclipse - a tale of two VMs (and many classloaders)

http://www.eclipsezone.com/articles/eclipse-vms/

Eclipse - a tale of two VMs (and many classloaders)

When starting off with Eclipse plugin development or rich client platform development, you're more than likely to run into issues likeClassNotFoundExceptionor problems with the Java command line and properties likejava.endorsed.dirs.

Most often, these problems arise because many Eclipse developers don't realise the magic that lets Eclipse do its work. Amongst these are the fact that there's actually two processes under the covers, and that each bundle has its own classloader. Once you understand how these fit together, debugging problems may be somewhat easier.

Eclipse Boot Process

Why does Eclipse need two processes to run? The simple answer is that an Eclipse application needs to be run with several system properties set in order to function properly. (These include parameters likeosgi.configuration.areaandosgi.instance.area.) It's a key requirement in the way that Eclipse starts up, because it needs to know where to put both temporary and persistent data that's not stored directly in one of your project locations. (Examples include your preferences and the workbench history, which tracks changes to files that you have made.)

Many other tools use a shell script to launch an application with a particular classpath; not only IDEs (like NetBeans) but also server-side tools (Maven, Ant, CruiseControl ...). Most of the time, these shell scripts use shell-specific routines to add entries to a classpath (e.g.for i in lib/*.jar), and on the whole, this approach works. But some operating systems aren't as expressive as others, and unless you have the ability to add other complex logic to the script via external programs, it may not be possible to do everything that you'd want. It also means that you potentially have to test the shell script on other operating systems to determine whether it's correct or not; though generally if it works on one Unix system, it will work on others too.

To solve this issue (and others), Eclipse doesn't use a shell script to boot itself. Instead, it uses a native executable (eclipse.exeoreclipse), to parse the command-line arguments (like-vmargs) and make them available to the OSGi platform. Importantly, it calculates defaults for values that aren't overridden. It then fires up the OSGi platformin a new process(the platform VM), and hands the rest of the booting process over.

You may wonder why it fires up a new process, rather than continuing booting by incorporating a VM in the same one. There's two reasons for this: firstly, the OSGi platform that's being launched can callSystem.exit()without taking down the launcher (c.f. the JavaDoc task in Ant, or the fork attribute of the Java task). The second (perhaps more important) one is that it allows the OSGi platform to be launched with a different set of parameters -- or even use a specfic version of the VM. The launcher can run on many versions of the Java VM, and the launcher can guarantee that your platform code will run in a known VM (for example, by shipping one with your code and placing it in thejre/directory).

The launcher also reads a variety of configuration files;eclipse.ini, if present, is a newline separated list of flags that are passed into the platform VM. The-vmargsflag is used to pass any subsequent arguments as VM arguments rather than normal arguments.

All of this means that when launching Eclipse viastartup.jarthe arguments and extra options are effectively ignored by the actual Eclipse runtime instance. You may think that:

eclipse -Xmx1024m

would give you a huge Eclipse memory runtime, but in actual fact, all you're doing is specifying an argument which is ignored by theeclipselauncher. The native launcher deals with some arguments directly; but otherwise, they're passed on verbatim to the Java launcherorg.eclipse.core.launcher.Mainwhere the real work is done. The arguments that the native launcher explicitly deals with are:

-vmargs

Arguments following this are passed directly into the platform VM's Java executable, before the class name. It must be the last argument, since anything following is put on the command line. Importantly, spaces need to be appropriately quoted or escaped since otherwise you may get the dreaded "Program/Eclipse cannot be located", which is usually because one of the VM arguments haveC:\Program Files\Eclipsein them. This is available from theeclipse.vmargssystem property, but it cannot be changed once the VM is started.

-vm

Full path to a Java executable that can be executed. The system path is searched if this is not specified. This is available from theeclipse.vmsystem property, but it cannot be changed once the VM is started.

To run Eclipse with a larger memory area, you need to pass the-vmargsto the launcher, followed by the options that you want:

eclipsearg1 arg2 arg3-vmargs -Xmx1024m

this instructs the launcher to create the platform VM, passing in argumentsarg1 arg2 arg3and setting up the platform VM with-Xmx1024m. However, we could equally have had a file calledeclipse.ini:

arg1
arg2
arg3
-vmargs
-Xmx1024m

which would have the same effect. The launcher looks forapplication.iniandeclipse.inito derive these parameters, if your executable is calledapplication.exe.

Theeclipselauncher then fires up a VM, which usesorg.eclipse.core.launcher.Main(fromstartup.jar) to instigate the next phase of the boot process. TheMainlauncher sets up specific areas that are needed by the OSGi platform, including setting up the properties such as where the configuration area will be. It then boots theOSGiplatform, which reads which plugins to start from theosgi.bundlesentry from theconfig.ini, and applies product branding from-productand OS/Language specific settings from-osand-nl. Once that's running, the Eclipse platform task over which locates and loads the bundle associated with the-applicationor-featurearguments. Certain plugins (likeorg.eclipse.core.resources) interpret specific command line arguments (like-refresh), but this is the exception rather than the rule.

If you want to embed Eclipse into another Java process, you can use theEclipseStarterclass, as long as you supply the appropriate entries. That will fire up all the necessary plugin support to kick your application off. There's alsoWebStartMainthat can be used to kick off an Eclipse install via Java WebStart (although withsome limitations).

There's a full list of the arguments and when they are interpreted in theEclipse help pagesunder "runtime options", and can be summarised as:

Handled by eclipse.exe	Handled byorg.eclipse.core.launcher.Main	Handed by the OSGi platform	Handled by the Eclipse platform
-vmargs -vm -name -noSplash -startup	-configuration -endSplash -framework -initialize -install -noSplash -showSplash	-arch -clean -console -data -debug -dev -nl -os -product -user -ws	-application -feature -keyring -noLazyRegistryCacheLoading -noRegistryCache -password -pluginCustomization

ClassLoaders, Bundles and Buddies

You may recall that Java uses aClassLoaderto bring classes into the VM. Most of the time, you probably don't need to know anything about how they work (or even that they exist) but every class in Java is loaded via aClassLoader. Its job is to turn a sequence of bytes into ajava.lang.Class. Where those bytes come from doesn't really matter; and it's this fact (and theURLClassLoader) that brought Java to fame with Applets in the first place. Mostly, client side applications don't need to worry about theClassLoader: they just set up aclasspathand It Just Works.

Server-side applications (J2EE servers and others like Tomcat) have long usedClassLoaders to enable classes to be loaded on demand from different structures (like WAR formats). As well as providing a way of accessing the classes, theClassLoaderalso provides another key benefit; it separates out classes with the same name. Every class in Java has an associatedClassLoader(and you can find out which byobj.getClass().getClassLoader()if you want).

Importantly, a class name is unique only within itsClassLoader. That means it's possible to have two classes with the same name loaded into a VM at once, provided that they have two separateClassLoaders that loaded them. Whilst this may sound freaky and unnatural, in fact it's how application servers like Tomcat can host any Web application and allow hot deployment. It simply creates a newClassLoader, loads in the classes (again) and runs the new version. Without this ability, an application server would not be able to reload a web application without having to restart the server in its entirety.

Eclipse uses this to its advantage. One of the key features of Eclipse 3.0 was the ability to stop and start a bundle whilst the platform continued running. (It's used when you update, and choose the 'Apply changes now' instead of restarting Eclipse, amongst other things.) Perhaps more importantly, Eclipse allows multiple different versions of a bundle to be loaded at one time, which might be useful if you have many parts of your plugin relying either on 2.7.1 or 2.8.0 of Xerces.

To do this, each bundle (OSGi) or plugin (Eclipse) has its ownClassLoader. When a bundle is started, it gets given its ownClassLoaderfor its lifetime. When it's stopped and restarted, a newClassLoaderis created. This allows the new bundle to have a different set of classes than the previous version.

The OSGi platform translates theManifest.MFpresent in every (OSGi-enabled) plugin into a hierarchy ofClassLoaders. When you can't load a class from your plugin directly, the bundle mechanism searches through all the required bundles to see if it can find the class there instead. Packages that depend on the same bundles (e.g.org.eclipse.ui) will result in the same class being loaded, because it comes fromorg.eclipse.ui'sClassLoader.

This causes confusion for new developers to the Eclipse platform. It doesn't matter what's in theCLASSPATHenvironment variable, or what's specified on the-classpathargument, because pretty much everyClassLoaderonly sees what itsManifest.MFtells it to see. If there's no dependency at the bundle level, then as far as Eclipse is concerned, it isn't there. (Incidentally, that's how the.internal.packages work; whilst they exist in the bundles, and can be loaded by the bundle'sClassLoader, the Eclipse class loading mechanism hides any package that's not explicitly mentioned in theExport-Packageheader in theManifest.MF. It also doesn't help that the PDE runtime only consults the entries in the.classpathwhen running/debugging inside Eclipse, and it's only when you try to export the product that theManifest.MFis consulted, often resulting in errors. AClassNotFoundExceptionduring product/plugin exporting is almost always down to the fact that it's mentioned in the.classpath(Java Build path) but not theManifest.MF.

A larger problem occurs when using libraries that expect to be able to see your code as well as their own. This includes libraries such aslog4jand generator tools such asJibXthat both supply services and consume code. Because Eclipse uses a partitioned class loading mechanism, theClassLoaderof theorg.apache.log4jcan't see the classes defined inorg.example.myplugin, since it's a separateClassLoader. As a result,log4jcan't use your supplied class for logging, and complains.

This is the purpose of thebuddy class loadingin Eclipse. It is designed to work around the issues that can be found in this type of problem. (It's quite similar to the options that you can configure with some of the application servers, such as "parent first" and "child first" lookup policies.) The buddy policy (specified with theEclipse-BuddyPolicyentry) takes one of:

dependent

search the dependent's classloaders

global

search the global packages exported viaExport-Package

app

search the application's classloader

ext

search the extension's classloader

boot

search the boot's classloader

registered

search the registered buddies classloaders

Figure 1. Buddy classloader diagram

Whilst all of these are generally fine, if you want to use a tool likelog4jthen it generally boils down to:

# log4j Manifest.MF
Bundle-Name: org.apache.log4j
Bundle-Version: 1.2.13
...
Eclipse-BuddyPolicy: registered

This says "If anyone registers with me, and I need to find a class that I can't otherwise find, I'll check with them before failing". You also need to define in your own plugin that you want to register with it:

# myplugin Manifest.MF
Bundle-Name: org.example.myplugin
Bundle-Version: 1.0.0
Requires-Bundle: org.apache.log4j,...
...
Eclipse-RegisterBuddy: org.apache.log4j

This now makes theorg.apache.log4jandorg.example.mypluginbuddies. Of course, ourorg.example.mypluginalways depended onorg.apache.log4jbefore, but now we've added the extra hook back that allows thelog4jto see our classes as well. In essence, it's like addingRequires-Bundle: org.example.mypluginto theorg.apache.log4jbundle, except that obviously you can't do that (it would create a circular reference) and I doubt that Ceki G?lc? would have had the foresight to depend on myplugin in advance. But by puttingEclipse-BuddyPolicy: registeredinto the definition, now any future bundle can plug in and register its code withorg.apache.log4j.

It's probably a pretty good idea to add theEclipse-BuddyPolicy: registeredto your plugin now, because in the future someone might need it.

Native code and classloaders

As well as resolving classes, theClassLoaderis also responsible for finding native code in response to aSystem.loadLibrary()call. Whilst it doesn't actually perform the loading of the DLL itself, it does figure out where the DLL is and passes a full path to the operating system to install the code. In the case of packed OSGi bundles, this call automatically extracts a copy of the DLL to a temporary location before passing the location back to the OS.

It's also worth bearing in mind that the DLL loaded may have other dependencies. Unfortunately, although Eclipse knows where to look for further dependencies (e.g. thejava.library.pathor the contents of a packed Jar file), once the operating system only knows about thePATHorLD_LIBRARY_PATHenvironment variables (depending on your operating system). So if you havea.dllwhich depends onb.dll, and you doSystem.loadLibrary("a"), it will fail with anUnsatisfiedLinkError. That's because although Eclipse knows where to find the dependent dll, the operating system doesn't know where to look forb.dlland gives up. Instead, if you didSystem.loadLibrary("b"); System.loadLibrary("a");then the DLL is available in memory fora.dllto trivially hook up against, and it all works. The moral of the story is always load the DLLs in the order in which they are dependent.

It's worth bearing in mind that Windows and Java have some issues when it comes to loading DLLs. A DLL can only be loaded once in a VM and only associated with oneClassLoader. If you have twoClassLoaders, and they attempt to load the same DLL, then the second one will fail and not be able to execute any native code. As a result of this, you cannot have two bundles that attempt to load the same native code in Eclipse. This will also apply if the bundle is updated or restarted, because the oldClassLoadermay retain a reference to the DLL whilst the new one starts. This is a Windows-specific problem that doesn't appear to manifest itself on other operating systems.

Lastly, whilst Eclipse 2.1 used a combination of directories (ws/os/arch, such aswin32/win32/x86/swt1234.dll) for storing native code, this is no longer the preferred way of doing it. Instead, native code should be at the root level of the plugin, probably with a suffix like swt1234-win32x86.dll. Even better, instead of doingSystem.loadLibrary(), you can defineBundle-NativeCode: swt1234.dlland the OSGi platform will load it automatically. You can either provide per-os fragments, or split them apart and use a platform filter (such asEclipse-PlatformFilter: (& (osgi.ws=win32) (osgi.os=win32) (osgi.arch=x86))).

Conclusion

Once you understand how the processes work within the Eclipse boot sequence, and the fact that it utilises many classloaders, some of theClassNotFoundExceptions become easier to understand. Specifying arguments works on a command linejavainvocation because you're specifying the VM on the command line (and most of the time, only using oneClassLoadertoo). In the Eclipse world, if you want to affect Eclipse's VM, you need to remember to prefix any arguments with-vmargs, either on the command line or on via theeclipse.inifile.

It's also worth checking when you haveClassNotFoundExceptions when exporting or running an application outside of Eclipse's debugger, that you have the dependencies listed inManifest.MFand not just in the.classpath(Java Build Path). In fact, you shouldn't need to put any extra entries in the.classpathif you're building a plugin project, because the entries inManifest.MFare automatically available in the.classpaththrough the "Plugin Dependencies" classpath container.

Lastly, if you're using native code in an Eclipse application, it's a very good idea to isolate the native code in its own bundle. Any plugin that needs to use that native functionality can then express a dependency on that bundle, which allows it to be shared by as many bundles as need it. That way, if you have any non-native updates to your bundle, you don't need to restart Eclipse to see those changes. Of course, if you have native bundle updates then you have to restart anyway to get the benefit.

We encourage you to ask the author any questions or discuss the articlehere.