Equinox Framework Handler and Configurator

This document is under construction.

Overview

This equinox incubator subproject consists of Framework Handler, Configurator, and Framework Handler for Configurators.

Bundles provided by this incubator subproject

They includes bundles related with a Configurator. If you don't know about a Configurator, please see Configurator

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.felix": APIs specific to Felix which will be used by clients and its implementation.
4. "org.eclipse.core.fwhandler.kf": APIs specific to Knopflerfish which will be used by clients and its implementation.
5. "org.eclipse.core.simpleConfigurator": Implementation of SimpleConfigurator.
6. "org.eclipse.core.simpleConfigurator.manipulator": Implementation of ConfiguratorManipulatorAdmin and ConfiguratorManipulator for a SimpleConfigurator.
7. "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
8. "org.eclipse.core.simpleConfigurator.manipulator".
9. "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

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.

This bundle registers a FwHandlerAdmin object into an OSGi service registry at its starting with the following service properties:

FwHandlerAdmin.PROP_FWNAME

“Felix”

FwHandlerAdmin.PROP_FWVERSION

“0.8.0.SNAPSHOT”

FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE

“org.eclipse.core.fwhandler.felix.FelixConfiguratorFwConfigHandler”;

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

FwHandlerAdmin.SERVICE_PROP_KEY_FWLAUCNHER_TYPE

"org.eclipse.core.fwhandler.felix.fwlixlauncher";

• • 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.

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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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).
7. 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.
8. For Felix, 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.

TBD about design of APIs

Currently, some APIs use File objects as its argument. Typical example is FwConfigHandler#saveFwConfig(File fwConfigFile, boolean backup). But URL instead of File might be better to support fw implementations that use fw config files not on local machine but on the remote site. OSGi spec allows it. However, realistically speaking, all fw implementations I know use fw config file on local. That's why the current APIs don't adopt it.

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)