Apache Felix Framework Launching and Embedding

Wiki Markup_\[This document describes framework launching introduced in Felix Framework 2.0.0 and continuing with the latest releases; it is incompatible with older versions of the Felix framework.\]_

• Introduction
• OSGi Launching and Embedding API Overview
  • Creating and Configuring the Framework Instance
  • Starting the Framework Instance
  • Stopping the Framework Instance
• Launching Felix
  • Standard Felix Launcher
  • Custom Felix Launcher
• Embedding Felix
  • Host/Felix Interaction
  • Providing Host Application Services
  • Using Services Provided by Bundles
    • Using Bundle Services via Reflection
    • Other Approaches
• Caveat
• Feedback

...

Creating and Configuring the Framework Instance

You use the framework factory to construct and configure a framework instance (or by directly instantiating the Felix class). The configuration map may contain the following OSGi standard properties:

• org.osgi.framework.system.packages - specifies a list of packages the system bundle should export from the environment; if this is not set, then the framework uses a reasonable default.
• org.osgi.framework.system.packages.extra - specifies a list of additional packages the system bundle should export from the environment that are appended to the packages specified in org.osgi.framework.system.packages; there is no default value for this property.
• org.osgi.framework.bootdelegation - specifies a list of packages that should be made implicitly available to all bundles from the environment (i.e., no need to import them); there is no default value for this property and its use should be avoided.
• org.osgi.framework.bundle.parent - Specifies which class loader is used for boot delegation. Possible values are: boot for the boot class loader, app for the application class loader, ext for the extension class loader, and framework for the framework's class loader. The default is boot.
• org.osgi.framework.storage - specifies the path to a directory, which will be created if it does not exist, to use for bundle cache storage; the default value for this property is "felix-cache" in the current working directory.
• org.osgi.framework.storage.clean - specifies whether the bundle cache should be flushed; the default value for this property is "none", but it can be changed to "onFirstInit" to flush the bundle cache when the framework is initialized.
• org.osgi.framework.startlevel.beginning - specifies the start level the framework enters upon startup; the default value for this property is 1.

Felix also has the following, non-standard configuration properties:

• felix.cache.rootdir - specifies which directory should be used to calculate absolute paths when relative paths are used for the org.osgi.framework.storage property; the default value for this property is the current working directory.
• felix.systembundle.activators - specifies a List of BundleActivator instances that are started/stopped when the System Bundle is started/stopped; the specified instances will receive the System Bundle's BundleContext when invoked.
• felix.log.logger - specifies an instance of org.apache.felix.framework.util.Logger that the framework uses as its default logger.
• felix.log.level - specifies an integer String whose value indicates the degree of logging reported by the framework; the default value is "1" and "0" turns off logging completely, otherwise log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug).
• felix.startlevel.bundle - specifies the start level for newly installed bundles; the default value is 1.
• felix.bootdelegation.implicit - specifies whether or not the framework should try to guess when to boot delegate when external code tries to load classes or resources; the default value is "true".
• framework.service.urlhandlers - specifies whether or not to activate the URL Handlers service for the framework instance; the default value is "true", which results in the URL.setURLStreamHandlerFactory() and URLConnection.setContentHandlerFactory() being called.

Creating and Configuring the Framework Instance

You use the framework factory to construct and configure a framework instance (or by directly instantiating the Felix class). The configuration map may contain any of the framework configuration properties listed in the Apache Felix Framework Configuration Properties document, not the launcher configuration properties. The configuration map is copied and the keys are treated as case insensitive. You are not able to change the framework's configuration after construction. If you need a different configuration, you must create a new framework instance.

...

package example;

import java.io.*;
import org.osgi.framework.launch.*;
import org.apache.felix.main.AutoProcessor;

public class Main
{
    private static Framework m_fwk = null;

    public static void main(String[] argv) throws Exception
    {
        // Print welcome banner.
        System.out.println("\nWelcome to My Launcher");
        System.out.println("======================\n");

        try
        {
            m_fwk = getFrameworkFactory().newFramework(null);
            m_fwk.init();
            AutoProcessor.process(null, m_fwk.getBundleContext());
            m_fwk.start();
            m_fwk.waitForStop(0);
            System.exit(0);
        }
        catch (Exception ex)
        {
            System.err.println("Could not create framework: " + ex);
            ex.printStackTrace();
            System.exit(-1);
        }
    }

    private static FrameworkFactory getFrameworkFactory() throws Exception
    {
        java.net.URL url = Main.class.getClassLoader().getResource(
            "META-INF/services/org.osgi.framework.launch.FrameworkFactory");
        if (url != null)
        {
            BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()));
            try
            {
                for (String s = br.readLine(); s != null; s = br.readLine())
                {
                    s = s.trim();
                    // Try to load first non-empty, non-commented line.
                    if ((s.length() > 0) && (s.charAt(0) != '#'))
                    {
                        return (FrameworkFactory) Class.forName(s).newInstance();
                    }
                }
            }
            finally
            {
                if (br != null) br.close();
            }
        }

        throw new Exception("Could not find framework factory.");
    }
}

...

            m_fwk.start();
            m_fwk.waitForStop(0);
            System.exit(0);

These final steps start the framework and cause the launching application thread to wait for the framework to stop and when it does the launching thread calls System.exit() to make sure the VM actually exits.

...