Configurator and Framework Handler for it

This document is under construction.

Overview: What Configurator enable?

Configurator enables a bundle running on a fw to do the following:

• Apply the bundle life cycle control information retrieved from the specified URL to the runtime environment.

A Configurator Bundle will call this API with a specified URL when it starts. That is, this bundle will change bundles life cycle on a fw instance at its start.

ConfiguratorManipulator is also defined as an element tightly coupled with Configurator (and ConfigurtorBundle). A client bundle of ConfiguratorManipulator can manipulate information about the corresponding Configurator. An example of its manipulations is setting parameters to be saved in the specified URL, which will be referred by Configurator later.

Terminologies Used In Here

Configurator config file: the location referred by the specified URL by a Configurator object, if the URL represents not a directory but a file. See also Equinox_Framework_Handler#Terminologies_used_in_here.

Background

As described in Equinox_Framework_Handler#Backgroud, there is an idea of using an installer application to solve the problem of current eclipse based application. We have two main requirements for it.

1. When a fw is launched, the installer has to control bundles’ life cycle on a running fw as it intends. (in a fw startup process)
2. After a fw launch and bundles composing applications start, the installer has to change bundles’ life cycle as it intends. (outside of a fw startup process)

The first one can be achieved by setting the list of bundles installed and started at the launch of a fw config file properly. However, the second one cannot be achieved by it.

Solution: Configurator

To achieve both of them, we propose concepts of Configurator and Configurator Bundle.

A Configurator is an OSGi service that enables a client bundle on a running fw to apply the bundles life cycle control information retrieved from the specified URL to the runtime.

Configurator Bundle is defined as a bundle that does the followings at its startup:

1. Create a Configurator service and register it into an OSGi service registry.
2. Get URL information by BundleContext#getProperty(String) with Configurator.PROP_KEY_CONFIGURL as a name argument.
3. If gotten URL is not null, call a method of the created Configurator object applyConfiguration(URL) with a gotten value as a URL.

• • Current AssumptionBold text: How a Configurator Bundle gets the information about what URL should be referred at its startup is an issue to discuss. Currently, as described above, BundleContext#getProperty(String name) with an argument of the predefined name is used. Other possibility is using ConfigurationAdmin service. However, a bundle which configures the predefined Configuration object will be required in that case and how the bundle will get that value to would be another problem, which is similar problem to the original one.

The first item can be achieved by doing the followings properly

• Add a Configurator Bundle to the list of bundles to be installed in a fw config file,
• Set the bundle lifecycle information and save them into the specified URL (if saving is possible).
• Set the specified URL into system property keyed by Configurator.PROP_KEY_CONFIGURL in a fw config file.
• Launch a fw using the fw config file.

The second item can be achieved by calling a method of Configurator service after launching.

We have two examples of Configurator and corresponding Configurator bundle; the first one is UpdateConfigurator, whose main job is searching bundles in the predefined directory (plugins/) and install all of them as the current “org.eclipse.update.configurator” plugin does. The second one is SimpleConfigurator, which will be introduced below.

• • TBD: There seems to be a contradiction between logic about why Configurator is needed in Background section where it is useful for installer application and the description of UpdateConfigurator; UpdateConfigurator is designed based on the current distribution way of Eclipse applications but the logic says that the current distribution way of Eclipse should be revised. (To tell the truth, we first thought SimpleConfigurator and later abstracted it into Configurator API).

Definition of SimpleConfigurator

SimpleConfigurator is an implementation of Configurator. In a nutshell, the main method of it is applyConfiguration(URL). It will firstly retrieve information about bundles lifecycle by reading a file specified in a URL. The file is a text file which contains a simple list of bundles with startlevel and flag of being started or not. (Each line in the file is comma separated strings and has information of one bundle, e.g. bundle location, startlevel, flag of being started or not). Then the method will retrieve state from the file and apply it to running OSGi fw instance.

In the method, it will get a flag by calling BundleContext#getProperty(String) with a key of “SimpleConfiguratorConstants.PROP_KEY_EXCLUSIVE_INSTALLATION”. No matter which the returned flag is true or not, the method tries to make bundles listed in the file installed and started with the specified startlevel as specified in the file. If the returned flag is true, in addition, the method tries to uninstall any bundle which is not included in the list of the config file.

SimpleConfiguratorManipulator is an implementation of ConfiguratorManipulator and manipulate information of SimpelConfigurator.

APIs: Package org.eclipse.core.configurator

Configurator

It provides methods to

• Apply the bundles life cycle control according to the information retrieved from the specified URL to the runtime OSGi environment.
• Expect bundles state if the bundles life cycle control information retrieved from the specified URL is applied to the runtime environment.
  • What kinds of information it retrieves and how it retrieves the information from the specified URL are dependent on the Configurator implementation.

ConfiguratorManipulator

To meet the requirements described in #Backgroud by Configurator, manipulating the information which will be referred by a Configurator will be needed. For example, setting up information of bundles to be installed by a Configurator and saving it into the specified configurator config file either on a fw where the target Configurator bundle is running or on a fw where it is not running in a proper format.

ConfiguratorManipulator provides such kinds of ways.

As described in #ConfiguratorManipulatorAdmin, objects implementing this API are not registered in a service registry but created by a ConfiguratorManipulatorAdmin object which is registered in the registry.

ConfiguratorManipulatorAdmin

ConfiguratorManipulatorAdmin object will be registered in a service registry with a service property keyed by the following:

ConfiguratorManipulatorAdmin.SERVICE_PROP_KEY_CONFIGURATOR_BUNDLESYMBOLICNAME: String; a symbolic name of target Configurator bundle.

A Client bundle that wants to use ConfiguratorManipulator can get the appropreate ConfigurationManipulatorAdmin object which will create appropretate ConfiguratorManipulator for the target Configurator by filtering service properties.

TBD: Conceptually, a bundle which registers Configurator and a bundle which calls a mehotd of Configurator to apply configuration can be implemented in separate bundles.

Framework Handler for Configurator

As for framework handler, see Equinox_Framework_Handler,. One of the typical usecases of FwHandler APIs by an installer application is

1. a client bundle saves the parameters into the desired fw config file so that bundles in the list of initial bundles will be installed (and started if intended) with specified startlevel after all fw launching process is completed for a future fw launch.
2. And the client launches a fw instance with the saved fw config file.

Now, if a Configurator bundle is in the list of intial bundles in a fw config file, the Configurator bundle will apply the bundle life cycle control information according to the specified URL at its startup during processes of a fw launch. That means, the final bundles state after processes of fw launching is completed will be affected by the list of initial bundles in a fw config file and a Configurator’s behaivior.

What an installer bundle achieves is making the final bundles state after the launch intended. In the case, it is desireable that the client (installer application) doesn’t need to consider what kinds of bundles to be listed as initial bundles and what kinds of bundles to written in a configurator config file. For supporting the use cases with a Configurator Bundle, we defined an API which extends FwConfigHanlder: org.eclipse.core.fwhandler.ConfiguratorFwConfigHandler.

ConfiguratorFwConfigHandler enables a client to save a fw config file and a configurator config file simultaneously according to the given bundles list that a client desires to be installed (and started) after a launching process. However, among bundles in the given bundles list, decision about which bundels should be listed in initial bundles in a fw config and what kinds of bundles to written in a configurator config file is dependent on not its FwConfigHandler object but target Configurator bundle’s behavior. For it, we prepared a method to do it in ConfiguratorManipulator, which depends on a Configurator.

Now, the following steps acheive it.

1. To a ConfiguratorFwConfigHandler object, a client bundle sets parameters about all bundles which it desired to install with startlevel and flag to be started after all process of fw launching finish.
2. The client calls the method of the ConfiguratorFwConfigHandler object that saves the specified fw config file and the specified configurator config file according to the parameters set. In that methods, ConfiguratorFwConfigHandler will do
   1. Get all ServiceReferences of ConfiguratorManipulatorAdmin services that the ConfiguratorFwConfigHandler object can get on the running fw.
   2. Get the symbolic names of target Configurator Bundle of each available services by getting the service property keyed by ConfiguratorManipulatorAdmin.SERVICE_PROP_KEY_CONFIGURATOR_BUNDLESYMBOLICNAME:
   3. Choose a group of Configurator Bundles each of whose symbolic names equals one of the symbolic names gotten.
   4. Choose the one which has the smallest start level among the group of Configurator Bundle and get the corresponding ConfiguratorManipulatorAdmin service available and create a ConfiguratorManipulator object.
   5. Call a method of ConfiguratorManipulator with bundles list to be installed. It will return which bundles should be listed in the initial bundles of a fw config file and set information about bundles to be listed in a configurator config file to the ConfiguratorManipulator object. For example, current SimpleConfiguratorManipulator implementation deals wiht given bundles as follows:
      1. First, all bundles given will be saved into the specified configurator config file.
      2. Check the given bundles to be installed (and started) to find the ConfiguratorBundle with the smallest startlevel. If no exists, all bundles will be allocated to the bundles to be listed in a fw config file. Otherwise proceed to the next step.
      3. Any bundles that are extention bundles of the system bundle will be allocated to the initial bundles.
      4. Any bundles with smaller startlevel than the ConfiguratorBundle will be allocated to the initial bundles.
      5. Any bundles with the same startlevel of the ConfiguratorBundle that appears prior to the ConfiguratorBundle in the given bundles list will be allocated to the initial bundles.
      6. Any bundles that is required to resolve bundles which has been allocated to the initial bundles at this point will be allocated to the initial bundles.
      7. Return the initial bundles.
   6. Save the returned bundle list into the specified fw config file.
   7. Call a method of ConfiguratorManipulator to save the information set into the specified configurator config file.
3. The client sets parameters including a fw config file location to a FwLauncher object,
4. The client launches a fw instance by the FwLauncher object.

Current Assumption of Configurator Bundle

It is assumed that there is no bundle that controls bundles’ lifecycle except only one Configurator bundle running on a fw instance. If there are several such bundles in an initial bundles list, the bundles state after all launching process is completed would be more complicated. It is not supported. In addition, it is assumed that a bundle installed and started by a Configurator Bundle will not control bundles’ lifecycle.