Question & Answer
How can the -clean option be used on startup of IBM Rational products based on the Rational Software Delivery Platform (which is also known as the Software Development Platform, or SDP)?
This startup switch performs several functions. Using Rational Application Developer for WebSphere Software as an example, this technote briefly describes the three main parts in the product that are affected by -clean and what the effects of using it are. The information is applicable to any product of the SDP.
Rational Application Developer versions 6.x and 7.x are based on Eclipse 3.x which caches all plugin.xml files into a single repository for quicker loading. If you used Rational Application Developer before installing a new plugin, you should restart with the -clean option. The -clean option forces Rational Application Developer to rebuild that repository. This applies to anything that is installed into Eclipse by unzipping it into its plugins folder.
Internal Details (Rational Application Developer 6.x and 7.0.x)
Configuration information that is affected by using -clean is stored in a directory called "configuration".
For Rational Application Developer v6 this directory is located in:
For Rational Application Developer v7 this directory is located in:
Any information present in that directory is applicable to the entire Rational Application Developer install and not just to a particular workspace. Changes made in this directory will affect all workspaces associated with this particular install.
In Rational Application Developer there are three main items that are present in the configuration: OSGi, Runtime and Update. This technote uses the name "Configurator" to represent the Eclipse Updater so as not to confuse it with the Rational Product Updater (RPU).
OSGi has three main parts:
- State: this is information regarding the various dependencies between the plug-ins available
- Cache: the binaries of manifest files (bundle data). Think of manifests as being like plugin.xml files. There is one manifest file for each plugin. During installation of Rational Application Developer, manifest files are created. These files contain information that was once part of plugin.xml files in WebSphere Studio Application Developer but has been moved to manifest files in Rational Application Developer. OSGi only handles information contained in manifest (.MF) files.
- .JXE file: this is a binary file containing a memory dump of classes loaded from a jar file. This allows for quick access to the classes. These files can be quickly loaded into memory.
- Runtime is what was referred to as the plugin registry in WebSphere Studio Application Developer. Cached information about plugin extensions and extension points is saved here.
- This is what installs the various bundles into OSGi. The platform.xml file contains a listing of bundles that should be loaded into OSGi.
Note: the terms bundle and plugin are synonymous here - the former is used when talking about OSGi.
Now what does -clean do?
- Manifest files are removed and regenerated.
- Cached binaries of manifest files are removed and regenerated from the newly created manifest files
- .JXE files are removed and regenerated
- Runtime plugin registry is removed and regenerated
- Beyond this it is up to each plugin that is listed in the configuration directory to handle what it does when the -clean option is used
Practical Use (Rational Application Developer 6.x and 7.0.x)
It is a good practice to start up Rational Application Developer using the -clean option after applying any Interim Fixes.This ensures that the plugin registry is regenerated to reflect any changes from the applied fixes.This only needs to be done once after applying any Interim Fixes, as running with -clean takes considerable time in regenerating the plugin registry.
To use -clean you add it to the end of the shortcut that launches the product. For example if you were launching Rational Application Developer in Windows you would modify the launch shortcut target to be
"C:\Program Files\IBM\SDP70\eclipse.exe" -product com.ibm.rational.rad.product.ide -clean
Note that you may use the same at the command-line to launch Rational Application Developer.
Internal Details (Rational Application Developer 7.5.x)
The behavior of -clean is different in Rational Application Developer 7.5.x (Eclipse 3.4.x) from previous versions due to the introduction of p2 provisioning mechanism. See the related information section at the end of this document for a link on a more detailed discussion about p2.
Recall previously (Eclipse 3.3 and earlier) when Eclipse was started the Configurator would run and cause the loading of all the bundles it had stored in its cache. When you started Eclipse with -clean the Configurator would disregard whatever cache data it had and would scan the plug-ins directory and build a new list of bundles to load and thus rebuilt the cache.
In Eclipse 3.4 with the p2 technology, the bundles.info file is read by the SimpleConfigurator and those bundles listed in the file are loaded. Along the way, OSGi loads something called the Reconciler. When the Reconciler runs it takes a look at what bundles are currently installed and compares that to what bundles are available on the file system. If it discovers a new bundle on the file system it installs it by adding it to the bundles.info, the platform.xml and possibly the eclipse.ini using p2 API. If you start Eclipse with -clean this will only cause the flushing of a framework cache (information found in MANIFEST.MF for each bundle) and extension point cache. Note that whether or not -clean is used, the Reconciler is always comparing currently installed bundles to what is on the file system. Currently, there is no way for IBM to clear the Reconciler cache. If clearing the cache is required then a re-install will be required.
Practical Use (Rational Application Developer 7.5.x)
Using -clean for circumstances similar to what you would use it for in earlier versions of Rational Application Developer no longer has value. The cache is never flushed as it was previously and the Reconciler is executed each time on startup to look for the addition of new plug-ins on the file system.
10 September 2020