Using FrameworkAdmin from Java programs

From Eclipsepedia

Jump to: navigation, search



Since version 1.1.0, FrameworkAdmin API and its implementation enables not only a bundle but also a Java program, which is not OSGi based application, 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.

Provider of FrameworkAdmin

To realize it, the provider should do

  1. implement a subclass of FrameworkAdminFactory whose createFrameworkAdmin() returns a FrameworkAdmin object which doesn’t use BundleContext at all.
  2. declare the fully qualified class name of it in public.
    • for instance, the name of the class in org.eclipse.equinox.frameworkadmin.equinox bundle is declared as org.eclipse.equinox.frameworkadmin.equinox.internal.EquinoxFrameworkAdminFactoryImpl.

Client Java program of FrameworkAdmin

On the other hand, a client Java program should do

  1. set classpath properly in order to load required classes.
    • Taking org.eclipse.equinox.frameworkadmin.equinox version 1.1.0 as an example, set org.eclipse.osgi_*.jar, org.eclipse.equinox.frameworkadmin_*.jar and org.eclipse.equinox.frameworkadmin.equinox_*.jar to its classpath.
  2. in the code, call static method FrameworkAdminFactory.getInstance(className) with the fully qualified class name of the FrameworkAdminFactory subclass for the target framework implementation. org.eclipse.equinox.frameworkadmin.equinox.internal.EquinoxFrameworkAdminFactoryImpl in order to get a FrameworkAdmin object for Equinox.

After instantiate a FrameworkAdmin object for the target framework implementation, do as same as a bundle which gets an FrameworkAdmin object from the service registry on running framework does for configuring and launching a framework.

Example code

Example code of a client Java program is included in org.eclipse.equinox.frameworkadmin.examples plug-in. In order to run it,

  1. set properties file called "" properly to your environment in advance (you don’t need to set properties related with either Knopflerfish or Felix, in this case).
  2. run Main class as a Java application from PDE (IDE)

The following is a pseudo code of it. Please see the actual code in org.eclipse.equinox.frameworkadmin.examples plug-in for more detail.

public static void main(String[] args) {
String className = "org.eclipse.equinox.frameworkadmin.equinox.internal.EquinoxFrameworkAdminFactory";
                     <--only this part is dependent on the target framework implementation. 

FrameworkAdmin fwAdmin = FrameworkAdminFactory.getInstance(className);

// After instanciating FrameworkAdmin object, completely same code can be used
// as the case that you get the object from a service registry on OSGi framework.
Manipulator manipulator = fwAdmin.getManipulator();
ConfigData configData = manipulator.getConfigData();
LauncherData launcherData = manipulator.getLauncherData();

// 1. Set Parameters to LaunchData.
launcherData.setJvm(new File("C:\Java\jre1.5.0_09\bin\java.exe"));
launcherData.setJvmArgs(new String[] {"-Dms40"});
launcherData.setFwPersistentDataLocation(new File("C:\eclipse\configuration"), true);
launcherData.setFwJar(new File("C:\eclipse\plugins\org.eclipse.osgi_3.3.0.v20070208.jar");
launcherData.setFwConfigLocation(new File("C:\eclipse\configuration"));

// 2. Set Parameters to ConfigData.
configData.addBundle(new BundleInfo( bundleLocation, startlevel, markedAsStartedOrNot);

// 3. Save them.;

// 4. Launch it.
Process process = fwAdmin.launch(manipulator, new File("C:\eclipse");


Theoretically, there is a limitations on using FrameworkAdmin from Java programs.

  • Since there is no ConfiguratorManipulater service available, save and load methods of Manipulator won't take Configurator into account.
    • c.f.) In case of using FrameworkAdmin which a bundle gets from service registry on running framework, save method will save info of bundles to be installed into not only framework configuration files but also configurator configuration files according to the availability of ConfiguratorManipulator services. See Configurator for more details.

For current FrameworkAdmin design (version 1.1.0), there are several limitations:

  • how the Java program can control the framework launched by the FrameworkAdmin is out of scope of it.
    • For Equinox, you can access to a console of the framework via telnet if you set its port number.
    • You can access to a management agent bundle, which is configured to be installed and started at a framework launch, in its own way.
  • FrameworkAdmin doesn't support launching a framework in the same process yet. It is one of the future work.

For current FrameworkAdmin implementation provided by this Equinox incubator subproject, there are several limitations:

  • org.eclipse.equinox.frameworkadmin.equinox_*.jar (ver. 1.1.0)
    • support for 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.
  • org.eclipse.equinox.frameworkadmin.knopflerfish_*.jar (ver. 1.0.2)
    • No support for launching a framework from Java programs yet. It will be supported soon.
  • org.eclipse.equinox.frameworkadmin.felix_*.jar (ver. 1.0.2)
    • No support for launching a framework from Java programs yet. It will be supported soon.


  1. Equinox_FrameworkAdmin