Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Equinox FrameworkAdmin"
(Initial Draft of Framework Handler API) |
|||
| Line 1: | Line 1: | ||
| − | + | <span style="color:red">'''This document is under construction.'''</span> | |
| + | |||
| + | == 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 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. | ||
| + | |||
| + | Currently, the focus of OSGi Service Platform Specification has been to standardize a runtime infrastracture. 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. | ||
| + | |||
| + | ==Overview:What FramerowkHandler enables?== | ||
| + | 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. | ||
| + | |||
| + | *Set parameters to be required to launch a fw and save these parameters into fw config files and launcher config files in the specified locations, where format of fw config files or format of launcher config files are dependent on a target fw and a target executable launcher implementation, respectively. | ||
| + | *Launch a fw with the specified configurations, such as Java VM, Java VM arguments and so on. | ||
| + | *Expect bundles state if the specified configurations are used for a fw launch. | ||
| + | **Bundles state represents that what kinds of bundles are installed, and resolved on a fw instance. | ||
| + | |||
| + | ==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. | ||
| + | ;Executable launcher:an executable fw 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 fw. | ||
| + | |||
| + | ==Senarios that the API would help== | ||
| + | ;PDE UI: to ease the targetting 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 | ||
| + | |||
| + | ==API: Package org.eclipse.core.fwhandler== | ||
| + | Interfaces defined in ''org.eclipse.core.fwhandler'' package will be introduced briefly. See the codes and Java docs in detail. | ||
| + | |||
| + | ===FwHandlerAdmin=== | ||
| + | The only interface 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, [[#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. | ||
| + | |||
| + | In addition, it also has a method to launch a fw according to the specified FwHandler object. | ||
| + | |||
| + | ===FwHandler=== | ||
| + | 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 target framework and launcher implementation dependent way. | ||
| + | |||
| + | The client also can load parameters from fw 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 migiht invoke a fw 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, FwHandler enables for a client bundle to expect bundles state if the specified configurations are used for launch without actual launch. | ||
| + | |||
| + | ===FwConfigData=== | ||
| + | FwConfigData is a class that keeps some parameters for a FwHandler 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 of a fw implementaion. | ||
| + | *System properties independent of a fw implementaion. | ||
| + | |||
| + | For most fw implementaions, 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. | ||
| + | |||
| + | ===FwLauncherData=== | ||
| + | FwLauncherData is a class that keeps some parameters for a FwHandler object such as, | ||
| + | *Location of Java VM. | ||
| + | *Java VM arguments. | ||
| + | *Location of fw 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. In addition, this location sho | ||
| + | *Clean flag: a flag to clean the specified locaiton of fw persistent data. | ||
| + | |||
| + | For most fw implementaions, 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. | ||
| + | |||
| + | ===FwBundleState=== | ||
| + | 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. | ||
| + | |||
| + | 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. | ||
| + | |||
| + | ===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 implementaion the most are the implementators of the target fw. | ||
| + | |||
| + | For clients to filter the proper service object, the provider must register the FwHandlerAdmin object with service properties keyed by the followings. | ||
| + | |||
| + | ;FwHandlerAdmin.SERVICE_PROP_KEY_FW_NAME: String; name of the framework | ||
| + | ;FwHandlerAdmin.SERVICE_PROP_KEY_FW_VERSION: String; version of the framework | ||
| + | ;FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_NAME: String; name of the launcher | ||
| + | ;FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_VERSION: String; version of the launcher | ||
| + | **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. | ||
| + | |||
| + | ===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. | ||
| + | |||
| + | ==TBD:Launching a fw 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. | ||
| + | *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). | ||
Revision as of 11:26, 16 January 2007
This document is under construction.
Contents
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 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.
Currently, the focus of OSGi Service Platform Specification has been to standardize a runtime infrastracture. 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.
Overview:What FramerowkHandler enables?
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.
- Set parameters to be required to launch a fw and save these parameters into fw config files and launcher config files in the specified locations, where format of fw config files or format of launcher config files are dependent on a target fw and a target executable launcher implementation, respectively.
- Launch a fw with the specified configurations, such as Java VM, Java VM arguments and so on.
- Expect bundles state if the specified configurations are used for a fw launch.
- Bundles state represents that what kinds of bundles are installed, and resolved on a fw instance.
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.
- Executable launcher
- an executable fw 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 fw.
Senarios that the API would help
- PDE UI
- to ease the targetting 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
API: Package org.eclipse.core.fwhandler
Interfaces defined in org.eclipse.core.fwhandler package will be introduced briefly. See the codes and Java docs in detail.
FwHandlerAdmin
The only interface 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 will explain it in detail. Then, the client will get new instance of FwHandler which plays a main role in this API.
In addition, it also has a method to launch a fw according to the specified FwHandler object.
FwHandler
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 target framework and launcher implementation dependent way.
The client also can load parameters from fw 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 migiht invoke a fw 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, FwHandler enables for a client bundle to expect bundles state if the specified configurations are used for launch without actual launch.
FwConfigData
FwConfigData is a class that keeps some parameters for a FwHandler 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 of a fw implementaion.
- System properties independent of a fw implementaion.
For most fw implementaions, 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.
FwLauncherData
FwLauncherData is a class that keeps some parameters for a FwHandler object such as,
- Location of Java VM.
- Java VM arguments.
- Location of fw 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. In addition, this location sho
- Clean flag: a flag to clean the specified locaiton of fw persistent data.
For most fw implementaions, 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.
FwBundleState
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.
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.
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 implementaion the most are the implementators of the target fw.
For clients to filter the proper service object, the provider must register the FwHandlerAdmin object with service properties keyed by the followings.
- FwHandlerAdmin.SERVICE_PROP_KEY_FW_NAME
- String; name of the framework
- FwHandlerAdmin.SERVICE_PROP_KEY_FW_VERSION
- String; version of the framework
- FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_NAME
- String; name of the launcher
- FwHandlerAdmin.SERVICE_PROP_KEY_LAUNCHER_VERSION
- String; version of the launcher
- 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.
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.
TBD:Launching a fw 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.
- 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).