Difference between revisions of "Equinox FrameworkAdmin"

Revision as of 14:21, 22 December 2006

This document is under construction.

Overview:What FramerowkHandler enables?

Framework Handler provides unified way for a bundle running on a fw to do the followings.

• Set parameters independent of fw implementations to be required to launch a fw instance and save these parameters into the specified configuration file, whose format is dependent on a target fw implementation.
  • In addition, set parameters dependent on a fw implementation about a fw launch and save them into the specified fw config file. In that case, the some part of client bundle implementation must be dependent on the target fw implementation.
• Launch a fw instance with the specified fw config file and other parameters, such as Java VM, Java VM arguments and so on, in another process.
  • Expect bundles state virtually if with the specified fw config file and other parameters, such as Java VM, Java VM arguments and so on, are used for a fw launch.
    • Bundles state represents that what kinds of bundles are installed, and resolved on a fw instance.
  • Current limitation: startlevel is not supported for bundles that recorded persistently by fw. But it should be.

In addition, a fw might be launched by an executable launcher (e.g. eclipse.exe).

• Set parameters to be written in a launcher config file which will be read by an executable launcher and save them into its launcher config file whose format is dependent on the target executable launcher.
• Launch a fw by executing the specified executable launcher in another process.
  • Expect bundles state if the specified executable launcher is executed.

In future, launching a fw instance in the same process will be supported.

Terminologies used in here

Fw config file

configuration file that will be read by a fw implementation at its launching, e.g. config.ini in the directory specified by osgi.configuration.area system property as for equinox.

Initial bundles

bundles which are listed in a fw config file as to be installed during a process of a fw launch. The file must specify each of bundles with its startlevel and a flag whether the bundle should be started or not.

Executable launcher

an executable fw launcher file without any arguments, e.g. eclipse.exe as for Eclipse.

Launcher config file

configuration file that will be read by an executable launcher, e.g. eclipse.ini as for eclipse.exe.

Needs for the common API to handle fw instances

Generally speaking, when an OSGi Framework (Hereafter abbreviated as fw) launches, it reads a configuration file which contains required information for launching. The format of a configuration file and how to launch a fw are dependent on each fw implementation.
It means, if a developer wants to implement a bundle running on a fw instance that will set up a fw config file and launch another framework instance using the fw config file, the developper has to implement the code dependly on each target fw implementation.
If there are needs for a bundle to set up a fw config file and launchs another framework instance using the fw config file, common APIs for doing them would be beneficial. At this point, we have two usecases which requires the common APIs: installer for new provisionning story and PDE plugins.

Installer for new provisioning story

As for Eclipse 3.2, currently each of eclipse based application is packed and delivered to a machine which it will run on in a Zip format (and it will be unzipped on a client machine). If you use several Eclipse based applications on a machine, it results in such a situation that there might be multiple copies of the same jar of a bundle (a plugin) on one machine. It’s no more than waste of disk space. One of ideas to solve this problem is having a shared plugins pool and a small installer application, which is also an OSGi based application composed by bundles, manages all eclipse based applications on a machine. In this case, the common APIs to set up a fw config file and launch a fw instance independently of a fw implementation is required.

PDE plugins

For PDE to support plugin developments on independent fw implementation, the common APIs to achieve them in a unified way is strongly required (is this recognition correct? --> Pascal). 

APIs: Package org.eclipse.core.fwhandler

FwHandlerAdmin

The only API whose implementation will be registered into the OSGi service registry in this package is FwHandlerAdmin.
The client bundle will get the appropriate FwHandlerAdmin service object that can meet its requirements by filtering service properties in the service registry. An example of filtering is the target fw implementation and its version. As for filtering, later section XXX will explain it in detail. Then, the client will get new instance of FwConfigHandler, FwLaucher, ExecutableFwLaucher, or FwBundleState by calling a method of FwHandlerAdmin. These objects provide actual functionalities.

FwConfigHandler

FwConfigHandler mainly handles parameters which should be recorded in a fw config file. It enables a client to read parameters from the specified fw config file, set parametes to this object and save the parameters currently set to this object into the specified fw config file These are done in an uniformed way (independently of fw implementations).

FwLauncher

FwLauncher enables a client to launch a new fw instance in another process using the specified parameters, which are not recorded in a fw config file but can be specified at its launching. Typical examples of the parematers are a Java VM, Java VM arguments, a fw config file to be used for the launch, and so on. These are done in an uniformed way (independently of fw implementations).

ExecutableFwLauncher

ExecutableFwLauncher enables a client to launch a new fw instance in another process by calling executable launcher file, e.g. eclipse.exe. For it, it also enables a client to handle parameters to be written in a launcher config. These are done in an uniformed way (independently of fw implementations).

• Current Assumption: We currently assume that an executable launcher will read a file whose relative path from the executable launcher is fixed as its launcher config file. The relative path is dependent on the executable launcher. It means, specifying the launcher configuration file is not supported. For example, eclipse.exe will read eclipse.ini in the same directory.
  • Remember that a fw config file which the executable launcher will use for that launch can be specified in the launcher config file.

FwBundleState

FwBundleState enables a client to handle bundles state of a virtual launch. FwBundleState can compose bundles state virtually (without launching a fw instance actually) from the specified location which a fw implementation records fw and state of installed bundles persistently. As for equinox, bunch of information are persistently recorded in in org.eclipse.osgi directory of the location specified by the system property keyed by osgi.configuraton.area. In addition, it enables a client bundle to expect the bundle state by virtually installing, uninstalling, and resolving.

Provider of these APIs

First of all, it is not mandatory but supposed that each implementation of these APIs for each fw implementation will be provided by the implementator of the target fw, because the persons who know the implementaion the most are the implementators of the target fw.
Each fw implementation might have some parameters written in its fw config file to be used not for other fw implementations but only for its fw implementation. For supporting to handling these parameters, a provider can customize a FwConfigHandler object which its FwHandlerAdmin creates.

Especially as for executable launchers, many types of ones which enable to launch fws could be considered. Examples of them are eclipse.exe in Eclipse, batch files in MS Windows systems, shell scripts in UNIX sysetms, and so on.

For it, the provider must register the FwHandlerAdmin object with service properties keyed by the followings.

FwHandlerAdmin.SERVICE_PROP_KEY_FWNAME

String; name of the framework

FwHandlerAdmin.SERVICE_PROP_KEY_FWVERSION

String; version of the framework

Current Limitation: there is no version range.Version Range might be required.

FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE

String; a name of type of ;FwConfigHandler implementation that getFwConfigHandler() of this FwHandlerAdmin object will return.

FwHandlerAdmin.SERVICE_PROP_KEY_FWLAUNCHER_TYPE

String; a name of type of FwLauncher implementation that getFwLauncher() of this FwHandlerAdmin object will return.

FwHandlerAdmin.SERVICE_PROP_KEY_EXECUTABLEFWLAUNCHER_TYPE

String; a name of type of ExecutableFwLauncher implementation that getExecutableFwLauncher() of this FwHandlerAdmin object will return.

On offline, the implemenentator of FwHandlerAdmin must declare

• The name of type of FwConfigHandler implementation that getFwConfigHandler() of this FwHandlerAdmin object will return and the interface name of the returned implementation implements.
  • The interface must be a subclass (subinterface) of FwConfigHandler.
• The name of type of FwLauncher implementation that getFwLauncher() of this FwHandlerAdmin object will return and the interface name of the returned implementation implements.that types of .
  • The interface must be a subclass (subinterface) of FwLauncher.
• The name of type of ExecutableFwLauncher implementation that getExecutableFwLauncher() of this FwHandlerAdmin object will return and the interface name of the returned implementation implements.that types of .
  • The interface must be a subclass (subinterface) of ExecutableFwLauncher.

For all of them,

• • • The name of type must be unique in that OSGi environment. Therefore, Reversed fully qualified domain based name is recommended for it.
  • It is ok usually that a unique name of a type usually equals the name of the interface which an object implements.
  • However, as for ExecutableFwLauncher, it might not be said. For example, even for the same fw implementation, there might be several types of executable launchers each of which implements just ExecutableFwLaucnher not any other interfaces.

Currently, FwHandlerAdmin is designed so that one object of it can creat only one type of objects for each FwConfigHandler, FwLaucnher, ExecutableFwLauncher, and FwBundleState. Therefore, if a provider wants to provide several types of ExecutableFwLauncher, for instance, several FwHandlerAdmin services must be registerd with different service property keyed by FwHandlerAdmin.SERVICE_PROP_KEY_EXECUTABLEFWLAUNCHER_TYPE.  

Client of these APIs

A client bundle will get appropriate FwHandlerAdmin service object from an OSGi service registry by filtering the service properties described in the previous subsection in order to get desired FwConfigHandler, FwLaucnher, ExecutableFwLauncher, and FwBundleState objects. 

Launching a fw instance in the Same Process: TBD

At this point, launching a fw instance in the same process is not considered yet in this APIs, explicitly. However, it will be supported.

• What is not sure is “general way of launching a fw instance in the same process”. The FwLauncher interface might support it (JavaVM and JavaVM arguments are not used for it obviously). Other interfaces might have better to be defined.

Bundles provided by this incubator subproject

1. "org.eclipse.core.fwhandler": APIs related with FwHandler and Configurator which will be used by clients.
2. "org.eclipse.core.fwhandler.equinox": APIs specific to Equinox which will be used by clients and its implementation.
3. "org.eclipse.core.fwhandler.kf": APIs specific to Knopflerfish which will be used by clients and its implementation.
4. "org.eclipse.core.simpleConfigurator": Implementation of SimpleConfigurator.
5. "org.eclipse.core.simpleConfigurator.manipulator": Implementation of ConfiguratorManipulatorAdmin and ConfiguratorManipulator for a SimpleConfigurator.
6. "org.eclipse.core.fwhandler.internal.utils": Utility classes used for implementing "org.eclipse.core.fwhandler.equinox", "org.eclipse.core.fwhandler.kf", # "org.eclipse.core.simpleConfigurator" and
7. "org.eclipse.core.simpleConfigurator.manipulator".
8. "org.eclipse.core.fwhandler.examples": An example of client bundle of the APIs related with FwHandlerAdmin and Configurator.

To understand how a provider is implemented the APIs, see bundle 1 and 2. To understand how a client uses the APIs, see bundle 1 and 7.

Implementation of FwHandler for Equinox

Bundle of "org.eclipse.core.fwhandler.equinox" contains APIs specific to Equinox which will be used by clients and its implementation of APIs related with FwHandler for Equinox.
This bundle registers a FwHandlerAdmin object into an OSGi service registry at its starting with the following service properties:

FwHandlerAdmin.PROP_FWNAME

“Equinox”

FwHandlerAdmin.PROP_FWVERSION

“3.2”

FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE

“org.eclipse.core.fwhandler.equinox.EquinoxConfiguratorFwConfigHandler”;

• • FwHandlerAdmin#getFwConfigHandler() returns a object which implements EquinoxConfiguratorFwConfigHandler interface that extends ConfiguratorFwConfigHandler. It can handle a fw config with a Configurator and its method of getFwConfigInfo() returns a object which implements EquinoxConfiguratorFwConfigInfo interface that extends ConfiguratorFwConfigInfo.

FwHandlerAdmin.SERVICE_PROP_KEY_FWLAUCNHER_TYPE

"org.eclipse.core.fwhandler.equinox.equinoxlauncher";

• • FwHandlerAdmin#getFwLaucher() returns a object which implements FwLauncher interface.

FwHandlerAdmin.SERVICE_PROP_KEY_EXECUTABLEFWLAUCNHER_TYPE

"org.eclipse.core.fwhandler.equinox.ecliselauncher";

• • FwHandlerAdmin#getExecutableFwLaucher() returns a object which implements ExecutableFwLauncher interface.

A FwBundleState object returned by FwHandlerAdmin#getFwBundleState() supports composing virtually bundles state taking the persistent stored fw state information and resolving bundles into account.

• PlatformAdmin service (in org.eclipse.osgi.service.resolver packages) registered by org.eclipse.osgi plugin is used to do it in this implementation.

Implementation of FwHandler for Felix

TODO: implementation of it. Bundle of "org.eclipse.core.fwhandler.felix" contains APIs specific to Felix which will be used by clients and its implementation of APIs related with FwHandler for Felix.

Implementation of FwHandler for Knopflerfish

Bundle of "org.eclipse.core.fwhandler.kf" contains APIs specific to Knopflerfish which will be used by clients and its implementation of APIs related with FwHandler for Knopferfish. This bundle registers a FwHandlerAdmin object into an OSGi service registry at its starting with the following service properties:

FwHandlerAdmin.PROP_FWNAME

“knopflerfish”

FwHandlerAdmin.PROP_FWVERSION

“2.0”

FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE

“org.eclipse.core.fwhandler.kf.KfConfiguratorFwConfigHandler”;

• • FwHandlerAdmin#getFwConfigHandler() returns a object which implements KfConfiguratorFwConfigHandler interface that extends ConfiguratorFwConfigHandler. It can handle a fw config with a Configurator and its method of getFwConfigInfo() returns a object which implements KfConfiguratorFwConfigInfo interface that extends ConfiguratorFwConfigInfo.

FwHandlerAdmin.SERVICE_PROP_KEY_FWLAUCNHER_TYPE

"org.eclipse.core.fwhandler.kf.kflauncher";

• • FwHandlerAdmin#getFwLaucher() returns a object which implements FwLauncher interface.

FwHandlerAdmin.SERVICE_PROP_KEY_EXECUTABLEFWLAUCNHER_TYPE

none is set;

• • FwHandlerAdmin#getExecutableFwLaucher() returns NULL.

A FwBundleState object returned by FwHandlerAdmin#getFwBundleState() does NOT support either of composing virtually bundles state taking the persistent stored fw state information and resolving bundles into account.

Example of client bundle of these APIs

Bundle of "org.eclipse.core.fwhandler.examples" is a client that shows several example of usage of API. For example,

1. For Equinox, without SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Then, launch a fw instance not by no executable launcher with the specified fw config file.

1. For Equinox, with SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Then, launch a fw instance by no executable launcher with the specified fw config file.

1. For Knopflerfish, without SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Then, launch a fw instance by no executable launcher with the specified fw config file.

1. For Knopflerfish, with SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Then, launch a fw instance by no executable launcher with the specified fw config file.

1. Without SimpleConfigurator,
   1. Set information about fw launch and save them into the specified fw config file for Knopflerfish.
   2. Then, retrieve the configuration information by reading the fw config file saved for Knopflerfish.
   3. Convert the information into the one for Equinox and save it into the other fw config file for Equinox
   4. Launch a fw instance by no executable launcher with the specified fw config file for Equinox.

1. For Equinox, without SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Set information an executable launcher including the fw config file to be used about and save it into the specified launcher config file (eclipse.ini).
   3. Launch a fw instance by executing the executable launcher (eclipse.ini).

1. For Equinox, with SimpleConfigurator
   1. Set information about fw launch and save them into the specified fw config file.
   2. Then, expect virtually bundles state as if a fw instance is launched by no executable launcher with the specified fw config file.

FAQ

Q1. Why new fw instance is required to launch an application? Why not install a set of bundles as an “applications” on running fw (one fw)? A1. To support the case that each of fw instances needs individual configuration.

• • Is it correct answer?.

Q2. (Related question to Q1) Does it need more memory comsumption and longer time to launch an application that launching multiple fw instances in different processes than launching application on the same fw instance? A2. That is correct. It needs more memory comsumption and longer time to launch an application. Launching another fw instance on a fw instance (within the same process) will solve this problem. While this is not supported yet, it is included in the future work of the APIs. Q3. Is there any other idea of Configurator? In other words, is it worth to define not SimpleConfigurator but Configuration interface? A2. To tell the truth, I’m not sure… If there are no other examples of Configurator, it’s not worth. If you have any idea, please tell me.

References

1. Equinox: Runtime options of Eclipse 3.2
2. Felix: Usage
3. Knopflerfish: Usage
4. Requirements for a new update manager (of Eclipse)