Difference between revisions of "Equinox FrameworkAdmin"

From Eclipsepedia

Jump to: navigation, search
m (Equinox Framework Handler moved to Equinox FrameworkAdmin)
(API names are renamed)
Line 2: Line 2:
  
 
== Motivation ==
 
== Motivation ==
Generally speaking, an OSGi framework (hereafter we call fw) needs some configuration files for its launch. A fw will be launched by invoking java command or by executing an executable launcher file. In the former case, configurations for fw implementation to read will be required. In the latter case, executable launcher file also might read some configuration files at its invocation.  
+
Generally speaking, an OSGi framework needs some configuration files for its launch. A framework will be launched by invoking java command or by executing an executable launcher file. In the former case, configurations for framework implementation to read will be required. In the latter case, executable launcher file also might read some configuration files at its invocation.  
* As in Eclipse, org.eclipse.osgi plug-in that contains main class of equinox fw implementation reads config.ini in a configuration area. In addition, eclipse.exe is provided as an executable launcher which reads eclipse.ini in the same directory and invokes fw.   
+
* As in Eclipse, org.eclipse.osgi plug-in that contains main class of equinox framework implementation reads config.ini in a configuration area. In addition, eclipse.exe, an executable launcher, reads eclipse.ini in the same directory of it and invokes a framework implementation.   
  
Currently, the focus of OSGi Service Platform Specification has been to standardize a runtime infrastructure. On the other hand, how to configure and launch a fw is not addressed. Therefore, scenarios such as bootstrapping OSGi on a clean system are left difficult to manage in a fw independent way.
+
Currently, the focus of OSGi Service Platform Specification has been to standardize a runtime infrastructure. On the other hand, how to configure and launch a framework is not addressed. Therefore, scenarios such as bootstrapping OSGi on a clean system are left difficult to manage in a framework independent way.
  
==Overview:What FramerowkHandler enables?==
+
==Overview: What does FrameworkAdmin service enable?==
We would like to address this problem by proposing a simple API that would allow to configure a non running framework and launch it in a fw independent way. Framework Handler provides fw independent way for a bundle running on a fw to do the followings.
+
We would like to address this problem by proposing FrameworkAdmin service, which allows a bundle running on a framework to do the followings in a framework independent way.
 
+
*Set configurations required to launch a framework, such as
*Set configurations required to launch a fw, such as
+
 
** Java VM location,
 
** Java VM location,
 
** Java VM arguments,
 
** Java VM arguments,
** executable launcher location,
+
** executable launcher location, if used
 
** beginning start level and initial bundle start level,
 
** beginning start level and initial bundle start level,
 
** Bundles to be installed and started with their start levels,
 
** Bundles to be installed and started with their start levels,
** fw configuration location,
+
** framework configuration location,
** fw persistent date location,
+
** framework persistent date location,
*Launch a fw with the specified configurations, such as Java VM, Java VM arguments and so on.
+
*Launch a framework with the specified configurations.
*Expect its bundles state if the specified configurations are used for a fw launch.
+
*Expect a bundles state if the specified configurations are used for a framework launch.
  
 
==Terminologies used in here==
 
==Terminologies used in here==
;Fw config files:configuration files 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.
+
;Framework config files: configuration files that will be read by a framework implementation at its launching, e.g. config.ini in the directory specified by osgi.configuration.area system property as for equinox.
;Executable launcher:an executable fw launcher file, e.g. eclipse.exe as for Eclipse.
+
;Executable launcher: an executable framework launcher file, e.g. eclipse.exe as for Eclipse.
;Launcher config files:configuration files that will be read by an executable launcher, e.g. eclipse.ini as for eclipse.exe.
+
;Launcher config files: configuration files that will be read by an executable launcher, e.g. eclipse.ini as for eclipse.exe.
;Bundles state: state of bundles that represents what kinds of bundles are installed, resolved and to be started on a fw.
+
;Bundles state: state of bundles that represents what kinds of bundles are installed, resolved and to be started on a framework.
 
   
 
   
==Senarios that the API would help==
+
==Scenarios that the API would help==
 
;PDE UI: to ease the targeting of various frameworks
 
;PDE UI: to ease the targeting of various frameworks
 
;Provisioning agent: to setup a non running framework
 
;Provisioning agent: to setup a non running framework
Line 34: Line 33:
 
See [[#references|[1]]] [[#references|[2]]].
 
See [[#references|[1]]] [[#references|[2]]].
  
==API: Package org.eclipse.core.fwhandler==
+
==API: Package org.eclipse.equinox.frameworkadmin==
Interfaces defined in ''org.eclipse.core.fwhandler'' package will be introduced briefly. See the codes and Java docs in detail.  
+
Interfaces defined in ''org.eclipse.equinox.frameworkadmin'' package will be introduced briefly. See the codes and Java docs in detail.  
  
===FwHandlerAdmin===
+
===FrameworkAdmin===
The only interface whose implementation will be registered into the OSGi service registry in this package is FwHandlerAdmin.
+
The only interface whose implementation will be registered into the OSGi service registry in this package is FrameworkAdmin.
  
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, [[#Provider of these APIs|later section]] will explain it in detail. Then, the client will get new instance of FwHandler which plays a main role in this API.
+
The client bundle will get the appropriate FrameworkAdmin service object that can meet its requirements by filtering service properties in the service registry. An example of filtering is the target framework implementation and its version. As for filtering, [[#Provider of these APIs|later section]] will explain it in detail. Then, the client will get new instance of Manipulator which plays a main role in this API.
  
The interface has a method which might return the FwHandler object initialized according to the running fw and launcher state. Detail of this would be introduced [[#Current our proposal|later]].  
+
The interface has a method which might return the Manipulator object initialized according to the running framework and launcher state. Detail of this would be introduced [[#Current our proposal|later]].  
  
In addition, it also has a method to launch a fw according to the specified FwHandler object.
+
In addition, it also has a method to launch a framework according to the specified Manipulator object.
  
===FwHandler===
+
===Manipulator===
A client bundle can get a FwHandler object by FwHandlerAdmin.getFwHandler(). This object keeps both a FwConfigData object and a FwLauncherData object, each of which has setter and getter methods on parameters to be required for a fw launch. The client can set some parameters to be required for launching a fw via FwConfigData object or FwLauncherData object. The parameters set in this object can be saved. Where to save is determined according to the parameters set at that time in a way dependent on a target framework and launcher implementation.
+
A client bundle can get a Manipulator object by FrameworkAdmin.getManipulator(). This object keeps both a ConfigData object and a LauncherData object, each of which has setter and getter methods on parameters to be required for a framework launch. The client can set some parameters to be required for launching a framework via ConfigData object or LauncherData object. The parameters set in this object can be saved. Where to save is determined according to the parameters set at that time in a way dependent on a target framework and launcher implementation.
  
The client also can load parameters from fw config files and launcher config files in the specified locations.
+
The client also can load parameters from framework config files and launcher config files in the specified locations.
  
After parameters are set to this object either by setting via a FwConfigData or a FwLaucnherData or loading from configuration files, FwHandlerAdmin.launch(FwHandler, File) will launch a fw according to the current parameters set in this object. It might invoke a fw by java command or executing the specified launcher.  
+
After parameters are set to this object either by setting via a ConfigData or a LauncherData or loading from configuration files, FrameworkAdmin.launch(Manipulator, File) will launch a framework according to the current parameters set in this object. It might invoke a framework by java command or executing the specified launcher.  
  
 
Remember if you have set parameters but not have saved yet, this launch might use other parameters because actual launch will use parameters retrieved from the configuration files.
 
Remember if you have set parameters but not have saved yet, this launch might use other parameters because actual launch will use parameters retrieved from the configuration files.
  
In addition, FwHandler enables for a client bundle to expect bundles state if the specified configurations are used for launch without actual launch.   
+
In addition, Manipulator enables for a client bundle to expect bundles state if the specified configurations are used for launch without actual launch.   
  
===FwConfigData===
+
===ConfigData===
FwConfigData is a class that keeps some parameters for a FwHandler object such as,
+
ConfigData is a class that keeps some parameters for a Manipulator object such as,
 
*Bundles list to be installed, with their persistently marked flag as started or not and their start level for its configuration.  
 
*Bundles list to be installed, with their persistently marked flag as started or not and their start level for its configuration.  
 
*Beginning start level and initial bundle start level.
 
*Beginning start level and initial bundle start level.
*System properties dependent on a fw implementation.
+
*System properties dependent on a framework implementation.
*System properties independent of a fw implementation.
+
*System properties independent of a framework implementation.
  
For most fw implementations, these parameters will be saved into their fw config files. However, this API doesn't restrict where to save. For example, a fw implementation and a launcher implementation might need to save these parameters not in fw config files but in a launcher config files. It depends on the target implementations.
+
For most framework implementations, these parameters will be saved into their framework config files. However, this API doesn't restrict where to save. For example, a framework implementation and a launcher implementation might need to save these parameters not in framework config files but in a launcher config files. It depends on the target implementations.
  
===FwLauncherData===
+
===LauncherData===
FwLauncherData is a class that keeps some parameters for a FwHandler object such as,
+
LauncherData is a class that keeps some parameters for a Manipulator object such as,
 
*Location of Java VM.  
 
*Location of Java VM.  
 
*Java VM arguments.
 
*Java VM arguments.
*Location of fw config files.
+
*Location of framework config files.
*Location of fw persistent data, where a fw implementation save information to be kept persistently, such as bundles state, permissions of bundles, start level information, private persistent storages for bundles, and so on.  
+
*Location of framework persistent data, where a framework implementation saves information to be kept persistently, such as bundles state, permissions of bundles, start level information, private persistent storages for bundles, and so on.  
*Clean flag: a flag to clean the specified location of fw persistent data.
+
*Clean flag: a flag to clean the specified location of framework persistent data.
  
For most fw implementations, these parameters will be saved into their launcher config files, if executable launcher is used. However, this API doesn't restrict where to save. As in Apache Felix, location of fw persistent data should be written in its fw config file. Therefore, the implementation of FwHandler for Felix should save it into not launcher config file but its fw config file.
+
For most framework implementations, these parameters will be saved into their launcher config files, if executable launcher is used. However, this API doesn't restrict where to save. As in Apache Felix, location of framework persistent data should be written in its framework config file. Therefore, the implementation of Manipulator for Felix should save it into not launcher config file but its framework config file.
  
===FwBundleState===
+
===BundlesState===
The implementating object of FwBundleState will be created by FwHandler object. At the time of its creation, this object will compose bundles state according to the parameters that the FwHandler object keeps. It means, bundles which can be obtained by FwHandler.getFwConfigData().getBundles() will be installed on a virtually launched fw using parameters about fw persistent data location. If the data location is not empty and clean flag is false, the installed bundles persistently recorded there should be taken into consideration to compose the bundles state.
+
The implementating object of BundlesState will be created by Manipulator object. At the time of its creation, this object will compose bundles state according to the parameters that the Manipulator object keeps. It means, bundles which can be obtained by Manipulator.getConfigData().getBundles() will be installed on a virtually launched framework using parameters about framework persistent data location. If the data location is not empty and clean flag is false, the installed bundles persistently recorded there should be taken into consideration to compose the bundles state.
  
After creating this object,  this object also provides ways for a client to resolve bundles, install additional bundles, uninstall bundles virtually. Modification of this object never affects the parameters of the FwHandler object which created this object.
+
After creating this object,  this object also provides ways for a client to resolve bundles, install additional bundles, uninstall bundles virtually. Modification of this object never affects the parameters of the Manipulator object which created this object.
  
 
===Provider of these APIs===
 
===Provider of these APIs===
First of all, we supposed that an implementation of this API for each fw implementation will be provided by the implementators of the target fw, because the persons who know the fw implementation the most are the implementators of the target fw.
+
First of all, we supposed that an implementation of this API for each framework implementation will be provided by the implementators of the target framework, because the persons who know the framework implementation the most are the implementators of the target framework.
  
For clients to filter the proper service object, the provider must register the FwHandlerAdmin object with service properties keyed by the followings.
+
For clients to filter the proper service object, the provider must register the FrameworkAdmin object with service properties keyed by the followings.
  
;FwHandlerAdmin.SERVICE_PROP_KEY_FW_NAME: String; name of the framework
+
;FrameworkAdmin.SERVICE_PROP_KEY_FW_NAME: String; name of the framework
;FwHandlerAdmin.SERVICE_PROP_KEY_FW_VERSION: String; version of the framework
+
;FrameworkAdmin.SERVICE_PROP_KEY_FW_VERSION: String; version of the framework
;FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_NAME: String; name of the launcher
+
;FrameworkAdmin.SERVICE_PROP_KEY_LAUNCHER_NAME: String; name of the launcher
;FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_VERSION: String; version of the launcher
+
;FrameworkAdmin.SERVICE_PROP_KEY_LAUNCHER_VERSION: String; version of the launcher
 
*Current Limitation: there is no version range.Version Range might be required.
 
*Current Limitation: there is no version range.Version Range might be required.
*Offline, the implemenentator of FwHandlerAdmin must declare these values and client must know them.
+
*Offline, the implementator of FrameworkAdmin must declare these values and client must know them.
  
 
There is another service property name to be standardized.
 
There is another service property name to be standardized.
;FwHandlerAdmin.SERVICE_PROP_KEY_RUNNING_FW_FLAG: true if its getFwHandlerRunning() returns the initialized FwHandler object of running system.
+
;FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG: true if its getRunningManipulator () returns the initialized Manipulator object of running system.
 
*Detail of it would be introduced [[#Current our proposal|later]].  
 
*Detail of it would be introduced [[#Current our proposal|later]].  
  
 
===Client of these APIs===
 
===Client of these APIs===
A client bundle will get appropriate FwHandlerAdmin service object from an OSGi service registry by filtering the service properties described previously in order to get the FwHandler objects to handle the desired fw and launcher implementation.  
+
A client bundle will get appropriate FrameworkAdmin service object from an OSGi service registry by filtering the service properties described previously in order to get the Manipulator objects to handle the desired framework and launcher implementation.  
  
 
==TBD==
 
==TBD==
 
===Which interface should a method of launch operation belong to?===
 
===Which interface should a method of launch operation belong to?===
Currently, a method of launch operation belongs to FwHandlerAdmin interface.
+
Currently, a method of launch operation belongs to FrameworkAdmin interface.
I can separate this API into another interface like ''"FwLauncher"''. But I am not sure how much merit of it would be.  
+
I can separate this API into another interface like ''"FrameworkLauncher"''. But I am not sure how much merit of it would be.  
* One merit of the separation is, we can restrict some bundles so that can configure a fw but cannot launch it, by not giving ServicePermission("GET","FwLauncher").
+
* One merit of the separation is, we can restrict some bundles so that can configure a framework but cannot launch it, by not giving ServicePermission("GET","FrameworkLauncher").
 
* One demerit of it is, number of interface will be increased by one, even if this interface only has one method.
 
* One demerit of it is, number of interface will be increased by one, even if this interface only has one method.
  
===Launching a fw instance in the Same Process===
+
===Launching a framework instance in the Same Process===
At this point, launching a fw instance in the same process is not considered yet in this API, explicitly. However, it will be supported in the future.
+
At this point, launching a framework instance in the same process is not considered yet in this API, explicitly. However, it will be supported in the future.
*What is not sure is “general way of launching a fw instance in the same process”. The API might be able to support it (JavaVM and JavaVM arguments are not used for it obviously).
+
*What is not sure is “general way of launching a framework instance in the same process”. The API might be able to support it (JavaVM and JavaVM arguments are not used for it obviously).
  
  
==How to handle running fw information?==
+
==How to handle running framework information?==
There is a need for manipulating configurations of not only a non-running fw but also a running fw. While there are several ways to realize it, currently we adopt the following way. The alternatives to realize it are shown [[Alternatives of Handling a Running Fw]].
+
There is a need for manipulating configurations of not only a non-running framework but also a running framework. While there are several ways to realize it, currently we adopt the following way. The alternatives to realize it are shown [[Alternatives of Handling a Running Framework]].
  
 
===Current our proposal===
 
===Current our proposal===
  
The bundle that registers a FwHandlerAdmin service for a particular fw and launcher implementation will do at its registration as follows;
+
The bundle that registers a FrameworkAdmin service for a particular framework and launcher implementation will do at its registration as follows;
  
# A bundle checks if the bundle can register a FwHandlerAdmin object whose getFwHandlerRunning() returns not null but a FwHandler object initialized according to the running fw and launcher implementation, somehow. The way how the bundle checks it is dependent of its target fw and launcher implementation.
+
# A bundle checks if the bundle can register a FrameworkAdmin object whose getManipulatorRunning() returns not null but a Manipulator object initialized according to the running framework and launcher implementation, somehow. The way how the bundle checks it is dependent of its target framework and launcher implementation.
# If no, the bundle registers a FwHandlerAdmin service for a target fw and launcher implementation, whose getFwHandlerRunning() returns null, with specified service properties including the ones representing fw name/version and launcher name/version.   
+
# If no, the bundle registers a FrameworkAdmin service for a target framework and launcher implementation, whose getRunningManipulator() returns null, with specified service properties including the ones representing framework name/version and launcher name/version.   
# If yes, the bundle registers a FwHandlerAdmin service for a target fw and launcher implementation, whose getFwHandlerRunning() returns a FwHandler object initialized according to the running fw and launcher implementation. The registration is done with specified service properties including not only the ones representing fw name/version and launcher name/version, but also '''FwHandlerAdmin.SERVICE_PROP_KEY_RUNNING_FW_FLAG'''="true".  
+
# If yes, the bundle registers a FrameworkAdmin service for a target framework and launcher implementation, whose getRunningManipulator() returns a Manipulator object initialized according to the running framework and launcher implementation. The registration is done with specified service properties including not only the ones representing framework name/version and launcher name/version, but also '''FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG'''="true".  
  
Regarding when the bundle should register a FwHandlerAdmin service is not addressed. However, the typical timing is at its start up.
+
Regarding when the bundle should register a FrameworkAdmin service is not addressed. However, the typical timing is at its start up.
  
A client bundle can get the initialized FwHandler object as follows;
+
A client bundle can get the initialized Manipulator object as follows;
 
<pre>
 
<pre>
String filter = “(FwHandlerAdmin.SERVICE_PROP_KEY_RUNNING_FW_FLAG=true)”.
+
String filter = “(FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG=true)”.
ServiceReference references[] = context.getServiceReferences(FwHandlerAdmin.class.getName(), filter);
+
ServiceReference references[] = context.getServiceReferences(FrameworkAdmin.class.getName(), filter);
FwHandlerAdmin fwHandlerAdmin = (FwHandlerAdmin) context.getService(references[0]);
+
FrameworkAdmin FrameworkAdmin = (FrameworkAdmin) context.getService(references[0]);
FwHandler fwHandler = fwHandlerAdmin.getFwHandlerRunning(); < initialized.
+
Manipulator manipulator = FrameworkAdmin.getManipulatorRunning(); <-- initialized.
 
</pre>
 
</pre>
  
Line 136: Line 135:
  
 
==Bundles provided by this incubator subproject==
 
==Bundles provided by this incubator subproject==
# "'''org.eclipse.core.fwhandler'''": APIs related with FwHandler and Configurator which will be used by clients.
+
# "'''org.eclipse.equinox.frameworkadmin'''": API related with FrameworkAdmin and Configurator. In addition, utility classes used for implementing "org.eclipse.equinox.frameworkadmin.equinox", "org.eclipse.equinox.frameworkadmin.knopflerfish",  "org.eclipse.equinox.simpleconfigurator" and "org.eclipse.equinox.simpleconfigurator.manipulator
# "'''org.eclipse.core.fwhandler.equinox'''": Implementation of FwHandler for Equinox. See javadoc of BundleActivator of this plug-in.
+
# "'''org.eclipse.equinox.frameworkadmin.equinox'''": Implementation of FrameworkAdmin service for Equinox. See javadoc of BundleActivator of this plug-in.
#* It supports taking fw persistent data into consideration and supports resolving bundles.
+
#* It supports taking framework persistent data into consideration and supports resolving bundles, if running on the Equinox.
 
#* It supports taking a configurator bundle into consideration.
 
#* It supports taking a configurator bundle into consideration.
#* Limitation of current implementation: A bundle must be JAR.
+
#* Limitation of current implementation:
# "'''org.eclipse.core.fwhandler.felix'''": Implementation of FwHandler for Apache Felix. See javadoc of BundleActivator of this plug-in.
+
#** A bundle must be JAR.
#* No supports for taking fw persistent data into consideration nor supports resolving bundles.
+
#** FrameworkAdmin.getRunningManipulator() returns not null just if the vendor and bundle version of running system bundle equal the target. The launcher name and version is not checked.
 +
#*** For checking the launcher name and version, eclipse.exe needs to tell them to a fw launching.  
 +
# "'''org.eclipse.equinox.frameworkadmin.felix'''": Implementation of FrameworkAdmin service for Apache Felix. See javadoc of BundleActivator of this plug-in.
 +
#* Essentially, this bundle should be provided by the implementator of Felix. This implementation is tentative.
 +
#* No supports for taking framework persistent data into consideration nor supports resolving bundles.
 
#* It supports taking a configurator bundle into consideration.
 
#* It supports taking a configurator bundle into consideration.
#* This bundle should be provided by the implementator of Felix.
+
# "'''org.eclipse.equinox.frameworkadmin.knopflerfish'''": Implementation of FrameworkAdmin service for Knopflerfish. See javadoc of BundleActivator of this plug-in.
# "'''org.eclipse.core.fwhandler.kf'''": Implementation of FwHandler for Knopflerfish. See javadoc of BundleActivator of this plug-in.
+
#* Essentially, this bundle should be provided by the implementator of Knopflerfish. This implementation is tentative.
#* No supports for taking fw persistent data into consideration nor supports resolving bundles.
+
#* No supports for taking framework persistent data into consideration nor supports resolving bundles.
 
#* It supports taking a configurator bundle into consideration.
 
#* It supports taking a configurator bundle into consideration.
#* This bundle should be provided by the implementator of Knopflerfish.
+
# "'''org.eclipse.equinox.simpleconfigurator'''": Implementation of SimpleConfigurator.
# "'''org.eclipse.core.simpleConfigurator'''": Implementation of SimpleConfigurator.
+
# "'''org.eclipse.equinox.simpleconfigurator.manipulator'''": Implementation of ConfiguratorManipulator for SimpleConfigurator.
# "'''org.eclipse.core.simpleConfigurator.manipulator'''": Implementation of ConfiguratorManipulator for SimpleConfigurator.
+
# "'''org.eclipse.equinox.frameworkadmin.examples'''": An example of client bundle of the APIs related with FrameworkAdminr.
# "'''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 "org.eclipse.core.simpleConfigurator.manipulator".
+
# "'''org.eclipse.core.fwhandler.examples'''": An example of client bundle of the APIs related with FwHandler.
+
  
To understand how a provider is implemented the APIs, see bundle 1 and 2.
+
To understand how a provider implements the APIs, see bundle 1 and 2.
To understand how a client uses the APIs, see bundle 1 and 8.
+
To understand how a client uses the API, see bundle 1 and 8.
  
 
==References==
 
==References==

Revision as of 15:57, 24 January 2007

This document is under construction.

Contents

Motivation

Generally speaking, an OSGi framework needs some configuration files for its launch. A framework will be launched by invoking java command or by executing an executable launcher file. In the former case, configurations for framework implementation to read will be required. In the latter case, executable launcher file also might read some configuration files at its invocation.

  • As in Eclipse, org.eclipse.osgi plug-in that contains main class of equinox framework implementation reads config.ini in a configuration area. In addition, eclipse.exe, an executable launcher, reads eclipse.ini in the same directory of it and invokes a framework implementation.

Currently, the focus of OSGi Service Platform Specification has been to standardize a runtime infrastructure. On the other hand, how to configure and launch a framework is not addressed. Therefore, scenarios such as bootstrapping OSGi on a clean system are left difficult to manage in a framework independent way.

Overview: What does FrameworkAdmin service enable?

We would like to address this problem by proposing FrameworkAdmin service, which allows a bundle running on a framework to do the followings in a framework independent way.

  • Set configurations required to launch a framework, such as
    • Java VM location,
    • Java VM arguments,
    • executable launcher location, if used
    • beginning start level and initial bundle start level,
    • Bundles to be installed and started with their start levels,
    • framework configuration location,
    • framework persistent date location,
  • Launch a framework with the specified configurations.
  • Expect a bundles state if the specified configurations are used for a framework launch.

Terminologies used in here

Framework config files
configuration files that will be read by a framework implementation at its launching, e.g. config.ini in the directory specified by osgi.configuration.area system property as for equinox.
Executable launcher
an executable framework launcher file, e.g. eclipse.exe as for Eclipse.
Launcher config files
configuration files that will be read by an executable launcher, e.g. eclipse.ini as for eclipse.exe.
Bundles state
state of bundles that represents what kinds of bundles are installed, resolved and to be started on a framework.

Scenarios that the API would help

PDE UI
to ease the targeting of various frameworks
Provisioning agent
to setup a non running framework
Building an application
to create all the config files required to run
Running the framework
to configure and start a framework from java command

See [1] [2].

API: Package org.eclipse.equinox.frameworkadmin

Interfaces defined in org.eclipse.equinox.frameworkadmin package will be introduced briefly. See the codes and Java docs in detail.

FrameworkAdmin

The only interface whose implementation will be registered into the OSGi service registry in this package is FrameworkAdmin.

The client bundle will get the appropriate FrameworkAdmin service object that can meet its requirements by filtering service properties in the service registry. An example of filtering is the target framework implementation and its version. As for filtering, later section will explain it in detail. Then, the client will get new instance of Manipulator which plays a main role in this API.

The interface has a method which might return the Manipulator object initialized according to the running framework and launcher state. Detail of this would be introduced later.

In addition, it also has a method to launch a framework according to the specified Manipulator object.

Manipulator

A client bundle can get a Manipulator object by FrameworkAdmin.getManipulator(). This object keeps both a ConfigData object and a LauncherData object, each of which has setter and getter methods on parameters to be required for a framework launch. The client can set some parameters to be required for launching a framework via ConfigData object or LauncherData object. The parameters set in this object can be saved. Where to save is determined according to the parameters set at that time in a way dependent on a target framework and launcher implementation.

The client also can load parameters from framework config files and launcher config files in the specified locations.

After parameters are set to this object either by setting via a ConfigData or a LauncherData or loading from configuration files, FrameworkAdmin.launch(Manipulator, File) will launch a framework according to the current parameters set in this object. It might invoke a framework by java command or executing the specified launcher.

Remember if you have set parameters but not have saved yet, this launch might use other parameters because actual launch will use parameters retrieved from the configuration files.

In addition, Manipulator enables for a client bundle to expect bundles state if the specified configurations are used for launch without actual launch.

ConfigData

ConfigData is a class that keeps some parameters for a Manipulator object such as,

  • Bundles list to be installed, with their persistently marked flag as started or not and their start level for its configuration.
  • Beginning start level and initial bundle start level.
  • System properties dependent on a framework implementation.
  • System properties independent of a framework implementation.

For most framework implementations, these parameters will be saved into their framework config files. However, this API doesn't restrict where to save. For example, a framework implementation and a launcher implementation might need to save these parameters not in framework config files but in a launcher config files. It depends on the target implementations.

LauncherData

LauncherData is a class that keeps some parameters for a Manipulator object such as,

  • Location of Java VM.
  • Java VM arguments.
  • Location of framework config files.
  • Location of framework persistent data, where a framework implementation saves information to be kept persistently, such as bundles state, permissions of bundles, start level information, private persistent storages for bundles, and so on.
  • Clean flag: a flag to clean the specified location of framework persistent data.

For most framework implementations, these parameters will be saved into their launcher config files, if executable launcher is used. However, this API doesn't restrict where to save. As in Apache Felix, location of framework persistent data should be written in its framework config file. Therefore, the implementation of Manipulator for Felix should save it into not launcher config file but its framework config file.

BundlesState

The implementating object of BundlesState will be created by Manipulator object. At the time of its creation, this object will compose bundles state according to the parameters that the Manipulator object keeps. It means, bundles which can be obtained by Manipulator.getConfigData().getBundles() will be installed on a virtually launched framework using parameters about framework persistent data location. If the data location is not empty and clean flag is false, the installed bundles persistently recorded there should be taken into consideration to compose the bundles state.

After creating this object, this object also provides ways for a client to resolve bundles, install additional bundles, uninstall bundles virtually. Modification of this object never affects the parameters of the Manipulator object which created this object.

Provider of these APIs

First of all, we supposed that an implementation of this API for each framework implementation will be provided by the implementators of the target framework, because the persons who know the framework implementation the most are the implementators of the target framework.

For clients to filter the proper service object, the provider must register the FrameworkAdmin object with service properties keyed by the followings.

FrameworkAdmin.SERVICE_PROP_KEY_FW_NAME
String; name of the framework
FrameworkAdmin.SERVICE_PROP_KEY_FW_VERSION
String; version of the framework
FrameworkAdmin.SERVICE_PROP_KEY_LAUNCHER_NAME
String; name of the launcher
FrameworkAdmin.SERVICE_PROP_KEY_LAUNCHER_VERSION
String; version of the launcher
  • Current Limitation: there is no version range.Version Range might be required.
  • Offline, the implementator of FrameworkAdmin must declare these values and client must know them.

There is another service property name to be standardized.

FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG
true if its getRunningManipulator () returns the initialized Manipulator object of running system.
  • Detail of it would be introduced later.

Client of these APIs

A client bundle will get appropriate FrameworkAdmin service object from an OSGi service registry by filtering the service properties described previously in order to get the Manipulator objects to handle the desired framework and launcher implementation.

TBD

Which interface should a method of launch operation belong to?

Currently, a method of launch operation belongs to FrameworkAdmin interface. I can separate this API into another interface like "FrameworkLauncher". But I am not sure how much merit of it would be.

  • One merit of the separation is, we can restrict some bundles so that can configure a framework but cannot launch it, by not giving ServicePermission("GET","FrameworkLauncher").
  • One demerit of it is, number of interface will be increased by one, even if this interface only has one method.

Launching a framework instance in the Same Process

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

  • What is not sure is “general way of launching a framework instance in the same process”. The API might be able to support it (JavaVM and JavaVM arguments are not used for it obviously).


How to handle running framework information?

There is a need for manipulating configurations of not only a non-running framework but also a running framework. While there are several ways to realize it, currently we adopt the following way. The alternatives to realize it are shown Alternatives of Handling a Running Framework.

Current our proposal

The bundle that registers a FrameworkAdmin service for a particular framework and launcher implementation will do at its registration as follows;

  1. A bundle checks if the bundle can register a FrameworkAdmin object whose getManipulatorRunning() returns not null but a Manipulator object initialized according to the running framework and launcher implementation, somehow. The way how the bundle checks it is dependent of its target framework and launcher implementation.
  2. If no, the bundle registers a FrameworkAdmin service for a target framework and launcher implementation, whose getRunningManipulator() returns null, with specified service properties including the ones representing framework name/version and launcher name/version.
  3. If yes, the bundle registers a FrameworkAdmin service for a target framework and launcher implementation, whose getRunningManipulator() returns a Manipulator object initialized according to the running framework and launcher implementation. The registration is done with specified service properties including not only the ones representing framework name/version and launcher name/version, but also FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG="true".

Regarding when the bundle should register a FrameworkAdmin service is not addressed. However, the typical timing is at its start up.

A client bundle can get the initialized Manipulator object as follows;

String filter = “(FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG=true)”.
ServiceReference references[] = context.getServiceReferences(FrameworkAdmin.class.getName(), filter);
FrameworkAdmin FrameworkAdmin = (FrameworkAdmin) context.getService(references[0]);
Manipulator manipulator = FrameworkAdmin.getManipulatorRunning(); <-- initialized.

Configurator

Bundles provided by this incubator subproject

  1. "org.eclipse.equinox.frameworkadmin": API related with FrameworkAdmin and Configurator. In addition, utility classes used for implementing "org.eclipse.equinox.frameworkadmin.equinox", "org.eclipse.equinox.frameworkadmin.knopflerfish", "org.eclipse.equinox.simpleconfigurator" and "org.eclipse.equinox.simpleconfigurator.manipulator
  2. "org.eclipse.equinox.frameworkadmin.equinox": Implementation of FrameworkAdmin service for Equinox. See javadoc of BundleActivator of this plug-in.
    • It supports taking framework persistent data into consideration and supports resolving bundles, if running on the Equinox.
    • It supports taking a configurator bundle into consideration.
    • Limitation of current implementation:
      • A bundle must be JAR.
      • FrameworkAdmin.getRunningManipulator() returns not null just if the vendor and bundle version of running system bundle equal the target. The launcher name and version is not checked.
        • For checking the launcher name and version, eclipse.exe needs to tell them to a fw launching.
  3. "org.eclipse.equinox.frameworkadmin.felix": Implementation of FrameworkAdmin service for Apache Felix. See javadoc of BundleActivator of this plug-in.
    • Essentially, this bundle should be provided by the implementator of Felix. This implementation is tentative.
    • No supports for taking framework persistent data into consideration nor supports resolving bundles.
    • It supports taking a configurator bundle into consideration.
  4. "org.eclipse.equinox.frameworkadmin.knopflerfish": Implementation of FrameworkAdmin service for Knopflerfish. See javadoc of BundleActivator of this plug-in.
    • Essentially, this bundle should be provided by the implementator of Knopflerfish. This implementation is tentative.
    • No supports for taking framework persistent data into consideration nor supports resolving bundles.
    • It supports taking a configurator bundle into consideration.
  5. "org.eclipse.equinox.simpleconfigurator": Implementation of SimpleConfigurator.
  6. "org.eclipse.equinox.simpleconfigurator.manipulator": Implementation of ConfiguratorManipulator for SimpleConfigurator.
  7. "org.eclipse.equinox.frameworkadmin.examples": An example of client bundle of the APIs related with FrameworkAdminr.

To understand how a provider implements the APIs, see bundle 1 and 2. To understand how a client uses the API, see bundle 1 and 8.

References

  1. Requirements for a new update manager (of Eclipse)
  2. Requirements discussed in OSGi Alliance Enterprise Workshop
  3. Equinox: Runtime options of Eclipse 3.2
  4. Felix: Usage
  5. Knopflerfish: Usage