org.apache.felix.main

Class Main

java.lang.Object

org.apache.felix.main.Main

public class Main
extends java.lang.Object

This class is the default way to instantiate and execute the framework. It is not intended to be the only way to instantiate and execute the framework; rather, it is one example of how to do so. When embedding the framework in a host application, this class can serve as a simple guide of how to do so. It may even be worthwhile to reuse some of its property handling capabilities.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BUNDLE_DIR_SWITCH Switch for specifying bundle directory.
static java.lang.String	CONFIG_DIRECTORY Name of the configuration directory.
static java.lang.String	CONFIG_PROPERTIES_FILE_VALUE The default name used for the configuration properties file.
static java.lang.String	CONFIG_PROPERTIES_PROP The property name used to specify an URL to the configuration property file to be used for the created the framework instance.
private static org.osgi.framework.launch.Framework	m_fwk
static java.lang.String	SHUTDOWN_HOOK_PROP The property name used to specify whether the launcher should install a shutdown hook.
static java.lang.String	SYSTEM_PROPERTIES_FILE_VALUE The default name used for the system properties file.
static java.lang.String	SYSTEM_PROPERTIES_PROP The property name used to specify an URL to the system property file.

Constructor Summary

Constructors

Constructor and Description
Main()

Method Summary

Modifier and Type	Method and Description
static void	copySystemProperties(java.util.Map configProps)
private static org.osgi.framework.launch.FrameworkFactory	getFrameworkFactory() Simple method to parse META-INF/services file for framework factory.
static java.util.Map<java.lang.String,java.lang.String>	loadConfigProperties() Loads the configuration properties in the configuration property file associated with the framework installation; these properties are accessible to the framework and to bundles and are intended for configuration purposes.
static void	loadSystemProperties() Loads the properties in the system property file associated with the framework installation into System.setProperty().
static void	main(java.lang.String[] args) This method performs the main task of constructing an framework instance and starting its execution.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BUNDLE_DIR_SWITCH

public static final java.lang.String BUNDLE_DIR_SWITCH

Switch for specifying bundle directory.

See Also:

Constant Field Values

SHUTDOWN_HOOK_PROP

public static final java.lang.String SHUTDOWN_HOOK_PROP

The property name used to specify whether the launcher should install a shutdown hook.

See Also:

Constant Field Values

SYSTEM_PROPERTIES_PROP

public static final java.lang.String SYSTEM_PROPERTIES_PROP

The property name used to specify an URL to the system property file.

See Also:

Constant Field Values

SYSTEM_PROPERTIES_FILE_VALUE

public static final java.lang.String SYSTEM_PROPERTIES_FILE_VALUE

The default name used for the system properties file.

See Also:

Constant Field Values

CONFIG_PROPERTIES_PROP

public static final java.lang.String CONFIG_PROPERTIES_PROP

The property name used to specify an URL to the configuration property file to be used for the created the framework instance.

See Also:

Constant Field Values

CONFIG_PROPERTIES_FILE_VALUE

public static final java.lang.String CONFIG_PROPERTIES_FILE_VALUE

The default name used for the configuration properties file.

See Also:

Constant Field Values

CONFIG_DIRECTORY

public static final java.lang.String CONFIG_DIRECTORY

Name of the configuration directory.

See Also:

Constant Field Values

m_fwk

private static org.osgi.framework.launch.Framework m_fwk

Constructor Detail

Main

public Main()

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

This method performs the main task of constructing an framework instance and starting its execution. The following functions are performed when invoked:

1. Examine and verify command-line arguments. The launcher accepts a "-b" command line switch to set the bundle auto-deploy directory and a single argument to set the bundle cache directory.
2. Read the system properties file. This is a file containing properties to be pushed into System.setProperty() before starting the framework. This mechanism is mainly shorthand for people starting the framework from the command line to avoid having to specify a bunch of -D system property definitions. The only properties defined in this file that will impact the framework's behavior are the those concerning setting HTTP proxies, such as http.proxyHost, http.proxyPort, and http.proxyAuth. Generally speaking, the framework does not use system properties at all.
3. Read the framework's configuration property file. This is a file containing properties used to configure the framework instance and to pass configuration information into bundles installed into the framework instance. The configuration property file is called config.properties by default and is located in the conf/ directory of the Felix installation directory, which is the parent directory of the directory containing the felix.jar file. It is possible to use a different location for the property file by specifying the desired URL using the felix.config.properties system property; this should be set using the -D syntax when executing the JVM. If the config.properties file cannot be found, then default values are used for all configuration properties. Refer to the Felix constructor documentation for more information on framework configuration properties.
4. Copy configuration properties specified as system properties into the set of configuration properties. Even though the Felix framework does not consult system properties for configuration information, sometimes it is convenient to specify them on the command line when launching Felix. To make this possible, the Felix launcher copies any configuration properties specified as system properties into the set of configuration properties passed into Felix.
5. Add shutdown hook. To make sure the framework shutdowns cleanly, the launcher installs a shutdown hook; this can be disabled with the felix.shutdown.hook configuration property.
6. Create and initialize a framework instance. The OSGi standard FrameworkFactory is retrieved from META-INF/services and used to create a framework instance with the configuration properties.
7. Auto-deploy bundles. All bundles in the auto-deploy directory are deployed into the framework instance.
8. Start the framework. The framework is started and the launcher thread waits for the framework to shutdown.

It should be noted that simply starting an instance of the framework is not enough to create an interactive session with it. It is necessary to install and start bundles that provide a some means to interact with the framework; this is generally done by bundles in the auto-deploy directory or specifying an "auto-start" property in the configuration property file. If no bundles providing a means to interact with the framework are installed or if the configuration property file cannot be found, the framework will appear to be hung or deadlocked. This is not the case, it is executing correctly, there is just no way to interact with it.

The launcher provides two ways to deploy bundles into a framework at startup, which have associated configuration properties:

• Bundle auto-deploy - Automatically deploys all bundles from a specified directory, controlled by the following configuration properties:
  • felix.auto.deploy.dir - Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the bundle/ directory of the current directory.
  • felix.auto.deploy.action - Specifies the auto-deploy actions to be found on bundle JAR files found in the auto-deploy directory. The possible actions are install, update, start, and uninstall. If no actions are specified, then the auto-deploy directory is not processed. There is no default value for this property.
• Bundle auto-properties - Configuration properties which specify URLs to bundles to install/start:
  • felix.auto.install.N - Space-delimited list of bundle URLs to automatically install when the framework is started, where N is the start level into which the bundle will be installed (e.g., felix.auto.install.2).
  • felix.auto.start.N - Space-delimited list of bundle URLs to automatically install and start when the framework is started, where N is the start level into which the bundle will be installed (e.g., felix.auto.start.2).

These properties should be specified in the config.properties so that they can be processed by the launcher during the framework startup process.

Parameters:

args - Accepts arguments to set the auto-deploy directory and/or the bundle cache directory.

Throws:

java.lang.Exception - If an error occurs.

getFrameworkFactory

private static org.osgi.framework.launch.FrameworkFactory getFrameworkFactory()
                                                                       throws java.lang.Exception

Simple method to parse META-INF/services file for framework factory. Currently, it assumes the first non-commented line is the class name of the framework factory implementation.

Returns:

The created FrameworkFactory instance.

Throws:

java.lang.Exception - if any errors occur.

loadSystemProperties

public static void loadSystemProperties()

Loads the properties in the system property file associated with the framework installation into System.setProperty(). These properties are not directly used by the framework in anyway. By default, the system property file is located in the conf/ directory of the Felix installation directory and is called "system.properties". The installation directory of Felix is assumed to be the parent directory of the felix.jar file as found on the system class path property. The precise file from which to load system properties can be set by initializing the "felix.system.properties" system property to an arbitrary URL.

loadConfigProperties

public static java.util.Map<java.lang.String,java.lang.String> loadConfigProperties()

Loads the configuration properties in the configuration property file associated with the framework installation; these properties are accessible to the framework and to bundles and are intended for configuration purposes. By default, the configuration property file is located in the conf/ directory of the Felix installation directory and is called "config.properties". The installation directory of Felix is assumed to be the parent directory of the felix.jar file as found on the system class path property. The precise file from which to load configuration properties can be set by initializing the "felix.config.properties" system property to an arbitrary URL.

Returns:

A Properties instance or null if there was an error.

copySystemProperties

public static void copySystemProperties(java.util.Map configProps)