Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Equinox FrameworkAdmin"

m
 
m (→‎Bundles provided by this incubator subproject)
 
(38 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
==Overview:What FramerowkHandler enables?==
+
== Overview ==
−
Framework Handler provides unified way for a bundle running on a fw to do the followings
+
===Background ===
−
*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.
+
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. In other words, the ways how to configure a launch of OSGi framework and how to launch it depend on its implementation. Therefore, it is difficult to manage scenarios such as bootstrapping OSGi on a clean system in a framework independent way.
−
**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.
+
We would like to address this problem by proposing FrameworkAdmin service.
−
**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.
+
===What does FrameworkAdmin service enable?===
−
***Bundles state represents that what kinds of bundles are installed, and resolved on a fw instance.
+
FrameworkAdmin service allows a bundle running on a framework to do the followings in a framework independent way.
−
**Current limitation: startlevel is not supported for bundles that recorded persistently by fw. But it should be.  
+
*Set configurations required to launch a framework, such as
−
In addition, a fw might be launched by an executable launcher (e.g. eclipse.exe).  
+
** Java VM location,
−
*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.
+
** Java VM arguments,
−
*Launch a fw by executing the specified executable launcher in another process.
+
** executable launcher location, if used
−
**Expect bundles state if the specified executable launcher is executed.
+
** beginning start level and initial bundle start level of a framework,
−
In future, launching a fw instance in the same process will be supported.
+
** Bundles to be installed and started with their start levels,
 +
** framework configuration location,
 +
** framework persistent date location,
 +
*Launch a framework with the specified configurations.
 +
*get the expected state of a framework when it runs.
 +
 
 +
<font color="red">In addition, FrameworkAdmin API and its implementation can be used for not a bundle but a Java program, which is not OSGi based application, to do the same things in a framework independent way (since version 1.1.0).</font> See [[#Example 2]] and [[Using FrameworkAdmin from Java programs]] for more detail.
 +
 
 +
==Scenarios that the API would help==
 +
;PDE UI: to ease the targeting of various frameworks. Currently PDE UI depends on ad-hoc API.  
 +
;Provisioning agent: to setup a non running framework
 +
;Building an application: to create at build time all the config files required to run the exported application
 +
;Running the framework: to configure and start a framework from either a  java command or launcher
 +
See [[#references|[1]]] [[#references|[2]]].
  
 
==Terminologies used in here==
 
==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.
+
;Framework config files: configuration files that will be read by a framework implementation on startup, e.g. config.ini in the directory specified by osgi.configuration.area system property 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 framework launcher file, e.g. eclipse.exe for Eclipse.
−
;Executable launcher:an executable fw launcher file without any arguments, e.g. eclipse.exe as for Eclipse.
+
;Launcher config files: configuration files that will be read by an executable launcher, e.g. eclipse.ini for eclipse.exe.
−
;Launcher config file:configuration file 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.
−
==Needs for the common API to handle fw instances==
+
;Framework persistent data location: under this location (including recursive subdirectories), a framework keeps data that should be kept persistently.
−
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===
+
==How does it work ?==
−
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).
+
I’ll explain how it works using some examples.
 +
There are two types of usage: usage by a bundle on a running framework and usage by a Java program.
 +
===Example 1===
 +
A bundle will get a FrameworkAdmin object via service registry on running framework and use it.
 +
====Example 1-1====
 +
Let me assume that there is a bundle, which wants to configure a launch of a target framework implementation, e.g. Equinox, and launch it.
 +
#On the framework, there is a registered FrameworkAdmin service for Equinox.
 +
#*There might be several registered FrameworkAdmin services for different frameworks.
 +
#The client checks if a FrameworkAdmin service for its target framework implementation (Equinox) is available or not.
 +
#If it is available, the client gets the FrameworkAdmin service object from the service registry. Otherwise, the client cannot realize what it wants.
 +
#The client creates a new Manipulator object from the FrameworkAdmin object.
 +
#*This Manipulator object has no parameters set yet.
 +
#The client sets configurations to the Manipulator object
 +
##The client gets the references of ConfigData of the Manipulator object and sets parameters to it such as
 +
##* beginning start level and initial bundle start level of a framework,
 +
##* Bundles to be installed and started with their start levels,
 +
##The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as
 +
##* Java VM location,
 +
##* Java VM arguments,
 +
##* framework implementation location,
 +
##* framework configuration location,
 +
##* framework persistent date location.
 +
#The client saves the configuration according to the parameters set to the Manipulator object.
 +
#The client launches a framework using the saved configuration by FrameworkAdmin#launch() with the Manipulator object as an argument.
 +
====Example 1-2====
 +
Let me assume that there is a bundle, which wants to get configurations for a launch of Knopflerfish and launch another framework , Equinox,  with the same set of bundles installed.
 +
#On the framework, there are registered FrameworkAdmin services for both Equinox and Knopflerfish.
 +
#The client checks if FrameworkAdmin services for both its target framework implementations (Equinox and Knopflerfish) are available or not.
 +
#If available, the client gets both FrameworkAdmin service objects from the service registry. Otherwise, the client cannot realize what it wants.
 +
# Load configurations of a launch for Knopflerfish.
 +
##The client creates a new Manipulator object from the FrameworkAdmin object for Knopflerfish.
 +
##*This Manipulator object has no parameters set yet.
 +
##The client gets the references of LauncherData of the Manipulator object for Knopferfish and sets parameters to it such as.
 +
##* framework configuration location,
 +
##* framework persistent date location.
 +
##The client loads configurations according to the parameters set, such as the framework configuration location and the framework persistent data location.
 +
#Copy configurations information from the Manipulator object for Knoflerfish to the one for Equinox.
 +
##The client creates a new Manipulator object from the FrameworkAdmin object for Equinox.
 +
##The client copies parameters of the Manipulator object for Knopflerfish to the ones of the Manipulator object for Equinox.
 +
##The client gets the references of LauncherData of the Manipulator object for Equinox and resets some parameters to it such as
 +
##* framework implementation location,
 +
##* framework configuration location,
 +
##* framework persistent date location.
 +
#The client saves the configuration according to the parameters set to the Manipulator object for Equinox.
 +
#The client launches a framework Equinox using the saved configuration by launch() method of the FrameworkAdmin object for Equinox with the Manipulator object for Equinox as an argument .
 +
====Example 1-3====
 +
Let me assume that there is a bundle, which wants to get configurations for a launch of Felix and expect bundles state if that configurations are used for a launch.
 +
#On the framework, there are registered FrameworkAdmin services for Felix.
 +
#The client checks if a FrameworkAdmin service for the target framework implementation (Felix) is available or not.
 +
#If available, the client gets a FrameworkAdmin service object from the service registry. Otherwise, the client cannot realize what it wants.
 +
#Expect bundles state if the specified locations are used for a launch.
 +
##The client creates a new Manipulator object from the FrameworkAdmin object for Felix.
 +
##*This Manipulator object has no parameters set yet.
 +
##The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as.
 +
##* framework implementation location,
 +
##* framework configuration location,
 +
##* framework persistent date location.
 +
##The client loads configurations according to the parameters set, such as the framework configuration location and the framework persistent data location.
 +
##The client creates a BundlesState object from the Manipulator object. At its creation, the BundlesState object contains bundles which the Manipulator object has at that time.
 +
##The client expects the bundles state by calling BundlesState#getExpectedState(), which tries to resolve bundles set and returns value representing which bundles are resolved and which are not.
 +
##If the client wants to modify installed bundles for some reason, for example in order to make all bundles resolved, the following procedures would be done.
 +
###The following two steps will be done repeatedly until the client satisfies with the expected state.
 +
####The client adds or removes bundles to be installed and started with their start levels to the BundlesState.
 +
####The client expects the bundles state by calling calling BundlesState#getExpectedState(), 
 +
###If the client satisfies with the expected state and wants to reflect the modification to the BundlesState object to the configuration, do the followings:
 +
####The client gets the references of ConfigData of the Manipulator object.
 +
####set bundles the BundleState keeps to the ConfigData.
 +
####The client saves the configuration according to the parameters set to the Manipulator object.
 +
===Example 2===
 +
A Java program will get a FrameworkAdmin object via static factory method defined newly in version 1.1.0 and use it.
 +
# Required class should be accessible by classloaders in advance.
 +
#* the FrameworkAdmin implementation classes support this feature for a target framework implementation.
 +
#* and prerequisite classes for those classes.
 +
# A Java program will get a FrameworkAdmin object by FrameworkAdminFactory.getInstance(name) with ''magic name of the FrameworkAdminFactory implementation class'', which is declared by the implementator in advance.
 +
#* <font color="red">The following steps are just same as [[#Example 1-1]]</font>.
 +
#The client creates a new Manipulator object from the FrameworkAdmin object.
 +
#*This Manipulator object has no parameters set yet.
 +
#The client sets configurations to the Manipulator object
 +
##The client gets the references of ConfigData of the Manipulator object and sets parameters to it such as
 +
##* beginning start level and initial bundle start level of a framework,
 +
##* Bundles to be installed and started with their start levels,
 +
##The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as
 +
##* Java VM location,
 +
##* Java VM arguments,
 +
##* framework implementation location,
 +
##* framework configuration location,
 +
##* framework persistent date location.
 +
#The client saves the configuration according to the parameters set to the Manipulator object.
 +
#The client launches a framework using the saved configuration by FrameworkAdmin#launch() with the Manipulator object as an argument.
 +
See [[Using FrameworkAdmin from Java programs]] for more detail.
  
−
===FwLauncher===
+
==API: Package org.eclipse.equinox.frameworkadmin==
−
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).
+
Interfaces defined in ''org.eclipse.equinox.frameworkadmin'' package will be introduced. See the codes and Java docs for more details.  
  
−
===ExecutableFwLauncher===
+
===FrameworkAdmin===
−
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).
+
The only interface whose implementation will be registered into the OSGi service registry in this package is FrameworkAdmin.
−
*[[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===
+
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.
−
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===
+
The interface has a method which might return the Manipulator object initialized according to the running framework and launcher state. Detail of this will be introduced [[#Current our proposal|later]].  
−
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
+
In addition, it also has a method to launch a framework according to the specified Manipulator object.
−
*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.
+
===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 have 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 those objects can be saved into configuration files. Where to save is determined according to the parameters set at that time in a framework and launcher independent way.
  
−
===Client of these APIs===
+
The client also can load parameters from framework config files and launcher config files in the specified locations. In addition, the persistently stored data in the framework persistent location specified should be taken into consideration.
−
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===
+
Once parameters are set to this object by either 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. How it will be launched will be up to the FrameworkAdmin implementation and parameters set at that time.
−
At this point, launching a fw instance in the same process is not considered yet in this APIs, explicitly. However, it will be supported.
+
*For example, if the implementation supports launching by an executable launcher and a laucher is set to the Manipulator object, FrameworkAdmin#launch(Manipulator, File) will invoke a framework by executing the launcher.
−
*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==
+
Remember the parameters set to this object should be saved before a launch.
−
# "org.eclipse.core.fwhandler": APIs related with FwHandler and Configurator which will be used by clients.
+
−
# "org.eclipse.core.fwhandler.equinox": APIs specific to Equinox which will be used by clients and its implementation.
+
−
# "org.eclipse.core.fwhandler.kf": APIs specific to Knopflerfish which will be used by clients and its implementation.
+
−
# "org.eclipse.core.simpleConfigurator": Implementation of SimpleConfigurator.
+
−
# "org.eclipse.core.simpleConfigurator.manipulator": Implementation of ConfiguratorManipulatorAdmin and ConfiguratorManipulator for a SimpleConfigurator.
+
−
# "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 FwHandlerAdmin and Configurator.
+
  
−
To understand how a provider is implemented the APIs, see bundle 1 and 2.
+
In addition, Manipulator enables for a client bundle to get the BundlesState object, which will be used for expecting bundles state.
−
To understand how a client uses the APIs, see bundle 1 and 7.
+
  
−
===Implementation of FwHandler for Equinox===  
+
===ConfigData===
−
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.
+
ConfigData is a class that keeps some parameters mainly related with framework internal behavior for a Manipulator object such as,
−
This bundle registers a FwHandlerAdmin object into an OSGi service registry at its starting with the following service properties:
+
*Bundles list to be installed, with their persistently marked flag as started or not and their start levels.  
−
;FwHandlerAdmin.PROP_FWNAME: “Equinox”
+
*Beginning start level and initial bundle start level of a framework.
−
;FwHandlerAdmin.PROP_FWVERSION: “3.2”
+
*System properties dependent on a framework implementation.
−
;FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE: “org.eclipse.core.fwhandler.equinox.EquinoxConfiguratorFwConfigHandler”;
+
*System properties independent of a framework implementation.
−
**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.
+
For most framework implementations, these parameters will be saved into their framework config files. However, this API doesn't restrict where to save.  
−
*PlatformAdmin service (in org.eclipse.osgi.service.resolver packages) registered by org.eclipse.osgi plugin is used to do it in this implementation.
+
* 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.
  
−
===Implementation of FwHandler for Felix===
+
===LauncherData===
−
TODO: implementation of it.
+
LauncherData is a class that keeps some parameters mainly related with information required before launching framework instance for a Manipulator object such as,
−
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.
+
*Location of Java VM.  
−
===Implementation of FwHandler for Knopflerfish===
+
*Java VM arguments.
−
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.
+
*Location of launcher (if launcher is used)
−
This bundle registers a FwHandlerAdmin object into an OSGi service registry at its starting with the following service properties:
+
*Launcher specific arguments (if launcher is used)
−
;FwHandlerAdmin.PROP_FWNAME: “knopflerfish”
+
*Location of framework implementation.
−
;FwHandlerAdmin.PROP_FWVERSION: “2.0”
+
*Location of framework config files.
−
;FwHandlerAdmin.SERVICE_PROP_KEY_FWCONFIGHANDLER_TYPE: “org.eclipse.core.fwhandler.kf.KfConfiguratorFwConfigHandler”;
+
*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.  
−
**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.
+
*Clean flag: a flag to clean the specified location of framework persistent data.
−
;FwHandlerAdmin.SERVICE_PROP_KEY_FWLAUCNHER_TYPE: "org.eclipse.core.fwhandler.kf.kflauncher";
+
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.
−
**FwHandlerAdmin#getFwLaucher() returns a object which implements  FwLauncher interface.
+
* 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 in launcher config files but framework config files.
−
;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.  
+
===BundlesState===
 +
BundlesState object is used to predict the bundles state of a framework.
 +
 +
A BundlesState object will be created by a Manipulator object. At its creation, bundles state according to the parameters that the Manipulator object keeps will be created in this object.
  
−
===Example of client bundle of these APIs===
+
This object reads the manifest information of bundles and tries to resolve bundles as a running framework would do.  
−
Bundle of "org.eclipse.core.fwhandler.examples" is a client that shows several example of usage of API. For example,
+
  
−
# For Equinox, without SimpleConfigurator
+
=== FrameworkAdminFactory===
−
## Set information about fw launch and save them into the specified fw config file.
+
This is an abstract class. The client of the subclass of it is supposed to be not a bundle but a Java program. Using it, developers can launch a framework from Java program. The details will be introduced in [[Using FrameworkAdmin from Java programs]].  
−
## Then, launch a fw instance not by no executable launcher with the specified fw config file.  
+
  
−
# For Equinox, with SimpleConfigurator
+
==Provider of FrameworkAdmin==
−
## Set information about fw launch and save them into the specified fw config file.
+
First of all, we supposed that an implementation of this API will be provided for each framework implementation.
−
## Then, launch a fw instance by no executable launcher with the specified fw config file.  
+
We expect it will be implemented by the team developing the framework, since it requires knowledge of the framework internals.
  
−
# For Knopflerfish, without SimpleConfigurator
+
For clients to filter the proper service object, the provider must register the FrameworkAdmin object with service properties keyed by the followings.
−
## Set information about fw launch and save them into the specified fw config file.
+
−
## Then, launch a fw instance by no executable launcher with the specified fw config file.  
+
  
−
# For Knopflerfish, with SimpleConfigurator
+
;FrameworkAdmin.SERVICE_PROP_KEY_FW_NAME: String; name of the framework
−
## Set information about fw launch and save them into the specified fw config file.
+
;FrameworkAdmin.SERVICE_PROP_KEY_FW_VERSION: String; version of the framework
−
## Then, launch a fw instance by no executable launcher with the specified fw config file.  
+
;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.
  
−
# Without SimpleConfigurator,
+
There is another service property name to be standardized.
−
##  Set information about fw launch and save them into the specified fw config file for Knopflerfish.
+
;FrameworkAdmin.SERVICE_PROP_KEY_RUNNING_SYSTEM_FLAG: true if its getRunningManipulator () returns the initialized Manipulator object of running system.
−
## Then, retrieve the configuration information by reading the fw config file saved for Knopflerfish.
+
*Detail of it would be introduced [[#Current proposal | later]].  
−
## Convert the information into the one for Equinox and save it into the other fw config file for Equinox
+
−
## Launch a fw instance by no executable launcher with the specified fw config file for Equinox.
+
  
−
# For Equinox, without SimpleConfigurator
+
==Client of FrameworkAdmin==
−
## Set information about fw launch and save them into the specified fw config file.
+
A client bundle can get appropriate FrameworkAdmin service object from an OSGi service registry by filtering the service properties described previously in order to get the Manipulator objects for the framework and launcher implementation which the client want to manipulate.
−
## 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).
+
==How to handle running framework information?==
−
## Launch a fw instance by executing the executable launcher (eclipse.ini).  
+
There is a need for manipulating configurations of not only a non-running framework but also a running framework. Two kinds of manipulator objects of the running framework come up to our mind:
 +
# a manipulator representing as the same state of the running framework at that time.
 +
# a manipulator representing the state of a framework launched by using the framework configuration location and framework persistent data location, which is used for the running framework.
  
−
# For Equinox, with SimpleConfigurator
+
The current FrameworkAdmin (tagged as v20070212-1630) only supports for the first one.
−
## Set information about fw launch and save them into the specified fw config file.
+
−
## Then, expect virtually bundles state as if a fw instance is launched by no executable launcher with the specified fw config file.  
+
  
−
==FAQ==
+
===Current proposal to realize it===
−
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)?
+
The bundle will do as follows when it registers a FrameworkAdmin service for any framework and launcher;
−
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.
+
  
 +
# The bundle checks if the running framework can be managed by a FrameworkAdmin object that itself will register. The way how the bundle checks it is dependent of its framework and launcher implementation.
 +
# If no, the bundle registers a FrameworkAdmin service for the 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 FrameworkAdmin service for the framework and launcher implementation, whose getRunningManipulator() returns a Manipulator object initialized according to the running system. 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".
 +
 +
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;
 +
<pre>
 +
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.
 +
</pre>
 +
===Scenario===
 +
One of the scenarios is
 +
# A client gets a manipulator object representing the running framework ''A''.
 +
# After the client overwrites framework configuration location and framework persistent data location of it, it saves it and launch it (framework ''B'').
 +
# As a result, the bundles running on framework ''A'' at that time will be running on framework ''B''.
 +
 +
==[[Configurator]]==
 +
==[[Using FrameworkAdmin from Java programs]]==
 +
 +
==Bundles provided by this incubator subproject==
 +
# "'''org.eclipse.equinox.frameworkadmin'''": API related with FrameworkAdmin and ConfiguratorManipulator. In addition, utility classes used for implementing "org.eclipse.equinox.frameworkadmin.equinox", "org.eclipse.equinox.frameworkadmin.knopflerfish",  "org.eclipse.equinox.frameworkadmin.felix" is stored.
 +
#* <font color="red">Since v1.3.0, Configurator interface and utility classes used for  "org.eclipse.equinox.simpleconfigurator" and "org.eclipse.equinox.simpleconfigurator.manipulator"  plugins were eliminated from this plugin (moved into "org.eclipse.equinox.simpleconfigurator" plugin) according to the request of [https://bugs.eclipse.org/bugs/show_bug.cgi?id=175809 bug#175809]. </font>
 +
# "'''org.eclipse.equinox.frameworkadmin.equinox'''": Implementation of FrameworkAdmin service for Equinox. See javadoc of BundleActivator of this plug-in for more detail.
 +
#* 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.
 +
#* Both bundle format in a JAR and a Directory are supported since v.1.5.0.
 +
#* bundle location starting with "'''reference:'''"  is supported since v.1.5.0.
 +
#** If BundleContext.getProperty(''EquinoxConstants.PROP_KEY_USE_REFERENCE'') does not equal "false", Manipulator#save(..) will add "reference:" to any bundle location specified osgi.bundles in order to avoid caching its bundle jar. Otherwise, it will add nothing to any bundle location.
 +
#* Manipulator#getTimeStamp() is supported since v.1.5.0.
 +
#* Even if LauncherData.getFwJar() == null, it will be automatically set in some operation,such as Manipulator#save(..) if framework jar (org.eclipse.osgi._*.jar) is included in ConfigData.getBundles().
 +
#* ''Limitation of current implementation'':
 +
#** To read framework persistently stored data, State objects created by PlatformaAdmin are used. That means this bundle has dependeny on them.
 +
#** Bundles whose location is set to "update@****" are not supported.
 +
#** FrameworkAdmin.getRunningManipulator() returns not null but a Manipulator object according to the vendor name and the bundle version of running system bundle. The launcher name and version are not checked.
 +
#*** For checking the launcher name and version (in future), eclipse.exe will need to tell them to a fw launching.
 +
#** Initial bundle start level cannot be set. A value set by ConfigData.setInitialBundleStartLevel(int) will be set to only bunldes installed by config.ini and EclipseUpdater(updateconfigurator). It's due to the current Equinox implementation. 
 +
#** It supports launching a framework from Java programs,
 +
#*** except a function of expecting bundles state because its implementation gets PlatformAdmin object from a service registry on a running framework and use it to resolve bundles (<font color="red">Since version 1.1.0</font>).
 +
# "'''org.eclipse.equinox.frameworkadmin.felix'''": Implementation of FrameworkAdmin service for Apache Felix. See javadoc of BundleActivator of this plug-in for more detail.
 +
#* 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.
 +
#* Launching a framework from Java programs is supported.
 +
#* No supports for Manipulator#getTimeStamp().
 +
# "'''org.eclipse.equinox.frameworkadmin.knopflerfish'''": Implementation of FrameworkAdmin service for Knopflerfish. See javadoc of BundleActivator of this plug-in for more detail.
 +
#* 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.
 +
#* Launching a framework from Java programs is supported.
 +
#* No supports for Manipulator#getTimeStamp().
 +
# "'''org.eclipse.equinox.simpleconfigurator'''": Implementation of SimpleConfigurator.
 +
#* Framework property keyed by ''SimpleConfiguratorConstants.PROP_KEY_CONFIGURL'' is used for SimpleConfigurator to do life cycle control of bundles. The file specified by the returned url is read by SimpleConfigurator and do life cycle control according to it. If improper value or null is returned, SimpleConfigurator doesn't do it.
 +
#* Framework property keyed by ''SimpleConfiguratorConstants.PROP_KEY_EXCLUSIVE_INSTALLATION'' equals "true" ignoring case, Configurator.applyConfiguration(url) will uninstall the installed bundles which are not listed in the simpleconfigurator config file after install bundles listed. Otherwise, it never uninstall any bundles.
 +
#* If this bundle is running on Equinox, Framework property keyed by ''SimpleConfiguratorConstants.PROP_KEY_USE_REFERENCE does not equal "false" ignoring case, when a SimpleConfigurator installs a bundle, "reference:" is added to its bundle location in order to avoid caching its bundle jar.  Otherwise, it will add nothing to any bundle location.
 +
#** Default: true
 +
#*** <font color="red"> This function is enabled only in case of running on Equinox because there is no standardized way to install a bundle without caching and other frameworks don't support it yet.</font>
 +
# "'''org.eclipse.equinox.simpleconfigurator.manipulator'''": Implementation of ConfiguratorManipulator for SimpleConfigurator.
 +
# "'''org.eclipse.equinox.frameworkadmin.examples'''": examples using FrameworkAdmin.
 +
#* In order to run these tests, <span style="color:red">read '''setting.properties''' in '''org.eclipse.equinox.frameworkadmin.examples''' package of this plug-in.
 +
#* This properties file should be set properly in advance.</span>
 +
#* <span style="color:red"> Example of a Java program using FrameworkAdmin is added (Since version 1.1.0)</span>
 +
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 7.
 +
 +
==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.
 +
===Version range===
 +
Currently, specifying version ranges of framework and launcher that the implementation can support are not supported at the registration of a FrameworkAdmin implementation. It might be required in future.
 +
===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).
 +
===File or URL or Location newly defined?===
 +
Currently, LauncherData keeps most information related with file location, such as location of framework jar implementation, framework configuration, framework persistent data, and so on, as a File object. Due to this design, these must exist on the local machine. It might be better URL or newly defined Location instead of File.
 +
===Explicit specifying a framework jar===
 +
Currently, a client bundle needs to call LauncherData.setFwJar(File) in advance to doing some operation. Another design can be thought:
 +
*Instead of having no LauncherData.setFwJar(File) method, client should call ConfigData.addBundle(BundleInfo of framework jar) as one of bundles set to ConfigData. The implementation will identify a framework jar among them.
 +
The problems of this approach would be:
 +
* Current OSGi specification doen's standardize how to identify if a jar is framework or not.
 +
** Identifying a bundle whose manifest has export-package header of "org.osgi.framework" as a framework jar might be used, although it is not a standardized way.
 +
* If the number of bundles which are identified as framework jar is more than one, how to determine the one to be activated ?
 +
** Maybe, the firstly added one among those framework jars each of which startlevel is 0 would be chosen.
 +
* Currently, FrameworkAdmin implementation of Equinox (since v.1.4.0) support some operation without setting fwJar explicitly by the way described above. To indentify an equinox(osgi) framework, Eclipse based bundle naming format (symbolicname_version.jar) assumption is used.
  
 
==References==
 
==References==
 +
# [http://wiki.eclipse.org/index.php/Requirements_for_a_new_update_manager Requirements for a new update manager (of Eclipse)]
 +
# [http://www2.osgi.org/EnterpriseWorkshop/Requirements Requirements discussed in OSGi Alliance Enterprise Workshop]
 
# [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html Equinox: Runtime options of Eclipse 3.2]
 
# [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html Equinox: Runtime options of Eclipse 3.2]
 
# [http://cwiki.apache.org/FELIX/felix-usage.html Felix: Usage]
 
# [http://cwiki.apache.org/FELIX/felix-usage.html Felix: Usage]
−
# [http://www.knopflerfish.org/running.html Knopflerfish: Usage]  
+
# [http://www.knopflerfish.org/running.html Knopflerfish: Usage]
−
# [http://wiki.eclipse.org/index.php/Requirements_for_a_new_update_manager Requirements for a new update manager (of Eclipse)]
+
 
 +
[[Category:Equinox|Framework Admin]]

Latest revision as of 00:52, 13 March 2007

Overview

Background

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. In other words, the ways how to configure a launch of OSGi framework and how to launch it depend on its implementation. Therefore, it is difficult to manage scenarios such as bootstrapping OSGi on a clean system in a framework independent way.

We would like to address this problem by proposing FrameworkAdmin service.

What does FrameworkAdmin service enable?

FrameworkAdmin service 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 of a framework,
    • Bundles to be installed and started with their start levels,
    • framework configuration location,
    • framework persistent date location,
  • Launch a framework with the specified configurations.
  • get the expected state of a framework when it runs.

In addition, FrameworkAdmin API and its implementation can be used for not a bundle but a Java program, which is not OSGi based application, to do the same things in a framework independent way (since version 1.1.0). See #Example 2 and Using FrameworkAdmin from Java programs for more detail.

Scenarios that the API would help

PDE UI
to ease the targeting of various frameworks. Currently PDE UI depends on ad-hoc API.
Provisioning agent
to setup a non running framework
Building an application
to create at build time all the config files required to run the exported application
Running the framework
to configure and start a framework from either a java command or launcher

See [1] [2].

Terminologies used in here

Framework config files
configuration files that will be read by a framework implementation on startup, e.g. config.ini in the directory specified by osgi.configuration.area system property for equinox.
Executable launcher
an executable framework launcher file, e.g. eclipse.exe for Eclipse.
Launcher config files
configuration files that will be read by an executable launcher, e.g. eclipse.ini for eclipse.exe.
Bundles state
state of bundles that represents what kinds of bundles are installed, resolved and to be started on a framework.
Framework persistent data location
under this location (including recursive subdirectories), a framework keeps data that should be kept persistently.

How does it work ?

I’ll explain how it works using some examples. There are two types of usage: usage by a bundle on a running framework and usage by a Java program.

Example 1

A bundle will get a FrameworkAdmin object via service registry on running framework and use it.

Example 1-1

Let me assume that there is a bundle, which wants to configure a launch of a target framework implementation, e.g. Equinox, and launch it.

  1. On the framework, there is a registered FrameworkAdmin service for Equinox.
    • There might be several registered FrameworkAdmin services for different frameworks.
  2. The client checks if a FrameworkAdmin service for its target framework implementation (Equinox) is available or not.
  3. If it is available, the client gets the FrameworkAdmin service object from the service registry. Otherwise, the client cannot realize what it wants.
  4. The client creates a new Manipulator object from the FrameworkAdmin object.
    • This Manipulator object has no parameters set yet.
  5. The client sets configurations to the Manipulator object
    1. The client gets the references of ConfigData of the Manipulator object and sets parameters to it such as
      • beginning start level and initial bundle start level of a framework,
      • Bundles to be installed and started with their start levels,
    2. The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as
      • Java VM location,
      • Java VM arguments,
      • framework implementation location,
      • framework configuration location,
      • framework persistent date location.
  6. The client saves the configuration according to the parameters set to the Manipulator object.
  7. The client launches a framework using the saved configuration by FrameworkAdmin#launch() with the Manipulator object as an argument.

Example 1-2

Let me assume that there is a bundle, which wants to get configurations for a launch of Knopflerfish and launch another framework , Equinox, with the same set of bundles installed.

  1. On the framework, there are registered FrameworkAdmin services for both Equinox and Knopflerfish.
  2. The client checks if FrameworkAdmin services for both its target framework implementations (Equinox and Knopflerfish) are available or not.
  3. If available, the client gets both FrameworkAdmin service objects from the service registry. Otherwise, the client cannot realize what it wants.
  4. Load configurations of a launch for Knopflerfish.
    1. The client creates a new Manipulator object from the FrameworkAdmin object for Knopflerfish.
      • This Manipulator object has no parameters set yet.
    2. The client gets the references of LauncherData of the Manipulator object for Knopferfish and sets parameters to it such as.
      • framework configuration location,
      • framework persistent date location.
    3. The client loads configurations according to the parameters set, such as the framework configuration location and the framework persistent data location.
  5. Copy configurations information from the Manipulator object for Knoflerfish to the one for Equinox.
    1. The client creates a new Manipulator object from the FrameworkAdmin object for Equinox.
    2. The client copies parameters of the Manipulator object for Knopflerfish to the ones of the Manipulator object for Equinox.
    3. The client gets the references of LauncherData of the Manipulator object for Equinox and resets some parameters to it such as
      • framework implementation location,
      • framework configuration location,
      • framework persistent date location.
  6. The client saves the configuration according to the parameters set to the Manipulator object for Equinox.
  7. The client launches a framework Equinox using the saved configuration by launch() method of the FrameworkAdmin object for Equinox with the Manipulator object for Equinox as an argument .

Example 1-3

Let me assume that there is a bundle, which wants to get configurations for a launch of Felix and expect bundles state if that configurations are used for a launch.

  1. On the framework, there are registered FrameworkAdmin services for Felix.
  2. The client checks if a FrameworkAdmin service for the target framework implementation (Felix) is available or not.
  3. If available, the client gets a FrameworkAdmin service object from the service registry. Otherwise, the client cannot realize what it wants.
  4. Expect bundles state if the specified locations are used for a launch.
    1. The client creates a new Manipulator object from the FrameworkAdmin object for Felix.
      • This Manipulator object has no parameters set yet.
    2. The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as.
      • framework implementation location,
      • framework configuration location,
      • framework persistent date location.
    3. The client loads configurations according to the parameters set, such as the framework configuration location and the framework persistent data location.
    4. The client creates a BundlesState object from the Manipulator object. At its creation, the BundlesState object contains bundles which the Manipulator object has at that time.
    5. The client expects the bundles state by calling BundlesState#getExpectedState(), which tries to resolve bundles set and returns value representing which bundles are resolved and which are not.
    6. If the client wants to modify installed bundles for some reason, for example in order to make all bundles resolved, the following procedures would be done.
      1. The following two steps will be done repeatedly until the client satisfies with the expected state.
        1. The client adds or removes bundles to be installed and started with their start levels to the BundlesState.
        2. The client expects the bundles state by calling calling BundlesState#getExpectedState(),
      2. If the client satisfies with the expected state and wants to reflect the modification to the BundlesState object to the configuration, do the followings:
        1. The client gets the references of ConfigData of the Manipulator object.
        2. set bundles the BundleState keeps to the ConfigData.
        3. The client saves the configuration according to the parameters set to the Manipulator object.

Example 2

A Java program will get a FrameworkAdmin object via static factory method defined newly in version 1.1.0 and use it.

  1. Required class should be accessible by classloaders in advance.
    • the FrameworkAdmin implementation classes support this feature for a target framework implementation.
    • and prerequisite classes for those classes.
  2. A Java program will get a FrameworkAdmin object by FrameworkAdminFactory.getInstance(name) with magic name of the FrameworkAdminFactory implementation class, which is declared by the implementator in advance.
  3. The client creates a new Manipulator object from the FrameworkAdmin object.
    • This Manipulator object has no parameters set yet.
  4. The client sets configurations to the Manipulator object
    1. The client gets the references of ConfigData of the Manipulator object and sets parameters to it such as
      • beginning start level and initial bundle start level of a framework,
      • Bundles to be installed and started with their start levels,
    2. The client gets the references of LauncherData of the Manipulator object and sets parameters to it such as
      • Java VM location,
      • Java VM arguments,
      • framework implementation location,
      • framework configuration location,
      • framework persistent date location.
  5. The client saves the configuration according to the parameters set to the Manipulator object.
  6. The client launches a framework using the saved configuration by FrameworkAdmin#launch() with the Manipulator object as an argument.

See Using FrameworkAdmin from Java programs for more detail.

API: Package org.eclipse.equinox.frameworkadmin

Interfaces defined in org.eclipse.equinox.frameworkadmin package will be introduced. See the codes and Java docs for more details.

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 will 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 have 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 those objects can be saved into configuration files. Where to save is determined according to the parameters set at that time in a framework and launcher independent way.

The client also can load parameters from framework config files and launcher config files in the specified locations. In addition, the persistently stored data in the framework persistent location specified should be taken into consideration.

Once parameters are set to this object by either 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. How it will be launched will be up to the FrameworkAdmin implementation and parameters set at that time.

  • For example, if the implementation supports launching by an executable launcher and a laucher is set to the Manipulator object, FrameworkAdmin#launch(Manipulator, File) will invoke a framework by executing the launcher.

Remember the parameters set to this object should be saved before a launch.

In addition, Manipulator enables for a client bundle to get the BundlesState object, which will be used for expecting bundles state.

ConfigData

ConfigData is a class that keeps some parameters mainly related with framework internal behavior for a Manipulator object such as,

  • Bundles list to be installed, with their persistently marked flag as started or not and their start levels.
  • Beginning start level and initial bundle start level of a framework.
  • 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 mainly related with information required before launching framework instance for a Manipulator object such as,

  • Location of Java VM.
  • Java VM arguments.
  • Location of launcher (if launcher is used)
  • Launcher specific arguments (if launcher is used)
  • Location of framework implementation.
  • 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 in launcher config files but framework config files.

BundlesState

BundlesState object is used to predict the bundles state of a framework.

A BundlesState object will be created by a Manipulator object. At its creation, bundles state according to the parameters that the Manipulator object keeps will be created in this object.

This object reads the manifest information of bundles and tries to resolve bundles as a running framework would do.

FrameworkAdminFactory

This is an abstract class. The client of the subclass of it is supposed to be not a bundle but a Java program. Using it, developers can launch a framework from Java program. The details will be introduced in Using FrameworkAdmin from Java programs.

Provider of FrameworkAdmin

First of all, we supposed that an implementation of this API will be provided for each framework implementation. We expect it will be implemented by the team developing the framework, since it requires knowledge of the framework internals.

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 FrameworkAdmin

A client bundle can get appropriate FrameworkAdmin service object from an OSGi service registry by filtering the service properties described previously in order to get the Manipulator objects for the framework and launcher implementation which the client want to manipulate.

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. Two kinds of manipulator objects of the running framework come up to our mind:

  1. a manipulator representing as the same state of the running framework at that time.
  2. a manipulator representing the state of a framework launched by using the framework configuration location and framework persistent data location, which is used for the running framework.

The current FrameworkAdmin (tagged as v20070212-1630) only supports for the first one.

Current proposal to realize it

The bundle will do as follows when it registers a FrameworkAdmin service for any framework and launcher;

  1. The bundle checks if the running framework can be managed by a FrameworkAdmin object that itself will register. The way how the bundle checks it is dependent of its framework and launcher implementation.
  2. If no, the bundle registers a FrameworkAdmin service for the 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 the framework and launcher implementation, whose getRunningManipulator() returns a Manipulator object initialized according to the running system. 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".

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.

Scenario

One of the scenarios is

  1. A client gets a manipulator object representing the running framework A.
  2. After the client overwrites framework configuration location and framework persistent data location of it, it saves it and launch it (framework B).
  3. As a result, the bundles running on framework A at that time will be running on framework B.

Configurator

Using FrameworkAdmin from Java programs

Bundles provided by this incubator subproject

  1. "org.eclipse.equinox.frameworkadmin": API related with FrameworkAdmin and ConfiguratorManipulator. In addition, utility classes used for implementing "org.eclipse.equinox.frameworkadmin.equinox", "org.eclipse.equinox.frameworkadmin.knopflerfish", "org.eclipse.equinox.frameworkadmin.felix" is stored.
    • Since v1.3.0, Configurator interface and utility classes used for "org.eclipse.equinox.simpleconfigurator" and "org.eclipse.equinox.simpleconfigurator.manipulator" plugins were eliminated from this plugin (moved into "org.eclipse.equinox.simpleconfigurator" plugin) according to the request of bug#175809.
  2. "org.eclipse.equinox.frameworkadmin.equinox": Implementation of FrameworkAdmin service for Equinox. See javadoc of BundleActivator of this plug-in for more detail.
    • 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.
    • Both bundle format in a JAR and a Directory are supported since v.1.5.0.
    • bundle location starting with "reference:" is supported since v.1.5.0.
      • If BundleContext.getProperty(EquinoxConstants.PROP_KEY_USE_REFERENCE) does not equal "false", Manipulator#save(..) will add "reference:" to any bundle location specified osgi.bundles in order to avoid caching its bundle jar. Otherwise, it will add nothing to any bundle location.
    • Manipulator#getTimeStamp() is supported since v.1.5.0.
    • Even if LauncherData.getFwJar() == null, it will be automatically set in some operation,such as Manipulator#save(..) if framework jar (org.eclipse.osgi._*.jar) is included in ConfigData.getBundles().
    • Limitation of current implementation:
      • To read framework persistently stored data, State objects created by PlatformaAdmin are used. That means this bundle has dependeny on them.
      • Bundles whose location is set to "update@****" are not supported.
      • FrameworkAdmin.getRunningManipulator() returns not null but a Manipulator object according to the vendor name and the bundle version of running system bundle. The launcher name and version are not checked.
        • For checking the launcher name and version (in future), eclipse.exe will need to tell them to a fw launching.
      • Initial bundle start level cannot be set. A value set by ConfigData.setInitialBundleStartLevel(int) will be set to only bunldes installed by config.ini and EclipseUpdater(updateconfigurator). It's due to the current Equinox implementation.
      • It supports launching a framework from Java programs,
        • except a function of expecting bundles state because its implementation gets PlatformAdmin object from a service registry on a running framework and use it to resolve bundles (Since version 1.1.0).
  3. "org.eclipse.equinox.frameworkadmin.felix": Implementation of FrameworkAdmin service for Apache Felix. See javadoc of BundleActivator of this plug-in for more detail.
    • 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.
    • Launching a framework from Java programs is supported.
    • No supports for Manipulator#getTimeStamp().
  4. "org.eclipse.equinox.frameworkadmin.knopflerfish": Implementation of FrameworkAdmin service for Knopflerfish. See javadoc of BundleActivator of this plug-in for more detail.
    • 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.
    • Launching a framework from Java programs is supported.
    • No supports for Manipulator#getTimeStamp().
  5. "org.eclipse.equinox.simpleconfigurator": Implementation of SimpleConfigurator.
    • Framework property keyed by SimpleConfiguratorConstants.PROP_KEY_CONFIGURL is used for SimpleConfigurator to do life cycle control of bundles. The file specified by the returned url is read by SimpleConfigurator and do life cycle control according to it. If improper value or null is returned, SimpleConfigurator doesn't do it.
    • Framework property keyed by SimpleConfiguratorConstants.PROP_KEY_EXCLUSIVE_INSTALLATION equals "true" ignoring case, Configurator.applyConfiguration(url) will uninstall the installed bundles which are not listed in the simpleconfigurator config file after install bundles listed. Otherwise, it never uninstall any bundles.
    • If this bundle is running on Equinox, Framework property keyed by SimpleConfiguratorConstants.PROP_KEY_USE_REFERENCE does not equal "false" ignoring case, when a SimpleConfigurator installs a bundle, "reference:" is added to its bundle location in order to avoid caching its bundle jar. Otherwise, it will add nothing to any bundle location.
      • Default: true
        • This function is enabled only in case of running on Equinox because there is no standardized way to install a bundle without caching and other frameworks don't support it yet.
  6. "org.eclipse.equinox.simpleconfigurator.manipulator": Implementation of ConfiguratorManipulator for SimpleConfigurator.
  7. "org.eclipse.equinox.frameworkadmin.examples": examples using FrameworkAdmin.
    • In order to run these tests, read setting.properties in org.eclipse.equinox.frameworkadmin.examples package of this plug-in.
    • This properties file should be set properly in advance.
    • Example of a Java program using FrameworkAdmin is added (Since version 1.1.0)

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

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.

Version range

Currently, specifying version ranges of framework and launcher that the implementation can support are not supported at the registration of a FrameworkAdmin implementation. It might be required in future.

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

File or URL or Location newly defined?

Currently, LauncherData keeps most information related with file location, such as location of framework jar implementation, framework configuration, framework persistent data, and so on, as a File object. Due to this design, these must exist on the local machine. It might be better URL or newly defined Location instead of File.

Explicit specifying a framework jar

Currently, a client bundle needs to call LauncherData.setFwJar(File) in advance to doing some operation. Another design can be thought:

  • Instead of having no LauncherData.setFwJar(File) method, client should call ConfigData.addBundle(BundleInfo of framework jar) as one of bundles set to ConfigData. The implementation will identify a framework jar among them.

The problems of this approach would be:

  • Current OSGi specification doen's standardize how to identify if a jar is framework or not.
    • Identifying a bundle whose manifest has export-package header of "org.osgi.framework" as a framework jar might be used, although it is not a standardized way.
  • If the number of bundles which are identified as framework jar is more than one, how to determine the one to be activated ?
    • Maybe, the firstly added one among those framework jars each of which startlevel is 0 would be chosen.
  • Currently, FrameworkAdmin implementation of Equinox (since v.1.4.0) support some operation without setting fwJar explicitly by the way described above. To indentify an equinox(osgi) framework, Eclipse based bundle naming format (symbolicname_version.jar) assumption is used.

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
Retrieved from "https://wiki.eclipse.org/index.php?title=Equinox_FrameworkAdmin&oldid=29791"

This page was last modified 00:52, 13 March 2007 by Ikuo Yamasaki. Based on work by DJ Houghton.

Back to the top