Plug-ins present in the client platform have a defined life cycle and states. Plug-ins are present in one and only one state at a time.
Plug-in life cycle
The defined states are as follows:
Information in this section applies to using the Lotus® Expeditor Client on a device, except where noted.
The underlying framework has added the plug-in. Under normal operation, a plug-in registered by the Eclipse update components will enter a resolving process and transition to the resolved state. If a plug-in is present in the platform, but is in installed state, then either the plug-in has dependencies that have not been met, or another plug-in with an identical Bundle-SymbolicName has been selected by the framework. A plug-in in installed state cannot share packages, nor can it contribute extensions or extension points.Resolved
All of the prerequisites of the plug-in have been met. A plug-in may contribute packages, extensions, and extension points to the platform. Starting
The plug-in has been requested to start and the framework is in the process of starting the plug-in. Start operations should be fast, so any plug-in that remains in a starting state is indicative of a plug-in that is failing to use best practices in its BundleActivator class. Plug-ins that are resolved and that have a bundle activation policy of lazy will enter the Starting state. The console window may show bundle state as <<LAZY . This indicates a bundle in the Starting state waiting for a class access to transition to active.Stopping
The plug-in has been requested to stop and the framework is in the process of stopping the plug-in. Stop operations should be fast, so any plug-in that remains in a stopping state is indicative of a plug-in that is failing to use best practices in its BundleActivator class. Active
The plug-in has been started.Uninstalled
The plug-in has been uninstalled and may not be used.
Fragment life cycle
Fragments are associated with a host plug-in. Since a fragment cannot be individually started and stopped, a fragment follows the life cycle associated with its host plug-in. Fragments are attached to their host plug-in during the resolution process.
Platform life cycle
When the platform is requested to start, the underlying framework will begin the initialization and startup process. To bootstrap the platform, a small number of plug-ins and fragments will be individually installed and started. This set of plug-ins is defined by the osgi.bundles property. The default value of this property is defined in the configdir
The remainder of the plug-ins and fragments for the platform will be installed next. The set of plug-ins and fragments to install will be determined based upon the platform configuration. If the framework is using a managed only configuration, the set of plug-ins and fragments will be determined based upon the platform configuration defined in the platform.xml file residing in the configdir
. If the framework is not using a managed only configuration, the set of plug-ins and fragments will be discovered by the Update Configurator component from the defined eclipse extension directories.
Once the installation of the plug-ins into the framework has completed, a resolver step will run and will attempt to resolve all of the plug-ins and fragments.
After the resolver step has completed, the framework will begin the process of starting the plug-ins. The framework uses settings known as Start Levels to organize the startup of the plug-ins. The framework exists at a specified level and the plug-ins are assigned to start at a specific level. The framework begins at level 0 with no plug-ins started. Next, the Framework will move to start level 1. All plug-ins assigned to start level 1 will then be started in some order. The framework will progress through each of the levels until it reaches the designated framework start level. The designated framework start level is determined by the osgi.startLevel property. The plug-ins that are started during the start level processing are those which have had a start level specifically assigned, and which have been marked to persistently start. A plug-in is marked for persistent start if it has been explicitly started by code that invokes the start()
method on a Bundle object.
A specific set of plug-ins must always be started (active) for the platform to execute properly. The plug-ins required at startup are specified in the config.ini file in the configuration directory. The osgi.bundles property defines the set of plug-ins required at startup.
For any plug-in specified in this property, if it must start prior to the update configurator plug-in, then it must be able to resolve using only the plug-ins specified by this property. Any plug-in specified to start after the update configurator plug-in can use any other plug-ins installed by the update configurator or by the platform definition. Plug-ins in this property should generally be limited to those essential for startup.
After the framework has processed all of the required start levels, the framework will start running an application. An application as used here is a class referenced by an extension to the org.eclipse.core.runtime.applications extension point. Multiple plug-ins may define extensions to the org.eclipse.core.runtime.applications extension point. The actual application used at startup will be the application specified as a specific startup argument, or the application specified for a particular product.
This application defines the controlling characteristics of the platform, such as whether it will contain a workbench and provide a graphical user interface, or whether it will run to perform a specific task and then exit.
As the application runs, it requires the packages, extensions, extension points, and services contributed by the plug-ins in the platform. These plug-ins can automatically start when needed, based on the bundle activation policy. The bundle activation policy is defined by the manifest property Bundle-ActivationPolicy. The current allowed value is lazy
. Previous versions of Lotus Expeditor used different manifest properties, such as Eclipse-LazyStart, or Eclipse-AutoStart. These properties have been deprecated, and the property Bundle-ActivationPolicy should be used instead. If a bundle has a bundle activation policy of lazy, defined using either the new or deprecated property, then when a request to obtain a class from that plug-ins class loader is detected, if that plug-in is not already in the active state, then the framework first attempts to start the plug-in to transition it from the resolved to active state. As part of the starting process, the BundleActivator start method is invoked to perform any required initialization for the plug-in. If the plug-in does not have a policy of lazy, then classes can be resolved from the plug-in without actually attempting to start the plug-in. If no activation policy is specified, the default is assumed to be none.
After the application is completed its task, the framework begins the exit process. In reverse order of the start levels, the plug-ins in the platform are called to stop; thus, allowing the plug-ins to perform any needed cleanup operations to free resources.
This product has added some additional capabilities into the startup processing beyond the capabilities provided by the underlying Eclipse frameworks. First, the com.ibm.rcp.lifecycle.platform plug-in has been added to the osgi.bundles property. This plug-in processes configuration information to select a set of plug-ins, assign those plug-ins a start level, and mark those plug-ins for persistent start.
Secondly, the platform has defined the com.ibm.rcp.lifecycle.application.startBundles extension point, as well as APIs provided in the com.ibm.rcp.lifecycle.application package, to enable applications to allow assemblers and deployers the ability to specify that certain plug-ins must be started when an application starts. This extension point is defined to assist in the startup of plug-ins that provide services and that do not export any packages. Since they do not export packages, there will be no normal class references to these plug-ins, so the presence of the Eclipse-LazyStart attribute will have no effect. The set of plug-ins to start with an application is set uniquely per application. The APIs will attempt to start each of the plug-ins specified by the extension point. Using framework techniques, the APIs will attempt to start the plug-in, invoking the start() method on the plug-in only if the Eclipse-LazyStart: true attribute is not set. When the application completes its tasks, the APIs will attempt to stop each of the plug-ins that it has started.
When using the Lotus Expeditor Client on desktops, the default application provided by the client platform, identified as com.ibm.rcp.personality.framework.RCPApplication, provides support for personalities. Each personality can be thought of as a mini application. Correspondingly, there is a com.ibm.rcp.lifecycle.personality.startBundles extension point which provides the ability to start (and stop) plug-ins that are associated with a specific personality. All of the same characteristics for plug-in startup for a specific application discussed in the previous paragraph can be applied to plug-in startup for a specific personality. For more information, see Using Personalities in .
The Lotus Expeditor Client for Devices only supports the com.ibm.rcp.lifecycle.application.startBundles extension point. However, this extension point may also be used similarly to the personality.startBundles extension point to start plug-ins when the Lotus Expeditor Client environment starts on the device. See Understanding application lifecycle in for more details.
Other notes on plug-in startup behavior
The webcontainer provides an extension point com.ibm.pvc.webcontainer.application that allows local web and portlet plug-ins to identify themselves via their context root to the webcontainer without requiring the plug-in to be started. When the webcontainer receives an HTTP request, if the plug-in that provides a local web or portlet application for that context root is not yet started, it will be started by the webcontainer. This will only apply to applications that have a specific context root. Applications that contribute behavior to the / context root will not be automatically started. Applications in this category include those applications that use the OSGi HttpService to provide servlet applications.
By using the XPDT_SKIP_EXT_UPDATE = true
property in their development environment, developers can prevent the com.ibm.pvc.webcontainer.application
extension from getting added to the plugin.xml
of the Client Services Web Project. This property can also be used with the WAB tools.
What's the difference between a bundle and a plug-in?
The term plug-in originated with Eclipse. The term bundle originated from the OSGi Alliance specifications. Eclipse changed to use an OSGi framework as its underlying componentization model. For purposes of this startup section, there is no difference between a bundle and a plug-in.
How should I set the activation policy?
The recommendation is to set all plug-ins to have a lazy activation policy. This will allow the plug-ins to be started in an automatically (or lazy) manner, and not require them to be explicitly started and marked for persistent start.
Why should I avoid having my plug-ins marked for persistent start?
Plug-ins marked for persistent start will be started each and every time that the platform starts. This can result in slower startup performance. In addition, if the platform has no need of the contributions of the plug-in, the plug-in will still consume resources, contributing to poorer runtime performance or increased memory consumption.
Parent topic: Managing life cycle: XPD622