org.apache.karaf.main
Class Main

java.lang.Object
  extended by org.apache.karaf.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. This class is completely static and is only intended to start a single instance of the framework.


Field Summary
static java.lang.String BUNDLE_LOCATIONS
          Config property which identifies directories which contain bundles to be loaded by SMX
static java.lang.String CONFIG_PROPERTIES_FILE_NAME
          The default name used for the configuration properties file.
static java.lang.String DEFAULT_REPO
           
static java.lang.String DEFAULT_SHUTDOWN_COMMAND
           
static java.lang.String ENV_KARAF_BASE
          The environment variable for specifying the Karaf base directory.
static java.lang.String ENV_KARAF_DATA
          The environment variable for specifying the Karaf data directory.
static java.lang.String ENV_KARAF_HOME
          The environment variable for specifying the Karaf home directory.
static java.lang.String ENV_KARAF_INSTANCES
          The system property for specifying the Karaf data directory.
static java.lang.String INCLUDES_PROPERTY
           
static java.lang.String KARAF_FRAMEWORK
           
static java.lang.String KARAF_FRAMEWORK_FACTORY
           
static java.lang.String KARAF_SHUTDOWN_COMMAND
           
static java.lang.String KARAF_SHUTDOWN_HOST
           
static java.lang.String KARAF_SHUTDOWN_PID_FILE
           
static java.lang.String KARAF_SHUTDOWN_PORT
           
static java.lang.String KARAF_SHUTDOWN_PORT_FILE
           
static java.lang.String KARAF_SHUTDOWN_TIMEOUT
           
static java.lang.String PROP_KARAF_BASE
          The system property for specifying the Karaf base directory.
static java.lang.String PROP_KARAF_DATA
          The system property for specifying the Karaf data directory.
static java.lang.String PROP_KARAF_HOME
          The system property for specifying the Karaf home directory.
static java.lang.String PROP_KARAF_INSTANCES
          The system property for specifying the Karaf data directory.
static java.lang.String PROPERTY_AUTO_INSTALL
          The property name prefix for the launcher's auto-install property.
static java.lang.String PROPERTY_AUTO_START
          The property for auto-discovering the bundles
static java.lang.String PROPERTY_CONVERT_TO_MAVEN_URL
          Config property that indicates we want to convert bundles locations to maven style urls
static java.lang.String PROPERTY_LOCK_CLASS
          The lock implementation
static java.lang.String PROPERTY_LOCK_CLASS_DEFAULT
           
static java.lang.String PROPERTY_LOCK_DELAY
           
static java.lang.String PROPERTY_LOCK_LEVEL
           
static java.lang.String PROPERTY_USE_LOCK
          If a lock should be used before starting the runtime
static java.lang.String STARTUP_PROPERTIES_FILE_NAME
          The default name used for the startup properties file.
static java.lang.String SYSTEM_PROPERTIES_FILE_NAME
          The default name used for the system properties file.
 
Constructor Summary
Main(java.lang.String[] args)
           
 
Method Summary
 void awaitShutdown()
           
protected static void copySystemProperties(java.util.Properties configProps)
           
 boolean destroy()
           
 java.lang.String[] getArgs()
          Retrieve the arguments used when launching Karaf
 int getExitCode()
           
 org.osgi.framework.launch.Framework getFramework()
           
 void launch()
           
protected static java.util.Properties loadPropertiesFile(java.net.URL configPropURL, boolean failIfNotFound)
           
protected static void loadSystemProperties(java.io.File karafBase)
           Loads the properties in the system property file associated with the framework installation into System.setProperty().
 void lock(java.util.Properties props)
           
static void main(java.lang.String[] args)
           This method performs the main task of constructing an framework instance and starting its execution.
 void setExitCode(int exitCode)
           
 void setShutdownCallback(ShutdownCallback shutdownCallback)
           
protected  void setStartLevel(int level)
           
protected  void setupShutdown(java.util.Properties props)
           
static java.lang.String substVars(java.lang.String val, java.lang.String currentKey, java.util.Map<java.lang.String,java.lang.String> cycleMap, java.util.Properties configProps)
           This method performs property variable substitution on the specified value.
 void unlock()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYSTEM_PROPERTIES_FILE_NAME

public static final java.lang.String SYSTEM_PROPERTIES_FILE_NAME
The default name used for the system properties file.

See Also:
Constant Field Values

CONFIG_PROPERTIES_FILE_NAME

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

See Also:
Constant Field Values

STARTUP_PROPERTIES_FILE_NAME

public static final java.lang.String STARTUP_PROPERTIES_FILE_NAME
The default name used for the startup properties file.

See Also:
Constant Field Values

PROPERTY_AUTO_INSTALL

public static final java.lang.String PROPERTY_AUTO_INSTALL
The property name prefix for the launcher's auto-install property.

See Also:
Constant Field Values

PROPERTY_AUTO_START

public static final java.lang.String PROPERTY_AUTO_START
The property for auto-discovering the bundles

See Also:
Constant Field Values

PROP_KARAF_HOME

public static final java.lang.String PROP_KARAF_HOME
The system property for specifying the Karaf home directory. The home directory hold the binary install of Karaf.

See Also:
Constant Field Values

ENV_KARAF_HOME

public static final java.lang.String ENV_KARAF_HOME
The environment variable for specifying the Karaf home directory. The home directory hold the binary install of Karaf.

See Also:
Constant Field Values

PROP_KARAF_BASE

public static final java.lang.String PROP_KARAF_BASE
The system property for specifying the Karaf base directory. The base directory holds the configuration and data for a Karaf instance.

See Also:
Constant Field Values

ENV_KARAF_BASE

public static final java.lang.String ENV_KARAF_BASE
The environment variable for specifying the Karaf base directory. The base directory holds the configuration and data for a Karaf instance.

See Also:
Constant Field Values

PROP_KARAF_DATA

public static final java.lang.String PROP_KARAF_DATA
The system property for specifying the Karaf data directory. The data directory holds the bundles data and cache for a Karaf instance.

See Also:
Constant Field Values

ENV_KARAF_DATA

public static final java.lang.String ENV_KARAF_DATA
The environment variable for specifying the Karaf data directory. The data directory holds the bundles data and cache for a Karaf instance.

See Also:
Constant Field Values

PROP_KARAF_INSTANCES

public static final java.lang.String PROP_KARAF_INSTANCES
The system property for specifying the Karaf data directory. The data directory holds the bundles data and cache for a Karaf instance.

See Also:
Constant Field Values

ENV_KARAF_INSTANCES

public static final java.lang.String ENV_KARAF_INSTANCES
The system property for specifying the Karaf data directory. The data directory holds the bundles data and cache for a Karaf instance.

See Also:
Constant Field Values

BUNDLE_LOCATIONS

public static final java.lang.String BUNDLE_LOCATIONS
Config property which identifies directories which contain bundles to be loaded by SMX

See Also:
Constant Field Values

PROPERTY_CONVERT_TO_MAVEN_URL

public static final java.lang.String PROPERTY_CONVERT_TO_MAVEN_URL
Config property that indicates we want to convert bundles locations to maven style urls

See Also:
Constant Field Values

PROPERTY_USE_LOCK

public static final java.lang.String PROPERTY_USE_LOCK
If a lock should be used before starting the runtime

See Also:
Constant Field Values

PROPERTY_LOCK_CLASS

public static final java.lang.String PROPERTY_LOCK_CLASS
The lock implementation

See Also:
Constant Field Values

PROPERTY_LOCK_DELAY

public static final java.lang.String PROPERTY_LOCK_DELAY
See Also:
Constant Field Values

PROPERTY_LOCK_LEVEL

public static final java.lang.String PROPERTY_LOCK_LEVEL
See Also:
Constant Field Values

DEFAULT_REPO

public static final java.lang.String DEFAULT_REPO
See Also:
Constant Field Values

KARAF_FRAMEWORK

public static final java.lang.String KARAF_FRAMEWORK
See Also:
Constant Field Values

KARAF_FRAMEWORK_FACTORY

public static final java.lang.String KARAF_FRAMEWORK_FACTORY
See Also:
Constant Field Values

KARAF_SHUTDOWN_TIMEOUT

public static final java.lang.String KARAF_SHUTDOWN_TIMEOUT
See Also:
Constant Field Values

KARAF_SHUTDOWN_PORT

public static final java.lang.String KARAF_SHUTDOWN_PORT
See Also:
Constant Field Values

KARAF_SHUTDOWN_HOST

public static final java.lang.String KARAF_SHUTDOWN_HOST
See Also:
Constant Field Values

KARAF_SHUTDOWN_PORT_FILE

public static final java.lang.String KARAF_SHUTDOWN_PORT_FILE
See Also:
Constant Field Values

KARAF_SHUTDOWN_COMMAND

public static final java.lang.String KARAF_SHUTDOWN_COMMAND
See Also:
Constant Field Values

KARAF_SHUTDOWN_PID_FILE

public static final java.lang.String KARAF_SHUTDOWN_PID_FILE
See Also:
Constant Field Values

DEFAULT_SHUTDOWN_COMMAND

public static final java.lang.String DEFAULT_SHUTDOWN_COMMAND
See Also:
Constant Field Values

PROPERTY_LOCK_CLASS_DEFAULT

public static final java.lang.String PROPERTY_LOCK_CLASS_DEFAULT

INCLUDES_PROPERTY

public static final java.lang.String INCLUDES_PROPERTY
See Also:
Constant Field Values
Constructor Detail

Main

public Main(java.lang.String[] args)
Method Detail

setShutdownCallback

public void setShutdownCallback(ShutdownCallback shutdownCallback)

launch

public void launch()
            throws Exception
Throws:
Exception

awaitShutdown

public void awaitShutdown()
                   throws Exception
Throws:
Exception

destroy

public boolean destroy()
                throws Exception
Throws:
Exception

main

public static void main(java.lang.String[] args)
                 throws 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.
  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. 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 an interactive impl; this is generally done by specifying an "auto-start" property in the framework configuration property file. If no interactive impl bundles 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. Refer to the Felix constructor documentation for more information on framework configuration options.

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

loadSystemProperties

protected static void loadSystemProperties(java.io.File karafBase)

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.

Parameters:
karafBase - the karaf base folder

loadPropertiesFile

protected static java.util.Properties loadPropertiesFile(java.net.URL configPropURL,
                                                         boolean failIfNotFound)
                                                  throws Exception
Throws:
Exception

copySystemProperties

protected 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<java.lang.String,java.lang.String> 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.

getArgs

public java.lang.String[] getArgs()
Retrieve the arguments used when launching Karaf

Returns:
the arguments of the main karaf process

getExitCode

public int getExitCode()

setExitCode

public void setExitCode(int exitCode)

getFramework

public org.osgi.framework.launch.Framework getFramework()

lock

public void lock(java.util.Properties props)

unlock

public void unlock()
            throws Exception
Throws:
Exception

setStartLevel

protected void setStartLevel(int level)
                      throws Exception
Throws:
Exception

setupShutdown

protected void setupShutdown(java.util.Properties props)


Copyright © 2007-2011 Apache Software Foundation. All Rights Reserved.