Launching and Embedding Apache Felix

This document is based on Felix 1.0.2.

• Introduction
• API Overview
• Launching Felix
  • Standard Felix Launcher
  • Custom Felix Launcher
• Embedding Felix
  • Embedded Execution Configuration Property
  • Host/Felix Interaction
  • Providing Host Application Services
  • Using Services Provided by Bundles
    • Using Bundle Services via Reflection
• Caveat
• Feedback

...

When you instantiate the Felix class, the resulting object is actually the System Bundle and can be cast to the Bundle interface. The start() method is used to start the framework instance, while the stop() method is used to asynchronously stop the framework instance. The Felix class also includes the following two three additional public methods:

public class Felix extends AbstractBundleFelixBundle
{
    public Felix(Map configMutableMap, List activatorList);
    public Felix(Logger logger, Map configMutableMap, List activatorList)
    public void stopAndWait();
}

The first method is the constructor two methods are constructors used to instantiate framework instances; the constructor accepts the important parameters of the constructors are the configuration properties and System Bundle activators, which are both described in more detail later. The stopAndWait() method is a synchronous version of the stop() method, used to stop the framework and block the calling thread until the framework is completely stopped.

...

Besides configuration properties for the bundle cache, it is usually necessary to set the org.osgi.framework.system.packages configuration property to export packages from the class path, such as the OSGi interface classes (e.g., org.osgi.framework) on which all bundles depend. If you are creating a launcher for Felix, then the felix.auto.start configuration property may also be used often you want to automatically install and start bundles when you start the framework instance. The default Felix launcher defines reusable functionality to automatically install and/or start various bundles upon framework startup; see the usage document for more information on configuring Felix and on the various configuration properties.

...

public static void main(String[] argv) throws Exception
{
    // (1) Load system properties.
    Main.loadSystemProperties();

    // (2) Read configuration properties.
    Properties configProps = Main.loadConfigProperties();

    // (3) Copy framework properties from the system properties.
    Main.copySystemProperties(configProps);

    // (4) See if the profile name property was specified.
    String profileName = configProps.getProperty(BundleCache.CACHE_PROFILE_PROP);

    // (4) See if the profile directory property was specified.
    String profileDirName = configProps.getProperty(BundleCache.CACHE_PROFILE_DIR_PROP);

    // Print welcome banner.
    System.out.println("\nWelcome to Felix.");
    System.out.println("=================\n");

    // (5) If no profile or profile directory is specified in the
    // properties, then ask for a profile name.
    if ((profileName == null) && (profileDirName == null))
    {
        System.out.print("Enter profile name: ");
        BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
        try
        {
            profileName = in.readLine();
        }
        catch (IOException ex)
        {
            System.err.println("Could not read input.");
            System.exit(-1);
        }
        System.out.println("");
        if (profileName.length() != 0)
        {
            configProps.setProperty(BundleCache.CACHE_PROFILE_PROP, profileName);
        }
    }

    // (6) A profile directory or name must be specified.
    if ((profileDirName == null) && (profileName.length() == 0))
    {
        System.err.println("You must specify a profile name or directory.");
        System.exit(-1);
    }

    try
    {
        // (7) NowCreate createa anlist instancefor ofcustom the framework activators and
        // add an instance of the auto-activator it for processing
        // auto-install and auto-start properties.
        List list = new ArrayList();
        list.add(new AutoActivator(configProps));
        // (8) Create a case-insensitive property map.
        Map configMap = new StringMap(configProps, false);
        // (9) Create an instance of the framework.
        m_felix = new Felix(new StringMap(configPropsconfigMap, false), nulllist);
        m_felix.start();
    }
    catch (Exception ex)
    {
        System.err.println("Could not create framework: " + ex);
        ex.printStackTrace();
        System.exit(-1);
    }
}

...

1. Load any system properties specified in the system.properties file; this file is typically located in the conf/ directory of the Felix installation directory, but it can be specified directly using the felix.system.properties system property. This file is not needed to launch Felix and is provided merely for convenience when system properties must be specified. The file is a standard Java properties file, but it also supports property substitution using ${<property-name} syntax. Property substitution can be nested; only system properties will be used for substitution.
2. Load any configuration properties specified in the config.properties file; this file is typically located in the conf/ directory of the Felix installation directory, but it can be specified directly using the felix.config.properties system property. This file is used to configure the Felix instance created by the launcher. The file is a standard Java properties file, but it also supports property substitution using "${<property-name}" syntax. Property substitution can be nested; configuration and system properties will be used for substitution with configuration properties having precedence.
3. For convenience, any configuration properties that are set as system properties will be copied into the set of configuration properties to provide an easy way to add to or override configuration properties specified in the config.properties file.
4. Try to load the profile name or profile directory configuration properties. At least one of these must be specified so that the bundle cache knows where to save installed bundles.
5. If either the profile name or profile directory configuration property has not been specified, then ask the user to specify a profile name and add it to the current set of configuration properties.
6. Error if there is no profile name or profile directory.
7. Create a list to hold custom framework activators and add an instance of org.apache.felix.main.AutoActivator, which will process felix.auto.install and felix.auto.start configuration properties during framework startup to automatically install and/or start bundles; see the usage document for more information configuration properties.
8. Create a case-insensitive map to hold our configuration properties.
9. Create the Felix instance passing in the configuration properties and custom framework activators, then call start().

The framework is not active until the start() method is called. If no shell bundles are specified in the config.properties file or if there is difficulty locating the shell bundles that are specified, then it will appear as if the framework is hung, but it is actually running without any way to interact with it since the shell bundles provide the only means of interaction.

...