org.apache.felix.main
Class Main

java.lang.Object
  extended by 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
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.
static java.lang.String DEFAULT_PROPERTIES_FILE_VALUE
          The default name used for the default configuration properties file.
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
Main()
           
 
Method Summary
static void copySystemProperties(java.util.Properties configProps)
           
static java.util.Properties 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[] argv)
           This method performs the main task of constructing an framework instance and starting its execution.
static java.lang.String substVars(java.lang.String val, java.lang.String currentKey, java.util.Map cycleMap, java.util.Properties configProps)
           This method performs property variable substitution on the specified value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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

DEFAULT_PROPERTIES_FILE_VALUE

public static final java.lang.String DEFAULT_PROPERTIES_FILE_VALUE
The default name used for the default configuration properties file.

See Also:
Constant Field Values
Constructor Detail

Main

public Main()
Method Detail

main

public static void main(java.lang.String[] argv)
                 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. 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.
  2. Perform system property variable substitution on system properties. Any system properties in the system property file whose value adheres to ${<system-prop-name>} syntax will have their value substituted with the appropriate system property value.
  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 the bare-bones default.properties configuration file will be used to set the configuration properties; this file is embedded in the launcher JAR file. Refer to the Felix constructor documentation for more information on the framework configuration options.
  4. Perform system property variable substitution on configuration properties. Any configuration properties whose value adheres to ${<system-prop-name>} syntax will have their value substituted with the appropriate system property value.
  5. Ensure the default bundle cache has sufficient information to initialize. The default implementation of the bundle cache requires either a profile name or a profile directory in order to start. The configuration properties are checked for at least one of the felix.cache.profile or felix.cache.profiledir properties. If neither is found, the user is asked to supply a profile name that is added to the configuration property set. See the DefaultBundleCache documentation for more details its configuration options.
  6. Creates and starts a framework instance. A case insensitive StringMap is created for the configuration property file and is passed into the framework.

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 specifying an "auto-start" property in the framework 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 default launcher provides two configuration properties to help you automatically install and/or start bundles, which are:

  • felix.auto.install.<n> - Space-delimited list of bundle URLs to automatically install into start level n when the framework is started. Append a specific start level to this property name to assign the bundles' start level (e.g., felix.auto.install.2); otherwise, bundles are installed into the default bundle start level.
  • felix.auto.start.<n> - Space-delimited list of bundle URLs to automatically install and start into start level n when the framework is started. Append a specific start level to this property name to assign the bundles' start level(e.g., felix.auto.start.2); otherwise, bundles are installed into the default bundle start level.

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

Parameters:
argv - An array of arguments, all of which are ignored.
Throws:
java.lang.Exception - If an error occurs.

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.Properties 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.Properties configProps)

substVars

public static java.lang.String substVars(java.lang.String val,
                                         java.lang.String currentKey,
                                         java.util.Map cycleMap,
                                         java.util.Properties configProps)
                                  throws java.lang.IllegalArgumentException

This method performs property variable substitution on the specified value. If the specified value contains the syntax ${<prop-name>}, where <prop-name> refers to either a configuration property or a system property, then the corresponding property value is substituted for the variable placeholder. Multiple variable placeholders may exist in the specified value as well as nested variable placeholders, which are substituted from inner most to outer most. Configuration properties override system properties.

Parameters:
val - The string on which to perform property substitution.
currentKey - The key of the property being evaluated used to detect cycles.
cycleMap - Map of variable references used to detect nested cycles.
configProps - Set of configuration properties.
Returns:
The value of the specified string after system property substitution.
Throws:
java.lang.IllegalArgumentException - If there was a syntax error in the property placeholder syntax or a recursive variable reference.